Assert Laravel Package

Product Decisions This Supports

• Narrow build-vs-buy call for XML/SAML datatype validation. The package’s genuinely distinctive value is its extra assertion set — validURI, validURL, validURN, validNCName, validQName, validDuration, validNMToken(s), validHexBinary, stringPlausibleBase64, validDateTime. If our roadmap includes SAML2, XML signature/canonicalization, or any protocol where schema datatypes must be enforced, this is a legitimate “buy/borrow” rather than hand-rolling regexes we’d get wrong.
• Domain-accurate failure semantics. The core design — pass an optional Throwable per assertion, falling back to an AssertionFailedException (an UnexpectedValueException, not InvalidArgumentException) — supports cleaner error contracts: mapped API status codes, typed exceptions for retry/fallback logic, and less exception-string matching in observability. This is a decision about how failures are surfaced, which affects support cost and incident triage.
• Guard clauses in service/integration layers, not user-facing validation. Where we want to treat “this should be impossible” as a hard stop inside our own code (constructors, adapter boundaries, config hydration, message/response builders), an assertion library is the right tool. It is explicitly not a replacement for Laravel’s Validator or Form Requests, which own user input, localization, and error shaping.
• Scope-limiting decision. This is a single-vendor, low-adoption utility (7 stars, 0 tracked dependents). The responsible product framing is: do not make it a platform-wide standard; allow it as a contained dependency in the one area that needs XML-datatype checks, or avoid it entirely and vendor the few assertions we actually use.
• Rejecting the “modernization” narrative. The surrounding material suggests enum assertions, Assert::extend, and Assert::custom are features of this package. The README does not document them; the documented additions are the XML/SAML datatype checks above plus a custom-exception mechanism. Any roadmap item premised on “this package gives us PHP 8.1 enum validation” is built on a false premise and should not drive adoption.
• Licensing decision, which is a PM decision. LGPL-2.1 is fine for internal use and dynamic linking, but it raises questions for redistributed/proprietary distributions and for legal review in regulated customers. That review is cheaper to run before it appears in twenty composer.json files.

When to Consider This Package

Adopt (narrowly) if:

• You are already in the SimpleSAMLphp ecosystem, or building/holding SAML2 or XML-heavy integrations where xs:NCName, xs:QName, xs:duration, xs:hexBinary, and base64/URI checks are real requirements.
• You need per-assertion custom exception classes to drive differentiated error handling or HTTP mapping, and you don’t want to wrap webmozart/assert yourself.
• You accept LGPL-2.1 and a single-maintainer bus factor, and you’re willing to pin the version and treat it as roughly vendored code.
• It arrives as a transitive dependency of SimpleSAMLphp rather than as a deliberate new commitment.

Look elsewhere if:

• The goal is Laravel request validation, authorization, or user-facing error messages — use Laravel’s Validator/Form Requests; that is its job.
• The goal is PHP 8.1+ enum validation. Use native enum types and backed-enum casting, or plain webmozart/assert / Symfony Validator. Do not select this package for that.
• You need broad domain rules (dates, currency, national IDs, uniqueness) — Symfony Validator, Respect/Validation, or Laravel rules are far better supported.
• You need long-term vendor support, a security response process, or a documented API-stability commitment. Seven stars and zero dependents is not a support posture.
• You are shipping closed-source binaries or have copyleft-sensitive legal constraints.
• You’re considering it because it looks like a “drop-in” upgrade — it is a fork of webmozart/assert, so adopting it means being deliberate about which assertion library owns a given call site, and it shouldn’t sit alongside it by accident.

Practical caveat for the team: the package is small enough that “vendor the six assertions we use” is a credible alternative and removes the licensing, bus-factor, and dependency-conflict risks entirely. That option should be on the table for any decision review.

How to Pitch It (Stakeholders)

Executive summary: This is a small, low-risk-per-line, low-strategic-value utility library. It does one thing well — it lets you assert a value and choose exactly which exception is thrown when the assertion fails — and adds a set of strict XML/SAML datatype checks. It is relevant to us only if we build SAML2 or XML protocol integrations. It is not a validation framework, not a Laravel component, and not a modernization play; recommending it broadly would add licensing review and maintenance exposure for little gain. Recommendation: no org-wide adoption; evaluate as a contained dependency in the SAML/XML workstream, or reproduce the handful of XML assertions internally.

For engineering: The API is a static facade over webmozart/assert with an extra trailing ?Throwable $exception parameter per assertion; on failure it throws the supplied throwable, otherwise a custom AssertionFailedException extending UnexpectedValueException. Use it for invariant/contract checks at boundaries (constructors, adapters, config hydration, XML builders), where throwing a specific domain exception is genuinely useful. Do not use it for user input validation, do not use it in hot loops, and do not assume enum or extend/custom helpers exist — verify against the installed version before designing around them. Pin the version, note the LGPL-2.1 obligation, and add a short ADR recording why the dependency exists so it doesn’t silently spread to unrelated services.