Download the PHP package treblle/treblle-php without Composer

Treblle - Runtime Intelligence Platform

Website • Documentation • Pricing

Discover, Govern, and Secure APIs, Agents, and AI Across Any Cloud, Gateway or Technology.

Treblle PHP SDK

Requirements

Installation

Setup

Add one line at the top of your entry point (e.g. index.php) before any output:

Both credentials are available in your Treblle Dashboard.

That's it. Treblle will automatically capture request and response data and ship it to the ingress asynchronously after your response has been sent.

Configuration

Pass options as the third argument to Treblle::create():

Or build a config object directly for more control:

sdkToken

Your Treblle SDK Token obtained from the Treblle Dashboard.

apiKey

Your Treblle API Key obtained from the Treblle Dashboard.

enabled

Controls whether Treblle is active. Defaults to true. Set to false to disable the SDK in specific environments without removing your credentials.

debug

When true, the SDK writes diagnostic messages to the PHP error log prefixed with [TREBLLE]. All messages are suppressed by default.

Useful for:

• Verifying your credentials are correct
• Seeing which requests are skipped and why
• Diagnosing ingress connectivity issues

Example debug output:

Debug output goes to wherever PHP's error_log is configured - typically your web server error log or a file defined in php.ini.

masked_keywords

Field names to mask in request bodies, response bodies, request headers, and response headers. Masking replaces every character of the value with *, preserving the original length, and is applied recursively to nested objects and arrays.

The SDK ships with a sensible default list. You control the list entirely - extend it, replace it, or set it to [] to disable masking.

The Authorization header is masked with scheme-preserving formatting (e.g. Bearer ****) when it appears in the keyword list.

excluded_paths

Paths that should not be tracked by Treblle. Supports exact matches, wildcards, and regular expressions.

Exact match - the full path must match character for character (case-insensitive):

Wildcard - use * (any sequence) or ? (any single character):

Regex - any string that starts and ends with / is treated as a regex:

custom_ingress

Override the default ingress endpoint. Useful for EU-hosted or self-hosted Treblle deployments:

Endpoint Detection

In plain PHP we are unable to effectively determine the endpoint path for a request. Example for: articles/12345 the endpoint path would be: articles/{id}. This allows us to build a much more accurate representation of how your API works.

However there are two ways to supply it to us:

Option 1 - Treblle::setRoutePath()

Call this after your router has resolved the route, before the request completes:

Works with any routing library. Example with nikic/fast-route:

Option 2 - $_SERVER['TREBLLE_ROUTE_PATH']

Set the server variable anywhere before the shutdown handler runs. Useful when Treblle is initialised in a bootstrap file and the route path is resolved in a different layer:

You can also set it from .htaccess for simple setups where a rewrite rule maps to a known pattern:

setRoutePath() always takes priority over $_SERVER['TREBLLE_ROUTE_PATH'].

Enrich Requests With Metadata

Attach custom key/value pairs to any request that will show up on the Treblle dashboard and you can filter/search for requests with specific metadata.

Note: user-id is a reserved keyword for helping us build entire customer dashboards and track customer usage across your API.

Call Treblle::metadata() anywhere during the request lifecycle - in a middleware, after authentication, inside a controller. Multiple calls are merged together:

The final payload will contain both sets of keys:

Metadata values can be any JSON-serializable type: strings, integers, booleans, or nested arrays.

In persistent runtimes (Swoole, RoadRunner, FrankenPHP), call Treblle::reset() at the start of each request cycle to clear metadata from the previous request alongside all other request state.

PSR-15 Middleware

If your application uses a PSR-15 compatible framework (Slim, Mezzio, Laravel via league/route, etc.) you can use TreblleMiddleware instead of Treblle::create(). The middleware integrates directly into the PSR-15 stack, reads request and response data from the PSR-7 objects (no output buffering), and ships the payload asynchronously via a shutdown function after the response has been delivered.

Register it as the outermost middleware so it wraps the full request/response cycle and captures all headers and the complete response body.

All options from Treblle::create() are supported as the third argument:

Or construct with a config object directly:

Route path in PSR-15

Supply the parameterised route pattern via a PSR-7 request attribute named _treblle_route_path. Most routers let you set attributes on the request object before calling the handler:

Treblle::setRoutePath() also works from inside the handler if you prefer that approach.

Metadata in PSR-15

Treblle::metadata() works the same way - call it anywhere inside the handler or its downstream middleware:

Async Mode

The SDK sends data to Treblle after your response has been delivered, using the first available strategy:

1. fastcgi_finish_request() (PHP-FPM) - flushes the HTTP response to the client and continues running in the background. The Treblle call is completely invisible to your end users. This is the default in most production PHP deployments.

2. pcntl_fork() (Linux/Unix CLI and FPM where pcntl is available) - forks a child process to send the data. The parent process returns immediately.

3. Sync fallback - if neither of the above is available, the data is sent synchronously after the response is flushed. This adds network latency to your shutdown phase but does not affect the response your users receive.

No configuration is required. The SDK detects the environment at runtime and picks the best available strategy.

Migrating from v5 to v6

1. Update the package

2. Remove the Guzzle dependency

v6 uses native PHP curl - Guzzle is no longer required. If your project only pulled it in for Treblle, you can remove it:

If other packages in your project depend on Guzzle, leave it - removing it won't break anything, it's simply no longer used by this SDK.

3. Replace TreblleFactory::create() with Treblle::create()

The factory class is gone. Initialisation now goes through Treblle::create() directly.

Before (v5):

After (v6):

Note that the parameter order is reversed - sdkToken is now first.

4. Update renamed and moved options

Full before/after example:

5. Review maskedFields vs masked_keywords

In v5, $maskedFields was additive - the SDK merged your list with its own defaults.

In v6, masked_keywords is the full list. If you pass a value, it replaces the defaults entirely. To extend the defaults, merge them explicitly:

6. excludedHeaders is removed

v5's $excludedHeaders excluded header names from being sent to Treblle at all. v6 does not have this option. Instead:

• To hide the value of a sensitive header, add its name to masked_keywords - the value will be replaced with * characters.

7. Async is now automatic

In v5, background sending required explicitly setting config['fork_process' => true] and having the pcntl extension available.

In v6, the SDK automatically uses the best available async strategy at runtime - fastcgi_finish_request() in PHP-FPM environments, pcntl_fork() on Unix where available, and a sync fallback otherwise. No configuration needed.

License

The MIT License (MIT). See LICENSE for details.