From fb27a705f7b9b2cbaf0c0b67a6c594ab5d14d47c Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 20 Apr 2016 08:54:12 +0200 Subject: [PATCH 1/5] Improved the docs for the DependencyInjection component --- .../dependency_injection/definitions.rst | 68 +++++++++++++++---- .../dependency_injection/introduction.rst | 5 +- 2 files changed, 58 insertions(+), 15 deletions(-) diff --git a/components/dependency_injection/definitions.rst b/components/dependency_injection/definitions.rst index bd13b766b43..e2c58613302 100644 --- a/components/dependency_injection/definitions.rst +++ b/components/dependency_injection/definitions.rst @@ -4,6 +4,9 @@ Working with Container Service Definitions ========================================== +Service definitions are the instructions followed by the container to build a +service, so they are not the actual services used by your application. + Getting and Setting Service Definitions --------------------------------------- @@ -32,7 +35,17 @@ with these methods and make changes to it these will be reflected in the container. If, however, you are creating a new definition then you can add it to the container using:: - $container->setDefinition($id, $definition); + use Symfony\Component\DependencyInjection\Definition; + + $definition = new Definition('Acme\Service\MyService'); + $container->setDefinition('app.my_service', $definition); + +.. tip:: + + Registering service definitions is so common that the container provides a + shortcut method called ``register()``: + + $container->register('app.my_service', 'Acme\Service\MyService'); Working with a Definition ------------------------- @@ -40,26 +53,50 @@ Working with a Definition Creating a New Definition ~~~~~~~~~~~~~~~~~~~~~~~~~ -If you need to create a new definition rather than manipulate one retrieved -from the container then the definition class is :class:`Symfony\\Component\\DependencyInjection\\Definition`. +In addition to manipulating and retrieving existing definitions, you can also +define new service definitions with the :class:`Symfony\\Component\\DependencyInjection\\Definition` +class. Class ~~~~~ -First up is the class of a definition, this is the class of the object returned -when the service is requested from the container. +The first optional argument of the ``Definition`` class is the fully qualified +class name of the object returned when the service is get from the container:: -To find out what class is set for a definition:: + use Symfony\Component\DependencyInjection\Definition; + + $definition = new Definition('Acme\Service\MyService'); + +If the class is unknown when instantiating the ``Definition`` class, use the +``setClass()`` method to set it later:: - $definition->getClass(); + $definition->setClass('Acme\Service\MyService'); -and to set a different class:: +To find out what class is set for a definition:: - $definition->setClass($class); // Fully qualified class name as string + $class = $definition->getClass(); + // $class = 'Acme\Service\MyService' Constructor Arguments ~~~~~~~~~~~~~~~~~~~~~ +The second optional argument of the ``Definition`` class is an array with the +arguments passed to the constructor of the object returned when the service is +get from the container:: + + use Symfony\Component\DependencyInjection\Definition; + + $definition = new Definition( + 'Acme\Service\MyService', + array('argument1' => 'value1', 'argument2' => 'value2') + ); + +If the arguments are unknown when instantiating the ``Definition`` class or if +you want to add new arguments, use the ``addArgument()`` method, which adds them +at the end of the arguments array:: + + $definition->addArgument($argument); + To get an array of the constructor arguments for a definition you can use:: $definition->getArguments(); @@ -69,12 +106,16 @@ or to get a single argument by its position:: $definition->getArgument($index); // e.g. $definition->getArgument(0) for the first argument -You can add a new argument to the end of the arguments array using:: +The argument can be a string, an array, a service parameter by using the +``%parameter_name%`` syntax:: - $definition->addArgument($argument); + $definition->addArgument('%kernel_debug%'); -The argument can be a string, an array, a service parameter by using ``%parameter_name%`` -or a service id by using:: +If the argument is another container service, don't use the ``get()`` method to +get the actual service, because it won't be available when defining services. +Instead, use the :class:`Symfony\\Component\\DependencyInjection\\Reference` +class to get a reference to the service available once the service container is +fully built:: use Symfony\Component\DependencyInjection\Reference; @@ -139,4 +180,3 @@ the service itself gets loaded. To do so, you can use the Notice that Symfony will internally call the PHP statement ``require_once``, which means that your file will be included only once per request. - diff --git a/components/dependency_injection/introduction.rst b/components/dependency_injection/introduction.rst index 42c526652fd..0ac5413dfe3 100644 --- a/components/dependency_injection/introduction.rst +++ b/components/dependency_injection/introduction.rst @@ -104,7 +104,10 @@ like this:: // ... } -Then you can register this as a service as well and pass the ``mailer`` service into it:: +Then you can register this as a service as well and pass the ``mailer`` service +into it. Instead of getting the actual ``mailer`` service, which doesn't exist +yet when defining the ``newsletter_manager``, use the ``Reference`` class to +get a reference to the future ``mailer`` service:: use Symfony\Component\DependencyInjection\ContainerBuilder; use Symfony\Component\DependencyInjection\Reference; From d7da32f4e6dce31b239d426c362ced840e7f11c9 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 25 Apr 2016 21:55:43 +0200 Subject: [PATCH 2/5] Fixes and rewordings --- components/dependency_injection/definitions.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/components/dependency_injection/definitions.rst b/components/dependency_injection/definitions.rst index e2c58613302..1e9e6bddbbd 100644 --- a/components/dependency_injection/definitions.rst +++ b/components/dependency_injection/definitions.rst @@ -61,7 +61,7 @@ Class ~~~~~ The first optional argument of the ``Definition`` class is the fully qualified -class name of the object returned when the service is get from the container:: +class name of the object returned when the service is fetched from the container:: use Symfony\Component\DependencyInjection\Definition; @@ -82,7 +82,7 @@ Constructor Arguments The second optional argument of the ``Definition`` class is an array with the arguments passed to the constructor of the object returned when the service is -get from the container:: +fetched from the container:: use Symfony\Component\DependencyInjection\Definition; @@ -106,15 +106,15 @@ or to get a single argument by its position:: $definition->getArgument($index); // e.g. $definition->getArgument(0) for the first argument -The argument can be a string, an array, a service parameter by using the +The argument can be a string, an array or a service parameter by using the ``%parameter_name%`` syntax:: $definition->addArgument('%kernel_debug%'); -If the argument is another container service, don't use the ``get()`` method to -get the actual service, because it won't be available when defining services. -Instead, use the :class:`Symfony\\Component\\DependencyInjection\\Reference` -class to get a reference to the service available once the service container is +If the argument is another service, don't use the ``get()`` method to fetch it, +because it won't be available when defining services. Instead, use the +:class:`Symfony\\Component\\DependencyInjection\\Reference` class to get a +reference to the service which will be available once the service container is fully built:: use Symfony\Component\DependencyInjection\Reference; From 7d24ee0185993a05f335f3409abd0f3104e3c024 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sat, 30 Apr 2016 12:40:43 +0200 Subject: [PATCH 3/5] Fixed a syntax issue --- components/dependency_injection/definitions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/dependency_injection/definitions.rst b/components/dependency_injection/definitions.rst index 1e9e6bddbbd..343b01ff567 100644 --- a/components/dependency_injection/definitions.rst +++ b/components/dependency_injection/definitions.rst @@ -43,7 +43,7 @@ it to the container using:: .. tip:: Registering service definitions is so common that the container provides a - shortcut method called ``register()``: + shortcut method called ``register()``:: $container->register('app.my_service', 'Acme\Service\MyService'); From d1f806c3df1342bd6444be635a2ce5bdc406ce2a Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sun, 1 May 2016 19:59:41 +0200 Subject: [PATCH 4/5] Rewords suggested by reviewers --- components/dependency_injection/definitions.rst | 4 ++-- components/dependency_injection/introduction.rst | 7 +++---- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/components/dependency_injection/definitions.rst b/components/dependency_injection/definitions.rst index 343b01ff567..7240de36ec4 100644 --- a/components/dependency_injection/definitions.rst +++ b/components/dependency_injection/definitions.rst @@ -4,8 +4,8 @@ Working with Container Service Definitions ========================================== -Service definitions are the instructions followed by the container to build a -service, so they are not the actual services used by your application. +Service definitions are the instructions describing how the container should +build a service. They are not the actual services used by your applications Getting and Setting Service Definitions --------------------------------------- diff --git a/components/dependency_injection/introduction.rst b/components/dependency_injection/introduction.rst index 0ac5413dfe3..a4ad2e93dac 100644 --- a/components/dependency_injection/introduction.rst +++ b/components/dependency_injection/introduction.rst @@ -104,10 +104,9 @@ like this:: // ... } -Then you can register this as a service as well and pass the ``mailer`` service -into it. Instead of getting the actual ``mailer`` service, which doesn't exist -yet when defining the ``newsletter_manager``, use the ``Reference`` class to -get a reference to the future ``mailer`` service:: +When defining the ``newsletter_manager`` service, the ``mailer`` service does +not exist yet. Use the ``Reference`` class to tell the container to inject the +``mailer`` service when it initializes the newsletter manager:: use Symfony\Component\DependencyInjection\ContainerBuilder; use Symfony\Component\DependencyInjection\Reference; From 396c4c732779592cedd1ae04d630dea83461989a Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 2 May 2016 16:00:17 +0200 Subject: [PATCH 5/5] Use "acme" instead of "app" --- components/dependency_injection/definitions.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/components/dependency_injection/definitions.rst b/components/dependency_injection/definitions.rst index 7240de36ec4..8fab146806d 100644 --- a/components/dependency_injection/definitions.rst +++ b/components/dependency_injection/definitions.rst @@ -38,14 +38,14 @@ it to the container using:: use Symfony\Component\DependencyInjection\Definition; $definition = new Definition('Acme\Service\MyService'); - $container->setDefinition('app.my_service', $definition); + $container->setDefinition('acme.my_service', $definition); .. tip:: Registering service definitions is so common that the container provides a shortcut method called ``register()``:: - $container->register('app.my_service', 'Acme\Service\MyService'); + $container->register('acme.my_service', 'Acme\Service\MyService'); Working with a Definition -------------------------