Client Common Laravel Package

Getting Started

Start by installing the package via Composer and selecting a HTTPlug-compatible client (e.g., php-http/guzzle6-adapter). You’ll typically use ClientCommon to wrap your base client with middleware-style plugins. For a minimal setup:

composer require php-http/client-common php-http/guzzle6-adapter

Then instantiate your decorated client:

use Http\Client\Common\Client;
use Http\Client\Common\PluginClient;
use Http\Client\Common\Plugins\ RetryPlugin;
use Http\Discovery\Psr17FactoryDiscovery;
use GuzzleHttp\Client as GuzzleClient;

$guzzle = new GuzzleClient(['base_uri' => 'https://api.example.com']);
$pluginClient = new PluginClient($guzzle, [
    new RetryPlugin(['retries' => 3]),
]);

// Now use $pluginClient like any HTTPlug client
$request = Psr17FactoryDiscovery::findRequestFactory()->createRequest('GET', '/users');
$response = $pluginClient->sendRequest($request);

The primary entry point is PluginClient, which composes a base HTTPlug client with an array of plugins.

Implementation Patterns

• Plugin Stack Composition: Use multiple plugins (e.g., AuthenticationPlugin, RedirectPlugin, HistoryPlugin, RetryPlugin) to build a layered client. Order matters — plugins are applied sequentially from top to bottom.
• Library-Ready Clients: As a library author, depend on Http\Client\Common\ClientInterface and let downstream consumers provide their own decorated client via HTTPlug’s discovery or DI.
• Test Isolation: Inject a decorated PluginClient and swap the underlying base client with a mock or in-memory client (e.g., php-http/mock-client) for unit tests.
• Custom Plugins: Extend Http\Client\Common\Plugin\AbstractPlugin and override handleRequest() / handleResponse() to implement custom logic (e.g., rate limiting, logging correlation IDs).
• Consistent Defaults: Use ClientCommon::create() to instantiate with sensible defaults (e.g., autodiscovery of PSR-17 factories), then override via the second argument for customization.

Gotchas and Tips

• Middleware vs Plugin Confusion: Plugins are HTTPlug’s middleware abstraction — not PSR-15 request handlers. They receive RequestInterface and FutureInterface, and must return either a response or a future.
• Plugin Order: A RedirectPlugin must precede an AuthenticationPlugin if redirect URLs require re-authentication (e.g., 302 to OAuth callback), otherwise the auth token may be lost on redirect.
• RetryPlugin Pitfall: By default, retries only cover network-level errors (TransferException). To retry on 5xx responses, pass 'retry_successful' => true and use RetryStrategyInterface for custom logic.
• Factory Discovery: ClientCommon relies on php-http/discovery to find PSR-17/18 implementations. If discovery fails, explicitly inject factories via ClientCommon::create([], $requestFactory, $streamFactory, ...).
• Caching Gotcha: The CachePlugin requires a cache adapter (e.g., symfony/cache), a cache policy (CachePlugin::DEFAULT_STRATEGY), and a cache key generator — misconfiguration leads to uncacheable requests or duplicate entries.
• Error Propagation: Exceptions from plugins (e.g., AuthenticationPlugin throwing AuthenticationException) bubble up — prefer catching Http\Client\Exception\HttpException or Throwable and inspecting the original request via $exception->getRequest().