Symfony Components are a set of decoupled and reusable PHP libraries and the foundation on which many PHP applications and libraries are built. Symfony Components are downloaded more than 3.5 million times every day, making them the most battle-tested libraries in the PHP landscape.

Symfony Contracts are a set of abstractions extracted out of the Symfony Components. They can be used to build on semantics that the Symfony Components proved useful - and that already have fully-tested implementations.

Symfony Contracts are split by domain and consist of a set of PHP interfaces, traits, normative docblocks and reference test suites when applicable. The versioning of Symfony Contracts is independent from Components, so we won't create a new tag if nothing changed on some contracts.

Starting from version 1.1 of Symfony Contracts, you can require each contract as a separate package, instead of installing all of them as a single package. For example, if you only care about the Cache contracts, install this package:

1
$ composer require symfony/cache-contracts

When applicable, the provided contracts are built on top of PSRs: some of them extend existing PSRs (Cache and EventDispatcher), some others provide alternative abstractions with a broader domain coverage (HttpClient), and the remaining provide abstractions that are not covered by PSRs (Translation and Service).

Should I add these contracts to my project?

If your project is used as a reusable third-party library and you want to build on these contracts to achieve higher decoupling and interoperability, you should add them as explicit dependencies.

If your project is a stand-alone Symfony application, you are not required to add these contracts explicitly as dependencies. Installing the Symfony Component will require the needed contracts automatically (e.g. installing symfony/cache will also install symfony/cache-contracts for you).

In both cases, we recommend using the interfaces provided by the contracts as the type-hints of your own classes or interfaces when possible.

Published in #Symfony