{
    "slug": "mediator_pattern",
    "term": "Mediator Pattern",
    "category": "quality",
    "difficulty": "intermediate",
    "short": "Centralises complex communications between multiple objects into a single mediator object, reducing direct dependencies between colleagues.",
    "long": "The Mediator pattern reduces chaotic many-to-many dependencies between objects by routing all communication through a central mediator. Instead of objects knowing about each other, they only know about the mediator. This reduces coupling from O(n²) to O(n). In PHP, the Command Bus (used in CQRS) is a form of mediator: commands are sent to the bus and routed to handlers, with no direct coupling between the sender and handler. Event dispatchers also act as mediators. Avoid letting the mediator become a God Object — it should route, not contain, business logic.",
    "aliases": [
        "mediator",
        "event bus",
        "message broker pattern"
    ],
    "tags": [
        "design-pattern",
        "oop",
        "behavioural",
        "decoupling"
    ],
    "misconception": "The mediator pattern reduces coupling by centralising it. It reduces coupling between components but concentrates it in the mediator — if the mediator grows without discipline it becomes a god class that knows about every other component.",
    "why_it_matters": "The Mediator reduces direct dependencies between components by routing communication through a central object — components stay loosely coupled and the interaction logic is centralised.",
    "common_mistakes": [
        "The mediator becoming a god class that knows too much — distribute logic back to components and keep the mediator as a router.",
        "Using a mediator for components that have a simple, stable relationship — adds unnecessary complexity.",
        "Not distinguishing mediator (coordinates peers) from observer (notifies subscribers) — they solve different problems.",
        "Tightly coupling mediator to concrete component types — use interfaces so components can be swapped."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "command_pattern",
        "observer_pattern",
        "coupling",
        "cqrs"
    ],
    "prerequisites": [
        "observer_pattern",
        "event_driven",
        "interfaces"
    ],
    "refs": [
        "https://refactoring.guru/design-patterns/mediator"
    ],
    "bad_code": "// Direct coupling between components — every component knows every other:\nclass Chat {\n    public function send(User $from, User $to, string $msg): void {\n        $to->receive($msg, $from); // Direct coupling — use a ChatMediator\n    }\n}",
    "good_code": "// Without mediator: components know about each other\n// With mediator: all communication goes through one hub\n\ninterface Mediator {\n    public function notify(object $sender, string $event): void;\n}\n\nclass DialogMediator implements Mediator {\n    public function __construct(\n        private Checkbox $checkbox,\n        private Input    $input,\n        private Button   $submitBtn,\n    ) {}\n\n    public function notify(object $sender, string $event): void {\n        if ($sender === $this->checkbox && $event === 'check') {\n            $this->input->setEnabled($this->checkbox->isChecked());\n            $this->submitBtn->setEnabled($this->checkbox->isChecked());\n        }\n    }\n}",
    "quick_fix": "When many objects communicate directly creating a mesh of dependencies, introduce a mediator — objects send messages to the mediator which routes them, they no longer know each other",
    "severity": "low",
    "effort": "medium",
    "created": "2026-03-15",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/mediator_pattern",
        "html_url": "https://codeclaritylab.com/glossary/mediator_pattern",
        "json_url": "https://codeclaritylab.com/glossary/mediator_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": "[Mediator Pattern](https://codeclaritylab.com/glossary/mediator_pattern) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/mediator_pattern"
            }
        }
    }
}