Skip to content

Commit

Permalink
minor #4129 [Components] consistent & complete config examples (xabbuh)
Browse files Browse the repository at this point in the history 
This PR was merged into the 2.3 branch.

Discussion
----------

[Components] consistent & complete config examples

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | no
| Applies to    | all
| Fixed tickets |

Make configuration examples in the components section consistent throughout the different configuration formats. Also fixing several syntax issues.

This is mainly the same that I did in #4114 for the book.

Commits
-------

d08da50 [Components] consistent & complete config examples
  • Loading branch information
@weaverryan
weaverryan committed Aug 16, 2014
2 parents 46f3108 + d08da50 commit 189a123
Show file tree
Hide file tree
Showing 11 changed files with 456 additions and 318 deletions.
60 changes: 48 additions & 12 deletions components/dependency_injection/advanced.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,10 +42,20 @@ Here is an example:
.. code-block:: xml
<service id="foo" class="Example\Foo" public="false" />
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
<services>
<service id="foo" class="Example\Foo" public="false" />
</services>
</container>
.. code-block:: php
use Symfony\Component\DependencyInjection\Definition;
$definition = new Definition('Example\Foo');
$definition->setPublic(false);
$container->setDefinition('foo', $definition);
Expand Down Expand Up @@ -88,15 +98,22 @@ To create a synthetic service, set ``synthetic`` to ``true``:
.. code-block:: xml
<service id="request"
synthetic="true" />
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
<services>
<service id="request" synthetic="true" />
</services>
</container>
.. code-block:: php
use Symfony\Component\DependencyInjection\Definition;
// ...
$container->setDefinition('request', new Definition())
$container
->setDefinition('request', new Definition())
->setSynthetic(true);
As you see, only the ``synthetic`` option is set. All other options are only used
Expand Down Expand Up @@ -128,14 +145,23 @@ services.
.. code-block:: xml
<service id="foo" class="Example\Foo"/>
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
<services>
<service id="foo" class="Example\Foo" />
<service id="bar" alias="foo" />
<service id="bar" alias="foo" />
</services>
</container>
.. code-block:: php
$definition = new Definition('Example\Foo');
$container->setDefinition('foo', $definition);
use Symfony\Component\DependencyInjection\Definition;
$container->setDefinition('foo', new Definition('Example\Foo'));
$containerBuilder->setAlias('bar', 'foo');
Expand Down Expand Up @@ -173,12 +199,22 @@ the service itself gets loaded. To do so, you can use the ``file`` directive.
.. code-block:: xml
<service id="foo" class="Example\Foo\Bar">
<file>%kernel.root_dir%/src/path/to/file/foo.php</file>
</service>
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
<services>
<service id="foo" class="Example\Foo\Bar">
<file>%kernel.root_dir%/src/path/to/file/foo.php</file>
</service>
</services>
</container>
.. code-block:: php
use Symfony\Component\DependencyInjection\Definition;
$definition = new Definition('Example\Foo\Bar');
$definition->setFile('%kernel.root_dir%/src/path/to/file/foo.php');
$container->setDefinition('foo', $definition);
Expand Down
1 change: 0 additions & 1 deletion components/dependency_injection/compilation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -203,7 +203,6 @@ The XML version of the config would then look like this:
<acme_demo:foo>fooValue</acme_hello:foo>
<acme_demo:bar>barValue</acme_demo:bar>
</acme_demo:config>
</container>
.. note::
Expand Down
58 changes: 34 additions & 24 deletions components/dependency_injection/configurators.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -155,30 +155,40 @@ The service config for the above classes would look something like this:
.. code-block:: xml
<services>
<service id="my_mailer">
<!-- ... -->
</service>
<service id="email_formatter_manager" class="EmailFormatterManager">
<!-- ... -->
</service>
<service id="email_configurator" class="EmailConfigurator">
<argument type="service" id="email_formatter_manager" />
<!-- ... -->
</service>
<service id="newsletter_manager" class="NewsletterManager">
<call method="setMailer">
<argument type="service" id="my_mailer" />
</call>
<configurator service="email_configurator" method="configure" />
</service>
<service id="greeting_card_manager" class="GreetingCardManager">
<call method="setMailer">
<argument type="service" id="my_mailer" />
</call>
<configurator service="email_configurator" method="configure" />
</service>
</services>
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
<services>
<service id="my_mailer">
<!-- ... -->
</service>
<service id="email_formatter_manager" class="EmailFormatterManager">
<!-- ... -->
</service>
<service id="email_configurator" class="EmailConfigurator">
<argument type="service" id="email_formatter_manager" />
<!-- ... -->
</service>
<service id="newsletter_manager" class="NewsletterManager">
<call method="setMailer">
<argument type="service" id="my_mailer" />
</call>
<configurator service="email_configurator" method="configure" />
</service>
<service id="greeting_card_manager" class="GreetingCardManager">
<call method="setMailer">
<argument type="service" id="my_mailer" />
</call>
<configurator service="email_configurator" method="configure" />
</service>
</services>
</container>
.. code-block:: php
Expand Down
120 changes: 70 additions & 50 deletions components/dependency_injection/factories.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,18 +47,24 @@ class:
.. code-block:: xml
<parameters>
<!-- ... -->
<parameter key="newsletter_manager.class">NewsletterManager</parameter>
<parameter key="newsletter_factory.class">NewsletterFactory</parameter>
</parameters>
<services>
<service id="newsletter_manager"
class="%newsletter_manager.class%"
factory-class="%newsletter_factory.class%"
factory-method="get"
/>
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
<parameters>
<!-- ... -->
<parameter key="newsletter_manager.class">NewsletterManager</parameter>
<parameter key="newsletter_factory.class">NewsletterFactory</parameter>
</parameters>
<services>
<service
id="newsletter_manager"
class="%newsletter_manager.class%"
factory-class="%newsletter_factory.class%"
factory-method="get" />
</services>
</services>
.. code-block:: php
Expand All @@ -69,13 +75,11 @@ class:
$container->setParameter('newsletter_manager.class', 'NewsletterManager');
$container->setParameter('newsletter_factory.class', 'NewsletterFactory');
$container->setDefinition('newsletter_manager', new Definition(
'%newsletter_manager.class%'
))->setFactoryClass(
'%newsletter_factory.class%'
)->setFactoryMethod(
'get'
);
$definition = new Definition('%newsletter_manager.class%');
$definition->setFactoryClass('%newsletter_factory.class%');
$definition->setFactoryMethod('get');
$container->setDefinition('newsletter_manager', $definition);
When you specify the class to use for the factory (via ``factory_class``)
the method will be called statically. If the factory itself should be instantiated
Expand All @@ -100,20 +104,27 @@ In this case, the method (e.g. get) should be changed to be non-static:
.. code-block:: xml
<parameters>
<!-- ... -->
<parameter key="newsletter_manager.class">NewsletterManager</parameter>
<parameter key="newsletter_factory.class">NewsletterFactory</parameter>
</parameters>
<services>
<service id="newsletter_factory" class="%newsletter_factory.class%"/>
<service id="newsletter_manager"
class="%newsletter_manager.class%"
factory-service="newsletter_factory"
factory-method="get"
/>
</services>
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
<parameters>
<!-- ... -->
<parameter key="newsletter_manager.class">NewsletterManager</parameter>
<parameter key="newsletter_factory.class">NewsletterFactory</parameter>
</parameters>
<services>
<service id="newsletter_factory" class="%newsletter_factory.class%"/>
<service
id="newsletter_manager"
class="%newsletter_manager.class%"
factory-service="newsletter_factory"
factory-method="get" />
</services>
</container>
.. code-block:: php
Expand All @@ -137,7 +148,8 @@ In this case, the method (e.g. get) should be changed to be non-static:
.. note::

The factory service is specified by its id name and not a reference to
the service itself. So, you do not need to use the @ syntax.
the service itself. So, you do not need to use the @ syntax for this in
YAML configurations.

Passing Arguments to the Factory Method
---------------------------------------
Expand Down Expand Up @@ -166,22 +178,30 @@ in the previous example takes the ``templating`` service as an argument:
.. code-block:: xml
<parameters>
<!-- ... -->
<parameter key="newsletter_manager.class">NewsletterManager</parameter>
<parameter key="newsletter_factory.class">NewsletterFactory</parameter>
</parameters>
<services>
<service id="newsletter_factory" class="%newsletter_factory.class%"/>
<service id="newsletter_manager"
class="%newsletter_manager.class%"
factory-service="newsletter_factory"
factory-method="get"
>
<argument type="service" id="templating" />
</service>
</services>
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
<parameters>
<!-- ... -->
<parameter key="newsletter_manager.class">NewsletterManager</parameter>
<parameter key="newsletter_factory.class">NewsletterFactory</parameter>
</parameters>
<services>
<service id="newsletter_factory" class="%newsletter_factory.class%"/>
<service
id="newsletter_manager"
class="%newsletter_manager.class%"
factory-service="newsletter_factory"
factory-method="get">
<argument type="service" id="templating" />
</service>
</services>
</container>
.. code-block:: php
Expand Down
38 changes: 22 additions & 16 deletions components/dependency_injection/introduction.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -244,22 +244,28 @@ config files:
.. code-block:: xml
<parameters>
<!-- ... -->
<parameter key="mailer.transport">sendmail</parameter>
</parameters>
<services>
<service id="mailer" class="Mailer">
<argument>%mailer.transport%</argument>
</service>
<service id="newsletter_manager" class="NewsletterManager">
<call method="setMailer">
<argument type="service" id="mailer" />
</call>
</service>
</services>
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
<parameters>
<!-- ... -->
<parameter key="mailer.transport">sendmail</parameter>
</parameters>
<services>
<service id="mailer" class="Mailer">
<argument>%mailer.transport%</argument>
</service>
<service id="newsletter_manager" class="NewsletterManager">
<call method="setMailer">
<argument type="service" id="mailer" />
</call>
</service>
</services>
</container>
.. code-block:: php
Expand Down
12 changes: 11 additions & 1 deletion components/dependency_injection/lazy_services.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -62,10 +62,20 @@ You can mark the service as ``lazy`` by manipulating its definition:
.. code-block:: xml
<service id="foo" class="Acme\Foo" lazy="true" />
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
<services>
<service id="foo" class="Acme\Foo" lazy="true" />
</services>
</container>
.. code-block:: php
use Symfony\Component\DependencyInjection\Definition;
$definition = new Definition('Acme\Foo');
$definition->setLazy(true);
$container->setDefinition('foo', $definition);
Expand Down
Loading

0 comments on commit 189a123

Please sign in to comment.