Ports and Adapters (Hexagonal)

Abstract integrations behind stable interfaces. Keep vendor SDKs out of your domain code.

Shape

• Port: PHP interface that expresses only what the app needs
• Adapters: one per provider, wrapping SDK quirks
• Selection: choose adapter via config/env/service provider

Example (email)

// Port
interface MailPort {
    public function send(string $to, string $subject, string $html): void;
}

// Adapter
final class SesMailAdapter implements MailPort {
    public function __construct(private \Aws\Ses\SesClient $ses) {}
    public function send(string $to, string $subject, string $html): void {
        // wrap SES specifics here
    }
}

// Composition (AppServiceProvider)
$this->app->singleton(MailPort::class, function () {
    return match (config('mail.driver')) {
        'ses' => new SesMailAdapter(app('aws.ses')),
        default => new SmtpMailAdapter(/* ... */),
    };
});

Tips

• Normalize SDK data into your own types/DTOs
• Expose only portable capabilities via the port
• Keep adapters thin and well-tested