HookShot

A Laravel package for capturing and tracking HTTP requests with configurable storage drivers and filtering options.

Overview

HookShot provides middleware-based HTTP request tracking for Laravel applications. It captures request/response data and stores it using database, cache, or file storage drivers with configurable filtering and performance controls.

How it works: The middleware captures request data during the request lifecycle and stores the complete request/response information during Laravel's terminate phase, ensuring your application's response time is not affected by the logging process.

Why HookShot?

• 🔍 Debug Issues - Reproduce bugs by seeing exactly what requests caused them
• 📊 Analytics - Track API usage patterns, popular endpoints, and user behavior
• 🛡️ Security - Monitor suspicious requests and track authentication attempts
• 📋 Compliance - Meet audit requirements with comprehensive request logging
• ⚡ Performance - Identify slow endpoints and optimize request handling
• 🔌 API Monitoring - Track external API integrations and webhook deliveries

Requirements

• PHP 8.2+
• Laravel 11.x, 12.x

Installation

Install via Composer:

composer require vildanbina/hookshot

Publish configuration:

php artisan vendor:publish --tag=hookshot-config

Run migrations for database storage:

php artisan migrate

Usage

Middleware Registration

Manual Registration (Recommended)

Apply to specific routes:

Route::middleware('track-requests')->group(function () {
    Route::get('/api/users', [UserController::class, 'index']);
    Route::post('/api/users', [UserController::class, 'store']);
});

Global Registration (Laravel 11+)

Add to bootstrap/app.php:

->withMiddleware(function (Middleware $middleware) {
    $middleware->append(\VildanBina\HookShot\Middleware\TrackRequestsMiddleware::class);
})

Retrieving Tracked Data

use VildanBina\HookShot\Facades\RequestTracker;

// Get all recent requests
$requests = RequestTracker::get(50);

// Find specific request by ID
$request = RequestTracker::find('uuid-here');

// Get requests with database driver (supports advanced queries)
$slowRequests = RequestTracker::query()
    ->where('execution_time', '>', 2.0)
    ->where('response_status', '>=', 400)
    ->get();

// Filter by date range
$todayRequests = RequestTracker::query()
    ->whereDate('timestamp', today())
    ->get();

Event Integration

Listen to request capture events:

use VildanBina\HookShot\Events\RequestCaptured;
use Illuminate\Support\Facades\Event;

Event::listen(RequestCaptured::class, function (RequestCaptured $event) {
    $request = $event->request;
    $requestData = $event->requestData;
    
    // Do something with the request and request data
});

Features

Storage Drivers:

• Database: Full query support with Eloquent models
• Cache: In-memory storage with configurable TTL
• File: JSON or raw format file logging
• Custom: Implement your own storage driver

Filtering & Sampling:

• Path exclusion patterns
• User agent filtering
• Configurable sampling rates
• Content-type based exclusions

Performance Controls:

• Request/response payload size limits
• Queue-based processing support
• Automatic data retention cleanup

Security:

• Sensitive header filtering
• Authentication data redaction
• Configurable data sanitization

Configuration

All configuration options with their purposes:

<?php

declare(strict_types=1);

return [
    /*
    |--------------------------------------------------------------------------
    | HookShot Request Tracking
    |--------------------------------------------------------------------------
    |
    | This file contains the configuration options for HookShot request tracking.
    | You can enable/disable tracking, choose storage drivers, and configure
    | filtering options to control what gets tracked.
    |
    */

    // Enable or disable request tracking globally
    'enabled' => env('HOOKSHOT_ENABLED', true),

    // Default storage driver: 'database', 'cache', or 'file'
    'default' => env('HOOKSHOT_DRIVER', 'database'),

    /*
    |--------------------------------------------------------------------------
    | Storage Drivers
    |--------------------------------------------------------------------------
    |
    | Configure how and where request data is stored. Each driver has its own
    | settings for connection, retention, and other storage-specific options.
    |
    */
    'drivers' => [
        'database' => [
            'connection' => env('HOOKSHOT_DB_CONNECTION'),
            'table' => env('HOOKSHOT_TABLE', 'hookshot_logs'),
            'retention_days' => 30,
        ],

        'cache' => [
            'store' => env('HOOKSHOT_CACHE_STORE'),
            'prefix' => 'hookshot',
            'retention_days' => 7,
            'max_index_size' => 10000,
        ],

        'file' => [
            'path' => storage_path('app/hookshot'),
            'format' => 'json', // json or raw
            'retention_days' => 30,
        ],
    ],

    /*
    |--------------------------------------------------------------------------
    | Exclusion Filters
    |--------------------------------------------------------------------------
    |
    | Define which requests should be excluded from tracking to reduce noise
    | and focus on meaningful application requests.
    |
    */

    // Paths to exclude from tracking (health checks, admin panels, etc.)
    'excluded_paths' => [
        'health-check',
        'up',
        '_debugbar/*',
        'telescope/*',
        'horizon/*',
        'pulse/*',
    ],

    // User agents to exclude (monitoring tools, bots, crawlers)
    'excluded_user_agents' => [
        'pingdom',
        'uptimerobot',
        'googlebot',
        'bingbot',
    ],

    /*
    |--------------------------------------------------------------------------
    | Performance Controls
    |--------------------------------------------------------------------------
    |
    | Configure performance-related settings to manage resource usage and
    | ensure tracking doesn't impact application performance.
    |
    */

    // Percentage of requests to track (1.0 = 100%, 0.5 = 50%, etc.)
    'sampling_rate' => env('HOOKSHOT_SAMPLING_RATE', 1.0),

    // Maximum size of request payload to store (in bytes)
    'max_payload_size' => 65536, // 64KB

    // Maximum size of response body to store (in bytes)
    'max_response_size' => 10240, // 10KB

    // Queue request tracking for better performance
    'use_queue' => env('HOOKSHOT_USE_QUEUE', false),

    /*
    |--------------------------------------------------------------------------
    | Security Settings
    |--------------------------------------------------------------------------
    |
    | Configure security-related settings for request tracking to ensure
    | sensitive data is properly filtered and protected.
    |
    */

    // Headers to filter/redact in request and response tracking
    'sensitive_headers' => [
        'authorization',
        'cookie',
        'set-cookie',
        'x-api-key',
        'x-auth-token',
        'x-csrf-token',
        'x-xsrf-token',
    ],

    /*
    |--------------------------------------------------------------------------
    | Response Capture Settings
    |--------------------------------------------------------------------------
    |
    | Configure which responses should be captured and stored for analysis.
    | These settings help control what response data is worth storing.
    |
    */

    // Enable or disable response header capture (saves database space)
    'capture_response_headers' => env('HOOKSHOT_CAPTURE_RESPONSE_HEADERS', true),

    // Enable or disable response body capture (saves significant database space)
    'capture_response_body' => env('HOOKSHOT_CAPTURE_RESPONSE_BODY', true),

    // Content types to exclude from response body capture (prefix matching)
    'excluded_content_types' => [
        'image/',
        'video/',
        'audio/',
        'application/pdf',
        'application/zip',
        'application/octet-stream',
    ],

    // HTTP status codes that are considered important to capture
    'important_status_codes' => [
        200,  // OK
        201,  // Created  
        400,  // Bad Request
        401,  // Unauthorized
        403,  // Forbidden
        404,  // Not Found
        422,  // Unprocessable Entity
        500,  // Internal Server Error
    ], 
];

Commands

Cleanup Old Data

Remove old tracking data based on retention settings:

# Clean using default settings
php artisan hookshot:cleanup

# Clean specific driver
php artisan hookshot:cleanup --driver=database

# Dry run to see what would be deleted
php artisan hookshot:cleanup --dry-run

Storage Drivers

Database Driver

• Best for queryable, persistent data
• Supports complex filtering and relationships
• Automatic cleanup via retention settings

Cache Driver

• Fastest performance for temporary data
• Good for high-traffic applications
• Limited querying capabilities

File Driver

• Good for development and debugging
• Human-readable storage format
• No database dependencies

Custom Driver

You can create custom storage drivers to integrate with your own storage systems or services. Custom drivers must implement the StorageDriverContract.

Creating a Custom Driver

<?php

namespace App\HookShot\Drivers;

use Illuminate\Support\Collection;
use VildanBina\HookShot\Contracts\StorageDriverContract;
use VildanBina\HookShot\Data\RequestData;

class CustomApiDriver implements StorageDriverContract
{
    public function __construct(array $config = [])
    {
        // Initialize your driver with config (API keys, endpoints, etc.)
    }

    public function store(RequestData $requestData): bool
    {
        // Store the request data to your storage system
        // Return true on success, false on failure
    }

    public function find(string $id): ?RequestData
    {
        // Find and return a specific request by ID
        // Return null if not found
    }

    public function get(int $limit = 100): Collection
    {
        // Get multiple requests with the given limit
        // Return Collection of RequestData objects
    }

    public function delete(string $id): bool
    {
        // Delete a specific request by ID
        // Return true if deleted, false otherwise
    }

    public function cleanup(): int
    {
        // Clean up old requests based on retention policy
        // Return number of deleted requests
    }

    public function isAvailable(): bool
    {
        // Check if your storage system is available
        // Return true if operational, false otherwise
    }
}

Configuring Your Custom Driver

Add your custom driver to the configuration file:

// config/hookshot.php
'default' => 'custom',

'drivers' => [
    // other drivers
    
    'custom' => [
        'via' => \App\HookShot\Drivers\CustomApiDriver::class,
        'endpoint' => env('CUSTOM_ENDPOINT', 'https://api.example.com'),
        'api_key' => env('CUSTOM_KEY'),
    ],
],

The via key tells HookShot which class to use for this driver. The entire config array (including the via key) is passed to your driver's constructor.

Captured Data Structure

Each tracked request includes:

[
    'id' => 'uuid',
    'method' => 'POST',
    'url' => 'https://app.com/api/users',
    'path' => 'api/users',
    'headers' => ['accept' => ['application/json']],
    'payload' => ['name' => 'John', 'email' => '[email protected]'],
    'ip' => '192.168.1.1',
    'user_agent' => 'Mozilla/5.0...',
    'user_id' => 123,
    'timestamp' => '2024-01-15T10:30:00Z',
    'execution_time' => 0.250,
    'response_status' => 201,
    'response_body' => ['id' => 456, 'name' => 'John'],
]

Performance Tips

• High Traffic: Set sampling_rate to 0.1 (10%) or lower for production
• Heavy Workloads: Enable use_queue to process tracking asynchronously
• Memory Management: Limit max_payload_size and max_response_size based on your needs
• Reduce Noise: Use excluded_paths for health checks, admin routes, and static assets
• Storage Optimization: Configure retention_days for automatic cleanup of old data
• Database Space: Disable response capture to save significant storage space:
  • Set capture_response_headers to false in order to disable response header capture
  • Set capture_response_body to false in order to disable response body capture
  • Both can be individually controlled based on your storage and debugging needs

Contributing

See CONTRIBUTING for details.

Security Vulnerabilities

Please e-mail [email protected] to report any security vulnerabilities instead of using the issue tracker.

Credits

• Vildan Bina
• All Contributors

License

The MIT License (MIT). Please see License File for more information.