PHPackages                             ronyldo12/php-stubs - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Testing & Quality](/categories/testing)
4. /
5. ronyldo12/php-stubs

ActiveLibrary[Testing & Quality](/categories/testing)

ronyldo12/php-stubs
===================

A flexible, simple and poweful PHP stubbing library for unit testing, built on the runkit7 extension. Easily stub instance and static methods, use advanced argument matchers, and set call expectations. Designed for seamless integration with PHPUnit and PHP 7.4+.

v0.0.1.x-dev(11mo ago)02PHPPHP >=7.2CI passing

Since Jun 19Pushed 11mo agoCompare

[ Source](https://github.com/ronyldo12/php-stubs)[ Packagist](https://packagist.org/packages/ronyldo12/php-stubs)[ RSS](/packages/ronyldo12-php-stubs/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (1)Versions (4)Used By (0)

PHP Stubs
=========

[](#php-stubs)

A flexible, simple, and powerful PHP stubbing library for unit testing, built on the runkit7 extension. Easily stub instance and static methods, use advanced argument matchers, and set call expectations. Designed for seamless integration with PHPUnit and PHP 7.4+.

Requirements
------------

[](#requirements)

- PHP 7.4 or higher
- [runkit7 extension](https://github.com/runkit7/runkit7)
- PHPUnit (for running tests)

Installation
------------

[](#installation)

Install via Composer:

```
composer require --dev ronyldo12/php-stubs

```

> **Note:** You must have the runkit7 extension installed and enabled in your PHP environment.

Usage Patterns
--------------

[](#usage-patterns)

### 1. Basic Method Stubbing

[](#1-basic-method-stubbing)

Stub a method to return a specific value:

```
Stubs::stub(MyClass::class)
    ->method('foo')->returns('stubbed value');
$obj = new MyClass();
$obj->foo(); // returns 'stubbed value'
```

### 2. Stubbing with Argument Matchers

[](#2-stubbing-with-argument-matchers)

Stub a method to return a value only for specific arguments:

```
Stubs::stub(MyClass::class)
    ->method('bar')->with('abc')->returns('stubbed_bar');
$obj = new MyClass();
$obj->bar('abc'); // returns 'stubbed_bar'
```

#### Supported Matchers

[](#supported-matchers)

- `Stubs::match_any()` — matches any argument
- `Stubs::match_text($text)` — matches if argument contains text
- `Stubs::match_regex($pattern)` — matches regex
- `Stubs::match_array($array)` — matches array
- `Stubs::match_object($object, $props = null)` — matches an object by value or by specific properties
- `Stubs::match_callback($callable)` — custom matcher

Example:

```
Stubs::stub(MyClass::class)
    ->method('bar')->with(Stubs::match_regex('/^foo\d+$/'))->returns('matched_regex');
$obj->bar('foo123'); // returns 'matched_regex'
```

#### Matching Object Properties Example

[](#matching-object-properties-example)

You can match an object by its properties using `Stubs::match_object`. Pass an example object and an array of properties to match:

```
$expected = (object)['x' => 1, 'y' => 2];
Stubs::stub(MyClass::class)
    ->method('foo')->with(Stubs::match_object($expected, ['x' => 1]))->returns('matched_object');

$obj = new MyClass();
$result = $obj->foo((object)['x' => 1, 'y' => 999]); // returns 'matched_object' (matches 'x' only)
$result2 = $obj->foo((object)['x' => 2, 'y' => 2]); // does not match, falls back to original or throws
```

If you omit the second argument, the matcher will compare all properties of the object:

```
$expected = (object)['x' => 1, 'y' => 2];
Stubs::stub(MyClass::class)
    ->method('foo')->with(Stubs::match_object($expected))->returns('matched_object');
$obj = new MyClass();
$obj->foo((object)['x' => 1, 'y' => 2]); // returns 'matched_object'
$obj->foo((object)['x' => 1]); // does not match
```

### 3. Stubbing Static Methods

[](#3-stubbing-static-methods)

Stub static methods just like instance methods:

```
Stubs::stub(MyClass::class)
    ->method('staticFoo')->returns('stubbed_static');
MyClass::staticFoo(); // returns 'stubbed_static'
```

### 4. Stubbing Methods to Return Null

[](#4-stubbing-methods-to-return-null)

```
Stubs::stub(MyClass::class)
    ->method('returnsNull')->returns(null);
$obj = new MyClass();
$obj->returnsNull(); // returns null
```

### 5. Stubbing to Raise Exceptions

[](#5-stubbing-to-raise-exceptions)

```
Stubs::stub(MyClass::class)
    ->method('foo')->raiseException(new \Exception('error!'));
$obj = new MyClass();
// $obj->foo(); // throws Exception with message 'error!'
```

### 6. Enforcing Expected Calls

[](#6-enforcing-expected-calls)

Require that a stubbed method must be called:

```
Stubs::stub(MyClass::class)
    ->method('foo')->expectCall()->returns('stubbed value');
$obj = new MyClass();
$obj->foo(); // OK
```

If not called, the test fails with a detailed exception message including file and line.

### 7. Multiple Stubs and Overriding

[](#7-multiple-stubs-and-overriding)

You can stub the same method multiple times; each call uses the next stub:

```
Stubs::stub(MyClass::class)->method('foo')->returns('first');
Stubs::stub(MyClass::class)->method('foo')->returns('second');
$obj = new MyClass();
$obj->foo(); // 'first'
$obj->foo(); // 'second'
// $obj->foo(); // throws Exception: no stub found (no fallback)
```

### 8. Error Reporting

[](#8-error-reporting)

If a stub is not called as expected, or arguments do not match, or you call a stubbed method more times than allowed, the exception message will include:

- The class and method
- The file and line where the stub was set up

Example error:

```
Expected stub was not called: MyClass::foo at /path/to/test.php:42

```

### 9. Call Count Expectations (once, twice, exactly, atLeast, anyTimes)

[](#9-call-count-expectations-once-twice-exactly-atleast-anytimes)

You can require that a stubbed method must be called a specific number of times:

```
// Must be called exactly once
Stubs::stub(MyClass::class)
    ->method('foo')->returns('stubbed')->once();

// Must be called exactly twice
Stubs::stub(MyClass::class)
    ->method('foo')->returns('stubbed')->twice();

// Must be called exactly n times
Stubs::stub(MyClass::class)
    ->method('foo')->returns('stubbed')->exactly(3);

// Must be called at least n times (extra calls allowed)
Stubs::stub(MyClass::class)
    ->method('foo')->returns('stubbed')->atLeast(2);

// Can be called any number of times (including zero)
Stubs::stub(MyClass::class)
    ->method('foo')->returns('stubbed')->anyTimes();
```

- If the method is called more than allowed (for once, twice, exactly), an exception is thrown immediately.
- If the method is called fewer than required (for once, twice, exactly, atLeast), an exception is thrown at verification.
- For atLeast, extra calls are allowed.
- For anyTimes, any number of calls is allowed.
- **There is no fallback to the original implementation.** If you call a stubbed method with no matching stub or with wrong arguments, an exception is thrown.

Supported Matchers
------------------

[](#supported-matchers-1)

- `Stubs::match_any()`
- `Stubs::match_text($text)`
- `Stubs::match_regex($pattern)`
- `Stubs::match_array($array)`
- `Stubs::match_object($object, $props = null)`
- `Stubs::match_callback($callable)`

Running Tests
-------------

[](#running-tests)

To run the test suite locally, you have two options:

### 1. Using Make (Recommended)

[](#1-using-make-recommended)

This will run the tests inside a Docker container with all dependencies:

```
make test

```

### 2. Manually with Composer and PHPUnit

[](#2-manually-with-composer-and-phpunit)

1. Make sure you have the required dependencies installed:

    - PHP 7.4 or higher
    - [runkit7 extension](https://github.com/runkit7/runkit7)
    - PHPUnit
2. Install Composer dependencies (if you haven't already):

    ```
    composer install

    ```
3. Run the tests:

    ```
    ./vendor/bin/phpunit

    ```

Contributing
------------

[](#contributing)

Contributions are welcome! To contribute to this project:

1. **Fork** the repository on GitHub.
2. **Clone** your fork to your local machine.
3. **Create a new branch** for your feature or bugfix: ```
    git checkout -b my-feature

    ```
4. **Make your changes** and add tests if applicable.
5. **Commit** your changes with a clear message.
6. **Push** to your fork: ```
    git push origin my-feature

    ```
7. **Open a Pull Request** on GitHub and describe your changes.

Please ensure your code follows the existing style and passes all tests. Thank you for helping improve this project!

License
-------

[](#license)

MIT

###  Health Score

20

—

LowBetter than 14% of packages

Maintenance52

Moderate activity, may be stable

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity19

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

333d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/f5cc16c77b1934c848b22a7d52629ed31793053e887b726195add0820c243fe4?d=identicon)[ronyldo12](/maintainers/ronyldo12)

---

Top Contributors

[![ronyldo12](https://avatars.githubusercontent.com/u/3726579?v=4)](https://github.com/ronyldo12 "ronyldo12 (11 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/ronyldo12-php-stubs/health.svg)

```
[![Health](https://phpackages.com/badges/ronyldo12-php-stubs/health.svg)](https://phpackages.com/packages/ronyldo12-php-stubs)
```

###  Alternatives

[phpspec/prophecy

Highly opinionated mocking framework for PHP 5.3+

8.5k551.7M682](/packages/phpspec-prophecy)[brianium/paratest

Parallel testing for PHP

2.5k118.8M754](/packages/brianium-paratest)[beberlei/assert

Thin assertion library for input validation in business models.

2.4k96.9M570](/packages/beberlei-assert)[mikey179/vfsstream

Virtual file system to mock the real file system in unit tests.

1.4k108.0M2.7k](/packages/mikey179-vfsstream)[orchestra/testbench

Laravel Testing Helper for Packages Development

2.2k39.1M32.1k](/packages/orchestra-testbench)[phpspec/phpspec

Specification-oriented BDD framework for PHP 7.1+

1.9k36.7M3.1k](/packages/phpspec-phpspec)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)