Weave Code
Hamcrest Php Laravel Package
hamcrest/hamcrest-php
Official PHP port of Hamcrest, the matching library originally written for Java. Provides readable matchers like equalTo, containsString and is for expressive assertions in PHP tests, with global proxy functions and MatcherAssert support.
PHP Hamcrest implementation [Official]
Frequently asked questions about Hamcrest Php
- How do I install hamcrest/hamcrest-php in a Laravel application?
- Run composer require --dev hamcrest/hamcrest-php. There is no service provider, config file, or Artisan command, so nothing needs to be published or registered in Laravel. You can then call \Hamcrest\MatcherAssert::assertThat() directly, or opt into the global proxy functions if you prefer that style. Keep it in require-dev so it never ships to production.
- Which Laravel and PHP versions does hamcrest-php support?
- hamcrest-php is framework-agnostic and depends on no Laravel or PHPUnit internals, so it generally works across Laravel 8 through 12 and PHPUnit 9, 10, 11, and 12. The exact PHP constraint is declared in the composer.json of each tagged release, so check that against your application's PHP version before installing. Because it is test-only, Laravel major upgrades rarely force a matching Hamcrest upgrade.
- Is hamcrest-php a replacement for PHPUnit's built-in assertions?
- No. Hamcrest is a composable matcher DSL, not a full assertion layer, so assertSame, assertCount, and Laravel's assertDatabaseHas remain the right tools for simple single-value checks. Hamcrest pays off when you need to describe a complex shape in one readable statement, using allOf(), anyOf(), or the array and traversable matchers. Use it where expressiveness compounds rather than replacing your assertion layer wholesale.
- Why does PHPUnit mark my Hamcrest test as risky for performing no assertions?
- Hamcrest tracks its own assertion count, and PHPUnit does not automatically see it, so tests can be flagged with This test did not perform any assertions. The documented fix is to call MatcherAssert::addToAssertionCount(MatcherAssert::getCount()) and then MatcherAssert::resetCount() in your test case tearDown(). Centralize that in a shared base TestCase instead of copy-pasting it into every test class.
- How do I enable the global assertThat() and is() functions in hamcrest-php?
- Call \Hamcrest\Util::registerGlobalFunctions() once during test bootstrap, for example in a bootstrap file or your base TestCase. That defines around 100 global functions such as assertThat(), is(), equalTo(), and containsString(). Prefer the class-based Matchers plus MatcherAssert API for IDE discoverability and static analysis, and treat the globals as a deliberate, documented opt-in.
- How do I combine matchers with both(), either(), allOf(), and anyOf()?
- Use both(x)->andAlso(y) and either(x)->orElse(y) for two-matcher chains, and allOf(...) or anyOf(...) when you have a list. These read left to right and produce failure messages that list each expectation separately. You can nest them with the array and traversable matchers to assert an entire structure in a single statement.
- How do I write a custom matcher in hamcrest-php?
- Subclass one of the base matcher types and implement matches() plus describeTo(), then expose it through a static factory on your own matchers class, for example isPending() or hasValidLineItems(). This extension pattern is what turns Hamcrest from a convenience into test-suite architecture. Be aware that version 3.0 adds native type hints to the base classes, so custom matchers written against 2.x loose signatures may need updating.
- What is the license of hamcrest/hamcrest-php?
- The Composer metadata reports NOASSERTION, while the Hamcrest family is historically BSD-3-Clause. Do not rely on package metadata for compliance sign-off; read the LICENSE file in the tagged release you actually install. For teams with license scanning, close this item before adopting the package broadly.
- Should hamcrest/hamcrest-php be in require-dev or require?
- It belongs in require-dev. It is an assertion DSL with no runtime services, no I/O, and no framework coupling, so it should never appear in a production image built with composer install --no-dev. Keeping it dev-only also means a bad upgrade can only affect CI and developer experience, not end users.
- What changed in hamcrest-php 3.0.0 and is it a breaking change?
- Yes. Version 3.0.0 adds native type hints to all classes, which is a genuine BC break for anyone who subclassed matcher base classes or wrote custom matchers with loose signatures. If you use that extension pattern, pin deliberately and validate your custom matchers before bumping. Also verify the git tag against the changelog text, since the 3.0.0 notes reference an older 2.x comparison range.
Weaver
How can I help you explore Laravel packages today?