{
    "slug": "debugging",
    "term": "Debugging PHP",
    "category": "php",
    "difficulty": "beginner",
    "short": "Systematic techniques for finding and fixing PHP bugs — from var_dump and error logs to Xdebug step-debugging, with the guiding principle of narrowing down where incorrect behaviour first appears.",
    "long": "PHP debugging escalates through levels of sophistication: basic output debugging (var_dump(), print_r(), dd() in Laravel — quick but not suitable for production); error log inspection (tail /var/log/php/error.log or Laravel's storage/logs/laravel.log); Xdebug step debugger (breakpoints, step-through, variable inspection in PhpStorm or VS Code — the most powerful technique); PHPStan/Psalm static analysis (finds type errors, undefined variables, dead code without running the code); profiling (Xdebug profiler, Blackfire — identifies slow functions rather than incorrect behaviour). The debugging mindset: state a hypothesis ('the user ID is null at this point'), verify it (var_dump($userId) or a breakpoint), revise the hypothesis based on evidence. The most common debugging mistake is adding output statements randomly rather than systematically narrowing down the location of the problem.",
    "aliases": [
        "debug",
        "var_dump",
        "Xdebug",
        "Blackfire",
        "dd()",
        "step debugger",
        "PHP debugger"
    ],
    "tags": [
        "debugging",
        "php",
        "xdebug",
        "var_dump",
        "development",
        "phpstorm"
    ],
    "misconception": "var_dump() is sufficient for all debugging needs. var_dump() is useful for quick checks but cannot pause execution at a specific line, inspect call stacks, or step through code interactively. Xdebug with an IDE provides all of these and significantly reduces debugging time for complex bugs. Setting up Xdebug in a Docker PHP development environment takes under 30 minutes and pays back immediately on the first complex bug.",
    "why_it_matters": "Every PHP developer spends a significant portion of their time debugging. The difference between a developer who uses only var_dump() and one who uses Xdebug step-debugging is hours per week — complex bugs that take 2 hours to trace with output statements take 10 minutes with a debugger. Learning to use Xdebug properly is one of the highest-ROI skills for a PHP developer. It also eliminates the risk of accidentally leaving debug output in production code.",
    "common_mistakes": [
        "Leaving var_dump() or dd() calls in committed code — use a pre-commit hook to catch debug statements.",
        "Not checking the PHP error log first — most bugs announce themselves immediately in the error log.",
        "Debugging in production — replicate the issue locally or in a staging environment; adding debug output to production exposes internals.",
        "Not using static analysis — PHPStan level 6+ catches type errors, null dereferences, and undefined variables before you even run the code."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "error_logging",
        "error_reporting",
        "xdebug",
        "hsts"
    ],
    "prerequisites": [],
    "refs": [
        "https://xdebug.org/docs/step_debug",
        "https://phpstan.org/"
    ],
    "bad_code": "// Scattered var_dumps — easy to forget to remove\nfunction processOrder(array $data): Order {\n    var_dump($data); // LEFT IN PRODUCTION\n    $total = 0;\n    foreach ($data['items'] as $item) {\n        var_dump($item); // LEFT IN PRODUCTION\n        $total += $item['price'];\n    }\n    return Order::create(['total' => $total]);\n}",
    "good_code": "// Laravel dd() for development — throws, never silently continues\n// But better: use Xdebug breakpoint instead of any output\n\n// PHPStan catches bugs before runtime\n// vendor/bin/phpstan analyse src/ --level=6\n// Found 3 errors:\n// - Undefined variable: $userId\n// - Cannot call method find() on null\n// - Function processOrder() should return Order but returns void\n\n// In php.ini / xdebug.ini:\n// xdebug.mode=debug\n// xdebug.start_with_request=yes\n// Then set breakpoint in IDE — no code changes needed",
    "quick_fix": "Install Xdebug, configure your IDE (PhpStorm/VS Code), set a breakpoint at the suspected problem location — faster than any amount of var_dump() for complex bugs",
    "severity": "info",
    "effort": "low",
    "created": "2026-03-23",
    "updated": "2026-04-04",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/debugging",
        "html_url": "https://codeclaritylab.com/glossary/debugging",
        "json_url": "https://codeclaritylab.com/glossary/debugging.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Debugging PHP](https://codeclaritylab.com/glossary/debugging) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/debugging"
            }
        }
    }
}