Skip to content

Updated Symfony Contracts package names and installation #11609

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 3 commits into from
Closed

Updated Symfony Contracts package names and installation #11609

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d7b3c37
Updated Symfony Contracts package names and installation
javiereguiluz May 27, 2019
b4dfb6b
Fixed the package names
javiereguiluz May 27, 2019
593930b
Removed an outdated section
javiereguiluz May 27, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 11 additions & 23 deletions components/contracts.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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"
}
}

Expand All @@ -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 </contributing/code/bc>` policies, with an
additional restriction to never remove deprecated interfaces.

.. _`PHP-FIG`: https://www.php-fig.org/