survelium / agent-analytics-laravel
Laravel integration for Survelium agent analytics: report AI crawlers and AI-referred visitors server-side.
Package info
github.com/survelium/agent-analytics-laravel
pkg:composer/survelium/agent-analytics-laravel
Requires
- php: ^8.2
- illuminate/contracts: ^11.0||^12.0||^13.0
- spatie/laravel-package-tools: ^1.16
- survelium/agent-analytics-php: ^0.1
Requires (Dev)
- larastan/larastan: ^3.0
- laravel/pint: ^1.14
- nunomaduro/collision: ^8.1
- orchestra/testbench: ^9.0||^10.0||^11.0
- pestphp/pest: ^3.0||^4.0
- pestphp/pest-plugin-arch: ^3.0||^4.0
- pestphp/pest-plugin-laravel: ^3.0||^4.0
- phpstan/extension-installer: ^1.4
- phpstan/phpstan-deprecation-rules: ^2.0
- phpstan/phpstan-phpunit: ^2.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-17 12:21:27 UTC
README
See which AI crawlers read your Laravel site and how many people AI assistants send you, in Survelium.
AI crawlers (GPTBot, ClaudeBot, PerplexityBot, …) do not run JavaScript, so a JS snippet never sees them. This
package adds a middleware that recognises them on the server, plus visitors arriving from ChatGPT, Perplexity,
Claude, Gemini or Copilot, and sends them to Survelium in batches from your queue. It is built on
survelium/agent-analytics-php.
What leaves your server
| Sent | Never sent | |
|---|---|---|
| AI crawler hit | time, user agent, path, HTTP status, IP (to verify it is really that crawler) | — |
| Visitor from an AI assistant | time, assistant domain (e.g. chatgpt.com), path, user agent |
IP, full referrer, cookies, session |
| Every page view by a person | a daily count, used for "share of traffic from AI" (other bots — Googlebot, SEO tools, monitors — are not counted) | anything about the request |
Requirements
PHP 8.2+, Laravel 12 or 13. Laravel 11 still installs, but is no longer tested: every 11.x release has open security advisories, so Composer refuses it by default.
Installation
composer require survelium/agent-analytics-laravel
Add your ingest key (Survelium → AI traffic → Integration) to .env:
SURVELIUM_INGEST_KEY=svk_...
Check it works:
php artisan survelium:flush --force # sends now; expects "Survelium answered 202"
php artisan survelium:status
That is all. The middleware is added to the web group automatically and does its work in terminate(),
after the response has been sent. Without a key nothing is recorded, so local and CI stay quiet.
Before you go live, check
- Behind Cloudflare or a load balancer: configure Laravel's trusted proxies (see Configuration), or every crawler arrives with the proxy's IP and Survelium cannot verify it.
- The scheduler runs (
* * * * * php artisan schedule:runin cron). Without it data still goes out, but only when new visits arrive. - A full-page cache in front of PHP (Varnish, LiteSpeed, Cloudflare "cache everything",
spatie/laravel-responsecacheserved by the web server) means cached pages never reach Laravel, so crawlers reading them are not seen. Exclude AI crawler user agents from that cache.
How it sends
- Hits are buffered in
storage/app/survelium. Every 50 items or 60 seconds aFlushAgentAnalyticsjob is queued (at most one a minute). On thesyncqueue it runs after the response, so visitors never wait. survelium:flushis scheduled every five minutes, so the buffer and the daily total also go out on quiet days. This needs the Laravel scheduler (schedule:runin cron) to be running.- If Survelium is unreachable the data stays buffered and is retried with back-off; a revoked key or a plan without AI traffic pauses sending without losing data.
Only page views are tracked: GET/HEAD requests that are not XHR, Livewire or prefetch requests.
Configuration
php artisan vendor:publish --tag="survelium-config"
| Option | Default | |
|---|---|---|
ingest_key |
SURVELIUM_INGEST_KEY |
Nothing happens while empty. |
enabled |
SURVELIUM_ENABLED, true |
|
track_referrals |
true |
false = crawlers only. |
middleware_groups |
['web'] |
Set [] and add TrackAgentAnalytics yourself for full control. |
deny_paths |
Telescope, Horizon, Pulse, Debugbar, /up |
Path prefixes neither reported nor counted. |
storage_path |
storage/app/survelium |
|
queue.connection, queue.name |
app default | SURVELIUM_QUEUE_CONNECTION, SURVELIUM_QUEUE. |
schedule |
true |
Registers survelium:flush every five minutes. |
Behind a load balancer or Cloudflare, configure Laravel's
trusted proxies so $request->ip() returns the
crawler's real IP; otherwise Survelium cannot verify it.
If you run several web servers, each keeps its own buffer and daily count. Crawler hits add up correctly, but the daily total is taken from one server at a time, so the AI share reads higher than it is.
Testing
composer test
Changelog
See CHANGELOG.
Security
Please report vulnerabilities through GitHub security advisories, not in issues.
License
The MIT License (MIT). See License File.