createStub()

Creates a test stub for the specified interface (or extendable class).

$stub = $this->createStub(InterfaceName::class);

All methods of the original type are replaced with an implementation that returns an automatically generated value that satisfies the method’s return type declaration without calling the original method. These methods are referred to as “doubled methods” or “stubbed methods”.

Doubled methods can be configured using the methods described below.

createStubForIntersectionOfInterfaces()

Creates a test stub for an intersection of interfaces.

$stub = $this->createStubForIntersectionOfInterfaces(
    [InterfaceA::class, InterfaceB::class]
);

This is useful when you need to replace an object that implements multiple interfaces.

createConfiguredStub()

Creates a test stub with methods already configured to return specific values.

$stub = $this->createConfiguredStub(
    InterfaceName::class,
    [
        'methodOne' => 'return value one',
        'methodTwo' => 'return value two',
    ]
);

// $stub->methodOne() will return "return value one"
// $stub->methodTwo() will return "return value two"

This is a convenience method for simple cases.

getStubBuilder()

The getStubBuilder() method provides a fluent API for creating test stubs. It should only be used for edge cases that are not supported by the simpler createStub() or createStubForIntersectionOfInterfaces() methods.

Use getStubBuilder() only when you need advanced configuration such as:

• Specifying a custom class name for the test stub

• Enabling the original constructor with custom arguments

• Creating partial test stubs (only doubling specific methods)

• Controlling clone behavior

• Disabling automatic return value generation

The getStubBuilder(string $type) method returns an object that can be used to configure and subsequently perform the creation of a test stub for the specified interface (or extendable class).

The object returned by getStubBuilder() has, among other methods, a method named getStub(). This creates and returns the configured test stub. This method must be called last in the fluent API’s method call chain.

The following methods can be used on the object returned by getStubBuilder() to configure the creation of the test stub:

setStubClassName(string $name)

Specifies a custom class name for the generated test stub class.

onlyMethods(array $methods)

Specifies which methods should be doubled (stubbed). Methods not in this list will retain their original implementation, creating a partial double.

setConstructorArgs(array $arguments)

Specifies the arguments to pass to the constructor when enableOriginalConstructor() (see below) is used.

disableOriginalConstructor()

This disables the invocation of the original constructor. This is useful when you want to create a partial double and the constructor either has side effects or requires dependencies that you do not want to provide.

enableOriginalConstructor()

Enables the invocation of the original constructor. Use this with setConstructorArgs() (see above) to pass required arguments.

disableOriginalClone()

Disables the invocation of the original __clone() method when the test stub is cloned.

enableOriginalClone()

Enables the invocation of the original __clone() method when the test stub is cloned.

enableAutoReturnValueGeneration()

Enables automatic generation of return values for doubled methods that do not have explicit return value configuration.

disableAutoReturnValueGeneration()

Disables automatic generation of return values. When disabled, stubbed methods without explicit configuration will return null or throw an exception depending on the declared return type.

willReturn()

Configures a method to return a specific value.

$stub = $this->createStub(InterfaceName::class);

$stub
    ->method('doSomething')
    ->willReturn('result');

// $stub->doSomething() always returns "result"

The return value must be compatible with the method’s return type declaration.

willReturn() can be used to configure a method to return different values on consecutive calls:

$stub = $this->createStub(InterfaceName::class);

$stub
    ->method('doSomething')
    ->willReturn('first result', 'second result');

// $stub->doSomething() returns "first result" when it is invoked for the first time
// $stub->doSomething() returns "second result" when it is invoked for the second time
// $stub->doSomething() will trigger an error when it is invoked more than twice

If a method is configured to return different values on consecutive calls, it can only be invoked a number of times equivalent to the number of configured return values.

willReturnSelf()

Configures a method to return the test stub object itself.

$stub = $this->createStub(InterfaceName::class);

$stub
    ->method('doSomething')
    ->willReturnSelf();

This is useful for testing fluent interfaces.

willReturnArgument()

Configures a method to return one of its arguments.

$stub = $this->createStub(InterfaceName::class);

$stub
    ->method('doSomething')
    ->willReturnArgument(0);

// $stub->doSomething('some value') returns 'some value'

The argument index is zero-based.

willReturnMap()

Configures a method to return different values based on the arguments it receives.

$stub = $this->createStub(InterfaceName::class);

$stub
    ->method('doSomething')
    ->willReturnMap([
        ['foo', 'bar', 'baz'],
        ['one', 'two', 'three'],
    ]);

// $stub->doSomething('foo', 'bar') returns 'baz'
// $stub->doSomething('one', 'two') returns 'three'

Each inner array contains the method arguments followed by the return value.

willReturnCallback()

Configures a method to return the result of a callback function.

$stub = $this->createStub(InterfaceName::class);

$stub
    ->method('doSomething')
    ->willReturnCallback(
        static fn(string $input) => strtoupper($input)
    );

// $stub->doSomething('string') returns 'STRING'

The callback receives the method arguments and can implement complex logic.

Get-Hooked Properties

PHP 8.4 introduced the language feature of get-hooked properties.

The example below shows an interface that declares a get-hooked property:

<?php declare(strict_types=1);
interface InterfaceWithGetHookedProperty
{
    public string $property { get; }
}

The behaviour of the get-hooked property property can be configured like so:

<?php declare(strict_types=1);
use PHPUnit\Framework\MockObject\Runtime\PropertyHook;
use PHPUnit\Framework\TestCase;

final class ExampleTest extends TestCase
{
    public function testExample(): void
    {
        $stub = $this->createStub(
            InterfaceWithHookedProperty::class,
        );

        $stub
            ->method(PropertyHook::get('property'))
            ->willReturn('value');

        $this->assertSame('value', $stub->property);
    }
}

In the example shown above, PropertyHook::get('property') to specify that we want to configure the behaviour of the method that is called when the property named property is accessed for reading.

willThrowException()

Configures a method to throw an exception instead of returning a value.

$stub = $this->createStub(InterfaceName::class);

$stub
    ->method('doSomething')
    ->willThrowException(new Exception);

// $stub->doSomething() throws the configured exception

createMock()

Creates a mock object for the specified interface (or extendable class).

$mock = $this->createMock(InterfaceName::class);

All methods can be configured with return values and expectations.

createMockForIntersectionOfInterfaces()

Creates a mock object for an intersection of interfaces.

$mock = $this->createMockForIntersectionOfInterfaces(
    [InterfaceA::class, InterfaceB::class]
);

This is useful when you need to replace an object that implements multiple interfaces.

createConfiguredMock()

Creates a mock object with methods already configured to return specific values.

$mock = $this->createConfiguredMock(
    InterfaceName::class,
    [
        'methodOne' => 'return value one',
        'methodTwo' => 'return value two',
    ]
);

// $mock->methodOne() will return "return value one"
// $mock->methodTwo() will return "return value two"

This is a convenience method for simple cases.

getMockBuilder()

The getMockBuilder() method provides a fluent API for creating mock objects. It should only be used for edge cases that are not supported by the simpler createMock() or createMockForIntersectionOfInterfaces() methods.

The documentation and recommendations for getStubBuilder() (see above) also apply to getMockBuilder(), with two differences:

• The method for specifying a custom class name for the generated mock object class is setMockClassName()

• The name of the method that must be called last in the fluent API’s method call chain is getMock()

once()

The method must be called exactly once.

$mock = $this->createMock(InterfaceName::class);

$mock
    ->expects($this->once())
    ->method('doSomething');

once() is a convenience wrapper for exactly(1).

exactly(int $count)

The method must be called exactly $count times.

$mock = $this->createMock(InterfaceName::class);

$mock
    ->expects($this->exactly(2))
    ->method('doSomething');

atLeastOnce()

The method must be called at least once.

$mock = $this->createMock(InterfaceName::class);

$mock
    ->expects($this->atLeastOnce())
    ->method('doSomething');

atLeastOnce() is a convenience wrapper for atLeast(1).

atLeast(int $requiredInvocations)

The method must be called at least $requiredInvocations times.

$mock = $this->createMock(InterfaceName::class);

$mock
    ->expects($this->atLeast(2))
    ->method('doSomething');

atMost(int $allowedInvocations)

The method must not be called more than $allowedInvocations times.

$mock = $this->createMock(InterfaceName::class);

$mock
    ->expects($this->atMost(2))
    ->method('doSomething');

never()

The method must not be called.

$mock = $this->createMock(InterfaceName::class);

$mock
    ->expects($this->never())
    ->method('doSomething');

never() is a convenience wrapper for exactly(0).

with()

The with() method verifies the arguments passed to the mocked method.

$mock = $this->createMock(InterfaceName::class);

$mock
    ->expects($this->once())
    ->method('doSomething')
    ->with('argument 1', 'argument 2');

In the example shown above, we configure the mock object to expect exactly one call to the method doSomething(). For this single call, the arguments "argument 1" and argument 2" must be passed.

The example shown above is equivalent to the following:

$mock = $this->createMock(InterfaceName::class);

$mock
    ->expects($this->once())
    ->method('doSomething')
    ->with($this->equalTo('argument 1'), $this->equalTo('argument 2'));

The with() method verifies the arguments passed to the mocked method using Constraint objects. If a value passed to with() is not a Constraint object then that value is automatically wrapped in a Constraint object that verifies equality. A Constraint object that verifies equality can be manually created using $this->equalTo().

PHPUnit provides many constraint methods for argument verification:

Identity and Equality

• identicalTo()

• equalTo()

• equalToCanonicalizing()

• equalToIgnoringCase()

• equalToWithDelta()

• objectEquals()

Cardinality

• isEmpty()

• countOf()

• greaterThan()

• greaterThanOrEqual()

• lessThan()

• lessThanOrEqual()

Math

• isFinite()

• isInfinite()

• isNan()

Boolean

• isFalse()

• isTrue()

Operator

• logicalAnd()

• logicalNot()

• logicalOr()

• logicalXor()

String

• isJson()

• matches()

• matchesRegularExpression()

• stringContains()

• stringEndsWith()

• stringEqualsStringIgnoringLineEndings()

• stringStartsWith()

Traversable

• arrayHasKey()

• containsEqual()

• containsIdentical()

• containsOnlyArray()

• containsOnlyBool()

• containsOnlyCallable()

• containsOnlyClosedResource()

• containsOnlyFloat()

• containsOnlyInstancesOf()

• containsOnlyInt()

• containsOnlyIterable()

• containsOnlyNull()

• containsOnlyNumeric()

• containsOnlyObject()

• containsOnlyResource()

• containsOnlyScalar()

• containsOnlyString()

• isList()

Type

• isArray()

• isBool()

• isCallable()

• isClosedResource()

• isFloat()

• isInstanceOf()

• isInt()

• isIterable()

• isNull()

• isNumeric()

• isObject()

• isResource()

• isScalar()

• isString()

Filesystem

• directoryExists()

• fileExists()

• isReadable()

• isWritable()

Verifying relative call order between mock object expectations

The id() and after() methods allow us to define dependencies between mock expectations, ensuring that one method is called only after another method has been called first.

• id(string $id): Assigns a unique identifier to an expectation

• after(string $id): Specifies that this expectation should only be verified after the expectation with the given ID has been matched

Below is a complete example demonstrating how to use id() and after() to verify that two() is called after one():

public function testTwoIsCalledAfterOne(): void
{
    $mock = $this->createMock(ServiceInterface::class);

    $mock
        ->expects($this->once())
        ->method('one')
        ->id('first-call');

    $mock
        ->expects($this->once())
        ->method('two')
        ->after('first-call');

    $mock->one();
    $mock->two();
}

1. Configuring the first expectation

$mock
    ->expects($this->once())
    ->method('one')
    ->id('first-call');

• expects($this->once()) sets up an expectation that the following method should be called exactly once

• method('one') specifies that this expectation applies to the one() method

• id('first-call') assigns the unique identifier "first-call" to this expectation. This ID can be referenced by other expectations using after().

2. Configuring the second expectation

$mock
    ->expects($this->once())
    ->method('two')
    ->after('first-call');

• expects($this->once()) sets up an expectation that two() should be called exactly once

• method('two') specifies that this expectation applies to the two() method

• after('first-call') creates a dependency on the expectation with ID "first-call"'"

This means:

• The expectation for two() will only be verified after one() has been called

• If two() is called before one(), that call will not count toward satisfying this expectation

• The test will fail if two() is not called after one() has been called

3. Executing the system under test

$mock->one();
$mock->two();

• The call to one() on the mock object satisfies the first expectation and “unlocks” the second expectation

• The call to two() on the mock object satisfies the second expectation, since one() was already called

If two() is called before one(), that call does not count toward satisfying the after() expectation.

Attempting to register the same ID twice will cause the test to error. Using after() with an ID that has not been registered with id() will cause the test to fail.

Why using id() and after() should be avoided:

• Brittle Tests: Tests that verify call order are tightly coupled to implementation details. Refactoring code that changes the order of internal calls (without changing behavior) will break these tests.

• Complexity: The id() and after() mechanism adds cognitive complexity. Readers of your tests need to understand this additional concept.

• Hidden Dependencies: The relationship between expectations is not immediately obvious, making tests harder to debug when they fail.

• Limited Flexibility: The mechanism only supports simple “A before B” relationships. More complex ordering requirements become even more unwieldy.

• Better Alternatives Exist: Most scenarios where call order matters can be tested more effectively:

  • Test the final state or output rather than intermediate calls

  • Use integration tests for workflows where order matters

  • Design interfaces that do not require specific call ordering

Methods that never return

The never return type indicates that a function or method will never return normally. Such methods either:

• Throw an exception

• Call exit() or die()

• Enter an infinite loop

When writing unit tests, mocking methods with a never return type requires special handling because the mock cannot actually “never return” as it must do something when called.

When you create a mock object of an interface or extendable class that has a method with a never return type, the mock object will throw a NeverReturningMethodException when that method is called. This exception simulates the behavior of a method that never returns normally.

Consider the following scenario where we have an ErrorHandler interface with a handle() method that has a never return type:

<?php declare(strict_types=1);
interface ErrorHandler
{
    public function handle(Exception $e): never;
}

<?php declare(strict_types=1);
final readonly class ErrorHandlerImplementation implements ErrorHandler
{
    public function handle(Exception $e): never
    {
        print $e->getMessage();

        exit;
    }
}

<?php declare(strict_types=1);
final readonly class ServiceImplementation implements Service
{
    private ErrorHandler $errorHandler;

    public function __construct(ErrorHandler $errorHandler)
    {
        $this->errorHandler = $errorHandler;
    }

    public function doSomething(): void
    {
        try {
            // ...

            throw new Exception('message');
        } catch (Exception $e) {
            $this->errorHandler->handle($e);
        }
    }
}

We want to test that, when an exception is thrown during the execution of ServiceImplementation::doSomething(), the ErrorHandler::handle() method is called with an exception object of the expected type. Here is how to do that:

1. Creating the mock object

$errorHandler = $this->createMock(ErrorHandler::class);

This line creates a mock object that implements the ErrorHandler interface. The mock object will have all the methods defined in the interface, including the handle() method with its never return type.

2. Configuring the mock object

$errorHandler
    ->expects($this->once())
    ->method('handle')
    ->with($this->isInstanceOf(Exception::class));

This fluent chain configures the mock object’s behavior and expectations:

• ->expects($this->once()): Sets up an expectation that the handle() method will be called exactly once during the test. If the method is not called, or called more than once, the test will fail.

• ->method('handle'): Specifies that we are configuring the handle() method of the mock object.

• ->with($this->isInstanceOf(Exception::class)): Specifies that the handle() method must be called with an argument that is an instance of the Exception class. This constraint validates the argument passed to the method.

3. Creating the system under test

$service = new ServiceImplementation($errorHandler);

This line creates an instance of the ServiceImplementation class, injecting the mock object we created and configured to replace the ErrorHandler dependency. This is standard dependency injection, allowing us to test ServiceImplementation in isolation from its dependency ErrorHandler.

4. Configuring the expectation that the mocked method never returns

$this->expectException(NeverReturningMethodException::class);

This line tells PHPUnit to expect that a NeverReturningMethodException will be thrown during the test. This is the key to testing methods with never return type:

• When $service->doSomething() is called, it will internally call $this->errorHandler->handle($e)

• Since handle() has a never return type, PHPUnit throws a NeverReturningMethodException

• By expecting this exception, we document our assumption that the handle() method never returns

5. Executing the system under test

$service->doSomething();

This line calls the method we want to test. The execution flow is:

1. doSomething() is called on the service

2. Inside doSomething(), an exception is thrown and caught

3. The caught exception is passed to $this->errorHandler->handle($e)

4. The mock object’s handle() method is invoked

5. PHPUnit verifies the expectation (called once with an Exception instance)

6. PHPUnit throws NeverReturningMethodException because the method has a never return type

7. The test passes because we expected this exception

Always use $this->expectException(NeverReturningMethodException::class) when testing code that calls a mocked method with never return type.

The exception replaces the “never return” behavior: In real code, a method with never return type would call exit(), throw an exception, or loop forever. In tests, NeverReturningMethodException simulates this by providing a controlled way to exit the method.

Verification still works: Even though an exception is thrown, PHPUnit still verifies that your expectations (like expects($this->once()) and with()) are met.

This pattern allows you to effectively test code that depends on methods that never return normally, while still being able to verify that those methods are called with the correct arguments.

Set-Hooked Properties

The example below shows an interface that declares a set-hooked property:

<?php declare(strict_types=1);
interface InterfaceWithSetHookedProperty
{
    public string $property { set; }
}

Expectations for the set-hooked property property can be configured like so:

<?php declare(strict_types=1);
use PHPUnit\Framework\MockObject\Runtime\PropertyHook;
use PHPUnit\Framework\TestCase;

final class SetHookedPropertyMockExampleTest extends TestCase
{
    public function testExample(): void
    {
        $mock = $this->createMock(
            InterfaceWithSetHookedProperty::class,
        );

        $mock
            ->expects($this->once())
            ->method(PropertyHook::set('property'))
            ->with('value');

        $mock->property = 'value';
    }
}

In the example shown above, PropertyHook::set('property') to specify that we want to configure an expectation for the method that is called when the property named property is accessed for writing.