The Contracts Component

The Contracts component provides a set of abstractions extracted out of theSymfony components. They can be used to build on semantics that the Symfonycomponents proved useful - and that already have battle-tested implementations.

Installation

Contracts are provided as separate packages, so you can install only the onesyour projects really need:

  1. $ composer require symfony/cache-contracts
  2. $ composer require symfony/event-dispatcher-contracts
  3. $ composer require symfony/http-client-contracts
  4. $ composer require symfony/service-contracts
  5. $ composer require symfony/translation-contracts

Note

If you install this component outside of a Symfony application, you mustrequire the vendor/autoload.php file in your code to enable the classautoloading mechanism provided by Composer. Readthis article for more details.

Usage

The abstractions in this package are useful to achieve loose coupling andinteroperability. By using the provided interfaces as type hints, you are ableto reuse any implementations that match their contracts. It could be a Symfonycomponent, or another package provided by the PHP community at large.

Depending on their semantics, some interfaces can be combined withautowiring to seamlessly inject a servicein your classes.

Others might be useful as labeling interfaces, to hint about a specific behaviorthat can be enabled when using autoconfigurationor manual service tagging (or any other meansprovided by your framework.)

Design Principles

  • Contracts are split by domain, each into their own sub-namespaces;
  • Contracts are small and consistent sets of PHP interfaces, traits, normativedocblocks and reference test suites when applicable, …;
  • Contracts must have a proven implementation to enter this repository;
  • Contracts must be backward compatible with existing Symfony components.Packages that implement specific contracts should list them in the providesection of their composer.json file, using the symfony/*-implementationconvention. For example:
  1. {
  2.     "...": "...",
  3.     "provide": {
  4.         "symfony/cache-implementation": "1.0"
  5.     }
  6. }

Frequently Asked Questions

How Is this Different From PHP-FIG's PSRs?

When applicable, the provided contracts are built on top of PHP-FIG's PSRs.However, PHP-FIG has different goals and different processes. Symfony Contractsfocuses on providing abstractions that are useful on their own while stillcompatible with implementations provided by Symfony.