Adapter Pattern

Also Known As

TL;DR

Explanation

The Adapter (Wrapper) pattern bridges the gap between an existing class with an incompatible interface and the interface expected by client code. It wraps the adaptee and implements the target interface, translating calls. This is essential when integrating third-party libraries or legacy code without modifying either. In PHP, adapting a payment gateway SDK to a standardised PaymentGatewayInterface, or wrapping a legacy Logger to a PSR-3 LoggerInterface, are common use cases. Adapters also facilitate testability by wrapping external dependencies.

Diagram

flowchart LR
    CLIENT[Client Code] -->|expects| TARGET[Target Interface<br/>send email]
    TARGET -.->|implemented by| ADAPTER[SendGridAdapter]
    ADAPTER -->|translates to| VENDOR[SendGrid SDK]
    ADAPTER2[MailgunAdapter] -->|translates to| VENDOR2[Mailgun SDK]
    CLIENT -.->|can swap| ADAPTER2
    INFO[Client never changes<br/>only swap the adapter]
style CLIENT fill:#1f6feb,color:#fff
style ADAPTER fill:#238636,color:#fff
style ADAPTER2 fill:#238636,color:#fff

Common Misconception

Why It Matters

Common Mistakes

• Adapters that transform data as well as interface — separate the data mapping from the interface adaptation.
• Not programming to the target interface — the adapter is only useful if callers depend on the interface, not the adapter.
• Creating an adapter for every third-party class rather than a single adapter for the library's entry point.
• Adapters that leak the underlying library's exceptions — wrap them in domain exceptions.

Avoid When

• The interface mismatch is trivial — a one-line wrapper does not need a full adapter class.
• You control both interfaces and can change them — adapt the source instead of wrapping it.
• Overusing adapters hides poor API design that should be fixed at the source.

When To Use

• Integrating a third-party library whose interface does not match your domain's expectations.
• Making legacy code work with a new interface without modifying the legacy code.
• Enabling multiple implementations behind a single interface for swappability.
• Wrapping external APIs so your domain is insulated from their changes.

Code Examples

// Direct dependency on third-party Stripe library everywhere:
class PaymentService {
    public function charge(float $amount): void {
        \Stripe\Charge::create(['amount' => $amount * 100, 'currency' => 'usd']);
        // Stripe leak throughout codebase — impossible to swap
    }
}
// Better: StripePaymentAdapter implements PaymentGatewayInterface

// Your app expects this interface
interface Logger {
    public function log(string $level, string $message): void;
}

// Third-party library uses a different API
class MonologAdapter implements Logger {
    public function __construct(private \Monolog\Logger $monolog) {}

    public function log(string $level, string $message): void {
        $this->monolog->$level($message); // adapts your interface to Monolog's
    }
}

// Your code depends on Logger — not Monolog directly
$logger = new MonologAdapter(new \Monolog\Logger('app'));
$service = new OrderService($logger);

References

• ↗ https://refactoring.guru/design-patterns/adapter

Tags

Related Terms