{
    "slug": "xdebug",
    "term": "Xdebug — Debugging & Profiling",
    "category": "php",
    "difficulty": "beginner",
    "short": "The essential PHP debugging extension providing step debugging, stack traces, code coverage, and profiling output.",
    "long": "Xdebug is the standard PHP debugging and profiling tool. It integrates with IDEs (PhpStorm, VS Code) via DAP (Debug Adapter Protocol) for step-through debugging, variable inspection, and breakpoints. In profiling mode it generates cachegrind files readable by KCacheGrind or WebGrind. It powers PHPUnit's code coverage reports (requires xdebug.mode=coverage). Key modes: debug (step debugging), profile (performance analysis), trace (full execution trace), coverage. Never run Xdebug in production — it adds significant overhead and exposes a remote debugging port.",
    "aliases": [
        "Xdebug",
        "PHP debugger",
        "PHP profiler"
    ],
    "tags": [
        "php",
        "debugging",
        "profiling",
        "tools"
    ],
    "misconception": "Xdebug can be left enabled in production for emergency debugging. Xdebug has a significant performance overhead (up to 10x slower) and exposes detailed stack traces. It must never run in production — use proper logging and error tracking (Sentry, Bugsnag) instead.",
    "why_it_matters": "Xdebug provides step debugging, code coverage, and profiling — without it, PHP debugging relies on var_dump and guesswork, making complex bugs orders of magnitude slower to diagnose.",
    "common_mistakes": [
        "Installing Xdebug in production — it adds significant overhead and exposes debug endpoints.",
        "Not configuring xdebug.mode = debug,coverage in php.ini — leaving it on develop mode without specific mode misses features.",
        "Not setting xdebug.start_with_request = trigger — without it, every request tries to connect to the debugger.",
        "Using var_dump as a substitute for a debugger — Xdebug step debugging shows the full call stack and variable state at any point."
    ],
    "when_to_use": [
        "Use Xdebug in local development for step debugging, profiling, and code coverage.",
        "Use Xdebug's profiler output with KCacheGrind/QCacheGrind to identify performance bottlenecks."
    ],
    "avoid_when": [
        "Never install Xdebug on a production server — it significantly degrades performance and exposes debugging interfaces.",
        "Disable xdebug.remote_enable and xdebug.mode=off in any non-development environment."
    ],
    "related": [
        "profiling",
        "code_coverage",
        "php_fpm",
        "opcache"
    ],
    "prerequisites": [
        "profiling",
        "static_analysis",
        "unit_testing"
    ],
    "refs": [
        "https://xdebug.org/docs/",
        "https://xdebug.org/docs/step_debug"
    ],
    "bad_code": "; php.ini — Xdebug in production:\n[xdebug]\nzend_extension=xdebug.so\nxdebug.mode=develop,debug\nxdebug.start_with_request=yes ; Every request tries to debug — massive overhead\nxdebug.client_host=localhost   ; Should never be active in production",
    "good_code": "; Xdebug 3 configuration\n[xdebug]\nzend_extension = xdebug\nxdebug.mode    = debug,coverage\nxdebug.start_with_request = trigger  ; activate only when triggered (not every request)\nxdebug.client_host = host.docker.internal\nxdebug.client_port = 9003\n\n; VS Code step debugging:\n; 1. Install PHP Debug extension\n; 2. Set breakpoint\n; 3. Start listening (F5)\n; 4. Trigger request with XDEBUG_SESSION cookie or ?XDEBUG_SESSION=1\n\n; Code coverage (PHPUnit):\n$ phpunit --coverage-html=coverage/\n; Requires xdebug.mode = coverage",
    "quick_fix": "Use xdebug.mode=debug for step debugging, xdebug.mode=coverage for code coverage reports, xdebug.mode=profile for performance profiling — never enable all modes in production",
    "severity": "info",
    "effort": "low",
    "created": "2026-03-15",
    "updated": "2026-03-31",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/xdebug",
        "html_url": "https://codeclaritylab.com/glossary/xdebug",
        "json_url": "https://codeclaritylab.com/glossary/xdebug.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": "[Xdebug — Debugging & Profiling](https://codeclaritylab.com/glossary/xdebug) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/xdebug"
            }
        }
    }
}