Download the PHP package chubbyphp/chubbyphp-mock without Composer

chubbyphp-mock

Description

A strict mocking solution. It works with any testing framework; the examples below use PHPUnit.

A mock is defined as an ordered list of expected method calls. Every call made on the mock must match the next expectation in that list by method name and parameters, otherwise an exception is thrown. Missing calls are detected as well: a mock that still has unconsumed expectations when it is destroyed throws too.

Every exception carries a JSON message with the mocked class, the position of the failing call, the actual and expected values, and the file and line where the mock was created.

Requirements

• php: ^8.3

Installation

Through Composer as chubbyphp/chubbyphp-mock.

Usage

Create a MockObjectBuilder and pass it the class or interface to mock together with the list of expected calls. Each expected call is an instance of one of the following mock methods:

Parameters are compared with === by default. Pass $strict = false to compare by value instead; arrays are then compared entry by entry and objects property by property (or via __serialize / __sleep when available).

Use WithCallback whenever a parameter cannot be known in advance (for example a generated id or a timestamp) or when you want to assert on it inside the callback.

Other testing frameworks

chubbyphp-mock has no dependency on PHPUnit. A host framework only needs to provide a place to build the mocks, a way to assert inside a WithCallback, and a test scope that ends when the test ends.

Unconsumed expectations are reported from the mock's destructor. Keep mocks in local variables of the test and do not store them in long-lived properties, statics or shared setup, otherwise the check is delayed and the failure is attributed to the wrong place.

The examples below use the same PingRequestHandler scenario as the PHPUnit example above.

Pest

expect() replaces the PHPUnit assertion inside the callback, everything else stays the same.

Codeception

Codeception unit tests are PHPUnit test cases with a different base class, so the PHPUnit example works unchanged.

phpspec

phpspec injects lenient, unordered Prophecy collaborators by default. Building the mocks with chubbyphp-mock instead gives the spec a strict, ordered script of expected calls.

FAQ

Howto mock final classes/methods

Use the third party package dg/bypass-finals.

This does not remove the final keyword from internal (PHP core or extension) classes.

What Cannot Be Mocked

• Static methods: They are declared on the mock but throw when called.

• Properties: Only method calls are intercepted.

• __construct and __destruct: The mock defines its own constructor and destructor.

• Internal final classes or methods: Even with dg/bypass-finals, final internal classes or methods cannot be mocked.

• Poorly built extension classes: Some older PHP extensions declare classes that cannot be fully reverse-engineered via reflection. Those classes are not mockable.

Special Handling

• \Traversable and interfaces extending it: PHP does not allow a userland class to implement \Traversable directly; it must implement \Iterator or \IteratorAggregate instead. The generated mock therefore additionally implements \IteratorAggregate and, if the mocked type does not declare it, a getIterator() method. That method behaves like any other mocked method and needs a matching expectation when called.

Please report if you find other restrictions / bugs.

Upgrade

Upgrade from 1.x

Copyright

2026 Dominik Zogg