Download the PHP package treblle/treblle-laravel without Composer

Treblle - Runtime Intelligence Platform

Website • Documentation • Pricing

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

Treblle Laravel SDK

Table of Contents

• Requirements
• Installation
• Quick Start
• Registering Middleware
  • Laravel 11 and 12
  • Laravel 10 and below
• Applying Middleware to Routes
• Excluding Routes from Monitoring
• Configuration Reference
• Environment Variables
• Advanced Features
  • Multi-Project Setup
  • Early Payload Capture
  • Custom Metadata
  • Queue-Based Transmission
  • Sensitive Data Masking
  • Header Exclusion
  • Debug Mode
• Verifying Your Setup
• Upgrading
  • v6.0 → v6.1
  • v5.x → v6.0

Requirements

Installation

Step 1 — Install via Composer:

Step 2 — Add your credentials to .env:

Get your API Key and SDK Token for free at platform.treblle.com.

Step 3 — (Optional) Publish the config file:

This creates config/treblle.php where you can customize all settings.

Quick Start

Apply the treblle middleware to the routes you want to monitor:

That's it. Requests to those routes will appear in your Treblle Dashboard in real time.

Registering Middleware

The treblle and treblle.early middleware aliases are registered automatically by the service provider. You do not need to add anything to your kernel or bootstrap file to use them.

If for some reason you need to register them manually, here's how:

Laravel 11 and 12

In bootstrap/app.php:

Laravel 10 and below

In app/Http/Kernel.php:

Applying Middleware to Routes

Monitor all routes in a group

Monitor a single route

Monitor only specific routes within a group

Excluding Routes from Monitoring

There are two ways to exclude specific routes from Treblle monitoring when the middleware is applied at a group level.

Option 1 — withoutMiddleware() on a route

Use Laravel's built-in withoutMiddleware() method directly on the routes you want to exclude:

Both the alias ('treblle') and the full class name work.

Option 2 — Exclude an entire nested group

Option 3 — Never apply the middleware in the first place

The simplest approach: only apply treblle where you want it, not to everything.

Configuration Reference

After publishing the config file, config/treblle.php contains all available options:

Environment Variables

Advanced Features

Multi-Project Setup

If you have multiple APIs in the same Laravel application and want to track them as separate projects in Treblle, pass the API key directly as a middleware parameter. This overrides the global TREBLLE_API_KEY for those routes.

The per-route API key always takes precedence over TREBLLE_API_KEY in .env.

Early Payload Capture

By default, Treblle captures request data after all middleware has run. If you have middleware that transforms the request body (e.g. normalising a legacy format, converting XML to JSON), you may want to capture what the client actually sent.

The treblle.early middleware solves this. Place it at the start of your middleware chain to snapshot the raw payload before anything else touches it.

Middleware order matters:

Example — API versioning:

With treblle.early, Treblle captures the original v1 payload the client sent. Without it, you'd only see the normalised v2 data.

Custom Metadata

Every Treblle payload includes a metadata object. By default it is empty. You can populate it with any key/value data you want to attach to requests — tenant IDs, feature flags, deployment versions, trace IDs, etc.

There are two ways to set metadata:

1. Static metadata (applies to every request)

Set it once in config/treblle.php:

2. Per-request metadata via the Treblle facade

The Treblle facade is the cleanest way to attach metadata at runtime. Call it from anywhere during the request lifecycle — controllers, service classes, middleware, event listeners.

Calls to Treblle::meta() always merge — calling it multiple times is safe and additive.

In a controller:

In a middleware (applies to all routes the middleware is on):

In a service class (no Request injection needed):

Merging behaviour: Per-request metadata is merged over static config metadata. If both define the same key, the runtime value wins.

What ends up in the payload:

Queue-Based Transmission

By default, Treblle sends data synchronously using Laravel's terminable middleware pattern — after the response is sent to the client, before the PHP process ends. This is non-blocking and has no impact on response time for most applications.

For high-throughput APIs or when you want to fully decouple transmission from the web process, enable queue mode:

Make sure your queue worker is running:

Supported connections:

Sensitive Data Masking

Fields listed in masked_fields have their values replaced with ***** before any data leaves your server. This happens at the PHP level — the values never reach Treblle.

Masking is case-insensitive and applies recursively to nested objects and arrays in both request and response bodies.

Example:

Header Exclusion

Headers listed in excluded_headers are completely removed from the data sent to Treblle. Unlike field masking, excluded headers do not appear at all — not even as *****.

Pattern types:

Debug Mode

Enable debug mode to log Treblle warnings and errors to your Laravel log file:

With debug enabled, you'll see log entries when:

• Configuration is missing (TREBLLE_SDK_TOKEN, TREBLLE_API_KEY)
• Data transmission fails
• The response exceeds the 2MB limit

Only use this during development. Disable it in production.

Verifying Your Setup

1. Run the built-in test command:

This checks your credentials, validates your environment, sends a real test payload to Treblle's ingress, and tells you exactly what's wrong if anything fails:

2. Check the about command:

Look for the Treblle section — shows your SDK version, URL, and masked credentials.

3. Make a real request and check your dashboard:

Log in to platform.treblle.com and confirm the request appears in real time.

4. Common issues:

Upgrading

v6.0 → v6.1

New configuration keys — if you have published config/treblle.php, two new keys are available. They are filled in automatically via deep-merge if missing, so no action is required, but you can add them explicitly for clarity:

If your published config has 'url' => null — update it to the line above. The old null default caused the ingress URL to resolve to an empty string, silently breaking data transmission. The new default reads from TREBLLE_API_URL and falls back to https://ingress.treblle.com.

ignored_methods behaviour — HEAD and OPTIONS were already silently excluded before v6.1 via a hardcoded fallback. This release makes the list explicit and configurable. No behaviour change for existing users.

Queue sub-keys — if you had a partial queue block in your published config (e.g. only enabled), the missing sub-keys (connection, queue) are now filled in from package defaults automatically. No action required.

Steps:

v5.x → v6.0

Breaking: environment variable rename

The values are swapped — update your .env:

Breaking: middleware parameter rename

Steps: