# Error Logging Setup

This template uses **Flare + Ignition** by Spatie for error logging.

## Overview

| Environment | Tool | Purpose |
|-------------|------|---------|
| Development | **Ignition** | Rich in-browser error pages with AI explanations |
| Development | **Telescope** (optional) | Request/query/job debugging dashboard |
| Production | **Flare** | Remote error tracking, notifications |

## Architecture

```
Development:
  Error → Ignition → Beautiful error page with:
                     - Stack trace with code context
                     - AI-powered explanations
                     - Click-to-open in VS Code
                     - Suggested solutions

Production:
  Error → Flare (remote) → Notifications (Slack/Email)
        ↓
  User sees clean 500.blade.php error page
```

## Setup

### 1. Run Post-Install Script

After creating your Laravel project:

```bash
# In Docker
make setup-tools

# Or manually
cd src
bash ../scripts/post-install.sh
```

### 2. Get Flare API Key

1. Sign up at [flareapp.io](https://flareapp.io)
2. Create a new project
3. Copy your API key

### 3. Configure Environment

**Development (.env):**
```env
FLARE_KEY=your_flare_key_here
IGNITION_THEME=auto
IGNITION_EDITOR=vscode
```

**Production (.env):**
```env
APP_DEBUG=false
FLARE_KEY=your_flare_key_here
```

## Ignition Features (Development)

### AI Error Explanations
Ignition can explain errors using AI. Click "AI" button on any error page.

### Click-to-Open in Editor
Errors link directly to the file and line in your editor.

Supported editors (set via `IGNITION_EDITOR`):
- `vscode` - Visual Studio Code
- `phpstorm` - PhpStorm
- `sublime` - Sublime Text
- `atom` - Atom
- `textmate` - TextMate

### Runnable Solutions
Ignition suggests fixes for common issues that you can apply with one click.

### Share Error Context
Click "Share" to create a shareable link for debugging with teammates.

## Telescope (Optional)

Telescope provides a debug dashboard at `/telescope` with:

- **Requests** - All HTTP requests with timing
- **Exceptions** - All caught exceptions
- **Logs** - Log entries
- **Queries** - Database queries with timing
- **Jobs** - Queue job processing
- **Mail** - Sent emails
- **Notifications** - All notifications
- **Cache** - Cache operations

### Installing Telescope

The post-install script offers to install Telescope. To install manually:

```bash
composer require laravel/telescope --dev
php artisan telescope:install
php artisan migrate
```

### Telescope in Production

Telescope is installed as a dev dependency. For production debugging:

1. Install without `--dev`
2. Configure authorization in `app/Providers/TelescopeServiceProvider.php`
3. Access via `/telescope` (requires authentication)

## Custom Error Pages

The post-install script creates custom error pages:

- `resources/views/errors/404.blade.php` - Not Found
- `resources/views/errors/500.blade.php` - Server Error
- `resources/views/errors/503.blade.php` - Maintenance Mode

These are shown to users in production while Flare captures the full error details.

## Flare Dashboard

In your Flare dashboard you can:

- View all errors with full stack traces
- See request data, session, user info
- Group errors by type
- Track error frequency over time
- Set up notifications (Slack, Email, Discord)
- Mark errors as resolved

## Testing Error Logging

### Test in Development

Add a test route in `routes/web.php`:

```php
Route::get('/test-error', function () {
    throw new \Exception('Test error for Flare!');
});
```

Visit `/test-error` to see:
- Ignition error page (development)
- Error logged in Flare dashboard

### Test in Production

```bash
php artisan down  # Enable maintenance mode
# Visit site - should see 503 page

php artisan up    # Disable maintenance mode
```

## Troubleshooting

### Errors not appearing in Flare
1. Check `FLARE_KEY` is set correctly
2. Verify `APP_ENV=production` and `APP_DEBUG=false`
3. Check network connectivity from server

### Ignition not showing AI explanations
1. Requires OpenAI API key in Flare settings
2. Available on paid Flare plans

### Telescope not loading
1. Run `php artisan telescope:install`
2. Run `php artisan migrate`
3. Clear cache: `php artisan config:clear`