Assert Laravel Package

Product Decisions This Supports

• Input Validation in APIs/CLIs: Enforce strict data contracts for Laravel APIs (e.g., REST, GraphQL) or CLI commands, reducing runtime errors and improving developer experience.
• Domain-Driven Design (DDD): Validate domain objects (e.g., User, Order) during construction to ensure invariants are met (e.g., Assert::positiveInteger($age)).
• Build vs. Buy: Avoid reinventing validation logic (e.g., custom if (!is_int($id)) throw new Exception()) by adopting a battle-tested, opinionated library.
• Error Handling: Replace generic exceptions with actionable error messages (e.g., "The email must be a valid address. Got: invalid@example"), improving debugging.
• Testing: Use assertions in unit tests to validate method inputs/outputs (e.g., Assert::isInstanceOf($result, User::class)).
• Migration from beberlei/assert: Standardize error messages and placeholder consistency across the codebase if using the older package.
• Security: Prevent edge cases (e.g., Assert::directory($uploadPath)) that could lead to runtime failures or security vulnerabilities.

When to Consider This Package

• Avoid if:
  • Your team prefers framework-native validation (e.g., Laravel’s Validator for HTTP requests) and doesn’t need granular, method-level assertions.
  • You’re building a high-performance system where assertion overhead is critical (though this package is optimized for efficiency).
  • Your use case requires custom validation logic beyond type/comparison checks (e.g., business rules like "discount must be ≤ 50%").
  • You’re using Symfony’s Validator Component and already have a consistent validation strategy.
• Look elsewhere if:
  • You need asynchronous validation (e.g., for background jobs).
  • Your project uses TypeScript/Python/Java, and you want language-specific validation.
  • You require database-backed validation (e.g., checking if a username exists in the DB).

How to Pitch It (Stakeholders)

For Executives:

"This package lets us fail fast and fail loudly by validating inputs/outputs at the method level—catching bugs early and reducing production errors. For example, instead of a cryptic TypeError in an API, we’ll get clear messages like 'The user ID must be an integer. Got: "abc123"'. This improves developer productivity and user experience. It’s a lightweight, MIT-licensed solution with 7.6K stars, used by teams building robust PHP applications."

For Engineers:

*"webmozart/assert gives us:

• Consistent error messages (unlike beberlei/assert, placeholders are standardized).
• Granular validation for domain objects, APIs, and CLI tools (e.g., Assert::email($email)).
• Zero boilerplate: Replace verbose if (!is_int($id)) throw new Exception() with Assert::integer($id).
• Composability: Chain assertions (e.g., Assert::integer($age)->greaterThan($age, 0)).
• Performance: Optimized for speed, with minimal runtime overhead.

Use cases:

• Validate constructor arguments in domain models.
• Sanitize API request payloads before processing.
• Enforce invariants in business logic (e.g., Assert::range($discount, 0, 100)).
• Replace if/throw spaghetti with readable assertions.

Migration path: Start with critical paths (e.g., user creation) and expand. Works alongside Laravel’s Validator for HTTP requests."*