README

winglet/client is the generic HTTP client infrastructure package for Winglet and compatible PHP microservice environments.

This package contains only the reusable technical client layer:

• target configuration loading
• authentication modes
• token caching
• retry and correlation-id middleware
• PSR-7 / PSR-17 / PSR-18 compatible HTTP handling
• optional Winglet bridge for reading config and inbound bearer tokens from a Winglet runtime

This package does not contain service-specific clients such as AuthClient or IdentityClient. Those should live in their own packages and depend on winglet/client.

Included namespaces

• Winglet\Client\Core\...
• Winglet\Client\Bridge\Winglet\...

Typical usage

Generic client outside Winglet

use Winglet\Client\Core\Config\ArrayTargetConfigRepository;
use Winglet\Client\Core\Factory\ClientFactory;

$repo = new ArrayTargetConfigRepository([
    'billing' => [
        'base_url' => 'https://billing.example.test',
        'auth' => [
            'mode' => 'static_bearer',
            'static_bearer' => 'example-token',
        ],
    ],
]);

$factory = new ClientFactory($repo, __DIR__ . '/var/cache/clients');
$billing = $factory->create('billing');

$response = $billing->getJson('/status');

Generic client inside Winglet

use Winglet\Client\Bridge\Winglet\WingletClientFactory;

$factory = new WingletClientFactory($appContext);
$authClient = $factory->client('auth');
$result = $authClient->getJson('/authorization/effective?identityId=123');

Authentication modes

Supported auth.mode values:

• none
• static_bearer
• service_token
• identity_session
• api_key
• mtls

Service token authentication

service_token is the common machine-to-machine authentication mode for Winglet-based service clients. Service-specific clients do not need their own authentication implementation; they should create their underlying ServiceClient through ClientFactory and let this package fetch and cache the bearer token.

$repo = new ArrayTargetConfigRepository([
    'auth' => [
        'base_url' => 'https://auth.example.test/winglet/Auth',
        'auth' => [
            'mode' => 'service_token',
            'service_token' => [
                'token_url' => 'https://identity.example.test/winglet/Identity/auth/service-token',
                'client_id' => 'identity',
                'client_secret' => getenv('IDENTITY_AUTH_CLIENT_SECRET'),
            ],
        ],
    ],
]);

The token request sent to Identity is:

{
  "clientId": "identity",
  "clientSecret": "..."
}

The expected Identity response is:

{
  "accessToken": "eyJ...",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "expiresAt": "2026-07-04T09:30:00+03:00"
}

ClientFactory wraps the token provider in CachedTokenProvider, so the client reuses the token until shortly before expiry instead of authenticating on every request. The generated Authorization: Bearer ... header is applied by middleware and is invisible to service-specific clients.

Service-specific clients

Service-specific clients should be implemented in separate packages, for example:

• winglet/auth-client
• winglet/identity-client
• winglet/subscription-client

A sample skeleton is included under examples/skeleton-client.

Development

composer install
composer run-script test