{
    "slug": "namespaces",
    "term": "PHP Namespaces",
    "category": "php",
    "difficulty": "beginner",
    "short": "Logical groupings that prevent class name collisions and form the basis of PSR-4 autoloading.",
    "long": "PHP namespaces (5.3+) encapsulate classes, interfaces, traits, functions, and constants into named scopes using namespace App\\Controller. The fully qualified class name (FQCN) like App\\Controller\\HomeController maps directly to a file path under PSR-4. Use statements (use App\\Service\\UserService) alias FCQNs for cleaner code. The global namespace is accessed with a leading backslash (\\Exception). Namespaces are essential for composer autoloading and preventing collisions between third-party packages.",
    "aliases": [
        "PHP namespaces",
        "namespace keyword",
        "use statement"
    ],
    "tags": [
        "php",
        "oop",
        "organisation"
    ],
    "misconception": "Namespaces prevent class name conflicts automatically. Namespaces only prevent conflicts between classes in different namespaces — two classes with the same fully-qualified name in different files will still conflict. Namespaces organise code; Composer autoloading enforces uniqueness.",
    "why_it_matters": "Namespaces eliminate class name collisions between your code, third-party packages, and the PHP standard library. Without them, every package would need globally unique class names, making modern dependency management impossible.",
    "common_mistakes": [
        "Mixing namespaced and non-namespaced code in the same project — it creates unpredictable autoloading behaviour.",
        "Forgetting that the global namespace requires a leading backslash inside a namespace (\\Exception, not Exception).",
        "Using deeply nested namespaces (App\\Modules\\Orders\\Domain\\Entities\\OrderLine) when shallower ones suffice.",
        "Not aliasing long namespace imports with use — leads to unreadable fully-qualified class names inline."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "psr_4",
        "composer",
        "interfaces"
    ],
    "prerequisites": [
        "psr_4",
        "composer",
        "autoloading"
    ],
    "refs": [
        "https://www.php.net/manual/en/language.namespaces.php"
    ],
    "bad_code": "// No namespace — class name collisions in large projects:\nclass Logger {} // Conflicts with any other Logger class\nclass Request {} // Conflicts with framework's Request class\n\n// With namespaces — no collision:\nnamespace App\\Logging;\nclass Logger {} // App\\Logging\\Logger\n\nnamespace Vendor\\Http;\nclass Request {} // Vendor\\Http\\Request — distinct",
    "good_code": "<?php\n// File: src/Domain/Order/OrderService.php\ndeclare(strict_types=1);\n\nnamespace App\\Domain\\Order;\n\nuse App\\Domain\\User\\User;          // import from another namespace\nuse App\\Infrastructure\\Mailer;\nuse DateTimeImmutable;              // global namespace class\nuse InvalidArgumentException as InvalidArg; // alias\n\nclass OrderService {\n    public function place(User $user, array $items): Order {\n        if (empty($items)) {\n            throw new InvalidArg('Items cannot be empty');\n        }\n        return new Order($user, $items, new DateTimeImmutable());\n    }\n}",
    "quick_fix": "Follow PSR-4: namespace App\\Services\\Payment maps to src/Services/Payment.php — configure in composer.json autoload section",
    "severity": "low",
    "effort": "low",
    "created": "2026-03-15",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/namespaces",
        "html_url": "https://codeclaritylab.com/glossary/namespaces",
        "json_url": "https://codeclaritylab.com/glossary/namespaces.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": "[PHP Namespaces](https://codeclaritylab.com/glossary/namespaces) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/namespaces"
            }
        }
    }
}