Download the PHP package mock-server/mockserver-client without Composer

MockServer PHP Client

PHP client for MockServer - enables easy mocking of any system you integrate with via HTTP or HTTPS.

Requirements

• PHP 8.1+
• Composer

Installation

Quick Start

API

Creating Expectations

JWT Request Matcher

Match a request by inspecting a JSON Web Token carried on it (by default the authorization header with a Bearer scheme). Each claim is matched by exact string or regular expression; a leading ! negates the match for that claim.

ALL_OF Body Matcher

Require several body matchers to all match the same request body. Compose any typed body matcher arrays — HttpRequest::jsonPathBody() and HttpRequest::regexBody() are provided as convenient helpers.

Class Callbacks

A class callback references a server-side class (already on MockServer's classpath) that implements one of MockServer's callback interfaces, and lets MockServer compute the response — or the request to forward — dynamically. It is pure JSON over the control plane, so it works fully from the PHP client.

Object / closure callbacks are not available in PHP. MockServer also supports object (closure) callbacks, where the callback runs in your own process: the client opens a callback WebSocket, the server hands it a clientId, and on each match it streams the request to your code, which returns the response. The PHP client is REST-only and does not implement that callback WebSocket, so object/closure callbacks cannot be used from PHP — use a class callback (a class on the MockServer classpath) instead. This is a transport limitation of the PHP client, not of MockServer.

See examples/php/callback for a runnable example.

Verification

Retrieving Recorded Data

Control Operations

SRE Control Plane

Methods for resilience verification — load generation, fault injection, SLO verdicts, preemption (cordon/drain) and scheduled chaos experiments. Some are gated behind a server start-up flag and raise FeatureNotEnabledException (HTTP 403) until that flag is set.

Mocking LLM APIs

Fluent builders under the MockServer\Llm namespace mock provider-agnostic LLM completions, embeddings, multi-turn conversations and provider failover. The wire JSON they produce is identical to the Java, Node and Python clients, so a mock scripted from PHP behaves the same as one scripted anywhere else.

Mocking MCP Servers

MockServer\Mcp\McpMockBuilder emulates a Streamable-HTTP MCP (Model Context Protocol) server speaking JSON-RPC 2.0. It generates the full set of expectations — initialize, ping, notifications/initialized, plus tools/list + tools/call, resources/list + resources/read and prompts/list + prompts/get for any tools, resources and prompts declared.

Every builder also exposes build() to obtain the raw Expectation object(s) without registering them (a single Expectation for llmMock, or an array of Expectation for conversations, failover and MCP).

Mocking A2A Agents

MockServer\A2a\A2aMockBuilder emulates an A2A (Agent-to-Agent) agent speaking JSON-RPC 2.0 over HTTP. It generates the agent card (GET /.well-known/agent.json by default) plus the tasks/send, tasks/get and tasks/cancel JSON-RPC methods, and optionally streaming (SSE) and push-notification delivery. A2A is purely declarative (request matchers plus templated/literal responses), so it is fully supported by the REST-only PHP client.

When withPushNotifications(...) is set, each tasks/send returns the JSON-RPC task response to the caller and POSTs the completed task to the webhook URL, and the agent card advertises capabilities.pushNotifications: true. Custom onTaskSend() handlers are matched by a regular expression against params.message.parts[0].text. Like the MCP builder, build() returns the raw array of Expectation objects without registering them.

Start / Launch MockServer

The PHP client does not include a binary launcher (PHP lacks the native WebSocket and subprocess management required for embedded launch). To start MockServer, use one of the following approaches:

• Docker: docker run -d -p 1080:1080 mockserver/mockserver
• Executable JAR: java -jar mockserver-netty-no-dependencies-<version>.jar -serverPort 1080
• Homebrew: brew install mockserver && mockserver -serverPort 1080
• Another client's launcher: The Node, Python, Ruby, Go, .NET, and Rust clients can each download and launch MockServer automatically without Java or Docker.

See the Running MockServer documentation for all available options.

Building

Using in tests (PHPUnit)

MockServer\Testing\MockServerTestTrait provides a MockServerClient and resets the server before and after each test, so recorded requests, expectations and logs never leak between tests. Mix it into your PHPUnit test case and call the lifecycle helpers from setUp() / tearDown():

The server URL is read from the MOCKSERVER_URL environment variable (for example http://localhost:1080); when it is unset the test is skipped.

Running Tests

Unit tests (no server required):

Integration tests (requires a running MockServer):

License

Apache 2.0 - see LICENSE