PHPackages                             aksoyih/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. [HTTP & Networking](/categories/http)
4. /
5. aksoyih/http-mock

ActiveLibrary[HTTP & Networking](/categories/http)

aksoyih/http-mock
=================

A PHP library for mocking HTTP clients with customizable responses and behaviors

v2.0.0(1mo ago)13181MITPHPPHP ^8.4CI passing

Since Jan 20Pushed 1mo ago1 watchersCompare

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

READMEChangelog (2)Dependencies (9)Versions (4)Used By (0)

HTTP Mock
=========

[](#http-mock)

[![CI](https://github.com/aksoyih/http-mock/actions/workflows/ci.yml/badge.svg)](https://github.com/aksoyih/http-mock/actions/workflows/ci.yml)

A PHP library for mocking HTTP clients with customizable responses, flexible request matching, and full verification support. Works with PSR-18, Guzzle, and Symfony HttpClient.

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

[](#installation)

```
composer require aksoyih/http-mock --dev
```

Quick Start
-----------

[](#quick-start)

```
use Aksoyih\HttpMock\HttpMock;

// Define a mock
HttpMock::when('GET', '/users')
    ->willReturn(['id' => 1, 'name' => 'John'])
    ->withStatus(200)
    ->register();

// Create a PSR-18 client
$client = HttpMock::createClient();
$response = $client->sendRequest($request);

// Verify it was called
HttpMock::assertCalled('GET', '/users');
```

Request Matching
----------------

[](#request-matching)

### Exact Match

[](#exact-match)

```
HttpMock::when('GET', '/users/123')
    ->willReturn(['id' => 123])
    ->register();
```

### Wildcard Patterns

[](#wildcard-patterns)

```
// * matches a single path segment
HttpMock::when('GET', '/users/*/posts')
    ->willReturn([])
    ->register();

// ** matches multiple segments
HttpMock::when('GET', '/api/**')
    ->willReturn([])
    ->register();
```

### Regex Patterns

[](#regex-patterns)

```
HttpMock::when('GET', '#^/users/\d+$#')
    ->willReturn(['found' => true])
    ->register();
```

### Callable Matchers

[](#callable-matchers)

```
HttpMock::whenMatching(fn($method, $url, $headers, $body) =>
    $method === 'POST' && str_contains($url, '/admin')
)->willReturn(['access' => 'granted'])
    ->register();
```

Shorthand
---------

[](#shorthand)

```
HttpMock::fake([
    'GET /users/*' => HttpMock::response(['id' => 1], 200),
    'POST /users'  => HttpMock::response(['created' => true], 201),
]);
```

Verification
------------

[](#verification)

```
HttpMock::assertCalled('GET', '/users');
HttpMock::assertCalledTimes('POST', '/users', 3);
HttpMock::assertNotCalled('DELETE', '/users');

// Or use expect() constraints
HttpMock::when('GET', '/users')
    ->willReturn([])
    ->expect(times: 2)
    ->register();

// ... make requests ...

HttpMock::verify(); // throws if expectations not met
```

HTTP Client Adapters
--------------------

[](#http-client-adapters)

### PSR-18

[](#psr-18)

```
$client = HttpMock::createClient();
```

### Guzzle

[](#guzzle)

```
$handler = HttpMock::createGuzzleHandler();
$stack = HandlerStack::create($handler);
$client = new \GuzzleHttp\Client(['handler' => $stack]);
```

### Symfony HttpClient

[](#symfony-httpclient)

```
$client = HttpMock::createSymfonyClient();
```

Unmatched Request Handling
--------------------------

[](#unmatched-request-handling)

```
// Strict mode (default) — throws on unmatched requests
HttpMock::onUnmatched(HttpMock::THROW);

// Return 404 for unmatched requests
HttpMock::onUnmatched(HttpMock::DEFAULT_404);

// Custom handler
HttpMock::onUnmatched(fn($method, $url) => [
    'status' => 503,
    'headers' => [],
    'body' => 'Service unavailable',
]);
```

Test Isolation
--------------

[](#test-isolation)

### PHPUnit Trait (recommended)

[](#phpunit-trait-recommended)

```
use Aksoyih\HttpMock\Testing\MocksHttp;

class MyTest extends TestCase
{
    use MocksHttp; // auto-resets after each test
}
```

### Scoped

[](#scoped)

```
HttpMock::scoped(function () {
    HttpMock::when('GET', '/users')->willReturn([])->register();
    // ... test code ...
}); // auto-resets, even on exception
```

### Manual

[](#manual)

```
HttpMock::reset();
```

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

[](#requirements)

- PHP 8.4+
- `psr/http-client` ^1.0
- `nyholm/psr7` ^1.0

Optional:

- `guzzlehttp/guzzle` ^7.0 (for Guzzle adapter)
- `symfony/http-client` ^7.0 (for Symfony adapter)

License
-------

[](#license)

MIT

###  Health Score

46

—

FairBetter than 93% of packages

Maintenance89

Actively maintained with recent releases

Popularity18

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity57

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 75% 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 ~210 days

Total

3

Last Release

54d ago

Major Versions

1.0.0 → v2.0.02026-03-17

PHP version history (2 changes)1.0.0PHP ^8.1

v2.0.0PHP ^8.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/5e60d1e2913a8bed8c8f2d8d5227360633a65cb625960406d964835b8b96e23b?d=identicon)[aksoyih](/maintainers/aksoyih)

---

Top Contributors

[![aksoyih](https://avatars.githubusercontent.com/u/54416061?v=4)](https://github.com/aksoyih "aksoyih (3 commits)")[![raphaelstolt](https://avatars.githubusercontent.com/u/48225?v=4)](https://github.com/raphaelstolt "raphaelstolt (1 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/aksoyih-http-mock/health.svg)

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

###  Alternatives

[laudis/neo4j-php-client

Neo4j-PHP-Client is the most advanced PHP Client for Neo4j

184616.9k31](/packages/laudis-neo4j-php-client)[phpro/http-tools

HTTP tools for developing more consistent HTTP implementations.

28137.8k](/packages/phpro-http-tools)[art4/requests-psr18-adapter

Use WordPress/Requests as a PSR-18 HTTP client

153.3k](/packages/art4-requests-psr18-adapter)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

255.2k](/packages/aedart-athenaeum)

PHPackages © 2026

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