{
    "slug": "facade_pattern",
    "term": "Facade Pattern",
    "category": "quality",
    "difficulty": "beginner",
    "short": "Provides a simplified, unified interface to a complex subsystem, hiding its internal complexity from clients.",
    "long": "The Facade pattern defines a higher-level interface that makes a subsystem easier to use. Rather than coordinating multiple subsystem classes directly, clients call the Facade which delegates internally. This reduces coupling between clients and the subsystem, simplifies APIs for common use cases, and provides a single seam for testing the subsystem in isolation. In PHP frameworks, facades are pervasive: Laravel's static facade classes (Cache::get(), Mail::send()) are thin proxies to the underlying container-managed services. The key trade-off: facades improve usability but can hide complexity and complicate static analysis.",
    "aliases": [
        "facade",
        "simplified interface",
        "subsystem facade"
    ],
    "tags": [
        "design-pattern",
        "oop",
        "structural"
    ],
    "misconception": "The facade pattern hides the subsystem completely, making it inaccessible. A facade provides a simplified interface to a complex subsystem but does not prevent direct access — advanced consumers can still use the subsystem directly when needed.",
    "why_it_matters": "The Facade pattern provides a simplified interface to a complex subsystem — callers interact with a single entry point rather than coordinating multiple subsystem classes directly.",
    "common_mistakes": [
        "Facades that expose the entire subsystem API — they simplify nothing and add an unnecessary layer.",
        "Forgetting the facade is an entry point, not a god class — keep it thin and delegate to subsystem components.",
        "Using Laravel's static Facade proxies and not understanding they resolve from the service container — makes testing harder if not using facades correctly.",
        "Testing through the facade instead of testing subsystem components directly — leads to slow, brittle tests."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "adapter_pattern",
        "decorator_pattern",
        "separation_of_concerns"
    ],
    "prerequisites": [
        "interfaces",
        "dependency_injection",
        "microservices"
    ],
    "refs": [
        "https://refactoring.guru/design-patterns/facade"
    ],
    "bad_code": "// Direct subsystem coordination in the client — what a facade should hide:\n$encoder = new VideoEncoder();\n$storage = new CloudStorage();\n$notifier = new NotificationService();\n$encoder->encode($file);\n$url = $storage->upload($encoder->getOutput());\n$notifier->notify($userId, $url); // Client manages all coordination",
    "good_code": "// Complex subsystem\nclass VideoEncoder   { public function encode(string $file): string { ... } }\nclass ThumbnailGen   { public function generate(string $file): string { ... } }\nclass StorageUploader { public function upload(string $file): string { ... } }\n\n// Facade — one simple interface for a common use case\nclass VideoUploadFacade {\n    public function __construct(\n        private VideoEncoder    $encoder,\n        private ThumbnailGen    $thumbs,\n        private StorageUploader $storage,\n    ) {}\n\n    public function upload(string $rawFile): UploadResult {\n        $encoded   = $this->encoder->encode($rawFile);\n        $thumbnail = $this->thumbs->generate($encoded);\n        $url       = $this->storage->upload($encoded);\n        return new UploadResult($url, $thumbnail);\n    }\n}",
    "quick_fix": "Create a facade when a subsystem has too many classes a client must interact with — expose a simple unified interface and hide the complexity behind it",
    "severity": "low",
    "effort": "low",
    "created": "2026-03-15",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/facade_pattern",
        "html_url": "https://codeclaritylab.com/glossary/facade_pattern",
        "json_url": "https://codeclaritylab.com/glossary/facade_pattern.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": "[Facade Pattern](https://codeclaritylab.com/glossary/facade_pattern) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/facade_pattern"
            }
        }
    }
}