{
    "slug": "profiling",
    "term": "Profiling & Benchmarking",
    "category": "performance",
    "difficulty": "intermediate",
    "short": "Measuring where a PHP application spends its time and memory to identify the highest-impact optimisation targets.",
    "long": "Premature optimisation without profiling is guesswork — 90% of bottlenecks are typically in 10% of the code. PHP profiling tools include Xdebug (call graph, trace, memory profiling), Blackfire.io (production-grade performance management), Tideways, and SPX. Micro-benchmarking uses microtime(true) for targeted comparisons. Profile in a production-like environment — OPcache and real data change performance characteristics significantly. Focus first on I/O (database queries, HTTP requests) before CPU.",
    "aliases": [
        "PHP profiling",
        "application profiling",
        "performance profiling"
    ],
    "tags": [
        "performance",
        "php",
        "debugging",
        "tools"
    ],
    "misconception": "Adding echo microtime() around code sections is sufficient for profiling. Manual timing only measures wall time for known bottlenecks. A profiler (Blackfire, Xdebug with profiling mode) captures the full call graph, revealing unexpected hotspots that manual timing misses entirely.",
    "why_it_matters": "Profiling shows you exactly where time is spent — without it, performance optimisation is guesswork. The bottleneck is almost never where you expect it to be, and optimising the wrong thing wastes time while leaving the real problem untouched.",
    "common_mistakes": [
        "Profiling in development with a different dataset than production — small datasets hide N+1 and index problems.",
        "Optimising based on code inspection rather than profiler output — intuition is wrong more often than not.",
        "Running the profiler in production without sampling — full profiling adds 10–100x overhead.",
        "Stopping after fixing the first bottleneck — fix one and profile again, the next bottleneck is now exposed."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "opcode_caching",
        "n_plus_one",
        "memory_leak",
        "query_optimisation"
    ],
    "prerequisites": [
        "xdebug",
        "flamegraph",
        "performance_monitoring"
    ],
    "refs": [
        "https://xdebug.org/docs/profiler",
        "https://blackfire.io/docs/introduction"
    ],
    "bad_code": "// Guessing the bottleneck without profiling:\nfunction slowReport(): array {\n    // Developer assumes the DB query is slow\n    // Adds caching around DB call\n    // Report still slow — actual bottleneck was CSV generation\n    // Profile first: Xdebug/Blackfire shows exactly where time is spent\n}",
    "good_code": "// Xdebug profiling — generates cachegrind files\n; php.ini\nxdebug.mode=profile\nxdebug.output_dir=/tmp/xdebug\nxdebug.profiler_output_name=cachegrind.out.%p\n; Trigger on demand: XDEBUG_PROFILE=1 in query string or cookie\n; Open output in KCacheGrind (Linux) or QCacheGrind (macOS/Windows)\n\n// In-code micro-benchmark with hrtime (nanosecond precision)\n$start = hrtime(true);\nexpensiveOperation();\n$ms = (hrtime(true) - $start) / 1e6;\necho \"Took {$ms}ms\\n\";\n\n// SPX — lightweight always-on profiler for development\n// composer require --dev reliforp/php-spx",
    "quick_fix": "Add Blackfire or Xdebug profiling to your local/staging environment; look for the widest bars in the flamegraph — those are the bottlenecks",
    "severity": "info",
    "effort": "medium",
    "created": "2026-03-15",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/profiling",
        "html_url": "https://codeclaritylab.com/glossary/profiling",
        "json_url": "https://codeclaritylab.com/glossary/profiling.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": "[Profiling & Benchmarking](https://codeclaritylab.com/glossary/profiling) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/profiling"
            }
        }
    }
}