Weave Code
Hamcrest Php Laravel Package
hamcrest/hamcrest-php
Official PHP port of Hamcrest matchers for expressive assertions in tests. Use MatcherAssert::assertThat() or convenient global functions (assertThat, equalTo, is, both/andAlso, either/orElse) to build readable, composable matchers with PHP-friendly typing.
PHP Hamcrest implementation [Official]
Frequently asked questions about Hamcrest Php
- How does Hamcrest-PHP improve Laravel test readability compared to native PHPUnit assertions?
- Hamcrest-PHP replaces verbose assertions like `assertEquals($user->email, 'test@example.com')` with fluent syntax like `assertThat($user, hasProperty('email', equalTo('test@example.com')))`. This mirrors Laravel’s expressive style (e.g., Eloquent queries) and reduces boilerplate, especially for complex validations. The composable matchers (e.g., `allOf()`, `either()`) also make multi-condition checks more intuitive.
- Can I use Hamcrest-PHP with Laravel’s default testing stack (PHPUnit) without extra setup?
- Yes. Hamcrest-PHP integrates seamlessly with Laravel’s PHPUnit setup—no additional configuration is needed. Just require the package via Composer (`hamcrest/hamcrest-php`) and use `MatcherAssert::assertThat()` or global functions like `assertThat()`, `equalTo()`, or `is()`. It works alongside Laravel’s built-in assertions (e.g., `assertDatabaseHas()`) without conflicts.
- Does Hamcrest-PHP support Laravel’s PHP 8.1+ requirements and typed properties?
- Absolutely. Hamcrest-PHP is fully compatible with PHP 8.1+ and Laravel’s typed properties. Version 2.1.1+ includes PHP 8.4 support and leverages nullable return types, reducing runtime assertion errors. For example, you can validate typed Eloquent models with `assertThat($user, hasProperty('created_at', anInstanceOf(Carbon::class)))`.
- Are there Laravel-specific matchers for common use cases like Eloquent models or Carbon dates?
- Hamcrest-PHP doesn’t include Laravel-specific matchers out of the box, but you can create custom ones. For example, to validate Carbon dates, build a matcher like `hasDateBetween($start, $end)`. For Eloquent models, use `hasKeyInArray()` for collections or extend the library with matchers like `hasRelationship('posts', arrayWithSize(3))`. The README provides patterns for this.
- Will Hamcrest-PHP slow down my Laravel tests, especially in high-frequency scenarios?
- Composing complex matchers (e.g., `allOf(hasKey()->andAlso(isArray()))`) introduces *minor* runtime overhead, but benchmarks show it’s negligible for most Laravel tests. For performance-critical tests (e.g., load tests), stick to native PHPUnit assertions. Hamcrest’s sweet spot is *readability*—use it for complex validations where its composability shines.
- How does Hamcrest-PHP work with PestPHP, which has its own fluent assertions?
- Hamcrest-PHP supports PestPHP’s syntax (e.g., `expect($user)->toHaveKey('email')`) but leans toward `assertThat()` style. For teams using Pest, Hamcrest’s matchers can still replace Pest’s `expect()` for complex logic, though the syntax may feel verbose. Example: `expect($response->json())->toMatchObject(hasKey('data', arrayContaining([...])))`.
- Can I validate Livewire/Inertia component props or API responses with Hamcrest-PHP?
- Yes. Use Hamcrest to validate Livewire props (e.g., `assertThat($component->props, hasKey('user', anInstanceOf(User::class)))`) or API responses (e.g., `assertThat($response->json(), hasKey('data', arrayWithSize(1)))`). For JSON APIs, matchers like `hasKey()`, `arrayContaining()`, or `equalToJson()` (via custom matchers) are ideal. XML responses can use `hasXPath()` for XPath queries.
- What’s the best way to migrate from PHPUnit’s native assertions to Hamcrest-PHP in Laravel?
- Start with a migration guide comparing side-by-side examples. For instance, replace `assertEquals($user->email, 'test@example.com')` with `assertThat($user, hasProperty('email', equalTo('test@example.com')))`. Focus on complex validations first (e.g., nested arrays, multi-condition checks) to justify the switch. Use a style guide to enforce Hamcrest for composable logic only.
- Are there alternatives to Hamcrest-PHP for expressive assertions in Laravel?
- Yes. For simpler cases, PHPUnit’s native assertions or PestPHP’s `expect()` suffice. For advanced composability, consider **PHP-Mock** (for mocking) or **Laravel’s `assertDatabaseHas()`** (for database tests). However, Hamcrest-PHP stands out for its *language-agnostic* matcher library (e.g., `both()`, `either()`) and PHP 8+ type safety, making it unique for Laravel’s expressive testing needs.
- How do I handle unsupported Laravel features like Carbon dates or Eloquent relationships with Hamcrest-PHP?
- Extend Hamcrest-PHP with custom matchers. For Carbon dates, create a matcher like `hasDateBetween($start, $end)` by subclassing `BaseMatcher`. For Eloquent relationships, use `hasKey()` combined with `anInstanceOf(Model::class)` or build a reusable matcher like `hasRelationship('posts', arrayWithSize(3))`. The GitHub repo includes examples for creating custom matchers.
Weaver
How can I help you explore Laravel packages today?