An application that calls a provider directly from controllers and business services becomes difficult to change. Provider-specific field names, status codes and authentication details spread through the codebase. An adapter creates a narrow boundary between the application's language and the external service's protocol.
Define an application-facing interface
Describe the capability the application needs, such as sendMessage, lookupAddress or createPaymentIntent. Avoid copying the provider's entire API into your interface. The application should express its own concepts and receive a normalized result that represents meaningful outcomes.
Translate at the boundary
The adapter maps internal values to provider request fields, performs the HTTP call and maps the response back. It translates provider errors into application error categories while retaining safe diagnostic metadata. Keep serialization and transport concerns out of domain rules. If two providers behave differently, make those differences explicit in their adapters rather than hiding them in scattered conditionals.
Avoid abstraction for its own sake
A one-off integration with a single stable endpoint may need only a small client class. Do not build a generic plugin system, dozens of interfaces or a framework before there is a real variation to support. The abstraction should make testing, provider replacement or failure handling measurably easier.
Test the seam
Test the application workflow against a fake adapter and test each real adapter against deterministic HTTP fixtures. Add a small sandbox test for provider-specific assumptions. When replacing a provider, compare behavior such as refunds, timeouts, idempotency and data retention—not just matching method names.
Further reading
- Martin Fowler: Gateway — https://martinfowler.com/articles/gateway-pattern.html
- PHP interfaces — https://www.php.net/manual/en/language.oop5.interfaces.php