# Installation

## Requirements

From the package's `composer.json`:

- PHP **^8.4**
- Laravel **12 or 13**

## 1. Install the package

```bash
composer require ranetrace/ranetrace-laravel
```

The service provider and `Ranetrace` facade alias are auto-discovered.

## 2. Add your key to your environment

```dotenv
RANETRACE_ENABLED=true
RANETRACE_KEY=your-key-here
```

`RANETRACE_KEY` authenticates with the API, and without it nothing is captured. `RANETRACE_ENABLED` is the master switch over every feature and defaults to `true`, so it only needs setting to switch Ranetrace off. Set them wherever Ranetrace should run. That is your **production** environment; add them to a local `.env` as well if you want to test the connection during development.

## 3. Wire up error reporting

Error tracking is on by default, so register Ranetrace on Laravel's exception handler in `bootstrap/app.php`. Without this line, unhandled exceptions are **not** captured:

```php
use Illuminate\Foundation\Configuration\Exceptions;
use Ranetrace\Laravel\Facades\Ranetrace;

->withExceptions(function (Exceptions $exceptions) {
    Ranetrace::handles($exceptions);
})
```

See [Error tracking](/docs/error-tracking) for what gets captured and how to report manually.

## 4. Publish the config (optional)

```bash
php artisan vendor:publish --tag=ranetrace-laravel-config
```

This creates `config/ranetrace.php`. The defaults are usable as-is; publish only if you want to customize buffer sizes, queue names, per-feature timeouts, or the lists of ignored JS errors / excluded log channels / excluded analytics paths.

## 5. Verify the connection

```bash
php artisan ranetrace:status
```

Status output shows which features are enabled, buffer sizes, and any active pauses.

## What's enabled by default

Defaults straight from `config/ranetrace.php`:

| Feature | Default |
|---|---|
| Error tracking (`errors.enabled`) | **On** |
| Event tracking (`events.enabled`) | **On** |
| Centralized logging (`logging.enabled`) | Off |
| Website analytics (`website_analytics.enabled`) | Off |
| JavaScript errors (`javascript_errors.enabled`) | Off |

## Next step

Schedule [the worker](/docs/the-worker): without it, buffered data never reaches the API.