{
    "slug": "reflection_api",
    "term": "Reflection API",
    "category": "php",
    "difficulty": "advanced",
    "short": "PHP's built-in introspection system for examining classes, methods, properties, and parameters at runtime.",
    "long": "The PHP Reflection API (ReflectionClass, ReflectionMethod, ReflectionProperty, ReflectionFunction, ReflectionParameter) enables runtime inspection of code structure — reading type declarations, attributes, docblocks, visibility, and default values without invoking the code. It underpins dependency injection containers (resolving constructor parameters), ORM hydration, serialisation libraries, and testing frameworks. Reflection is powerful but has a performance cost — production DI containers cache reflection results. PHP 8.0 Attributes provide a structured, performant alternative to docblock-parsed metadata.",
    "aliases": [
        "PHP Reflection",
        "ReflectionClass",
        "introspection PHP"
    ],
    "tags": [
        "php",
        "metaprogramming",
        "oop",
        "advanced"
    ],
    "misconception": "The Reflection API is only useful for framework developers. Reflection enables runtime code generation, attribute processing, dependency injection containers, test mocking, and documentation generation — it is the backbone of most modern PHP frameworks.",
    "why_it_matters": "The Reflection API gives runtime access to class structure, docblocks, and attributes — it powers dependency injection containers, ORMs, and testing frameworks, but has non-trivial performance cost.",
    "common_mistakes": [
        "Using Reflection in hot code paths without caching results — ReflectionClass instantiation is expensive.",
        "Not caching reflected class metadata in a DI container — reflecting the same class on every request adds measurable overhead.",
        "Using Reflection to access private members of other classes in production code — breaks encapsulation.",
        "Not using PHP 8 Attributes instead of docblock parsing when possible — native attributes are faster and type-safe."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "attributes",
        "dependency_injection",
        "magic_methods"
    ],
    "prerequisites": [
        "php_attributes_builtin",
        "magic_methods",
        "static_analysis"
    ],
    "refs": [
        "https://www.php.net/manual/en/book.reflection.php"
    ],
    "bad_code": "// Uncached reflection in a hot path:\nfunction resolve(string $class): object {\n    $ref = new ReflectionClass($class); // Expensive — not cached\n    $params = $ref->getConstructor()->getParameters();\n    // ... inject dependencies\n}",
    "good_code": "// Inspect class structure at runtime\n\\$ref = new ReflectionClass(OrderService::class);\necho \\$ref->getName();       // 'App\\Domain\\OrderService'\necho \\$ref->getShortName();  // 'OrderService'\n\n\\$methods    = \\$ref->getMethods(ReflectionMethod::IS_PUBLIC);\n\\$constructor = \\$ref->getConstructor();\n\n// Read PHP 8.0+ attributes:\nforeach (\\$ref->getMethods() as \\$method) {\n    foreach (\\$method->getAttributes(Route::class) as \\$attr) {\n        \\$route = \\$attr->newInstance();\n        echo \\$route->path;\n    }\n}\n\n// Instantiate without constructor (DI containers, test fixtures):\n\\$instance = \\$ref->newInstanceWithoutConstructor();",
    "quick_fix": "Use PHP's Reflection API for framework-level metaprogramming (DI containers, ORMs, test mocking) — avoid using it in application code as it bypasses encapsulation and is significantly slower",
    "severity": "low",
    "effort": "high",
    "created": "2026-03-15",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/reflection_api",
        "html_url": "https://codeclaritylab.com/glossary/reflection_api",
        "json_url": "https://codeclaritylab.com/glossary/reflection_api.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": "[Reflection API](https://codeclaritylab.com/glossary/reflection_api) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/reflection_api"
            }
        }
    }
}