Assert Laravel Package

Product Decisions This Supports

• Build vs. buy vs. vendor: Decides whether contract-style assertions (preconditions, postconditions, invariants) become a shared engineering standard or stay as ad-hoc if (...) { throw new InvalidArgumentException(...) } blocks scattered across services. At ~100 LOC, "vendor into an internal app/Support package" is a legitimate third option worth scoring against adoption.
• Coding standards / definition of done: If adopted, it supports a concrete, reviewable rule — public service methods assert their preconditions at the boundary — which is easier to enforce in code review than a vague "validate your inputs" guideline.
• Library and SDK hardening: Relevant if your roadmap includes publishing internal PHP packages consumed by other teams. Fail-fast parameter assertions on a public API convert integration bugs into immediate, attributable exceptions instead of corrupt rows discovered weeks later.
• Incident and MTTR reduction: Assertions at the entry point of jobs, queue consumers, and domain services move failure detection upstream, which shortens the distance between cause and stack trace. This is a reliability argument, not a feature argument, so it belongs in the engineering-health budget rather than the customer-facing roadmap.
• Use cases that actually fit: MediaWiki-adjacent integrations, PHP libraries with internal callers, domain-layer invariant checks, and validating payloads from trusted internal producers (other services, your own jobs). Note explicitly what it does not cover: user-supplied input, form/request validation, and anything that needs localized, field-level error messages.
• Roadmap positioning: Treat this as utility-tier infrastructure. It is not a differentiator, it should not anchor a platform bet, and no customer-facing commitment should depend on it.

When to Consider This Package

Adopt when most of the following hold:

• You are writing a PHP library or SDK with a public API where callers are other engineers, and you want programmer errors to fail loudly and immediately.
• You specifically want the contract vocabulary (precondition / postcondition / invariant / parameter type) rather than a generic validator — the semantics are the product here, not the assertions themselves.
• You want assertion failures to be distinguishable from user-facing validation errors in logs and alerting, via a dedicated exception type.
• You value a minimal footprint: MIT-licensed, no transitive dependency tree, stable namespace, maintained under the Wikimedia umbrella.
• Your team accepts the contribution model — this is a read-only mirror of a Gerrit repository. Patches go upstream via Gerrit/Phabricator; there are no GitHub pull requests and no GitHub issue tracker. Confirm your security and dependency-review process can handle a repo whose activity graph looks dormant.

Look elsewhere when:

• You are validating untrusted input. Use Laravel's Validator, Symfony Validator, or Respect/Validation. Assertions throw on programmer error; they do not produce user-comprehensible messages, and using them for request validation is a category error that will surface as 500s instead of 422s.
• You want static analysis to understand the assertions. webmozart/assert is the better-known choice and pairs with PHPStan/Psalm assertion annotations; this package gives you runtime checks only.
• You are already on Laravel and the need is a handful of call sites. throw_if, throw_unless, abort_if, and a small custom exception hierarchy cover most of it with zero new dependencies.
• You need active community support — 9 stars, 0 dependents, and a mirror-only repository are weak signals for ecosystem momentum and third-party security response. Nothing here suggests abandonment, but nothing suggests a thriving support surface either.
• You need localized or structured error payloads, or assertions that degrade gracefully in production. This package throws; that is the whole design.

How to Pitch It (Stakeholders)

To executives: This is a tiny, MIT-licensed PHP utility that lets engineers declare and enforce the assumptions their code depends on, so bugs surface at the boundary instead of deep in the data layer. Cost of adoption is near zero and the license risk is nil. The honest caveat is that it carries no strategic weight: low adoption, no dependents, and a contribution workflow that runs through Wikimedia's Gerrit rather than GitHub. Recommendation: adopt it narrowly, behind an internal wrapper, if the team wants contract-style assertions as a standard — and do not let any roadmap item depend on it.

To engineering: It gives you explicit, greppable contract semantics — precondition, postcondition, parameter type, invariant — and a distinct exception type, which makes "this is a bug in the caller" obvious in logs. The trade-offs are real: it overlaps with Laravel's throw_if/throw_unless helpers and with webmozart/assert, it does nothing for static analysis, and it is the wrong tool for user input. Suggested path is a one-service spike, wrapped so the dependency stays swappable, judged on whether the contract vocabulary actually changes how the team reviews code — not on line count saved.