Systematic Debugging for Laravel

Overview

Random fixes waste time and create new bugs in Laravel applications. Quick patches mask underlying issues.

Core principle: ALWAYS find root cause before attempting fixes. Symptom fixes are failure.

Violating the letter of this process is violating the spirit of debugging.

The Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

If you haven't completed Phase 1, you cannot propose fixes.

When to Use

Use for ANY Laravel technical issue:

• Test failures

• Eloquent query issues

• Authentication/authorization bugs

• Validation failures

• Queue job failures

• Route errors

• Migration issues

• N+1 query problems

• Performance issues

Use this ESPECIALLY when:

• Under time pressure

• "Just one quick fix" seems obvious

• You've already tried multiple fixes

• Previous fix didn't work

• You don't fully understand the issue

The Four Phases

You MUST complete each phase before proceeding to the next.

Phase 1: Root Cause Investigation

BEFORE attempting ANY fix:

Read Error Messages Carefully

SQLSTATE[23000]: Integrity constraint violation → Check foreign key constraints, not a code bug

Class 'App\Models\Post' not found → Check namespace, run composer dump-autoload

Method Illuminate\Database\Eloquent\Collection::save does not exist → get() returns Collection, not Model. Use first() or update()

Check Laravel Logs

Main Laravel log

tail -f storage/logs/laravel.log

Check for specific errors

grep "SQLSTATE" storage/logs/laravel.log

Clear logs if too large

storage/logs/laravel.log

Enable Debug Mode (Local Only)

APP_DEBUG=true APP_ENV=local

Use Laravel Telescope

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

Access at /telescope

View: Requests, Queries, Jobs, Events, Exceptions

Check Recent Changes

What changed that could cause this?

git log --oneline -10 git diff HEAD~5

Check if migrations ran

php artisan migrate:status

Check if config cached

php artisan config:show

Reproduce Consistently

Can you trigger it every time?

php artisan tinker

App\Models\Post::first();

Try in different environments

APP_ENV=testing php artisan test

Trace Data Flow for Eloquent Issues

// Enable query logging DB::listen(function ($query) { Log::debug('Query executed', [ 'sql' => $query->sql, 'bindings' => $query->bindings, 'time' => $query->time, ]); });

// Or in specific code DB::enableQueryLog(); $posts = Post::with('user')->get(); dd(DB::getQueryLog());

Phase 2: Pattern Analysis

Find the pattern before fixing:

Find Working Examples in Laravel

Search for similar working code

grep -r "belongsTo" app/Models/ grep -r "middleware" app/Http/

Check Laravel docs for the pattern

Check other models that work correctly

Compare Against Laravel Conventions

// ❌ What you have class Post extends Model { public function author() { return $this->hasOne(User::class, 'id', 'user_id'); } }

// ✅ Laravel convention class Post extends Model { public function user(): BelongsTo { return $this->belongsTo(User::class); } }

Check Laravel Documentation

• Read the COMPLETE section, don't skim

• Follow examples exactly first

• Customize only after understanding

Identify Differences

// Working model class User extends Model { protected $fillable = ['name', 'email']; }

// Broken model - difference: missing mass assignment protection class Post extends Model { // No $fillable or $guarded defined }

Phase 3: Hypothesis and Testing

Scientific method:

Form Single Hypothesis

Hypothesis: "Posts aren't saving because mass assignment protection is blocking the 'user_id' field"

Expected: Adding 'user_id' to $fillable will fix it

Test Minimally

// Before (broken) protected $fillable = ['title', 'content'];

// Test change (ONE variable) protected $fillable = ['title', 'content', 'user_id'];

// Don't change multiple things at once

Verify in Tinker

php artisan tinker

$post = Post::create(['title' => 'Test', 'content' => 'Test', 'user_id' => 1]); $post->user_id; // Should be 1

When You Don't Know

• Say "I don't understand why X is happening"

• Check Laravel GitHub issues for similar problems

• Ask in Laravel Discord/Forums with specifics

• Don't pretend to know

Phase 4: Implementation

Fix the root cause, not the symptom:

Create Failing Test Case

use Illuminate\Foundation\Testing\RefreshDatabase;

test('user can create post', function () { $user = User::factory()->create();

$response = $this->actingAs($user)
    ->post('/posts', [
        'title' => 'Test Post',
        'content' => 'Test content',
    ]);

$response->assertRedirect();

expect(Post::where('title', 'Test Post')->exists())->toBeTrue();
expect(Post::first()->user_id)->toBe($user->id);

});

// Run and watch it FAIL first php artisan test --filter=user_can_create_post

Implement Single Fix

// ONE fix for the root cause protected $fillable = ['title', 'content', 'user_id'];

// NO bundled improvements like: // - Adding casts // - Refactoring methods // - Changing other code

Verify Fix

Test passes now

php artisan test --filter=user_can_create_post

All tests still pass

php artisan test

Manual verification

php artisan tinker

$post = Post::create([...]);

If Fix Doesn't Work

• STOP

• Count: How many fixes have you tried?

• If < 3: Return to Phase 1 with new information

• If ≥ 3: STOP and question the approach

If 3+ Fixes Failed: Question Architecture

Pattern indicating architectural problem:

• Each fix reveals new shared state/coupling
• Fixes require "massive refactoring"
• Each fix creates new symptoms elsewhere

STOP and question fundamentals:

• Is this Laravel pattern correct?
• Should we use a different approach (repository/service)?
• Are we fighting the framework?

Discuss with team before attempting more fixes.

Laravel-Specific Debug Techniques

Eloquent Debugging

// See actual SQL $posts = Post::where('status', 'published'); dd($posts->toSql(), $posts->getBindings());

// Check relationship loading $post = Post::first(); $post->relationLoaded('user'); // false $post->load('user'); $post->relationLoaded('user'); // true

// Prevent lazy loading (catch N+1) Model::preventLazyLoading(!app()->isProduction());

Route Debugging

List all routes

php artisan route:list

Find specific route

php artisan route:list --name=posts

Check route exists

php artisan tinker

route('posts.show', 1);

Queue Debugging

See failed jobs

php artisan queue:failed

Retry failed job

php artisan queue:retry <id>

Work queue with verbose output

php artisan queue:work --verbose

Check job payload

php artisan tinker

DB::table('jobs')->first();

Validation Debugging

// See exact validation errors protected function failedValidation(Validator $validator) { Log::debug('Validation failed', [ 'errors' => $validator->errors()->toArray(), 'input' => $this->all(), ]);

parent::failedValidation($validator);

}

Red Flags - STOP and Follow Process

If you catch yourself thinking:

• "Quick fix for now, investigate later"

• "Just try changing X and see if it works"

• "Add protected $guarded = [] to see if that helps"

• "Skip the test, I'll manually verify"

• "It's probably the relationship definition"

• "I don't fully understand Eloquent but this might work"

• "The docs say X but I'll adapt it differently"

• "One more fix attempt" (when already tried 2+)

ALL of these mean: STOP. Return to Phase 1.

Common Laravel Debugging Scenarios

Scenario 1: N+1 Query Problem

Phase 1: Detect it

• Enable Model::preventLazyLoading()
• Exception thrown showing the problem

Phase 2: Find the pattern

• Check working code that uses with()
• Identify which relationship is lazy loading

Phase 3: Hypothesis

• "Adding with('user') will prevent the N+1"

Phase 4: Fix

• Add test that counts queries
• Add with('user') to the query
• Verify query count reduced

Scenario 2: Route Model Binding Not Working

Phase 1: Investigate

• Check route definition: /posts/{post}
• Check controller parameter: Post $post
• Check if using custom key

Phase 2: Pattern

• Compare with working route binding
• Check Post model for getRouteKeyName()

Phase 3: Hypothesis

• "Parameter name doesn't match or model not found"

Phase 4: Fix

• Ensure route parameter matches method parameter
• Or customize: public function getRouteKeyName() { return 'slug'; }

Scenario 3: Mass Assignment Exception

Phase 1: Error says "Add [field] to fillable property" Phase 2: Check other models' $fillable arrays Phase 3: Hypothesis: "Field not in $fillable" Phase 4: Add field to $fillable, test

Integration with Laravel Agents

• Use laravel-debugger for Laravel-specific debugging help

• Use laravel-testing-expert for creating failing tests (Phase 4)

• Use eloquent-specialist for relationship debugging

• Use laravel-performance-optimizer for performance issues

Quick Reference

Phase Laravel-Specific Activities Success Criteria

1. Root Cause Check logs, Telescope, Tinker, recent changes Understand WHAT and WHY

2. Pattern Find working Laravel examples, check docs Identify differences

3. Hypothesis Form theory, test in Tinker Confirmed or new hypothesis

4. Implementation Create Pest test, fix, verify Bug resolved, tests pass

Remember

• Laravel has excellent error messages - read them fully

• Use Telescope for comprehensive debugging

• Tinker is your friend for testing hypotheses

• Follow Laravel conventions - fighting the framework causes bugs

• 95% of "weird Laravel behavior" is misunderstanding the framework

Always investigate systematically, understand the root cause, then fix once correctly.