README

Description

A strict mocking solution.

Requirements

• php: ^8.3
• nikic/php-parser: ^5.8

Installation

Through Composer as chubbyphp/chubbyphp-mock.

composer require chubbyphp/chubbyphp-mock "^2.2" --dev

Usage

<?php

declare(strict_types=1);

namespace MyProject\Tests\Unit\RequestHandler;

use Chubbyphp\Mock\MockMethod\WithCallback;
use Chubbyphp\Mock\MockMethod\WithReturn;
use Chubbyphp\Mock\MockMethod\WithReturnSelf;
use Chubbyphp\Mock\MockObjectBuilder;
use MyProject\RequestHandler\PingRequestHandler;
use PHPUnit\Framework\TestCase;
use Psr\Http\Message\ResponseFactoryInterface;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Message\StreamInterface;

final class PingRequestHandlerTest extends TestCase
{
    public function testHandle(): void
    {
        $builder = new MockObjectBuilder();

        $request = $builder->create(ServerRequestInterface::class, []);

        $responseBody = $builder->create(StreamInterface::class, [
            new WithCallback('write', static function (string $string): int {
                $data = json_decode($string, true);
                self::assertArrayHasKey('datetime', $data);

                return \strlen($string);
            }),
        ]);

        $response = $builder->create(ResponseInterface::class, [
            new WithReturnSelf('withHeader', ['Content-Type', 'application/json']),
            new WithReturnSelf('withHeader', ['Cache-Control', 'no-cache, no-store, must-revalidate']),
            new WithReturnSelf('withHeader', ['Pragma', 'no-cache']),
            new WithReturnSelf('withHeader', ['Expires', '0']),
            new WithReturn('getBody', [], $responseBody),
        ]);

        $responseFactory = $builder->create(ResponseFactoryInterface::class, [
            new WithReturn('createResponse', [200, ''], $response),
        ]);

        $requestHandler = new PingRequestHandler($responseFactory);

        self::assertSame($response, $requestHandler->handle($request));
    }
}

FAQ

Howto mock final classes/methods

Use the third party package dg/bypass-finals.

This does not work to get rid of the final keyword on internal classes.

What Cannot Be Mocked

• Static methods

• Properties

• __construct and __destruct methods

• Internal final classes or methods: Even with tools like dg/bypass-finals, you cannot mock internal final classes or methods.

• Poorly built extension classes: Some older PHP extensions create classes that cannot be fully reverse-engineered using reflection. These classes are not mockable.

Special Handling

• \Traversable and interfaces extending it: PHP does not allow userland classes to implement \Traversable directly; a class can only implement it by also implementing \Iterator or \IteratorAggregate. chubbyphp-mock handles this automatically by adding \IteratorAggregate (and a matching getIterator() method if needed) to the generated mock, so \Traversable and interfaces extending it can be mocked.

Please report if you find other restrictions / bugs.

Upgrade

Upgrade from 1.x

Copyright

2026 Dominik Zogg