citruslab/mokkd

A library for mocking free-standing functions in PHP

v0.0.1 2025-10-06 21:39 UTC

Requires

• php: >=8.2
• ext-dom: *
• ext-mbstring: *
• ext-uopz: *

Requires (Dev)

• phpunit/phpunit: 11.*

Apache-2.0

README

Mokkd is pre-release software.

Aims to do for free functions what Mockery does for classes. Test doubles for functions can be quickly built using a fluent interface. For example, to mock the time() built-in function so that it returns 0, use:

$time = Mokkd::func("time")
    ->returning(0);

Basic usage scenarios are covered in this readme. See the documentation for more.

Return successive array elements

$time = Mokkd::func("time")
    ->returningFrom([0, 1, 2])

Return a mapped value

$getEnv = Mokkd::func("getenv"
    ->returningMappedValueFrom(
        [
            "host" => "example.com",
            "secret" => "fake-secret"
        ],
        0,
    )

Completely replace a function

$time = Mokkd::func("time")
    ->returningUsing(static function(): int {
        static $count = 0;
        return 60 * $count++;
    })

Setting expectations

Control call count

$time = Mokkd::func("time")
    ->times(3)
    ->returning(0);

Convenience once() and twice()

$time = Mokkd::func("time")
    ->once()
    ->returning(0);

$time = Mokkd::func("time")
    ->twice()
    ->returning(0);

Expect specified arguments

$getEnv = Mokkd::func("getenv")
    ->expects("host")
    ->returning("example.com")

Matching arguments

$getEnv = Mokkd::func("substr")
    ->expects(Mokkd::isString(), 0, Mokkd::isIntGreaterThan(2))
    ->returning("leftmost")

Allowing unmatched calls

$getEnv = Mokkd::func("getenv")
    ->expects("host")
    ->returning("example.com")
    ->withoutBlocking()