surfgeo/laravel-aireferral-sdk

Track AI bot traffic (ChatGPT, Claude, Perplexity) in Laravel applications

dev-main 2026-01-06 12:54 UTC

Requires

• php: ^8.1
• guzzlehttp/guzzle: ^7.0
• illuminate/http: ^10.0|^11.0
• illuminate/support: ^10.0|^11.0

Requires (Dev)

• mockery/mockery: ^1.5
• orchestra/testbench: ^8.0|^9.0
• phpunit/phpunit: ^10.0

MIT

• surfgeo

• analytics
• bot
• laravel
• tracking
• ai
• ChatGpt
• claude
• perplexity
• surfgeo

README

Track AI bot traffic in your Laravel applications.

Installation

composer require surfgeo/laravel-aireferral-sdk

Quick Start

1. Publish Configuration

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

Or use the install command:

php artisan surfgeo:install

2. Configure Environment

Add to your .env file:

SURFGEO_SCRIPT_KEY=sk_your_key_here
SURFGEO_ENABLED=true

3. Test Connection

php artisan surfgeo:test

Configuration

Full configuration options in config/surfgeo.php:

return [
    'script_key' => env('SURFGEO_SCRIPT_KEY', ''),
    'endpoint' => env('SURFGEO_ENDPOINT', 'https://api.surfgeo.com/api/track'),
    'enabled' => env('SURFGEO_ENABLED', true),
    'timeout' => env('SURFGEO_TIMEOUT', 0.05),
    'debug' => env('SURFGEO_DEBUG', false),
    'async' => env('SURFGEO_ASYNC', false),
    'excluded_paths' => ['/health-check', '/metrics'],
    'excluded_environments' => ['local', 'testing'],
];

Usage

Automatic Tracking

The middleware automatically tracks all requests. No additional code needed.

Custom Tracking

Use the facade to track custom events:

use surfgeo\Laravel\Facades\surfgeo;

surfgeo::track([
    'timestamp' => time(),
    'path' => '/custom-event',
    'method' => 'POST',
    'user_agent' => request()->userAgent(),
]);

Features

• ✅ Auto-discovered service provider
• ✅ Laravel HTTP client integration
• ✅ Queue-based tracking (optional)
• ✅ Artisan commands (install, test)
• ✅ Facade for convenience
• ✅ Path and environment exclusions
• ✅ Debug logging

License

MIT