PHPackages                             hafriedlander/phockito - 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. hafriedlander/phockito

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

hafriedlander/phockito
======================

PHP Mocking framework inspired by Mockito for Java

1.0.0(12y ago)70286.4k↓20.9%24[8 issues](https://github.com/hafriedlander/phockito/issues)[6 PRs](https://github.com/hafriedlander/phockito/pulls)17BSD-3-ClausePHP

Since Jul 22Pushed 6y ago7 watchersCompare

[ Source](https://github.com/hafriedlander/phockito)[ Packagist](https://packagist.org/packages/hafriedlander/phockito)[ RSS](/packages/hafriedlander-phockito/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependenciesVersions (4)Used By (17)

Phockito - Mockito for PHP
==========================

[](#phockito---mockito-for-php)

Mocking framework inspired by Mockito for Java

Checkout [the original's website](http://mockito.org/) for the philosophy behind the API and more examples (although be aware that this is only a partial implementation for now)

Thanks to the developers of Mockito for the inspiration, and hamcrest-php for making this easy.

Example mocking:
----------------

[](#example-mocking)

```
// Create the mock
$iterator = Phockito::mock('ArrayIterator');

// Use the mock object - doesn't do anything, functions return null
$iterator->append('Test');
$iterator->asort();

// Selectively verify execution
Phockito::verify($iterator)->append('Test');
// 1 is default - can also do 2, 3  for exact numbers, or 1+ for at least one, or 0 for never
Phockito::verify($iterator, 1)->asort();
```

If PHPUnit is available, on failure verify throws a `PHPUnit_Framework_AssertionFailedError` (looks like an assertion failure), otherwise just throws an `Exception`

Example stubbing:
-----------------

[](#example-stubbing)

```
// Create the mock
$iterator = Phockito::mock('ArrayIterator');

// Stub in a value
Phockito::when($iterator->offsetGet(0))->return('first');

// Prints "first"
print_r($iterator->offsetGet(0));

// Prints null, because get(999) not stubbed
print_r($iterator->offsetGet(999));
```

Alternative API, jsMockito style

```
// Stub in a value
Phockito::when($iterator)->offsetGet(0)->return('first');
```

Spies
-----

[](#spies)

Mocks are full mocks - method calls to unstubbed function always return null, and never call the parent function.

You can also create partial mocks by calling `spy` instead of `mock`. With spies, method calls to unstubbed functions call the parent function.

Because spies are proper subclasses, this lets you stub in methods that are called by other methods in a class

```
class A {
	function Foo(){ return 'Foo'; }
	function Bar(){ return $this->Foo() . 'Bar'; }
}

// Create a mock
$mock = Phockito::mock('A');
print_r($mock->Foo()); // 'null'
print_r($mock->Bar()); // 'null'

// Create a spy
$spy = Phockito::spy('A');
print_r($spy->Foo()); // 'Foo'
print_r($spy->Bar()); // 'FooBar'

// Stub a method
Phockito::when($spy)->Foo()->return('Zap');
print_r($spy->Foo()); // 'Zap'
print_r($spy->Bar()); // 'ZapBar'
```

Argument matching
-----------------

[](#argument-matching)

Phockito allows the use of [Hamcrest](http://code.google.com/p/hamcrest/) matchers on any argument. Hamcrest is a library of "matching functions" that, given a value, return true if that value matches some rule.

Hamcrest matchers are not included by default, so the first step is to call `Phockito::include_hamcrest();` immediately after including Phockito. Note that this will import the Hamcrest matchers as global functions - passing false as an argument will keep your namespace clean by making all matchers only available as static methods of `Hamcrest` (at the expense of worse looking test code).

Once included you can pass a Hamcrest matcher as an argument in your when or verify rule, eg:

```
class A {
	function Foo($a){ }
}

$stub = Phockito::mock('A');
Phockito::when($stub)->Foo(anything())->return('Zap');
```

Some common Hamcrest matchers:

- Core
    - `anything` - always matches, useful if you don't care what the object under test is
- Logical
    - `allOf` - matches if all matchers match, short circuits (like PHP &&)
    - `anyOf` - matches if any matchers match, short circuits (like PHP ||)
    - `not` - matches if the wrapped matcher doesn't match and vice versa
- Object
    - `equalTo` - test object equality using the == operator
    - `anInstanceOf` - test type
    - `notNullValue`, `nullValue` - test for null
- Number
    - `closeTo` - test floating point values are close to a given value
    - `greaterThan`, `greaterThanOrEqualTo`, `lessThan`, `lessThanOrEqualTo` - test ordering
- Text
    - `equalToIgnoringCase` - test string equality ignoring case
    - `equalToIgnoringWhiteSpace` - test string equality ignoring differences in runs of whitespace
    - `containsString`, `endsWith`, `startsWith` - test string matching

Differences from Mockito
------------------------

[](#differences-from-mockito)

#### Stubbing methods more flexible

[](#stubbing-methods-more-flexible)

In Mockito, the methods when building a stub are limited to thenReturns, thenThrows. In Phockito, you can use any method as long as it has 'return' or 'throw' in it, so `Phockito::when(...)->return(1)->thenReturn(2)` is fine.

#### Type-safe argument matching

[](#type-safe-argument-matching)

In Mockito, to use a Hamcrest matcher, the `argThat` method is used to satisfy the type checker. In PHP, a little extra help is needed. Phockito provides the `argOfTypeThat` for provided Hamcrest matchers to type-hinted parameters:

```
class A {
    function Foo(B $b){ }
}

class B {}

$stub = Phockito::mock('A');
$b = new B();
Phockito::when($stub)->Foo(argOfTypeThat('B', is(equalTo($b))))->return('Zap');
```

It's also possible to pass a mock to 'when', rather than the result of a method call on a mock, e.g. `Phockito::when($mock)->methodToStub(...)->thenReturn(...)`. This side-steps the type system entirely.

Note that `argOfTypeThat` is only compatible with object type-hints; arguments with `array` or `callable` type-hints cannot be handled in a type-safe way.

#### Verify 'times' argument changed

[](#verify-times-argument-changed)

In Mockito, the 'times' argument to verify is an object of interface VerificationMode (like returned by the functions times, atLeastOnce, etc).

For now we just take either an integer, or an integer followed by '+'. It's not extensible.

#### Callback instead of answers

[](#callback-instead-of-answers)

In Mockito, you can return dynamic results from a stubbed method by calling thenAnswer with an instance of an object that has a specific method. In Phockito you call thenCallback with a `callback` argument, which gets called with the arguments the stubbed method was called with.

#### Default arguments

[](#default-arguments)

PHP has default arguments, unlike Java. If you don't specify a default argument in your stub or verify matcher, it'll match the default argument.

```
class Foo {
  function Bar($a, $b = 2){ /* NOP */ }
}

// Create the mock
$mock = Phockito::mock('Foo');

// Set up a stub
Phockito::when($mock->Bar(1))->return('A');

$mock->Bar(1); // Returns 'A'
$mock->Bar(1, 2); // Also returns 'A'
$mock->Bar(1, 3); // Returns null, since no stubbed return value matches
```

#### Return typing

[](#return-typing)

Mockito returns a type-compatible false, based on the declared return type. We don't have defined type values in PHP, so we always return null. TODO: Support using phpdoc @return when declared.

TODO
----

[](#todo)

- Mockito-specific hamcrest matchers (anyString, etc)
- Ordered verification

License
-------

[](#license)

Copyright (C) 2012 Hamish Friedlander / SilverStripe.

Distributable under either the same license as SilverStripe or the Apache Public License V2 () at your choice

You don’t have to do anything special to choose one license or the other and you don’t have to notify anyone which license you are using.

Hamcrest-php is under it's own license - see hamcrest-php/LICENSE.txt.

###  Health Score

43

—

FairBetter than 91% of packages

Maintenance18

Infrequent updates — may be unmaintained

Popularity49

Moderate usage in the ecosystem

Community31

Small or concentrated contributor base

Maturity65

Established project with proven stability

 Bus Factor1

Top contributor holds 55.6% 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

4659d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/654636?v=4)[Aaron Carlino](/maintainers/unclecheese)[@unclecheese](https://github.com/unclecheese)

![](https://avatars.githubusercontent.com/u/111025?v=4)[Ingo Schommer](/maintainers/chillu)[@chillu](https://github.com/chillu)

![](https://avatars.githubusercontent.com/u/1168676?v=4)[Maxime Rainville](/maintainers/maxime-rainville)[@maxime-rainville](https://github.com/maxime-rainville)

---

Top Contributors

[![rowanhill](https://avatars.githubusercontent.com/u/2607287?v=4)](https://github.com/rowanhill "rowanhill (5 commits)")[![chillu](https://avatars.githubusercontent.com/u/111025?v=4)](https://github.com/chillu "chillu (2 commits)")[![drdamour](https://avatars.githubusercontent.com/u/1514496?v=4)](https://github.com/drdamour "drdamour (1 commits)")[![FredrikWendt](https://avatars.githubusercontent.com/u/89504?v=4)](https://github.com/FredrikWendt "FredrikWendt (1 commits)")

---

Tags

testingmocksmockito

### Embed Badge

![Health badge](/badges/hafriedlander-phockito/health.svg)

```
[![Health](https://phpackages.com/badges/hafriedlander-phockito/health.svg)](https://phpackages.com/packages/hafriedlander-phockito)
```

###  Alternatives

[phpunit/phpunit

The PHP Unit Testing framework.

20.0k910.7M134.8k](/packages/phpunit-phpunit)[phpunit/php-code-coverage

Library that provides collection, processing, and rendering functionality for PHP code coverage information.

8.9k892.4M1.5k](/packages/phpunit-php-code-coverage)[mockery/mockery

Mockery is a simple yet flexible PHP mock object framework

10.7k497.0M23.6k](/packages/mockery-mockery)[behat/behat

Scenario-oriented BDD framework for PHP

4.0k96.8M2.0k](/packages/behat-behat)[symfony/phpunit-bridge

Provides utilities for PHPUnit, especially user deprecation notices management

2.5k201.2M4.2k](/packages/symfony-phpunit-bridge)[brianium/paratest

Parallel testing for PHP

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

PHPackages © 2026

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