# Install on Laravel

> The Composer package for Laravel — install, proxies, scheduler and cache.

The package adds a middleware that sees AI crawlers and people arriving from assistants, and sends the data through
your app's queue.

**Requirements:** PHP 8.2 or newer, Laravel 11, 12 or 13.

## Install

1. **Create a key** in Survelium → **Brand settings → Integrations → Create key**. It is shown once.
2. Until the package is on Packagist, add both repositories to `composer.json`:

   ```json
   "repositories": [
       { "type": "vcs", "url": "https://github.com/survelium/agent-analytics-laravel" },
       { "type": "vcs", "url": "https://github.com/survelium/agent-analytics-php" }
   ]
   ```

3. Install the package:

   ```bash
   composer require survelium/agent-analytics-laravel:^0.1@dev
   ```

4. Put the key in `.env`:

   ```dotenv
   SURVELIUM_INGEST_KEY=svk_...
   ```

5. Check it:

   ```bash
   php artisan survelium:flush --force   # sends now; expects "Survelium answered 202"
   php artisan survelium:status
   ```

That is all. The middleware adds itself to the `web` group and works after the response has gone out. Without a key
it does nothing, so local and CI stay quiet.

## Before you leave it running, check

- **Behind Cloudflare or a load balancer**, configure
  [trusted proxies](https://laravel.com/docs/requests#configuring-trusted-proxies) so `$request->ip()` returns the real
  IP. Otherwise crawlers cannot be [verified](https://survelium.com/docs/ai-traffic/crawlers.md#verification).
- **The scheduler runs** (`* * * * * php artisan schedule:run` in cron). `survelium:flush` is scheduled every five
  minutes; without it data only goes out when new visits arrive.
- **A page cache in front of PHP** (Varnish, LiteSpeed, Cloudflare "cache everything") hides the crawlers reading
  cached pages. Exclude AI crawler user agents from it ([the list](https://survelium.com/docs/ai-traffic/crawlers.md#crawler-list)).

## What it counts

Page views only: `GET`/`HEAD` requests that are not XHR, Livewire or prefetch. The data sits in
`storage/app/survelium` and goes out every 50 items or 60 seconds, through a queued job (on the `sync` queue it runs
after the response).

## Configuration

```bash
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` = AI crawlers only. |
| `middleware_groups` | `['web']` | `[]` and add `TrackAgentAnalytics` yourself where you want it. |
| `deny_paths` | Telescope, Horizon, Pulse, Debugbar, `/up` | Paths neither reported nor counted. |
| `queue.connection`, `queue.name` | the default queue | `SURVELIUM_QUEUE_CONNECTION`, `SURVELIUM_QUEUE`. |
| `schedule` | `true` | Schedules `survelium:flush` every five minutes. |

**On several web servers**, each keeps its own buffer and total. Crawler hits add up correctly, but the daily total
comes from one server, so the [AI traffic share](https://survelium.com/docs/ai-traffic/traffic-share.md) reads higher.