PHP Contracts
June 11, 2026 · View on GitHub
A curated list of PHP contract packages: small, stable interfaces that define how two pieces of code work together without forcing either side to depend on one concrete implementation.
Contracts are most useful at the boundaries of an application. A package can depend on an HTTP client contract such as PSR-18 instead of depending directly on Guzzle, Symfony HttpClient or any other client. The application can then choose the implementation, swap it later, mock it in tests, or share code across frameworks with less friction.
This repository collects interface packages that are worth considering when designing those boundaries. It is not a list of every abstraction in the PHP ecosystem. The focus is on contracts that are documented, mature enough for real projects, and supported by practical implementations.
Guidelines:
- The package must define a clear contract through one or more PHP interfaces.
- The contract must describe behavior and expectations, not the internals of a specific implementation.
- The interfaces must be usable without requiring a particular framework, service container or runtime.
- Implementations may exist in the same ecosystem, but user code should be able to depend on the contract package alone.
- The project must provide useful English documentation, including the purpose of the contract and the expectations for implementers.
- The interfaces must comply with PSR-1 and should comply with PSR-12.
- There should be real implementations or adapters that demonstrate the practical value of the contract.
- The package should be available through Packagist and follow normal Composer versioning practices.
Stable
(Click on an item to get a list of available implementations)
Contract-oriented packages
Not every useful PHP contract is a PSR. The following packages are still useful when their domain matches an application boundary, because they publish interfaces separately from implementations or are mostly contract packages.
| Project | Latest | Focus | Implementations / Notes |
|---|---|---|---|
| Symfony Cache Contracts |  | Cache access with Symfony's cache semantics on top of PSR-6/PSR-16. | Compatible Packages |
| Symfony Event Dispatcher Contracts |  | Event dispatching contract compatible with Symfony components and PSR-14. | Compatible Packages |
| Symfony HTTP Client Contracts |  | HTTP client contract for synchronous, asynchronous and streaming HTTP clients. | Compatible Packages |
| Symfony Service Contracts |  | Service and dependency-injection contracts built around PSR-11. | Compatible Packages |
| Symfony Translation Contracts |  | Translation interfaces for framework-independent internationalization boundaries. | Compatible Packages |
| HTTPlug |  | HTTP client abstraction built on PSR-7, especially useful for asynchronous clients. | Compatible Packages; prefer PSR-18 for purely synchronous HTTP clients. |
| Doctrine Persistence |  | Shared persistence interfaces and base contracts for Doctrine object mappers. | Useful at Doctrine-style persistence boundaries, not as a general repository standard. |
| Illuminate Contracts |  | Broad Laravel ecosystem contracts for cache, container, events, queues, routing and more. | Best suited for Laravel-compatible packages and applications. |
Noteworthy projects
- HttpKernelInterface – HttpKernelInterface handles a Request to convert it to a Response.
- FlySystem – Flysystem is a filesystem abstraction which allows you to easily swap out a local filesystem for a remote one. Reducing technical debt and chance of vendor lock-in.
Wishlist
- 3rd Party APIs (Amazon, Google etc)
- Authentication
- (More) Communication (Email, Sms, Notifications etc.)
- (More) Date-, Time-, Interval-, Calendar-Manipulation
- (More) Dependency-Injection-Container interfaces with more methods (make, call etc.)
- E-Commerce (Payment, common order structures, common address structures etc.)
- FileSystem-Abstraction
- Filetype-Abstraction
- Filtering
- Image-Manipulation
- Key-Value-Stores
- ORM / Data-Handling / Data-Structures
- Queues (like RabbitMQ / Gearman)
- Search-Server-Interfaces (querying, Responses, Facettes etc)
- Template-Engines
- URL-Manipulation
- Validation