hamcrest/hamcrest-php

★ 7,013PHPAudience · developerComplexity · 1/5Setup · easy

Mindmap

mindmap
  root((hamcrest-php))
    What it does
      Readable test assertions
      Clear failure messages
      Port of Java Hamcrest
    Matcher types
      Array and collection
      String matching
      Number comparisons
      Type and null checks
    Usage
      Works with PHPUnit
      Composer install
      Namespace or global style
    Audience
      PHP test writers
      Backend developers

mindmap root((hamcrest-php)) What it does Readable test assertions Clear failure messages Port of Java Hamcrest Matcher types Array and collection String matching Number comparisons Type and null checks Usage Works with PHPUnit Composer install Namespace or global style Audience PHP test writers Backend developers

Click or tap to explore — scroll the page freely

Things people build with this

USE CASE 1

Replace raw PHPUnit assertEquals calls with readable assertThat expressions that produce better error messages on failure.

USE CASE 2

Write tests that check arrays contain a specific item, have a certain size, or match a pattern in one fluent line.

USE CASE 3

Combine multiple matchers in a single assertion to verify a value satisfies two conditions at once.

USE CASE 4

Add hamcrest-php matchers to a legacy PHPUnit test suite to improve readability without changing existing test logic.

Tech stack

PHPComposer

Getting it running

Difficulty · easy Time to first run · 30min

Global shorthand functions require an explicit registration call before they are available in tests.

License details are not described in the explanation.

In plain English

Hamcrest-PHP is a library for PHP developers who write automated tests. Its job is to give you a readable way to describe what a value should look like before you check it. Instead of writing a raw comparison in your test, you write something like "assertThat($result, equalTo(true))" or "assertThat($list, hasItemInArray(4))", and the library checks whether the value matches that description and produces a clear error message when it does not. The library is a direct port of Hamcrest, which originally came from the Java world and has since been translated into many languages. This is the official PHP version. The translation is fairly literal, though a handful of Java features that do not exist in PHP were left out, and a few method names were adjusted to avoid conflicts with PHP reserved words. For example, the Java method called "and" becomes "andAlso" here because "and" is a keyword in PHP. The matchers cover a wide range of situations. You can check arrays for specific values, keys, sizes, or ordering. You can check whether a variable is null, what type it is, or whether it is an instance of a particular class. There are string matchers for checking substrings, case-insensitive equality, and pattern matching. Number matchers handle greater-than, less-than, and close-to comparisons. You can also combine matchers, so a single assertion can check that a value satisfies two conditions at once, or that it satisfies at least one of several conditions. Installation is done through Composer, which is the standard PHP dependency manager. After installing, you can call matchers either through a namespaced class or through shorter global proxy functions. The global functions need to be registered explicitly with one setup call before they are available. The library is commonly used alongside PHPUnit, the most widely used PHP testing framework. It slots in as an alternative to PHPUnit's own assertion style, and many PHP projects pull it in as a dependency simply because other testing tools require it.

Copy-paste prompts

Prompt 1

I am writing PHPUnit tests for a PHP API. Rewrite these assertEquals and assertContains calls using hamcrest-php assertThat matchers to make them more readable.

Prompt 2

Using hamcrest-php, write test assertions that check a returned array has exactly 3 items, contains the string admin, and each item is an instance of UserDTO.

Prompt 3

Show me how to register hamcrest-php global functions so I can call equalTo() and hasItem() without a namespace prefix in my PHPUnit tests.

Prompt 4

I need to check that a number is between 10 and 20 in a hamcrest-php assertion. Show me the correct matcher combination using greaterThan and lessThan.

Open on GitHub → Explain another repo

← hamcrest on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.