FlightPHP SDK — Apirelio Documentation

Quickstart

Install the FlightPHP adapter.

Composer installs Flight and the shared PHP Core contract. Configure the project key, stable service name and deployment environment.

Terminalbash

composer require apirelio/flightphp:^1.0

.envbash

APIRELIO_API_KEY=apr_live_your_key
APIRELIO_ENDPOINT=https://apirelio.com
APIRELIO_SERVICE=billing-api
APIRELIO_ENVIRONMENT=production
APIRELIO_RELEASE=2026.08.28.1

Automatic tracking

Attach middleware to a route group.

Flight calls the adapter before and after each matched route. Named routes provide an additional stable operation name, while Flight's route pattern keeps endpoint cardinality bounded.

public/index.phpphp

use Apirelio\FlightPHP\ApirelioMiddleware;
use Apirelio\FlightPHP\Config as ApirelioConfig;
use flight\Engine;

$app = new Engine;
$apirelio = new ApirelioMiddleware($app, new ApirelioConfig(
    apiKey: $_ENV['APIRELIO_API_KEY'],
    endpoint: $_ENV['APIRELIO_ENDPOINT'],
    service: $_ENV['APIRELIO_SERVICE'],
    environment: $_ENV['APIRELIO_ENVIRONMENT'],
    release: $_ENV['APIRELIO_RELEASE'] ?? null,
    paths: ['/api/*'],
    bufferPath: __DIR__.'/../var/apirelio/events.ndjson',
));

$app->group('/api', function () use ($app): void {
    $app->get('/invoices/@id', [InvoiceController::class, 'show'], false, 'invoices:view');
}, [$apirelio]);

$app->start();

Errors stay native

The adapter observes Flight's flight.error lifecycle event and never replaces Flight's own exception handling.

Customer context

Resolve the authenticated account.

Resolvers receive the current Flight engine and route parameters, so they can translate your authentication state into stable customer and consuming-application identifiers.

Apirelio middlewarephp

use Apirelio\Core\Data\ApirelioApplication;
use Apirelio\Core\Data\ApirelioCustomer;

$apirelio = new ApirelioMiddleware(
    app: $app,
    config: $config,
    customerResolver: static function (Engine $app, array $params): ?ApirelioCustomer {
        $account = $app->get('authenticatedAccount');

        return $account === null ? null : new ApirelioCustomer(
            id: (string) $account->id,
            name: $account->name,
            plan: $account->plan,
        );
    },
    applicationResolver: static fn (Engine $app): ApirelioApplication =>
        new ApirelioApplication((string) $app->get('apiClientId')),
);

Diagnostics

Add bounded route context.

Add allowlisted scalar metadata or a stable error code inside the active route. PHP Core filters every value before delivery.

Route handlerphp

$apirelio->context()?->addMetadata(['region' => 'eu-central']);
$apirelio->context()?->setErrorCode('PAYMENT_REQUIRED');

Reliability

Keep delivery outside the response path.

Configure a writable NDJSON buffer in production. Locked local buffering batches telemetry and contains network failures without changing the Flight response.

Buffered deliveryphp

new ApirelioConfig(
    // ...
    bufferPath: __DIR__.'/../var/apirelio/events.ndjson',
    batchSize: 500,
    flushIntervalSeconds: 10,
)

Privacy boundary

Operational metadata only.

✓

Captured

Method, matched route, route name, status, duration, byte counts and bounded customer identity.

Excluded

Request and response bodies, query strings, cookies, credentials, client IPs and exception messages.

Fail-safe

SDK and ingestion failures cannot replace the customer response or hide the original exception.

Instrument FlightPHP APIs.