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

winglet / client

Maintainers

Package info

Statistics

Security