Download the PHP package traffical/sdk without Composer

Traffical PHP SDK

Traffical is one control plane for experimentation, feature flags, and adaptive optimization. Instead of hard-coding decisions, you expose typed parameters — numbers, strings, booleans, and JSON, not just on/off toggles — and control behavior across web, mobile, push, and backend from a single place. Parameters are resolved locally in the SDK (sub-millisecond, no network round trips at runtime), and metrics are computed warehouse-native, against data you own. Start with a feature flag, graduate it to an A/B test, and let adaptive optimization shift traffic to the winning allocation — all on the same parameter, without a deploy.

This package is the official PHP SDK (PHP ^8.1) that brings the Traffical parameter control plane to your PHP services.

Features

• Local, in-process evaluation — resolve a cached config bundle with no per-decision network call.
• Typed parameters with safe defaults — bool / string / number / JSON, each with a caller-provided fallback.
• Layered experimentation & targeting — Google-style layered isolation, condition/attribute segmentation, and progressive (percentage) rollouts.
• Adaptive optimization — contextual-bandit scoring evaluated client-side.
• BYO warehouse-native assignment logging — route structured assignment rows through your own pipeline (Segment, RudderStack, a DB, a queue) so assignment data never has to leave your infrastructure.
• Event tracking — exposure, decision, and custom track events, batched and flushed PHP-FPM-aware via fastcgi_finish_request() so the response returns before events are sent.
• Plugin system — hook into the decide / exposure / track lifecycle from day one.
• PSR-first & framework-ready — PSR-18 HTTP, PSR-17 factories, PSR-16 cache, PSR-3 logger, and PSR-20 clock are all injectable; first-party Laravel, Symfony, and OpenFeature integrations.

Modes

• Bundle mode (default) — the SDK fetches a config bundle, caches it (shared across PHP-FPM workers via a PSR-16 store), and resolves every parameter locally. No per-decision network call.
• Server mode — resolution is delegated to the Traffical edge via POST /v1/resolve (cached per request). Use it when you want zero client-side evaluation logic.

Further reading

• docs/warehouse-native.md — BYO assignment logging and warehouse-native metrics
• docs/plugins.md — the plugin lifecycle and built-in plugins
• docs/php-lifecycle.md — event batching and flushing under PHP-FPM
• docs/conformance.md — cross-language determinism and the bundle-vs-server tradeoffs
• examples/ — runnable examples: basic, server mode, warehouse-native BYO, custom plugin, plus Symfony guides

Installation

You also need a PSR-18 HTTP client and PSR-17 factories. Any compliant implementation works; the SDK auto-discovers them via php-http/discovery:

Quickstart (bundle mode)

Decide + track exposure

decide() returns a DecisionResult (assignments + metadata). Call trackExposure() when the user actually sees the treatment so exposures are attributed correctly.

Server mode

Delegate resolution to the edge worker instead of evaluating a local bundle. Each getParams()/decide() performs (and caches per request) a POST /v1/resolve.

See docs/conformance.md for the bundle-vs-server tradeoffs.

BYO warehouse-native assignment logging

Pass an assignmentLogger to route structured rows through your own pipeline. The WarehouseNativeLogger helper maps each entry to a snake_case row (including the stable policy_key/allocation_key used for warehouse joins):

Full guide: docs/warehouse-native.md.

Plugins

Hook into the SDK lifecycle (onBeforeDecision, onDecision, onExposure, onTrack, …). Built-ins: DebugPlugin, DecisionTrackingPlugin, WarehouseNativeLoggerPlugin.

Full guide: docs/plugins.md.

Framework integrations

• Laravel — auto-discovered TrafficalServiceProvider + Traffical facade. See examples/laravel.md.
• Symfony — TrafficalBundle with a traffical config tree. See examples/symfony.md.
• OpenFeature — optional TrafficalProvider (requires open-feature/sdk).

PHP lifecycle

The client registers a shutdown handler that calls fastcgi_finish_request() (when available) so the HTTP response is returned to the user before events are flushed. See docs/php-lifecycle.md.

Configuration reference

ClientOptions is an immutable value object. Construct it with named arguments, or refine an existing instance with the fluent with*() methods (each returns a new instance):

Request timeouts. PSR-18 defines no portable timeout API, so the SDK cannot set connect/read timeouts on an arbitrary injected or auto-discovered HTTP client. The configTimeoutMs / eventsTimeoutMs / resolveTimeoutMs options carry the spec's intended values (10s / 10s / 5s); configure the matching timeout on the PSR-18 client you pass as httpClient (e.g. Guzzle's connect_timeout / timeout) to enforce them.

Cross-language conformance

The PHP SDK shares the language-agnostic Traffical SDK spec with the JS/TS and Swift SDKs: the same SHA-256 v2 (UTF-8 byte) bucketing, the same layered resolution engine, and the same contextual-bandit scoring. Every release is gated on the spec's deterministic conformance vectors, so a given unit buckets identically on every platform. The fixtures are pinned via the tests/sdk-spec git submodule and run as part of composer conformance.

Development

Conformance fixtures are pinned via the tests/sdk-spec git submodule. After cloning:

License

MIT