generated from theradcoza/Laravel-Docker-Dev-Template
332 lines
6.8 KiB
Markdown
332 lines
6.8 KiB
Markdown
# 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. 🔍
|