Assert Laravel Package

Getting Started

Install with composer require webmozart/assert, then import use Webmozart\Assert\Assert;. Begin by validating method inputs—especially in value objects, DTOs, or domain services—to enforce type and value constraints early. Start with basic type checks like Assert::string($name) or Assert::integer($id), and add context with custom messages (e.g., 'User ID must be a positive integer. Got: %s'). The first use case is usually constructor validation in immutable objects to prevent invalid states.

Implementation Patterns

• Value Objects & DTOs: Use assertions in constructors to guarantee invariants (e.g., Assert::email($email), Assert::range($age, 0, 120)).
• Service Layer Guard Clauses: Replace verbose if (...) throw ... blocks with concise Assert::notNull($entity), Assert::greaterThan($quantity, 0).
• API Input Validation: Combine with PSR-7/15 to validate request parameters before processing (e.g., Assert::uuid($id), Assert::ip($clientIp)).
• Custom Assertion Classes: Extend Assert or create static helpers for domain-specific rules (e.g., EmployeeAssert::validTaxId()).
• Type Coercion Safety: Use integerish(), scalar(), or isArrayAccessible() when accepting loosely-typed input (e.g., from JSON or legacy systems).

Gotchas and Tips

• Exceptions are thrown, not returned: Assertions always throw InvalidArgumentException, so ensure they’re used where exceptions are acceptable (e.g., not in high-throughput loops without profiling).
• Placeholder order matters: %s = the tested value; additional args use %2$s, %3$s, etc. Misordering (e.g., mixing up min/max in lengthBetween) breaks custom messages.
• Avoid == comparisons: Use same()/notSame() for strict identity (especially booleans and 0 vs '0')—eq() can be misleading.
• String assertions require type safety first: Always call string() before length(), regex(), etc.—chaining string()->length() is common.
• Custom messages override defaults: Provide meaningful context—e.g., 'Invoice number must be non-empty string' instead of just 'Invalid'.
• Performance note: Assertions are optimized for development/testing; consider wrapping heavy checks (e.g., file(), isStatic()) behind assert_options(ASSERT_ACTIVE, true) in production if used heavily.
• Static analysis synergy: Works well with PHPStan/PSalm—no special config needed, but @phpstan-ignore-line may help for intentionally-loose cases.