PHPackages                             2pd/guzzle-http-mock - 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. 2pd/guzzle-http-mock

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

2pd/guzzle-http-mock
====================

A mock library for verifying requests made with the Guzzle Http Client, and mocking responses.

4.0(4y ago)4950↓16.7%2GPL-3.0-or-laterPHPPHP >=7.1||^8.0

Since Dec 31Pushed 4y agoCompare

[ Source](https://github.com/2pd/GuzzleHttpMock)[ Packagist](https://packagist.org/packages/2pd/guzzle-http-mock)[ RSS](/packages/2pd-guzzle-http-mock/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (5)Dependencies (2)Versions (23)Used By (2)

GuzzleHttpMock
==============

[](#guzzlehttpmock)

A mock library for verifying requests made with the [Guzzle Http Client](http://guzzle.readthedocs.org/), and mocking responses.

This is a fork of the [original version](https://github.com/aerisweather/GuzzleHttpMock). This version was changed to support Guzzle 6 and did receive some other minor changes.

---

- [Installation](#installation)
    - [Composer](#composer)
- [Overview](#overview)
    - [How does it work?](#how-does-it-work)
- [Usage](#usage)
    - [Attaching to a Guzzle Client](#attaching-to-a-guzzle-client)
    - [Creating Request Expectations](#creating-request-expectations)\* [Available Expectations](#available-expectations)\* [Default Expectations](#default-expectations)\* [Directly Setting an Expected Request](#directly-setting-an-expected-request)\* [Custom Expectations](#custom-expectations)
    - [Mocking Responses](#mocking-responses)
    - [Verifying Expectations](#verifying-expectations)
    - [Gotchyas](#gotchyas)
        - [Unspecified expectations](#unspecified-expectations)
        - [Where's my UnexpectedRequestException?](#wheres-my-unexpectedrequestexception)
        - [Why's it doing that thing I don't think it should do?](#whys-it-doing-that-thing-i-dont-think-it-should-do)
    - [Contributing](#contributing)
        - [Wish List](#wish-list)

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

[](#installation)

### Composer

[](#composer)

You can install GuzzleHttpMock using composer:

```
php composer.phar require --dev systemhaus/guzzle-http-mock
```

Overview
--------

[](#overview)

GuzzleHttpMock allows you to setup Http request expectations, and mock responses.

```
// Create a mock object
$httpMock = new \Aeris\GuzzleHttp\Mock();

// Create a guzzle http client and attach the mock handler
$guzzleClient = new \GuzzleHttp\Client([
	'base_url' => 'http://www.example.com',
	'handler' => $httpMock->getHandlerStackWithMiddleware();
]);

// Setup a request expectation
$httpMock
    ->shouldReceiveRequest()
    ->withUrl('http://www.example.com/foo')
    ->withMethod('GET')
    ->withBodyParams([ 'foo' => 'bar' ])
    ->andRespondWithJson([ 'faz', 'baz' ], $statusCode = 200);

// Make a matching request
$response = $guzzleClient->get('/foo', ['json' => ['foo' => 'bar'] ]);
json_decode((string) $response->getBody(), true) == ['faz' => 'baz'];  // true
$response->getStatusCode() == 200;      // true
$httpMock->verify();                    // all good.

// Make an unexpected request
$guzzleClient->post('/bar', ['json' => ['faz' => 'baz'] ]);;
$httpMock->verify();
// UnexpectedHttpRequestException: Request does not match any expectation:
// 	Request url does not match expected value. Actual: '/bar', Expected: '/foo'
//	Request body params does not match expected value. Actual: [ 'faz' => 'baz'], Expected: ['foo' => 'bar' ]
```

### How does it work?

[](#how-does-it-work)

When a GuzzleHttpMock Handler is attached to the Guzzle Http client, it will intercept all requests made by the client. Whenever a request is made, the mock checks the request against set expectations, and sends a response to matching requests. If your client uses custom middleware you can attach it to the handler stack of the mock handler.

Calling `$httpMock->verify()` checks that all expected requests have been made, and complains about any unexpected requests.

Usage
-----

[](#usage)

### Attaching to a Guzzle Client

[](#attaching-to-a-guzzle-client)

To start intercepting Http requests, the GuzzleHttpMock must be attached to a GuzzleClient:

```
// Create a mock object
$httpMock = new \Aeris\GuzzleHttp\Mock();

// Create a guzzle http client and attach mock handler
$guzzleClient = new \GuzzleHttp\Client([
	'base_url' => 'http://www.example.com',
	'handler' => $httpMock->getHandlerStackWithMiddleware()
]);
```

### Creating Request Expectations

[](#creating-request-expectations)

The `shouldReceiveRequest` method returns a `\Aeris\GuzzleHttpMock\Expectation\RequestExpectation` object.

```
$requestExpectation = $httpMock->shouldReceiveRequest();
```

The `RequestExpectation` object uses `withXyz` methods to set expectations:

```
$requestExpectation->withUrl('http://www.example.com/foo');
```

The expectation setters are chainable, allowing for a fluid interface:

```
$httpMock
    ->shouldReceiveRequest()
    ->withUrl('http://www.example.com/foo')
    ->withMethod('POST');
```

#### Available Expectations

[](#available-expectations)

The following expectations are available on a `\Aeris\GuzzleHttpMock\Expectation\RequestExpectation` object.

MethodNotes`withUrl($url:string)`URL (full absolute path)`withMethod($url:string)`Http method.`withQuery($query:\GuzzleHttp\Query)`Query with a Guzzle query object`withQueryParams($params:array)`Query string with array`withQueryString($queryString:string)`Literal query string comparison`withContentType($contentType:string)`Content Type`withJsonContentType()`JSON Content Type`withBody($stream:StreamInterface)`Compare request body`withBodyParams($params:array)`Compare request body params`withJsonBodyParams($params:array)`JSON body params`once()`The request should be made a single time`times($callCount:number)`The request should be made `$callCount` times.#### Default Expectations

[](#default-expectations)

By default, a request is expected to be made one time, with an Http method of 'GET'.

```
// So this:
$httpMock
    ->shouldReceiveRequest()
    ->withUrl('http://www.example.com/foo');

// is the same as this:
$httpMock
    ->shouldReceiveRequest()
    ->withUrl('http://www.example.com/foo')
    ->once()
    ->withMethod('GET');
```

#### Directly Setting an Expected Request

[](#directly-setting-an-expected-request)

In addition to specifying request expectations individually, you can also directly set a `Psr\Http\Message\RequestInterface` object as an expectation.

```
$expectedRequest = new Request(
    'PUT',
    'http://www.example.com/foo?faz=baz',
    [
		'body'    => json_encode(['shazaam' => 'kablooey']),
		'headers' => [
			'Content-Type' => 'application/json'
		],
	]
);

$httpClient->shouldReceiveRequest($expectedRequest);
```

#### Custom Expectations

[](#custom-expectations)

All expectation methods accept either a value or a `callable` as a parameter. By passing a callable, you can create custom expectations. For example:

```
$httpMock
    ->shouldReceiveRequest()
    ->withBodyParams(function($actualParams) {
        return $actualParams['foo'] === 'bar';
    });
```

In this case, the expectation will fail if the actual request body has a `foo` params which does not equal `bar`.

GuzzleHttpMock provides some built-in custom expectations, as well. For example:

```
use Aeris\GuzzleHttpMock\Expect;

$httpMock
	->shouldReceiveRequest()
	// Check URL against a regex
	->withUrl(new Expect\Matches('/^https:/'))
	// Check query params against an array
	->withQueryParams(new Expect\ArrayEquals(['foo' => 'bar']))
	// Allow any body params
	->withBodyParams(new Expect\Any());
```

### Mocking Responses

[](#mocking-responses)

When a request is made which matches an expectation, the GuzzleHttpMock will intercept the request, and respond with a mock response.

```
$httpMock
  ->shouldReceiveRequest()
  ->withMethod('GET')
  ->withUrl('http://www.example.com/foo')
  ->andRespondWithJson(['foo' => 'bar']);

$response = $guzzleClient->get('/foo');
$response->json() == ['foo' => 'bar'];  // true
```

#### Available Responses

[](#available-responses)

The following methods are available for mocking responses:

MethodNotes`andRespondWith($response:\Psr\Http\Message\ResponseInterface)`See [Directly Setting a Mock Response](#directly-setting-a-mock-response)`andRespondWithContent($data:array, $statusCode:string)`Sets the response body`andRespondWithJson($data:array, $statCode:String)`Sets a JSON response body#### Directly Setting a Mock Response

[](#directly-setting-a-mock-response)

You may mock a response directly using a response object:

```
$response = new \GuzzleHttp\Psr7\Response(
    200,
    ['Content-Type' = 'application/json'],
    json_encode(['foo' => 'bar' ]
);

$httpMock
    ->shouldReceiveRequest()
    ->withMethod('GET')
    ->withUrl('http://www.example.com/foo')
    ->andResponseWith($response);
```

### Verifying Expectations

[](#verifying-expectations)

Expectations may be verified using the `\Aeris\GuzzleHttpMock::verify()` method.

```
$httpMock
  ->shouldReceiveRequest()
  ->withUrl('http://www.example.com/foo');

$guzzleClient->get('/bar');

$httpMock->verify();
// UnexpectedRequestException: Request does not match any expectation.
//	Request url does not match expected value. Actual: '/bar', Expected: '/foo'.
```

#### With PHPUnit

[](#with-phpunit)

When using GuzzleHttpMock with PHPUnit, make sure to add `Mock::verify()` to your teardown:

```
class MyUnitTest extends \PHPUnit_Framework_TestCase {
    private $guzzleClient;
    private $httpMock;

    public function setUp() {
    	// Setup your guzzle client and mock
    	$this->httpMock = new \Aeris\GuzzleHttpMock();

    	$this->guzzleClient = new \GuzzleHttp\Client([
			'base_url' => 'http://www.example.com',
			'handler' => $this->httpMock->getHandlerStackWithMiddleware();
		]);
   	}

    public function tearDown() {
    	// Make sure all request expectations are met.
    	$this->httpMock->verify();
        // Failed expectations will throw an \Aeris\GuzzleHttpMock\Exception\UnexpectedHttpRequestException
    }
}
```

### Gotchyas

[](#gotchyas)

We have used GuzzleHttpMock enough internally to feel comfortable using it on production projects, but also enough to know that there are a few "gotchyas". Hopefully, knowing these issues up-front will prevent much conflict between your forehead and your desk.

If you'd like to take a shot at resolving any of these issues, take a look at our [contribution guidelines](#contributing).

#### Unspecified expectations

[](#unspecified-expectations)

In the current version of GuzzleHttpMock, any expectations which are not specified will result in a failed request.

```
$httpMock
    ->shouldReceiveRequest()
    ->withUrl('http://www.example.com/foo');

$guzzleClient->get('/foo', [
	'query' => ['foo' => 'bar']
]);

$httpMock->verify();
// UnexpectedHttpRequestException: Request does not match any expectation:
// 	Request query params does not match any expectation: Actual: [ 'foo' => 'bar' ], Expected: []
```

You might argue that it would make more sense for the RequestExpectation to accept any value for unspecified expectations by default. And you might be right. Future versions of GuzzleHttpMock may do just that.

#### Where's my UnexpectedRequestException?

[](#wheres-my-unexpectedrequestexception)

There are a couple of possible culprits here:

1. Make sure you're calling `Mock::verify()`. If you're using a testing framework (eg PHPUnit), you can put `verify()` in the `tearDown` method.
2. Another exception may be thrown before you had a chance to verify your request expectations.

Solving #2 can be a little tricky. If a RequestExpectation cannot be matched, GuzzleHttpClient will not respond with your mock response, which may cause other code to break before you have a chance to call `verify()`.

If you're calling `verify()` in your test `tearDown`, you may want to try adding another `verify()` call immediately after the http request is made.

You can also try wrapping the offending code in a `try...catch` block, to give the `UnexpectedRequestException` priority.

```
$this->httpMock
    ->shouldReceiveRequest()
    ->withXYZ()
    ->andRespondWith($aValidResponse);

try {
    $subjectUnderTest->doSomethingWhichExpectsAValidHttpResponse();
}
catch (\Exception $ex) {
    // uh oh, $subjectUnderTest made an unexpected request,
    // and now if does not have a valid response to work with!

    // Let's check our http mock, and see what happened
    $httpMock->verify();

    // If it's not a request expectation problem, throw the original error
    throw $ex;
}
```

That's more verbosity than you may want in all of your tests, but it can be helpful if you're debugging.

#### Why's it doing that thing I don't think it should do?

[](#whys-it-doing-that-thing-i-dont-think-it-should-do)

I don't know. That's really weird. Bummer...

Hey, why don't you open a new issue and tell us about it? Maybe we can help.

### Contributing

[](#contributing)

For that warm fuzzy open-sourcey feeling, contribute to GuzzleHttpMock today!

We only ask that you include PHPUnit tests, and update documentation as needed. Also, if it's not an open issue or on our wish list, you might want to open an issue first, to make sure you're headed in the right direction.

#### Wish List

[](#wish-list)

Take a look at the ["Gotchyas"](#gotchyas) section for some things that could be fixed. Have another idea? Open an issue, and we'll talk.

###  Health Score

37

—

LowBetter than 83% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity21

Limited adoption so far

Community16

Small or concentrated contributor base

Maturity78

Established project with proven stability

 Bus Factor2

2 contributors hold 50%+ of commits

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 ~164 days

Total

17

Last Release

1522d ago

Major Versions

v1.2.2 → 2.02017-07-19

2.3 → 3.02022-03-09

3.0 → 4.02022-03-10

PHP version history (3 changes)1.0.0PHP >=5.3.3

2.1PHP >=5.6.0

3.0PHP >=7.1||^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/6813961d7fc3a6a6c102c6cf732f41e8043fa3c6f3c9e4106bf466eebbdec218?d=identicon)[Liang Shi](/maintainers/Liang%20Shi)

---

Top Contributors

[![maartenderie](https://avatars.githubusercontent.com/u/19903985?v=4)](https://github.com/maartenderie "maartenderie (13 commits)")[![2pd](https://avatars.githubusercontent.com/u/365354?v=4)](https://github.com/2pd "2pd (12 commits)")[![eschwartz](https://avatars.githubusercontent.com/u/1153371?v=4)](https://github.com/eschwartz "eschwartz (7 commits)")[![narcoticfresh](https://avatars.githubusercontent.com/u/245441?v=4)](https://github.com/narcoticfresh "narcoticfresh (4 commits)")[![JuliaPoberezhnaia](https://avatars.githubusercontent.com/u/30119582?v=4)](https://github.com/JuliaPoberezhnaia "JuliaPoberezhnaia (2 commits)")[![plorenz-etes](https://avatars.githubusercontent.com/u/43336309?v=4)](https://github.com/plorenz-etes "plorenz-etes (1 commits)")

---

Tags

httptestingmockingclientGuzzlemock

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/2pd-guzzle-http-mock/health.svg)

```
[![Health](https://phpackages.com/badges/2pd-guzzle-http-mock/health.svg)](https://phpackages.com/packages/2pd-guzzle-http-mock)
```

###  Alternatives

[aeris/guzzle-http-mock

A mock library for verifying requests made with the Guzzle Http Client, and mocking responses.

2613.1k1](/packages/aeris-guzzle-http-mock)[blastcloud/guzzler

Supercharge your app or SDK with a testing library specifically for Guzzle.

272419.3k35](/packages/blastcloud-guzzler)[doppiogancio/mocked-client

A simple way to mock a client

2174.9k3](/packages/doppiogancio-mocked-client)[donatj/mock-webserver

Simple mock web server for unit testing

1382.5M80](/packages/donatj-mock-webserver)[mcustiel/phiremock

A mocker for HTTP and REST services. Full bundle.

151947.1k5](/packages/mcustiel-phiremock)[quizlet/hammock

Hammock is a stand-alone mocking library for Hacklang.

27445.5k](/packages/quizlet-hammock)

PHPackages © 2026

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