# Instalare pe Laravel

> Pachetul Composer pentru Laravel — instalare, proxy-uri, scheduler și cache.

Pachetul adaugă un middleware care vede boții AI și oamenii veniți din asistenți, și trimite datele prin coada
aplicației tale.

**Cerințe:** PHP 8.2 sau mai nou, Laravel 11, 12 sau 13.

## Instalare

1. **Creează o cheie** în Survelium → **Setări brand → Integrări → Creează cheia**. Apare o singură dată.
2. Până când pachetul e pe Packagist, adaugă ambele repo-uri în `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. Instalează pachetul:

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

4. Pune cheia în `.env`:

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

5. Verifică:

   ```bash
   php artisan survelium:flush --force   # trimite acum; așteaptă „Survelium answered 202”
   php artisan survelium:status
   ```

Atât. Middleware-ul se adaugă singur în grupul `web` și lucrează după ce răspunsul a plecat. Fără cheie nu face nimic,
deci mediile locale și CI rămân liniștite.

## Înainte să-l lași să ruleze, verifică

- **În spatele Cloudflare sau al unui load balancer**, configurează
  [trusted proxies](https://laravel.com/docs/requests#configuring-trusted-proxies), ca `$request->ip()` să întoarcă IP-ul
  real. Altfel boții nu pot fi [verificați](https://survelium.ro/docs/ai-traffic/crawlers.md#verificarea).
- **Scheduler-ul rulează** (`* * * * * php artisan schedule:run` în cron). `survelium:flush` e programat la 5 minute;
  fără el datele pleacă doar când vin vizite noi.
- **Un cache de pagini în fața PHP-ului** (Varnish, LiteSpeed, Cloudflare „cache everything”) ascunde boții care citesc
  paginile din cache. Exclude din cache user agent-ii boților AI ([lista](https://survelium.ro/docs/ai-traffic/crawlers.md#lista-botilor)).

## Ce numără

Doar afișările de pagină: cereri `GET`/`HEAD` care nu sunt XHR, Livewire sau prefetch. Datele stau în
`storage/app/survelium` și pleacă la 50 de elemente sau la 60 de secunde, printr-un job pe coadă (pe coada `sync`
rulează după răspuns).

## Configurare

```bash
php artisan vendor:publish --tag="survelium-config"
```

| Opțiune | Implicit | |
|---|---|---|
| `ingest_key` | `SURVELIUM_INGEST_KEY` | Fără cheie nu se întâmplă nimic. |
| `enabled` | `SURVELIUM_ENABLED`, `true` | |
| `track_referrals` | `true` | `false` = doar boții AI. |
| `middleware_groups` | `['web']` | `[]` și adaugi tu `TrackAgentAnalytics` unde vrei. |
| `deny_paths` | Telescope, Horizon, Pulse, Debugbar, `/up` | Căi nici raportate, nici numărate. |
| `queue.connection`, `queue.name` | coada implicită | `SURVELIUM_QUEUE_CONNECTION`, `SURVELIUM_QUEUE`. |
| `schedule` | `true` | Programează `survelium:flush` la 5 minute. |

**Pe mai multe servere web**, fiecare are buffer-ul și totalul lui. Accesările boților se adună corect, dar totalul
zilnic vine de la un singur server, deci [procentul de trafic AI](https://survelium.ro/docs/ai-traffic/traffic-share.md) iese mai mare.