Adapter Pattern

Definition

The Adapter pattern converts the interface of a class into another interface clients expect. It lets classes work together that couldn't otherwise because of incompatible interfaces.

Problem: Incompatible External APIs

// Your internal payment interface
namespace Vendor\Payment\Api;

interface PaymentGatewayInterface
{
    public function charge(float $amount, string $currency): PaymentResult;
    public function refund(string $transactionId, float $amount): RefundResult;
}

// External library (you can't modify this)
class StripeSdk
{
    public function createCharge(array $params): \Stripe\Charge
    {
        return \Stripe\Charge::create($params);
    }

    public function createRefund(string $chargeId, int $amountInCents): \Stripe\Refund
    {
        return \Stripe\Refund::create([
            'charge' => $chargeId,
            'amount' => $amountInCents,
        ]);
    }
}

// StripeSdk API is incompatible with PaymentGatewayInterface

Solution: Adapter

namespace Vendor\Payment\Adapter;

class StripeAdapter implements \Vendor\Payment\Api\PaymentGatewayInterface
{
    private \Stripe\StripeSdk $stripe;

    public function __construct(string $apiKey)
    {
        $this->stripe = new \Stripe\StripeSdk($apiKey);
    }

    public function charge(float $amount, string $currency): \Vendor\Payment\Api\PaymentResult
    {
        // Adapt: convert our interface to Stripe's format
        $stripeAmount = (int) ($amount * 100); // Stripe uses cents

        $charge = $this->stripe->createCharge([
            'amount' => $stripeAmount,
            'currency' => strtolower($currency),
            'source' => $this->getStripeToken(),
        ]);

        // Adapt: convert Stripe's response to our format
        return new PaymentResult(
            success: $charge->status === 'succeeded',
            transactionId: $charge->id,
            message: $charge->status
        );
    }

    public function refund(string $transactionId, float $amount): \Vendor\Payment\Api\RefundResult
    {
        $stripeAmount = (int) ($amount * 100);

        $refund = $this->stripe->createRefund($transactionId, $stripeAmount);

        return new RefundResult(
            success: $refund->status === 'succeeded',
            refundId: $refund->id
        );
    }
}

The adapter translates between your interface and the third-party API.

Object Adapter (Composition)

Wraps the adaptee via composition (most common in PHP):

// Wraps PayPal SDK via composition
class PayPalAdapter implements PaymentGatewayInterface
{
    private PayPalRestApiSdk $paypal; // Adaptee

    public function __construct(PayPalRestApiSdk $paypal)
    {
        $this->paypal = $paypal;
    }

    public function charge(float $amount, string $currency): PaymentResult
    {
        $payment = $this->paypal->createPayment([
            'intent' => 'sale',
            'amount' => [
                'total' => number_format($amount, 2, '.', ''),
                'currency' => $currency,
            ],
        ]);

        return new PaymentResult(
            success: $payment->getState() === 'approved',
            transactionId: $payment->getId()
        );
    }
}

When to Use Each

In PHP, Object Adapter (composition) is almost always preferred because:

1. PHP doesn't support multiple inheritance
2. Composition is more flexible
3. You can swap the adaptee at runtime

Magento Payment Gateway Adapters

Magento uses adapters extensively for payment gateways. Each gateway has an adapter that converts between Magento's payment interface and the gateway's API:

// Magento's payment gateway adapter pattern
// Each gateway adapter wraps an external SDK

namespace Magento\Payment\Gateway\Request\Builder\Composite;

// Builder (adapter) converts order data to gateway-specific format
interface BuilderInterface
{
    public function build(array $buildSubject): array;
}

// Example: builds Stripe-specific request from Magento order data
class StripePaymentRequestBuilder implements BuilderInterface
{
    public function build(array $buildSubject): array
    {
        $paymentDO = $buildSubject['payment'];
        $order = $paymentDO->getOrder();

        return [
            'amount' => (int) ($order->getGrandTotalAmount() * 100),
            'currency' => $order->getCurrencyCode(),
            'source' => $buildSubject['token'],
            'description' => sprintf(
                'Order #%s',
                $order->getOrderNumber()
            ),
        ];
    }
}

// PayPal adapter builds different structure
class PayPalPaymentRequestBuilder implements BuilderInterface
{
    public function build(array $buildSubject): array
    {
        $paymentDO = $buildSubject['payment'];
        $order = $paymentDO->getOrder();

        return [
            'intent' => 'sale',
            'payer' => [
                'payment_method' => 'credit_card',
            ],
            'transactions' => [[
                'amount' => [
                    'total' => $order->getGrandTotalAmount(),
                    'currency' => $order->getCurrencyCode(),
                ],
            ]],
        ];
    }
}

Shipping Carrier Adapters

// Shipping carrier adapters wrap carrier-specific APIs
namespace Vendor\Shipping\Adapter;

class DhlAdapter implements \Vendor\Shipping\Api\CarrierInterface
{
    public function __construct(
        private \Dhl\Api\Client $dhlClient // Third-party SDK
    ) {}

    public function getRates(array $params): array
    {
        // Adapt: convert Magento params to DHL API format
        $dhlRequest = $this->dhlClient->createRateRequest([
            'originCountryCode' => $params['origin_country'],
            'originPostalCode' => $params['origin_zip'],
            'destinationCountryCode' => $params['dest_country'],
            'destinationPostalCode' => $params['dest_zip'],
            'weight' => $params['total_weight'],
        ]);

        $dhlRates = $dhlRequest->getRates();

        // Adapt: convert DHL response to our format
        return array_map(fn($rate) => [
            'carrier' => 'dhl',
            'method' => $rate->getServiceCode(),
            'price' => $rate->getTotalAmount() / 100,
            'currency' => $rate->getCurrencyCode(),
            'delivery_days' => $rate->getEstimatedDays(),
        ], $dhlRates);
    }
}

The adapter pattern lets Magento support dozens of payment gateways and shipping carriers without modifying core code.