PHP code example of treblle / treblle-laravel

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

treblle / treblle-laravel example snippets

// routes/api.php
Route::middleware(['treblle'])->group(function () {
    Route::get('/users', [UserController::class, 'index']);
    Route::post('/users', [UserController::class, 'store']);
    Route::get('/users/{id}', [UserController::class, 'show']);
});

use Treblle\Laravel\Middlewares\TreblleMiddleware;
use Treblle\Laravel\Middlewares\TreblleEarlyMiddleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withMiddleware(function ($middleware) {
        $middleware->alias([
            'treblle'       => TreblleMiddleware::class,
            'treblle.early' => TreblleEarlyMiddleware::class,
        ]);
    })
    ->create();

protected $middlewareAliases = [
    // ... other middleware
    'treblle'       => \Treblle\Laravel\Middlewares\TreblleMiddleware::class,
    'treblle.early' => \Treblle\Laravel\Middlewares\TreblleEarlyMiddleware::class,
];

Route::middleware(['treblle'])->group(function () {
    Route::get('/users', [UserController::class, 'index']);
    Route::post('/users', [UserController::class, 'store']);
    Route::get('/users/{id}', [UserController::class, 'show']);
    Route::put('/users/{id}', [UserController::class, 'update']);
    Route::delete('/users/{id}', [UserController::class, 'destroy']);
});

Route::get('/users/{id}', [UserController::class, 'show'])
    ->middleware('treblle');

Route::prefix('api/v1')->group(function () {

    // These routes are monitored
    Route::middleware(['treblle'])->group(function () {
        Route::get('/products', [ProductController::class, 'index']);
        Route::get('/orders', [OrderController::class, 'index']);
    });

    // These routes are not monitored
    Route::post('/internal/cache/clear', [CacheController::class, 'clear']);
    Route::post('/internal/queue/retry', [QueueController::class, 'retry']);

});

Route::middleware(['treblle'])->group(function () {

    Route::get('/users', [UserController::class, 'index']);
    Route::post('/users', [UserController::class, 'store']);

    // This route is excluded from Treblle monitoring
    Route::get('/users/export', [UserController::class, 'export'])
        ->withoutMiddleware('treblle');

    // This route is also excluded
    Route::post('/users/bulk-import', [UserController::class, 'bulkImport'])
        ->withoutMiddleware(\Treblle\Laravel\Middlewares\TreblleMiddleware::class);

});

Route::middleware(['treblle'])->prefix('api')->group(function () {

    // Monitored routes
    Route::get('/users', [UserController::class, 'index']);
    Route::get('/products', [ProductController::class, 'index']);

    // This entire group is excluded
    Route::withoutMiddleware('treblle')->prefix('internal')->group(function () {
        Route::post('/cache/clear', [CacheController::class, 'clear']);
        Route::get('/health', [HealthController::class, 'check']);
        Route::post('/queue/retry', [QueueController::class, 'retry']);
    });

});

// routes/api.php

// Monitored
Route::middleware(['auth:sanctum', 'treblle'])->group(function () {
    Route::apiResource('users', UserController::class);
    Route::apiResource('orders', OrderController::class);
});

// Not monitored — no treblle middleware
Route::middleware(['auth:sanctum'])->prefix('internal')->group(function () {
    Route::get('/health', [HealthController::class, 'check']);
    Route::post('/cache/flush', [CacheController::class, 'flush']);
});

return [

    /*
    |--------------------------------------------------------------------------
    | Enable / Disable Monitoring
    |--------------------------------------------------------------------------
    | Set to false to completely disable Treblle. Useful for maintenance windows,
    | load testing, or when you want to turn it off without removing middleware.
    |
    | Env: TREBLLE_ENABLE
    | Default: true
    */
    'enable' => env('TREBLLE_ENABLE', true),

    /*
    |--------------------------------------------------------------------------
    | Treblle Ingress URL
    |--------------------------------------------------------------------------
    | The endpoint Treblle data is sent to. Only change this if you are running
    | a self-hosted Treblle instance or pointing at a test endpoint.
    |
    | Env: TREBLLE_API_URL
    | Default: https://ingress.treblle.com
    */
    'url' => env('TREBLLE_API_URL', 'https://ingress.treblle.com'),

    /*
    |--------------------------------------------------------------------------
    | SDK Token
    |--------------------------------------------------------------------------
    | Your Treblle SDK Token. Found in your Treblle account settings.
    | Previously called TREBLLE_API_KEY in v5.x.
    |
    | Env: TREBLLE_SDK_TOKEN
    | Required: yes
    */
    'sdk_token' => env('TREBLLE_SDK_TOKEN'),

    /*
    |--------------------------------------------------------------------------
    | API Key
    |--------------------------------------------------------------------------
    | Your Treblle project API Key. Identifies which project this data belongs to.
    | Previously called TREBLLE_PROJECT_ID in v5.x.
    |
    | Env: TREBLLE_API_KEY
    | Required: yes
    */
    'api_key' => env('TREBLLE_API_KEY'),

    /*
    |--------------------------------------------------------------------------
    | Ignored Environments
    |--------------------------------------------------------------------------
    | Treblle will not send any data when your app is running in one of these
    | environments. Comma-separated list. Compared against app()->environment().
    |
    | Env: TREBLLE_IGNORED_ENV
    | Default: dev,test,testing
    */
    'ignored_environments' => env('TREBLLE_IGNORED_ENV', 'dev,test,testing'),

    /*
    |--------------------------------------------------------------------------
    | Masked Fields
    |--------------------------------------------------------------------------
    | Field names listed here will have their values replaced with asterisks
    | before the data leaves your server. Matching is case-insensitive and
    | applies to both request body and response body.
    |
    | The fields below are masked by default. Add your own sensitive fields.
    */
    'masked_fields' => [
        'password',
        'pwd',
        'secret',
        'password_confirmation',
        'cc',
        'card_number',
        'ccv',
        'ssn',
        'credit_score',
        'api_key',
    ],

    /*
    |--------------------------------------------------------------------------
    | Excluded Headers
    |--------------------------------------------------------------------------
    | Headers listed here are completely removed before the data is sent to
    | Treblle. Supports exact match, wildcard patterns, and regex.
    |
    | Examples:
    |   'authorization'       — exact match (case-insensitive)
    |   'x-*'                 — all headers starting with x-
    |   '*-token'             — all headers ending with -token
    |   '/^x-(api|auth)-/i'  — regex pattern
    */
    'excluded_headers' => [],

    /*
    |--------------------------------------------------------------------------
    | Custom Metadata
    |--------------------------------------------------------------------------
    | Static key/value pairs 

// Public API — Project A
Route::middleware(['treblle:api_key_project_a'])->prefix('api/public')->group(function () {
    Route::get('/products', [PublicProductController::class, 'index']);
    Route::get('/categories', [PublicCategoryController::class, 'index']);
});

// Partner API — Project B
Route::middleware(['treblle:api_key_project_b'])->prefix('api/partner')->group(function () {
    Route::get('/orders', [PartnerOrderController::class, 'index']);
    Route::post('/webhooks', [PartnerWebhookController::class, 'handle']);
});

// Admin API — Project C
Route::middleware(['treblle:api_key_project_c'])->prefix('api/admin')->group(function () {
    Route::get('/analytics', [AdminAnalyticsController::class, 'index']);
});

// Correct — treblle.early runs first, before any transformations
Route::middleware(['treblle.early', 'transform-legacy-format', 'treblle'])->group(function () {
    Route::post('/api/v1/orders', [OrderController::class, 'store']);
});

// Wrong — treblle.early after transformation is pointless
Route::middleware(['transform-legacy-format', 'treblle.early', 'treblle'])->group(function () {
    Route::post('/api/v1/orders', [OrderController::class, 'store']);
});

// Clients send v1 format, your app works with v2 format internally
Route::middleware(['treblle.early', 'normalize-to-v2', 'treblle'])
    ->prefix('api/v1')
    ->group(function () {
        Route::post('/users', [UserController::class, 'store']);
    });

'metadata' => [
    'environment' => env('APP_ENV'),
    'region'      => env('AWS_DEFAULT_REGION', 'us-east-1'),
    'version'     => '2.4.1',
],

use Treblle\Laravel\Facades\Treblle;

// Single key/value
Treblle::meta('tenant_id', auth()->user()->tenant_id);

// Multiple key/values at once
Treblle::meta([
    'tenant_id' => auth()->user()->tenant_id,
    'plan'      => auth()->user()->plan,
    'trace_id'  => $request->header('X-Trace-Id'),
]);

use Treblle\Laravel\Facades\Treblle;

class OrderController extends Controller
{
    public function store(Request $request): JsonResponse
    {
        Treblle::meta([
            'tenant_id'    => auth()->user()->tenant_id,
            'plan'         => auth()->user()->plan,
            'order_source' => 'api',
        ]);

        // ... create the order
    }
}

use Treblle\Laravel\Facades\Treblle;

class AttachTreblleContext
{
    public function handle(Request $request, Closure $next)
    {
        Treblle::meta([
            'trace_id'  => $request->header('X-Trace-Id', (string) Str::uuid()),
            'tenant_id' => $request->header('X-Tenant-Id'),
        ]);

        return $next($request);
    }
}

use Treblle\Laravel\Facades\Treblle;

class PaymentService
{
    public function charge(array $data): void
    {
        Treblle::meta('payment_gateway', 'stripe');

        // ... process payment
    }
}

// config/treblle.php
'queue' => [
    'enabled'    => env('TREBLLE_QUEUE_ENABLED', false),
    'connection' => env('TREBLLE_QUEUE_CONNECTION', 'redis'),
    'queue'      => env('TREBLLE_QUEUE_NAME', 'default'),
],

// config/treblle.php
'masked_fields' => [
    'password',
    'pwd',
    'secret',
    'password_confirmation',
    'cc',
    'card_number',
    'ccv',
    'ssn',
    'credit_score',
    'api_key',
    // Add your own
    'access_token',
    'refresh_token',
    'private_key',
    'stripe_secret',
],

// config/treblle.php
'excluded_headers' => [
    // Exact match (case-insensitive)
    'authorization',
    'cookie',
    'x-api-key',

    // Wildcard — all headers starting with x-internal-
    'x-internal-*',

    // Wildcard — all headers ending with -token
    '*-token',

    // Wildcard — headers containing -secret-
    '*-secret-*',

    // Regex — headers matching x-api- or x-auth-
    '/^x-(api|auth)-/i',
],

// config/treblle.php

// Override the Treblle ingress endpoint (e.g. for custom deployments or local testing)
'url' => env('TREBLLE_API_URL', 'https://ingress.treblle.com'),

// HTTP methods Treblle will never monitor
'ignored_methods' => ['HEAD', 'OPTIONS'],

// Static metadata sent with every request (per-request metadata merges over this)
'metadata' => [],

// Old (v5.x)
Route::middleware(['treblle:project-id-1'])

// New (v6.0)
Route::middleware(['treblle:api-key-1'])

bash
php artisan vendor:publish --provider="Treblle\Laravel\TreblleServiceProvider"

bash
php artisan queue:work redis --queue=treblle

bash
php artisan treblle:test

bash
php artisan about