Skip to content

[Components] consistent & complete config examples #4129

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

Merged
merged 1 commit into from
Aug 16, 2014
Merged

[Components] consistent & complete config examples #4129

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
60 changes: 48 additions & 12 deletions components/dependency_injection/advanced.rst
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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