Assert Laravel Package

Technical Evaluation

Architecture fit. beberlei/assert is a deliberately framework-agnostic, dependency-free PHP library that lives at the domain/application boundary. It fits Laravel well as an invariant and precondition layer (DTO constructors, value objects, service-layer guards, shared packages, queued jobs, console commands) and fits poorly as a user-facing form validator. Laravel's Validator owns localization, error bags, request binding, and 422 semantics; Assert owns fast, low-level "this must never be true" checks that throw. Treating these as substitutes rather than complements is the primary architectural failure mode.

Integration feasibility. High. composer require beberlei/assert requires no service provider, config file, facade, or container binding. The library exposes a static API (Assertion::*), a fluent API (Assert::that()), nullOr / all modifiers, and a lazy API that accumulates failures and throws once via verifyNow(). The README explicitly recommends subclassing Assertion in a project namespace to shield against BC breaks and to override the thrown exception — that subclass is the natural seam for a Laravel integration. The one real integration gap is that LazyAssertionException is not a ValidationException; an adapter is required if lazy results should surface as standard 422 responses.

Technical risk.

• License ambiguity. Metadata reports NOASSERTION. Upstream is understood to be BSD-2-Clause, but this must be resolved by legal before adoption; it is a hard gate, not a nice-to-have.
• Maintainership and bus factor. Single-maintainer, long-lived library. The package has been stable, but "stable" here can also mean "low activity." Recent release metadata (2026-06-10) should be verified against the actual Packagist history rather than trusted at face value.
• Metadata inconsistency. Dependents: 0 is implausible given ~2.4k stars and heavy Packagist download volume; treat dependency-graph signals in this evaluation as unreliable and re-derive from Packagist/GitHub directly.
• Exception-driven control flow. Any uncaught AssertionFailedException becomes a 500 in Laravel's handler unless mapped. This is the most likely production incident.
• Static/global surface. Customizing the exception class is a package-level (process-wide) setting; runtime mutation is unsafe under Octane and other long-running workers.
• Testability. Static assertions are awkward to mock; tests must assert on thrown exceptions rather than injected collaborators.
• Validation is not filtering. The library will not sanitize input; teams that conflate the two will ship vulnerabilities.
• PHP compatibility. Supported PHP versions must be checked against the Laravel version in use (L10/L11 imply PHP 8.1/8.2); the badge is not a substitute for reading composer.json.

Key questions.

1. Has legal cleared the license, and what is the actual SPDX identifier upstream?
2. What is the supported PHP matrix, and does it intersect our Laravel upgrade roadmap (next two majors)?
3. Is this for domain invariants, user input validation, or both — and who owns that boundary decision?
4. Do we run Octane/Swoole/RoadRunner, and will any static configuration be mutated at request time?
5. What is our error contract for assertion failures (422 with MessageBag, 400, or domain exception)?
6. If the package goes unmaintained, do we fork, vendor, or replace — and what is the exit cost given the wrapper?
7. Why does the dependency data show zero dependents, and does the real graph change our supply-chain posture?

Integration Approach

Stack fit. Composer-native, PSR-4, zero framework coupling. It installs cleanly into a Laravel app, into first-party packages, and into non-Laravel shared libraries consuming the same domain code — which is the strongest argument for it over Illuminate\Validation in package code. Its near-zero dependency footprint keeps the transitive supply chain thin, a genuine operational benefit in a Laravel app that already carries a large dependency tree.

Migration path. Incremental, boundary-first — never a big-bang replacement of Laravel validation.

1. Create App\Support\Assertion extends \Assert\Assertion to pin messages, override stringify(), and control the exception type.
2. Add an adapter that converts LazyAssertionException into Illuminate\Validation\ValidationException (using getErrorExceptions() to build the MessageBag keyed by property path).
3. Introduce assertions at the innermost boundaries first: value object constructors, DTO hydration, service preconditions.
4. Only then consider Assert for controller-adjacent validation, and only for internal/API endpoints where the error contract is already machine-readable.
5. Leave Form Requests on Laravel's validator where user-facing messages, localization, and old() redisplay matter.

Compatibility. Verify the PHP constraint against the target Laravel version before any code is written. Note that the functional constructors (Assert\that(), lazy()) do not honor an extended Assertion class — standardize on Assert::that() / Assert::lazy() on the subclass, or wrap them in project-local helper functions, otherwise the exception customization silently doesn't apply. Add PHPStan/Psalm rules (or a phpcs forbidden-call sniff) to prevent raw \Assert\Assertion:: usage from leaking outside the wrapper.

Sequencing.

1. License and maintenance due diligence — blocking.
2. Timeboxed spike in one bounded context with the subclass and the ValidationException adapter.
3. Bake in the wrapper, error mapping, and a small set of test helpers (assert-throws utilities) as shared infrastructure.
4. Publish a one-page convention: when to use Assert vs. Laravel Validator.
5. Roll out to domain layer and shared packages; add CI static-analysis enforcement.
6. Re-evaluate after the first Laravel major upgrade to confirm the compatibility assumption held.

Operational Impact

Maintenance. Low ongoing cost: no runtime configuration, no migrations, no service provider, small surface area. The maintenance burden is concentrated in two places — the wrapper (ours, fully controlled) and the upstream dependency (not ours). Because the wrapper is thin and the library is stateless, the eventual "package is abandoned" scenario is a bounded swap rather than a rewrite. That property should be recorded as the explicit mitigation for the bus-factor risk.

Support. No vendor support; community issues only. Internal support load is low but front-loaded: the API is small (~80 assertions, clear naming, decent README), yet the conceptual distinction between invariant assertions and user input validation is the thing engineers get wrong. Budget for a short internal doc and a code-review checklist rather than formal training.

Scaling. Effectively free. Checks are plain function calls with no object instantiation on the static path, making them cheaper than instantiating Laravel validator objects, translators, and rule sets. Negligible memory and CPU impact at any realistic request volume. The scaling caveat is not performance but state: the static exception configuration must be set once at bootstrap, never per-request, or Octane workers will leak configuration across requests.

Failure modes.

• Uncaught assertion → HTTP 500. Highest-probability incident; mitigated by the ValidationException adapter and a handler-level mapping.
• Silent misconfiguration. Functional constructors bypassing the subclass means custom exceptions/messages never fire — failures look correct in tests but produce the wrong contract in production.
• Message-callback opacity. Custom message callbacks receive a parameter array including ::assertion; callbacks that ignore it misreport which assertion failed, degrading debuggability.
• Process-wide exception substitution. Changing the exception class affects every consumer in the process, including third-party libraries that catch AssertionFailedException — a subtle cross-cutting change.
• Upstream BC break. Historically plausible; the subclass wrapper is the containment boundary.
• PHP version drift. A future Laravel upgrade may raise the PHP floor past the library's supported range, forcing a fork.
• False confidence. Teams assuming assertions sanitize input; they do not and are documented as not doing so.

Ramp-up. A mid-level Laravel developer is productive with the static and fluent APIs in well under a day. Establishing the wrapper, the exception adapter, the testing helpers, and the "when to use which validator" convention is a 1–2 day effort for one engineer, and that investment is what makes the rest of the rollout low-risk.