# Connect a Laravel app

> Install the lampwick/laravel package, add your project's ingest token to .env and run php artisan lampwick:agent next to your app.

The `lampwick/laravel` package sends requests, queries, jobs, exceptions, logs and more from your Laravel app to Lampwick. Your app hands its records to an agent on the same server at `127.0.0.1:2407`, so requests never wait on the network. The agent sends them in batches to `https://app.lampwick.dev/ingest`. While Lampwick is unreachable, it keeps up to 64 MB of records in memory and retries.

## Requirements

- PHP 8.2 or later with the `curl` extension.
- Laravel 12 or 13.
- Optional: the `pcntl` extension, so the agent sends its buffer when it stops.
- The project's ingest token, from its **Settings** page. Only team owners see it.

## Install the package

1. Add the package:

   ```bash
   composer require lampwick/laravel
   ```

2. Add the ingest token to `.env`:

   ```dotenv
   LAMPWICK_TOKEN=YOUR_PROJECT_TOKEN
   ```

   `YOUR_PROJECT_TOKEN` is the ingest token from the **Connect your app** card on the project's **Settings** page.

3. Optional: to send your application logs, add the `lampwick` channel to your log stack:

   ```dotenv
   LOG_STACK=single,lampwick
   ```

4. Start the agent:

   ```bash
   php artisan lampwick:agent
   ```

## Check that it works

In a second terminal, run:

```bash
php artisan lampwick:test
```

It sends a test log record straight to Lampwick, to check your token and network, and checks that the agent runs. Then open your app: the request shows up in Lampwick within seconds.

## Keep the agent running in production

Run one agent per server under a process manager, like a queue worker. Restart it after each deploy: it reads `.env` and the config only when it starts.

### Laravel Forge

Go to your server → **Daemons** → **New daemon**:

| Field | Value |
|---|---|
| Command | `php artisan lampwick:agent` |
| Directory | your site's directory, for example `/home/forge/example.com/current` |
| User | `forge` |
| Stop wait seconds | `15` |

### Supervisor

```ini
[program:lampwick-agent]
command=php /var/www/example.com/artisan lampwick:agent
directory=/var/www/example.com
user=www-data
autostart=true
autorestart=true
stopsignal=TERM
stopwaitsecs=15
redirect_stderr=true
stdout_logfile=/var/log/lampwick-agent.log
```

Replace `/var/www/example.com` and `www-data` with your app's directory and PHP user, then load the program:

```bash
sudo supervisorctl reread && sudo supervisorctl update
```

On `SIGTERM` the agent stops taking records, sends what it has buffered and exits within `LAMPWICK_AGENT_SHUTDOWN_TIMEOUT` seconds (10 by default). Keep `stopwaitsecs` above that.

### Docker and multiple servers

Every server or container that runs PHP needs an agent it can reach. Run it in the same container, or as a sidecar with `LAMPWICK_AGENT_LISTEN` set to `0.0.0.0:2407` for the agent and `agent:2407` for the app. Never expose the agent's port to the internet: it accepts data from anyone who can reach it.

## Configuration

Set everything with environment variables, or publish the config file with `php artisan vendor:publish --tag=lampwick-config`.

| Variable | Default | What it does |
|---|---|---|
| `LAMPWICK_TOKEN` | none | The project's ingest token. Without it nothing is captured. |
| `LAMPWICK_ENABLED` | `true` | `false` turns the instrumentation off. |
| `LAMPWICK_AGENT_LISTEN` | `127.0.0.1:2407` | Address the agent listens on and the app sends to. |
| `LAMPWICK_AGENT_SHUTDOWN_TIMEOUT` | `10` | Seconds the agent takes to send its buffer when it stops. |
| `LAMPWICK_SERVER` | hostname | Server name shown in Lampwick. |
| `LAMPWICK_DEPLOY` | Forge, Vapor or Cloud commit | Deployment identifier. |
| `LAMPWICK_REQUEST_SAMPLE_RATE` | `1.0` | Share of requests to capture, from 0.0 to 1.0. |
| `LAMPWICK_SCHEDULED_TASK_SAMPLE_RATE` | `1.0` | Same, for scheduled tasks. Keep it at 1: alerts about missed runs need every run. |
| `LAMPWICK_IGNORE_QUERIES` | `false` | Don't capture database queries. |
| `LAMPWICK_IGNORE_CACHE_EVENTS` | `false` | Don't capture cache hits, misses and writes. |
| `LAMPWICK_LOG_LEVEL` | `LOG_LEVEL` | Lowest log level sent through the `lampwick` channel. |
| `LAMPWICK_CAPTURE_REQUEST_PAYLOAD` | `false` | Include request bodies, with the fields below redacted. |
| `LAMPWICK_REDACT_PAYLOAD_FIELDS` | `_token,password,password_confirmation` | Comma-separated. |
| `LAMPWICK_REDACT_HEADERS` | `Authorization,Cookie,Proxy-Authorization,X-XSRF-TOKEN` | Comma-separated. |

The [package's README](https://github.com/lmpwck/laravel) lists every variable.

## Troubleshooting

| What you see | Cause and fix |
|---|---|
| Nothing shows up in Lampwick | Run `php artisan lampwick:test`. Check that the agent runs with the same `.env` as the app, and that `LAMPWICK_TOKEN` is set for both. |
| `address already in use` | Another agent already listens on that port. Stop it, or pick another `LAMPWICK_AGENT_LISTEN` (the app and the agent read the same setting). |
| `HTTP 401` in the agent's log | The token is wrong or the project was deleted. Copy it again from the project's **Settings** page. |
| A changed `.env` has no effect | The config is cached. Run `php artisan config:cache` again and restart the agent. |
| Two apps on one server mix up | They can't: the agent refuses payloads with another token. Give each app its own `LAMPWICK_AGENT_LISTEN` port. |