Initial commit

2026-03-24 17:01:12 +00:00
commit a88504357d
237 changed files with 34375 additions and 0 deletions
--- a/docs/error-logging.md
+++ b/docs/error-logging.md
@@ -0,0 +1,177 @@
+# 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`