Download the PHP package phphd/exceptional-validation without Composer

Exceptional Matcher 🏹

💼 Match the Exceptions to the Object's Properties

A lightweight bridge from domain exceptions to validation violations.

Your domain code that processes Dto (i.e. services / entities) can run validation by throwing business exceptions. \ Using Matcher, you can correlate it to the property that originated it – thereby allowing to return precise field-specific validation errors inferred from the exceptions.

Thence it makes up for what was lacking in tools for relating validation exceptions to their originator fields.

Quick Start ⚡

Install 📥

1. Require via composer:

2. [Symfony] enable the bundles in the bundles.php:

   Note: PhdExceptionToolkitBundle is a required dependency \ that provides exception unwrapping needful for this library.

3. [Non-Symfony] configure the container:

   You can use features of this library outside frameworks. \ See Standalone Usage.

Map and Throw 🎯

Mark a command or dto with #[Try_] attribute, and properties with #[Catch_].

#[Try_] lets the matcher know it's included for processing. \ #[Catch_] defines rules about "what" and "how" to catch.

Finally, throw those exceptions from your use-case handler:

Note: UserRegistration embodies both data (DTO) and behavior (Service) over this data, \ effectively attaining well-comprehensible Object-Oriented Design.

These mappings describe what exceptions what properties correlate with.

Here, LoginAlreadyTakenException is bound to the login property, \ while PasswordCompromisedException is bound to the password property.

You can have additional matching conditions beyond just the exception class name. \ See Match Conditions 🖇️.

The equivalent (very rough) simplified manual logic if not using this library:

Catch and Match 🎣

Exceptional Validation is like a parable of fisherman.

One man went out to fish carps. \ Having cast a fishing rod, he waits... \ And there it is! It's biting! \ In anticipation of a catch, he starts reeling up... \ Yet, to his disappointment, it's a fry and not a fish! \ He throws it back.

The second time he casts the line... \ In faith of a good catch, he waits... \ And now at last, he pulls a fine 5-pound carp. \ He takes it home and roasts it to eat.

The code:

The cue to a parable:

• Exception is the fish;
• Code that catches is the fisherman;
• Data object's mappings – man's expectation of a carp;
• ConstraintViolation – the fish after roasting.

Fisherman evaluates the fish against his expectation - \ ExceptionMatcher matches the exception against UserRegistration object.

Fisherman roasts the fish - \ ExceptionMatcher returns the ConstraintViolation list (or custom format) created of the exception.

Fisherman releases the fry - \ ExceptionMatcher didn't match, and the main code throws $exception; back.

Finally, the created ConstraintViolationList contains violation-objects with matched property path, message translation, and invalid value.

You can serialize it into a json-response or render on a form.

Why Exceptional Matcher ✨

Exceptional Matcher opens the way for Exceptional Validation, wherewith you can omit any peripheral validation off of your dto objects, \ and rely solely on validation in real code (services, value objects) – that belongs to and resides in the domain.

Thus, you have a full-fledged domain-embedded validation that naturally expresses itself with the exceptions.

Where is the Power 🚀

Consider another use-case: after registration, the user should be able to update his profile.

Updating the login must ensure its uniqueness in spite of the current user.

Here's what we'd have to do with an upfront attribute-driven validation:

Compare this to #[Catch_] approach and recognize which communicates the intent better:

The first approach is very imperative, verbose. \ The second declaratively states the fact.

Moreover, now you don't restrain yourself with the limitations of the framework. \ You don't have limitations at all. \ Exceptional Validation enables you to implement everything at the highest quality possible.

The mapping for profile update Dto is just as high-level as it was for registration Dto:

No custom validators, no attribute-driven-rules - just pure business description.

The main code is just as simple as it could be, throwing the same elucidated exceptions:

• the same LoginAlreadyTakenException as used in registration, just under another condition.
• the same check of PasswordCompromisedException as with registration.
• additional PasswordCannotBeReusedException, specific to profile update.

This communicates the design much better than what we've seen thus far.

This is where the power comes from. You don't cram the validation into the framework. \ You broaden the framework so that it embraces your validation in a way that it naturally fits in.

Read more in: Exceptional Validation.

Interaction approaches 🔁

The library provides a few interaction points:

• Matcher Service – manual handling (just as shown);
• Bus Middleware – automated handling.

Features 💎

#[Try_] and #[Catch_] attributes allow implementation of very flexible matching rules. \ It's highly recommended to get acquainted with the examples to apprehend the full power of these solutions.

There are two configuration features:

• Match Conditions 🖇️ – determine whether a given exception should match the given property;
• Violation Formatters 🎨 – represent the exception in a desired format.

That's really all this library does – matches the exception and formats it (i.e. roasts the fish).

Cheat Sheet 📝

For a cheat-sheet example of configuration, check the following:

Deep analysis 🌊

The matcher automatically picks all nested objects for analysis, provided that they define #[Try_] attribute.

With nested matching with array properties, property paths are formatted differently.

In the example above, when the exception is matched, the path would be items[<index>].<filed>:

• <index> - a particular array index;
• <field> - a particualr property name of that object.

When nesting is really deep, the resulting property path of the formatted violation would include all intermediary properties in its path, starting from the root, down to the leaf item where the exception was actually matched.

Need for conditions

Finding a match for the exception in array field is like finding your luggage in the baggage claim \ when everyone else took just the same alike red backpack as you did.

When many backpacks are as yours, you must know which one is yours.

Similarly, finding a match for BackorderDisabledForCategoryException across ImportProductDto[] must know which one to relate to, lest it would choose the first object by exception's class: condition (i.e. "grab the first red one and go").

To find your backpack, you would look at some other characteristics that discern it from the rest, \ yea, up to the point of opening it and discovering (or not discovering) your stuff in there.

That's what if: condition is there for – to relate an exception to $this particular object.

In our example, we check that the object's category (e.g. stuff in a backpack) is the same as the one we seek for of the exception.

If the category is different, the object is skipped and another is taken for consideration.

The same applies to the products that don't enable backorder (backorderLimit is not filled):

Thus, we prevent false attribution of the exception to an object that had nothing to do with it.

Advanced 🛠️

• Matching multiple exceptions 🕎 – beyond just one thrown exception.

Standalone Usage 🔧

If you are not using a Symfony framework, you can still have a great advantage of this library.

In your vanilla project, create a Service Container (symfony/dependency-injection is required) \ and use it to get necessary services:

Herein, you create a Container, compile it, and use to get ExceptionMatcher.

Upgrading 👻

The basic upgrade should be performed by Rector using ExceptionalMatcherSetList \ that comes with the library and contains automatic upgrade rules.

To upgrade a project to the latest version of exceptional-matcher, \ make the following configuration to your rector.php file:

Make sure to specify your current version of the library so that upgrade sets will be matched correctly.

You should also check UPGRADE.md for the list of breaking changes and additional instructions.