Assert Laravel Package

Getting Started

Start by installing the package as a development dependency:

composer require --dev "bovigo/assert": "^8.1"

💡 Requirement: Requires PHP 8.3+.

Begin with simple assertions using the functional API. Import core functions in your test files:

use function bovigo\assert\assertThat;
use function bovigo\assert\predicate\equals;
use function bovigo\assert\predicate\isInstanceOf;

assertThat($result, equals(42));
assertThat($object, isInstanceOf(SomeClass::class));

The assertThat() function is your primary entry point—combine it with predicate functions (e.g., equals(), isEmpty(), matches()) to validate values. Failures produce clear, PHPUnit-integrated error messages.

Implementation Patterns

• Predicate Composition: Chain predicates using logical combinators (and(), or(), not()) for complex validations:

  assertThat($value, isString()->and(matches('/^[A-Z]/')));
  

• Contextual Aliases: Use type-specific shorthand predicates (e.g., isString(), isArray(), isObject()) instead of generic isOfType() to avoid typos and improve readability.
• Assertion Descriptions: Add human-readable failure context:

  assertThat($config, isNotEmpty(), 'Config must not be empty after bootstrapping');
  

• PHPUnit Integration: Leverages AssertionFailure extending \PHPUnit\Framework\AssertionFailedError—no extra setup needed. Works seamlessly with phpunit/phpunit and tools like phpunit-gtk.
• Test Data Validation: Validate JSON responses, arrays, and file paths using contains(), hasKey(), isExistingFile(), etc.:

  assertThat($json, isString()->and(matches('/^{"status":"ok"}/')));
  assertThat($outputDir, isExistingDirectory());
  

Gotchas and Tips

• String Comparison: contains() is case-sensitive for strings. Use equalsIgnoreCase() (if available) or convert case explicitly—note: no equalsIgnoreCase() predicate exists in v8.1.
• Traversable Handling: isOfSize() uses iterator_count() on a clone of Traversable—safe for iterators that move internal pointers, but ensure your data source supports cloning.
• Emptyness Definition: isEmpty() follows PHP’s empty() logic and Countable::count() === 0. Beware: 0, '0', and false are considered empty—use isFalse() for explicit boolean checks.
• Delta for Floats: Always use ->withDelta() when comparing floats:

  assertThat($result, equals(3.14)->withDelta(0.01));
  

• Namespace Clashes: Avoid importing assert() (PHP’s built-in) alongside assertThat()—use use function bovigo\assert\assertThat as ah; or qualify explicitly to prevent conflicts.
• Late Release Activity: Despite the 2025-11-30 release date (likely a typo—verify actual version), check changelog for current features. Prioritize predicates like matchesFormat() for structured string validation (e.g., logging, dates).