diff --git a/components/contracts.rst b/components/contracts.rst index cfc1081101a..4f84c5f2935 100644 --- a/components/contracts.rst +++ b/components/contracts.rst @@ -12,9 +12,16 @@ The Contracts Component Installation ------------ +Contracts are provided as separate packages, so you can install only the ones +your projects really need: + .. code-block:: terminal - $ composer require symfony/contracts + $ composer require symfony/cache-contracts + $ composer require symfony/event-dispatcher-contracts + $ composer require symfony/http-client-contracts + $ composer require symfony/service-contracts + $ composer require symfony/translation-contracts .. include:: /components/require_autoload.rst.inc @@ -45,15 +52,15 @@ Design Principles * Contracts must be backward compatible with existing Symfony components. Packages that implement specific contracts should list them in the ``provide`` -section of their ``composer.json`` file, using the -``symfony/*-contracts-implementation`` convention. For example: +section of their ``composer.json`` file, using the ``symfony/*-implementation`` +convention. For example: .. code-block:: javascript { "...": "...", "provide": { - "symfony/cache-contracts-implementation": "1.0" + "symfony/cache-implementation": "1.0" } } @@ -68,23 +75,4 @@ However, PHP-FIG has different goals and different processes. Symfony Contracts focuses on providing abstractions that are useful on their own while still compatible with implementations provided by Symfony. -Why Isn't this Package Split into Several Packages? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Putting all interfaces in one package eases discoverability and dependency -management. Instead of dealing with a myriad of small packages and the -corresponding matrix of versions, you only deal with one package and one -version. Also when using IDE autocompletion or reading the source code, it makes -it easier to figure out which contracts are provided. - -There are two downsides to this approach: - -* You may have unused files in your ``vendor/`` directory. This has no impact in - practice because the file sizes are very small and there is no performance - overhead at all since they are never loaded. -* In the future, it will be impossible to use two different sub-namespaces in - different major versions of the package. However, this package follows the - :doc:`Symfony BC + deprecation ` policies, with an - additional restriction to never remove deprecated interfaces. - .. _`PHP-FIG`: https://www.php-fig.org/