Initial commit

2026-03-24 17:01:12 +00:00
commit a88504357d
237 changed files with 34375 additions and 0 deletions
--- a/DEBUGGING.md
+++ b/DEBUGGING.md
@@ -0,0 +1,331 @@
+# Debugging Strategy
+
+**CRITICAL**: This template includes enhanced error tracking. Always check logs FIRST before guessing at solutions.
+
+## 🚨 Golden Rule: Logs First, Guessing Never
+
+When encountering errors:
+
+### ❌ WRONG Approach:
+1. See error message
+2. Guess at the cause
+3. Try random fixes
+4. Waste time
+
+### ✅ CORRECT Approach:
+1. **Check Laravel logs immediately**
+2. Read the full stack trace
+3. Identify the exact file and line
+4. Fix the root cause
+
+---
+
+## Error Tracking Suite
+
+This template includes:
+
+- **Spatie Laravel Ignition** v2.11.0 - Enhanced error pages
+- **Spatie Flare Client** v1.10.1 - Error tracking
+- **Laravel Logs** - Full context and stack traces
+
+---
+
+## How to Debug Errors
+
+### 1. Check Laravel Logs (PRIMARY METHOD)
+
+```bash
+# View recent errors
+docker-compose exec app tail -n 100 storage/logs/laravel.log
+
+# Search for specific error
+docker-compose exec app cat storage/logs/laravel.log | grep "ErrorType"
+
+# Watch logs in real-time
+docker-compose exec app tail -f storage/logs/laravel.log
+```
+
+**What you'll see:**
+- Exact file path and line number
+- Full stack trace
+- Variable values at time of error
+- User context (if logged in)
+
+### 2. Check Container Logs
+
+```bash
+# Application logs
+docker-compose logs --tail=50 app
+
+# Nginx logs (for 502/504 errors)
+docker-compose logs --tail=50 nginx
+
+# All services
+docker-compose logs --tail=50
+```
+
+### 3. Use Ignition Error Pages (Development)
+
+When `APP_DEBUG=true`, Laravel shows beautiful error pages with:
+- Code context (lines around the error)
+- Stack trace with clickable frames
+- Solution suggestions for common errors
+- Request data and environment info
+
+**Access**: Errors automatically show in browser during development
+
+---
+
+## Common Error Patterns
+
+### TypeError: htmlspecialchars() expects string, array given
+
+**Log Location**: `storage/logs/laravel.log`
+
+**What to look for**:
+```
+htmlspecialchars(): Argument #1 ($string) must be of type string, array given
+at /var/www/html/path/to/file.blade.php:LINE
+```
+
+**Root Cause**: Blade template trying to echo an array with `{{ }}`
+
+**Fix**: Use proper component or `@json()` directive
+
+---
+
+### 504 Gateway Timeout
+
+**Log Location**: 
+- `docker-compose logs nginx`
+- `storage/logs/laravel.log`
+
+**What to look for**:
+```
+upstream timed out (110: Operation timed out)
+```
+
+**Common Causes**:
+- Stale cache after package installation
+- Infinite loop in code
+- Database query timeout
+- Permission cache issues
+
+**Fix**:
+```bash
+docker-compose exec app php artisan cache:clear
+docker-compose exec app php artisan config:clear
+docker-compose exec app php artisan view:clear
+docker-compose exec app php artisan permission:cache-reset
+docker-compose restart app nginx
+```
+
+---
+
+### Database Connection Errors
+
+**Log Location**: `storage/logs/laravel.log`
+
+**What to look for**:
+```
+SQLSTATE[HY000] [2002] Connection refused
+```
+
+**Fix**:
+```bash
+# Check if database is running
+docker-compose ps
+
+# Check database logs
+docker-compose logs mysql
+
+# Restart database
+docker-compose restart mysql
+
+# Wait for database to be ready
+docker-compose exec mysql mysqladmin ping -h localhost
+```
+
+---
+
+### Redis Connection Errors
+
+**Log Location**: `storage/logs/laravel.log`
+
+**What to look for**:
+```
+php_network_getaddresses: getaddrinfo for redis failed
+```
+
+**Fix**:
+```bash
+# Check Redis is running
+docker-compose ps redis
+
+# Restart Redis
+docker-compose restart redis
+
+# Clear config cache
+docker-compose exec app php artisan config:clear
+```
+
+---
+
+## Debugging Workflow for AI Agents
+
+When a user reports an error, follow this exact sequence:
+
+### Step 1: Get the Full Error
+```bash
+docker-compose exec app cat storage/logs/laravel.log | grep -A 20 "ErrorType"
+```
+
+### Step 2: Identify Root Cause
+- Read the stack trace
+- Find the originating file and line
+- Understand what the code is trying to do
+
+### Step 3: Verify the Fix
+- Make the change
+- Clear relevant caches
+- Test the specific scenario that caused the error
+
+### Step 4: Document
+- Explain what was wrong
+- Show the fix
+- Explain why it works
+
+---
+
+## Cache Clearing Commands
+
+Always clear caches after:
+- Installing new packages
+- Changing configuration
+- Modifying service providers
+- Updating permissions/roles
+
+```bash
+# Clear all caches
+docker-compose exec app php artisan optimize:clear
+
+# Or individually
+docker-compose exec app php artisan cache:clear
+docker-compose exec app php artisan config:clear
+docker-compose exec app php artisan route:clear
+docker-compose exec app php artisan view:clear
+docker-compose exec app php artisan permission:cache-reset
+
+# Regenerate autoloader
+docker-compose exec app composer dump-autoload
+```
+
+---
+
+## Performance Debugging
+
+### Slow Page Loads
+
+**Check**:
+1. Laravel Debugbar (if installed)
+2. Query count and time
+3. OPcache status
+4. Redis connection
+
+**Commands**:
+```bash
+# Check OPcache status
+docker-compose exec app php -i | grep opcache
+
+# Monitor Redis
+docker-compose exec redis redis-cli monitor
+
+# Check query logs
+# Enable in config/database.php: 'log_queries' => true
+```
+
+---
+
+## Production Error Tracking
+
+For production, consider:
+
+1. **Flare** (https://flareapp.io)
+   - Add `FLARE_KEY` to `.env`
+   - Automatic error reporting
+   - Error grouping and notifications
+
+2. **Sentry** (alternative)
+   ```bash
+   composer require sentry/sentry-laravel
+   ```
+
+3. **Log Aggregation**
+   - Papertrail
+   - Loggly
+   - CloudWatch
+
+---
+
+## Best Practices
+
+### ✅ DO:
+- Check logs before making changes
+- Read the full stack trace
+- Clear caches after changes
+- Test the specific error scenario
+- Document the fix
+
+### ❌ DON'T:
+- Guess at solutions without checking logs
+- Make multiple changes at once
+- Skip cache clearing
+- Assume the error message tells the whole story
+- Leave debugging code in production
+
+---
+
+## Quick Reference
+
+| Error Type | First Check | Quick Fix |
+|------------|-------------|-----------|
+| TypeError | Laravel logs | Check variable types |
+| 504 Timeout | Nginx logs | Clear caches, restart |
+| Database | MySQL logs | Check connection, restart DB |
+| Redis | Laravel logs | Restart Redis, clear config |
+| Permission | Laravel logs | `permission:cache-reset` |
+| View | Laravel logs | `view:clear` |
+| Route | Laravel logs | `route:clear` |
+
+---
+
+## Log File Locations
+
+| Service | Log Location |
+|---------|--------------|
+| Laravel | `storage/logs/laravel.log` |
+| Nginx | Docker logs: `docker-compose logs nginx` |
+| PHP-FPM | Docker logs: `docker-compose logs app` |
+| MySQL | Docker logs: `docker-compose logs mysql` |
+| Redis | Docker logs: `docker-compose logs redis` |
+
+---
+
+## Emergency Commands
+
+When everything is broken:
+
+```bash
+# Nuclear option - reset everything
+docker-compose down
+docker-compose up -d
+docker-compose exec app php artisan optimize:clear
+docker-compose exec app composer dump-autoload
+docker-compose exec app php artisan migrate:fresh --seed
+```
+
+**⚠️ WARNING**: `migrate:fresh` will delete all data!
+
+---
+
+**Remember**: Logs are your friend. Always check them first. 🔍