ADR-0003: Depend on PSR Interfaces, Not Concrete Implementations

Status

Accepted

Context

PHP-FIG's PSR standards define interoperability contracts for logging (psr/log), HTTP messages (psr/http-message), and more. A shared foundation library like this one is consumed by multiple SDKs and ultimately by end-user applications that already have their own logger (Monolog, Laravel's logger, Symfony's logger, etc.) and potentially their own HTTP infrastructure.

If the library depended on a concrete logger or a fixed PSR version, it would force version conflicts on consumers.

Decision

• Logging is typed to Psr\Log\LoggerInterface with a default of NullLogger (no-op). Consumers inject any PSR-3 compatible implementation.
• HTTP messages are typed to Psr\Http\Message\RequestInterface / ResponseInterface — PSR-7 contracts.
• psr/log is declared with a broad constraint: ^1.1|^2.0|^3.0.
• psr/http-message is declared as ^1.0|^2.0.

This prevents the library from forcing a specific PSR version on downstream consumers and allows coexistence with Laravel 11+, Symfony 6/7, and other modern PHP stacks.

Consequences

• Enables: Drop-in compatibility with any PSR-3 logger and any PSR-7 HTTP stack.
• Prevents: Using concrete logger or HTTP client features not in the PSR interfaces (e.g., Monolog-specific channel methods).
• Testing: monolog/monolog is a require-dev dependency only — used in tests to verify log output, never in library source.