From b63cb299c3adb45cf3cb98a237939901bd287f98 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 15 Apr 2019 12:59:36 +0200 Subject: [PATCH 1/3] Documented the Contracts component --- components/contracts.rst | 90 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 components/contracts.rst diff --git a/components/contracts.rst b/components/contracts.rst new file mode 100644 index 00000000000..00892f76cce --- /dev/null +++ b/components/contracts.rst @@ -0,0 +1,90 @@ +.. index:: + single: Contracts + single: Components; Contracts + +The Contracts Component +========================= + + The Contracts component provides 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 battle-tested implementations. + +Installation +------------ + +.. code-block:: terminal + + $ composer require symfony/contracts + +.. include:: /components/require_autoload.rst.inc + +Usage +----- + +The abstractions in this package are useful to achieve loose coupling and +interoperability. By using the provided interfaces as type hints, you are able +to reuse any implementations that match their contracts. It could be a Symfony +component, or another package provided by the PHP community at large. + +Depending on their semantics, some interfaces can be combined with +:doc:`autowiring ` to seamlessly inject a service +in your classes. + +Others might be useful as labeling interfaces, to hint about a specific behavior +that can be enabled when using :ref:`autoconfiguration ` +or manual :doc:`service tagging ` (or any other means +provided 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, normative + docblocks 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 ``provide`` +section of their ``composer.json`` file, using the +``symfony/*-contracts-implementation`` convention. For example: + +.. code-block:: javascript + + { + "...": "...", + "provide": { + "symfony/cache-contracts-implementation": "1.0" + } + } + +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 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/ From ef18cb535fa0193c8ca5fcd4f53db98d3761ee85 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 15 Apr 2019 13:01:07 +0200 Subject: [PATCH 2/3] - --- components/contracts.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/contracts.rst b/components/contracts.rst index 00892f76cce..2bf61dd68a0 100644 --- a/components/contracts.rst +++ b/components/contracts.rst @@ -3,7 +3,7 @@ single: Components; Contracts The Contracts Component -========================= +======================= The Contracts component provides a set of abstractions extracted out of the Symfony components. They can be used to build on semantics that the Symfony From 28e0e96f5901ddc7e0aeff39190ee602b2c97ab6 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 15 Apr 2019 14:55:53 +0200 Subject: [PATCH 3/3] Fixed title case --- components/contracts.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/components/contracts.rst b/components/contracts.rst index 2bf61dd68a0..cfc1081101a 100644 --- a/components/contracts.rst +++ b/components/contracts.rst @@ -60,7 +60,7 @@ section of their ``composer.json`` file, using the Frequently Asked Questions -------------------------- -How is This Different from PHP-FIG's PSRs? +How Is this Different From PHP-FIG's PSRs? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When applicable, the provided contracts are built on top of `PHP-FIG`_'s PSRs. @@ -68,7 +68,7 @@ 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? +Why Isn't this Package Split into Several Packages? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Putting all interfaces in one package eases discoverability and dependency