Download the PHP package andy87/php-client-sdk without Composer

PHP Client SDK

Base abstractions for building typed PHP API clients.

Russian documentation

Overview

andy87/php-client-sdk provides a small set of reusable building blocks for API client SDKs:

• prompt DTOs for request method, endpoint, path parameters, query parameters, body and validation;
• response DTOs for normalized response data, status code, headers and API errors;
• provider base class for executing typed API methods;
• pluggable authorization strategies;
• pluggable HTTP transport with a native PHP stream implementation.

The package does not generate API clients and does not depend on a specific HTTP client library.

Requirements

• PHP 8.1 or higher.
• Composer.

Installation

Core Concepts

The package separates an API call into three parts:

• PromptInterface describes an outgoing request.
• ResponseInterface describes a typed API response.
• AbstractProvider connects prompts, responses, authorization and HTTP transport.

NativeHttpTransport can be used without extra dependencies. If a project needs another transport, implement HttpTransportInterface.

Prompt DTO

Extend AbstractPrompt to describe a request. The base class hydrates declared properties from input data, validates required fields, builds path/query/body arrays and normalizes nested DTO values through toArray() or toValue() when those methods exist.

Use PublicPrompt for public endpoints and PrivatePrompt for private endpoints with an authorization profile. AbstractPrompt remains the generic base class for custom prompt schemes.

Response DTO

Extend AbstractResponse to describe data returned by the API. On successful responses the base class hydrates properties listed in FIELD_MAP and validates REQUIRED_FIELDS. On HTTP errors it stores ApiError and skips required-field validation.

Provider Usage

Extend AbstractProvider and expose public methods for concrete API operations. The protected request() method validates the prompt, adds authorization headers when required, sends the HTTP request and returns the requested response DTO.

Create the provider with a base URL, authorization strategy and transport:

Client Options

ClientOptions is the main extension point. If it is not passed, the SDK uses safe defaults: JSON requests and responses, strict successful response validation, native no-retry policy and default request factory.

Configurable parts:

• timeout, headers, events;
• strictValidation;
• validatePrompt;
• retryPolicy;
• queryEncoder;
• bodyEncoder;
• responseDecoder;
• errorFactory;
• requestFactory.
• authorizationResolver;
• refreshAuthorizationStatusCodes.

Retry is disabled by default. Use DefaultRetryPolicy only when repeated requests are safe for the target API operation.

validatePrompt controls local prompt validation before a request is built. It is enabled by default. Set it to false only in mock or test environments where a client must return success fixtures for incomplete input:

refreshAuthorizationStatusCodes defaults to [401]. If the selected authorization strategy implements RefreshableAuthorizationStrategyInterface, the provider refreshes authorization and retries the request once after these statuses. Pass an empty list to disable this behavior.

Use BaseUrl when a client wants to configure protocol, host, port and path prefix separately:

Runtime Events and Headers

ClientRuntime stores default request headers and event listeners shared by a client and its providers. Pass the same runtime object to providers that must share headers and listeners.

Supported events:

• ClientEvents::AFTER_INIT after a concrete client finishes initialization.
• ClientEvents::BEFORE_REQUEST before transport sends a mutable HttpRequest.
• ClientEvents::AFTER_REQUEST after raw HTTP response is converted to a typed response DTO.
• ClientEvents::REQUEST_EXCEPTION after transport, JSON decoding or response DTO construction fails.

Header names are merged case-insensitively. Authorization headers override default runtime headers, and BEFORE_REQUEST listeners can still mutate the final request.

Authorization

Use NullAuthorizationStrategy for public APIs:

Use ClientCredentialsAuthorizationStrategy for OAuth client_credentials. The strategy requests an access token through the configured transport and caches it until it expires. By default, the token is stored in process memory.

Pass CacheInterface when the token must outlive the current PHP process. The SDK ships ArrayCache for memory scenarios and SimpleCacheAdapter for plugging in PSR-16/simple-cache compatible stores without adding a direct dependency on a concrete framework.

External cache payloads store access_token and expires_at. clockSkew controls early refresh: with 60, the strategy stops using the token 60 seconds before expires_at.

ClientCredentialsAuthorizationStrategy refreshes its cached token when a provider receives a configured refresh status, 401 by default, and then the provider retries the original request once.

Other built-in strategies:

• BearerTokenAuthorizationStrategy for a static Bearer token;
• BasicAuthorizationStrategy for HTTP Basic auth;
• ApiKeyAuthorizationStrategy for header or query API keys;
• CallbackAuthorizationStrategy for project-specific authorization headers.

Prompts require authorization by default. Override the prompt constant when a request is public:

Use an authorization resolver when different operations require different authorization strategies:

For PrivatePrompt subclasses, prefer profile names such as default, avito-client-credentials, api-key or sandbox-token:

HTTP Transport

NativeHttpTransport sends requests through PHP stream wrappers. It supports:

• query parameters;
• JSON request bodies;
• application/x-www-form-urlencoded request bodies;
• multipart/form-data request bodies through MultipartFile;
• already encoded raw request bodies;
• response status code and headers;
• JSON response decoding through HttpResponse::json().

Custom transports must implement HttpTransportInterface:

Mock Transport

MockTransport returns configured HttpResponse fixtures and never falls back to real network requests. Use it for test stands where a client must return successful API-shaped data without calling the external service.

Routes match by HTTP method and absolute URL, path or endpoint template stored in request metadata. OAuth token requests can be mocked by absolute token URL:

validatePrompt=false disables only Prompt::validate(). Request building can still fail when a prompt cannot provide a method, endpoint or required path placeholder.

If route paths are unstable or generated, use PromptClassMockResponseResolver to bind fixtures to Prompt DTO classes:

Traceable Transport

TraceableTransport wraps any HttpTransportInterface and records requests, responses, exceptions and duration without changing transport behavior.

Response DTOs can also store local diagnostic notes:

Error Handling

• Prompt validation throws InvalidArgumentException when a required field is missing or empty.
• Request factory validation can throw ValidationException when an endpoint contains an unfilled path placeholder.
• Authorization failures throw AuthorizationException.
• Transport failures throw TransportException.
• Successful non-JSON responses throw ResponseDecodeException.
• Response DTO construction failures throw ResponseHydrationException.
• HTTP responses with status code 400 or higher are converted to ApiError and available through ResponseInterface::getError(), including non-JSON error bodies.
• Successful responses with missing required fields throw UnexpectedValueException when strictValidation is enabled.

License

MIT.