Skip to content

Commit

Permalink
[Components] consistent & complete config examples
Browse files Browse the repository at this point in the history 
Make configuration examples in the components section consistent
throughout the different configuration formats. Also fixing several
syntax issues.
  • Loading branch information
@xabbuh
xabbuh committed Aug 16, 2014
1 parent 7bb4f34 commit d08da50
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 d08da50

Please sign in to comment.