Exceptional Validation Laravel Package

Getting Started

• Install the pre-release explicitly, e.g. composer require phphd/exceptional-matcher:2.0.0-rc3 or constrain to ^2.0@rc, and pin the exact RC in applications where exception output is user-facing.
• Start with the README examples and then inspect src/Integration/. In 2.0.0-rc3, Validator integration and Uid/Validator integrated conditions were moved there, so this is the first place to look when wiring Laravel-specific behavior.
• First practical use case: route Laravel validation failures through the matcher so ValidationFailedException and ViolationsEmbeddedException are rendered through one consistent formatter instead of duplicating response-shaping logic.
• Register the matcher in your Laravel exception handling flow, either in a dedicated exception handler/service or via renderable hooks, and keep the matcher rules close to your app’s exception policy rather than scattering conditionals across controllers.

Implementation Patterns

• Keep matcher definitions declarative: map exception types/conditions to handlers or formatters in one place, then let Laravel’s exception pipeline delegate to it. This makes day-to-day changes like adding a new validation exception or response shape a one-line rule change.
• For Laravel validation, use the Integration\ namespace for Validator-related classes and conditions. The RC3 refactor intentionally separates framework integrations from the core matcher, so application code should import from the integration namespace rather than the older core locations.
• Use the single formatter introduced for both ValidationFailedException and ViolationsEmbeddedException. Configure it once and verify both paths produce the same envelope: message, errors/violations, status code, and any debug metadata.
• Use Uid/Validator integrated conditions from Integration\ when matching depends on request identity, validation state, or similar Laravel context. Keep app-specific conditions in your own namespace and compose them with package conditions.
• A common pattern is a small ExceptionMatcher service resolved from the container, injected into the Laravel exception handler. That keeps matching testable in isolation and avoids hard-coding matcher construction in Handler::render.
• Add feature tests around the Laravel exception handler for both validation exception types, including nested violations. Unit-test formatter output separately so formatter changes do not require full HTTP tests.
• If you support non-Laravel contexts, keep the core matcher usage separate from Integration\ imports so the Laravel-specific Validator/Uid pieces remain optional.

Gotchas and Tips

• RC3 contains namespace moves: Validator integration and Uid/Validator integrated conditions now live under Integration\. After upgrading from 2.0.0-rc-2, grep for old imports of Validator, Uid, ValidationFailedException, and ViolationsEmbeddedException and update them.
• The formatter refactor means separate formatter configuration for ValidationFailedException and ViolationsEmbeddedException may no longer apply. Consolidate to the single formatter and re-check both exception paths.
• This is still a release candidate. Pin the exact version, review the changelog before each RC bump, and treat namespace/API changes as expected until 2.0.0 stable.
• Debug matcher behavior by logging which rule matched and the condition result before formatting. Exception handler ordering matters: Laravel may convert or wrap validation exceptions before your matcher sees them.
• Check that ValidationFailedException and ViolationsEmbeddedException are not both handled by legacy app code. Remove duplicate formatting/response logic or the new single formatter may not be the source of truth.
• Extension points are best kept at the edges: custom conditions and custom formatters in app code, package integration classes imported as-is. Avoid editing vendor classes for namespace compatibility; use your own adapters if you need to support both RC2 and RC3 during a transition.