AuthorizationHeader

Pair framework: AuthorizationHeader

Pair\Http\AuthorizationHeader centralizes parsing for HTTP Authorization headers.

It is shared by Request, OAuth2Token, and the Pair API bootstrap path so Basic and Bearer credentials are read consistently across SAPIs.

Why it exists

Different web servers expose the Authorization header through different PHP variables. Pair checks the common server keys and falls back to apache_request_headers() when available.

This avoids having one auth path read HTTP_AUTHORIZATION while another misses the same request.

Main methods

fromGlobals(): ?string

Reads the raw Authorization header from the current request environment.

It checks:

• Authorization
• HTTP_AUTHORIZATION
• REDIRECT_HTTP_AUTHORIZATION
• apache_request_headers() fallback

The returned value is trimmed, and empty values become null.

fromServer(array $server): ?string

Reads the raw header from a server-like array. This is useful for tests and for code that wants deterministic input.

$header = \Pair\Http\AuthorizationHeader::fromServer([
    'HTTP_AUTHORIZATION' => 'Bearer opaque-token',
]);

bearerToken(?string $header): ?string

Extracts a Bearer token case-insensitively.

$token = \Pair\Http\AuthorizationHeader::bearerToken('Bearer opaque-token');

Only the standard Bearer <token> shape is accepted.

basicCredentials(?string $header): ?array

Extracts Basic credentials from a valid Authorization header.

$credentials = \Pair\Http\AuthorizationHeader::basicCredentials(
    'Basic ' . base64_encode('client-id:client-secret')
);

The returned array contains:

• id
• secret

Invalid base64 data, missing separators, and empty IDs or secrets return null.

Framework behavior

Request delegates header('Authorization') and bearerToken() to this helper.

OAuth2Token also uses this helper so legacy OAuth bearer checks and mobile/API bearer checks parse the same header value.

Common pitfalls

• Reading only $_SERVER['HTTP_AUTHORIZATION'] in custom code.
• Treating any value after Bearer as valid without checking the standard shape.
• Logging raw Authorization headers while debugging authentication failures.

See also: Request, OAuth2Token, ApiController, ApiToken, API.