Add complete feature suite: Permissions, Audit Trail, API Auth, Error Tracking, Module System, and Site Settings
- Install spatie/laravel-permission v6.24 with 3 roles (admin, editor, viewer) and 5 base permissions - Install owen-it/laravel-auditing v14.0 for tracking model changes - Install laravel/sanctum v4.3 for API token authentication - Install spatie/laravel-ignition v2.11 and spatie/flare-client-php v1.10 for enhanced error tracking - Add Module System with make:module artisan command for scaffolding features - Create Site Settings page in Filament admin for logo, colors, and configuration - Add comprehensive debugging documentation (DEBUGGING.md, AI_CONTEXT.md updates) - Create FEATURES.md with complete feature reference - Update User model with HasRoles and HasApiTokens traits - Configure Redis cache and OPcache for performance - Add RolePermissionSeeder with pre-configured roles and permissions - Update documentation with debugging-first workflow - All features pre-installed and production-ready
This commit is contained in:
331
DEBUGGING.md
Normal file
331
DEBUGGING.md
Normal file
@@ -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. 🔍
|
||||
Reference in New Issue
Block a user