From 2394e3f194a506c9858988ec4fa589a4103fdc1c Mon Sep 17 00:00:00 2001 From: Christian Flothmann Date: Sun, 13 Dec 2015 12:30:28 +0100 Subject: [PATCH] use AppBundle examples and follow best practices --- book/from_flat_php_to_symfony2.rst | 2 +- book/page_creation.rst | 4 +- book/routing.rst | 6 +- book/service_container.rst | 231 +++++++++++++++-------------- 4 files changed, 122 insertions(+), 121 deletions(-) diff --git a/book/from_flat_php_to_symfony2.rst b/book/from_flat_php_to_symfony2.rst index e93324304c4..bfbc99b2138 100644 --- a/book/from_flat_php_to_symfony2.rst +++ b/book/from_flat_php_to_symfony2.rst @@ -554,7 +554,7 @@ them for you. Here's the same sample application, now built in Symfony:: { $posts = $this->get('doctrine') ->getManager() - ->createQuery('SELECT p FROM AcmeBlogBundle:Post p') + ->createQuery('SELECT p FROM AppBundle:Post p') ->execute(); return $this->render('Blog/list.html.php', array('posts' => $posts)); diff --git a/book/page_creation.rst b/book/page_creation.rst index 7c1d83fa9c7..4a762d61478 100644 --- a/book/page_creation.rst +++ b/book/page_creation.rst @@ -191,7 +191,7 @@ at the end: .. code-block:: xml - + ``BlogController``) and ``Action`` to the method name (``show`` => ``showAction``). You could also refer to this controller using its fully-qualified class name -and method: ``Acme\BlogBundle\Controller\BlogController::showAction``. -But if you follow some simple conventions, the logical name is more concise -and allows more flexibility. +and method: ``AppBundle\Controller\BlogController::showAction``. But if you +follow some simple conventions, the logical name is more concise and allows +more flexibility. .. note:: diff --git a/book/service_container.rst b/book/service_container.rst index 3cfd209f62d..da165ceae4b 100644 --- a/book/service_container.rst +++ b/book/service_container.rst @@ -79,7 +79,7 @@ For example, suppose you have a simple PHP class that delivers email messages. Without a service container, you must manually create the object whenever you need it:: - use Acme\HelloBundle\Mailer; + use AppBundle\Mailer; $mailer = new Mailer('sendmail'); $mailer->send('ryan@example.com', ...); @@ -111,8 +111,8 @@ be specified in YAML, XML or PHP: # app/config/services.yml services: - my_mailer: - class: Acme\HelloBundle\Mailer + app.mailer: + class: AppBundle\Mailer arguments: [sendmail] .. code-block:: xml @@ -125,7 +125,7 @@ be specified in YAML, XML or PHP: http://symfony.com/schema/dic/services/services-1.0.xsd"> - + sendmail @@ -136,8 +136,8 @@ be specified in YAML, XML or PHP: // app/config/services.php use Symfony\Component\DependencyInjection\Definition; - $container->setDefinition('my_mailer', new Definition( - 'Acme\HelloBundle\Mailer', + $container->setDefinition('app.mailer', new Definition( + 'AppBundle\Mailer', array('sendmail') )); @@ -150,10 +150,10 @@ be specified in YAML, XML or PHP: ``config_dev.yml`` for the ``dev`` environment or ``config_prod.yml`` for ``prod``). -An instance of the ``Acme\HelloBundle\Mailer`` object is now available via -the service container. The container is available in any traditional Symfony -controller where you can access the services of the container via the ``get()`` -shortcut method:: +An instance of the ``AppBundle\Mailer`` class is now available via the service +container. The container is available in any traditional Symfony controller +where you can access the services of the container via the ``get()`` shortcut +method:: class HelloController extends Controller { @@ -162,12 +162,12 @@ shortcut method:: public function sendEmailAction() { // ... - $mailer = $this->get('my_mailer'); + $mailer = $this->get('app.mailer'); $mailer->send('ryan@foobar.net', ...); } } -When you ask for the ``my_mailer`` service from the container, the container +When you ask for the ``app.mailer`` service from the container, the container constructs the object and returns it. This is another major advantage of using the service container. Namely, a service is *never* constructed until it's needed. If you define a service and never use it on a request, the service @@ -185,7 +185,7 @@ later how you can configure a service that has multiple instances in the In this example, the controller extends Symfony's base Controller, which gives you access to the service container itself. You can then use the - ``get`` method to locate and retrieve the ``my_mailer`` service from + ``get`` method to locate and retrieve the ``app.mailer`` service from the service container. You can also define your :doc:`controllers as services `. This is a bit more advanced and not necessary, but it allows you to inject only the services you need into your controller. @@ -202,18 +202,18 @@ straightforward. Parameters make defining services more organized and flexible: .. code-block:: yaml - # app/config/config.yml + # app/config/services.yml parameters: - my_mailer.transport: sendmail + app.mailer.transport: sendmail services: - my_mailer: - class: Acme\HelloBundle\Mailer - arguments: ['%my_mailer.transport%'] + app.mailer: + class: AppBundle\Mailer + arguments: ['%app.mailer.transport%'] .. code-block:: xml - + - sendmail + sendmail - - %my_mailer.transport% + + %app.mailer.transport% .. code-block:: php - // app/config/config.php + // app/config/services.php use Symfony\Component\DependencyInjection\Definition; - $container->setParameter('my_mailer.transport', 'sendmail'); + $container->setParameter('app.mailer.transport', 'sendmail'); - $container->setDefinition('my_mailer', new Definition( - 'Acme\HelloBundle\Mailer', - array('%my_mailer.transport%') + $container->setDefinition('app.mailer', new Definition( + 'AppBundle\Mailer', + array('%app.mailer.transport%') )); The end result is exactly the same as before - the difference is only in -*how* you defined the service. By surrounding the ``my_mailer.transport`` -string in percent (``%``) signs, the container knows to look for a parameter +*how* you defined the service. By enclosing the ``app.mailer.transport`` +string with percent (``%``) signs, the container knows to look for a parameter with that name. When the container is built, it looks up the value of each parameter and uses it in the service definition. @@ -332,13 +332,13 @@ configuration. Read on to learn more about both methods. Importing Configuration with ``imports`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -So far, you've placed your ``my_mailer`` service container definition directly +So far, you've placed your ``app.mailer`` service container definition directly in the application configuration file (e.g. ``app/config/config.yml``). Of course, since the ``Mailer`` class itself lives inside the AcmeHelloBundle, it -makes more sense to put the ``my_mailer`` container definition inside the +makes more sense to put the ``app.mailer`` container definition inside the bundle as well. -First, move the ``my_mailer`` container definition into a new container resource +First, move the ``app.mailer`` container definition into a new container resource file inside AcmeHelloBundle. If the ``Resources`` or ``Resources/config`` directories don't exist, create them. @@ -348,12 +348,12 @@ directories don't exist, create them. # src/Acme/HelloBundle/Resources/config/services.yml parameters: - my_mailer.transport: sendmail + app.mailer.transport: sendmail services: - my_mailer: - class: Acme\HelloBundle\Mailer - arguments: ['%my_mailer.transport%'] + app.mailer: + class: AppBundle\Mailer + arguments: ['%app.mailer.transport%'] .. code-block:: xml @@ -365,12 +365,12 @@ directories don't exist, create them. http://symfony.com/schema/dic/services/services-1.0.xsd"> - sendmail + sendmail - - %my_mailer.transport% + + %app.mailer.transport% @@ -380,11 +380,11 @@ directories don't exist, create them. // src/Acme/HelloBundle/Resources/config/services.php use Symfony\Component\DependencyInjection\Definition; - $container->setParameter('my_mailer.transport', 'sendmail'); + $container->setParameter('app.mailer.transport', 'sendmail'); - $container->setDefinition('my_mailer', new Definition( - 'Acme\HelloBundle\Mailer', - array('%my_mailer.transport%') + $container->setDefinition('app.mailer', new Definition( + 'AppBundle\Mailer', + array('%app.mailer.transport%') )); The definition itself hasn't changed, only its location. Of course the service @@ -554,22 +554,22 @@ If you want to expose user friendly configuration in your own bundles, read the Referencing (Injecting) Services -------------------------------- -So far, the original ``my_mailer`` service is simple: it takes just one argument +So far, the original ``app.mailer`` service is simple: it takes just one argument in its constructor, which is easily configurable. As you'll see, the real power of the container is realized when you need to create a service that depends on one or more other services in the container. As an example, suppose you have a new service, ``NewsletterManager``, that helps to manage the preparation and delivery of an email message to -a collection of addresses. Of course the ``my_mailer`` service is already +a collection of addresses. Of course the ``app.mailer`` service is already really good at delivering email messages, so you'll use it inside ``NewsletterManager`` to handle the actual delivery of the messages. This pretend class might look something like this:: - // src/Acme/HelloBundle/Newsletter/NewsletterManager.php - namespace Acme\HelloBundle\Newsletter; + // src/AppBundle/Newsletter/NewsletterManager.php + namespace AppBundle\Newsletter; - use Acme\HelloBundle\Mailer; + use AppBundle\Mailer; class NewsletterManager { @@ -586,13 +586,13 @@ something like this:: Without using the service container, you can create a new ``NewsletterManager`` fairly easily from inside a controller:: - use Acme\HelloBundle\Newsletter\NewsletterManager; + use AppBundle\Newsletter\NewsletterManager; // ... public function sendNewsletterAction() { - $mailer = $this->get('my_mailer'); + $mailer = $this->get('app.mailer'); $newsletter = new NewsletterManager($mailer); // ... } @@ -607,18 +607,18 @@ the service container gives you a much more appealing option: .. code-block:: yaml - # src/Acme/HelloBundle/Resources/config/services.yml + # app/config/services.yml services: - my_mailer: + app.mailer: # ... - newsletter_manager: - class: Acme\HelloBundle\Newsletter\NewsletterManager - arguments: ['@my_mailer'] + app.newsletter_manager: + class: AppBundle\Newsletter\NewsletterManager + arguments: ['@app.mailer'] .. code-block:: xml - + - + - - + + .. code-block:: php - // src/Acme/HelloBundle/Resources/config/services.php + // app/config/services.php use Symfony\Component\DependencyInjection\Definition; use Symfony\Component\DependencyInjection\Reference; - $container->setDefinition('my_mailer', ...); + $container->setDefinition('app.mailer', ...); - $container->setDefinition('newsletter_manager', new Definition( - 'Acme\HelloBundle\Newsletter\NewsletterManager', - array(new Reference('my_mailer')) + $container->setDefinition('app.newsletter_manager', new Definition( + 'AppBundle\Newsletter\NewsletterManager', + array(new Reference('app.mailer')) )); -In YAML, the special ``@my_mailer`` syntax tells the container to look for -a service named ``my_mailer`` and to pass that object into the constructor -of ``NewsletterManager``. In this case, however, the specified service ``my_mailer`` +In YAML, the special ``@app.mailer`` syntax tells the container to look for +a service named ``app.mailer`` and to pass that object into the constructor +of ``NewsletterManager``. In this case, however, the specified service ``app.mailer`` must exist. If it does not, an exception will be thrown. You can mark your dependencies as optional - this will be discussed in the next section. Using references is a very powerful tool that allows you to create independent service -classes with well-defined dependencies. In this example, the ``newsletter_manager`` -service needs the ``my_mailer`` service in order to function. When you define +classes with well-defined dependencies. In this example, the ``app.newsletter_manager`` +service needs the ``app.mailer`` service in order to function. When you define this dependency in the service container, the container takes care of all the work of instantiating the classes. @@ -670,9 +670,9 @@ dependencies for a class, then "setter injection" may be a better option. This means injecting the dependency using a method call rather than through the constructor. The class would look like this:: - namespace Acme\HelloBundle\Newsletter; + namespace AppBundle\Newsletter; - use Acme\HelloBundle\Mailer; + use AppBundle\Mailer; class NewsletterManager { @@ -692,19 +692,19 @@ Injecting the dependency by the setter method just needs a change of syntax: .. code-block:: yaml - # src/Acme/HelloBundle/Resources/config/services.yml + # app/config/services.yml services: - my_mailer: + app.mailer: # ... - newsletter_manager: - class: Acme\HelloBundle\Newsletter\NewsletterManager + app.newsletter_manager: + class: AppBundle\Newsletter\NewsletterManager calls: - - [setMailer, ['@my_mailer']] + - [setMailer, ['@app.mailer']] .. code-block:: xml - + - + - + - + @@ -726,16 +726,16 @@ Injecting the dependency by the setter method just needs a change of syntax: .. code-block:: php - // src/Acme/HelloBundle/Resources/config/services.php + // app/config/services.php use Symfony\Component\DependencyInjection\Definition; use Symfony\Component\DependencyInjection\Reference; - $container->setDefinition('my_mailer', ...); + $container->setDefinition('app.mailer', ...); - $container->setDefinition('newsletter_manager', new Definition( - 'Acme\HelloBundle\Newsletter\NewsletterManager' + $container->setDefinition('app.newsletter_manager', new Definition( + 'AppBundle\Newsletter\NewsletterManager' ))->addMethodCall('setMailer', array( - new Reference('my_mailer'), + new Reference('app.mailer'), )); .. note:: @@ -749,8 +749,8 @@ Making References optional Sometimes, one of your services may have an optional dependency, meaning that the dependency is not required for your service to work properly. In -the example above, the ``my_mailer`` service *must* exist, otherwise an exception -will be thrown. By modifying the ``newsletter_manager`` service definition, +the example above, the ``app.mailer`` service *must* exist, otherwise an exception +will be thrown. By modifying the ``app.newsletter_manager`` service definition, you can make this reference optional. The container will then inject it if it exists and do nothing if it doesn't: @@ -758,15 +758,15 @@ it exists and do nothing if it doesn't: .. code-block:: yaml - # src/Acme/HelloBundle/Resources/config/services.yml + # app/config/services.yml services: - newsletter_manager: - class: Acme\HelloBundle\Newsletter\NewsletterManager - arguments: ['@?my_mailer'] + app.newsletter_manager: + class: AppBundle\Newsletter\NewsletterManager + arguments: ['@?app.mailer'] .. code-block:: xml - + - + - - + + .. code-block:: php - // src/Acme/HelloBundle/Resources/config/services.php + // app/config/services.php use Symfony\Component\DependencyInjection\Definition; use Symfony\Component\DependencyInjection\Reference; use Symfony\Component\DependencyInjection\ContainerInterface; - $container->setDefinition('my_mailer', ...); + $container->setDefinition('app.mailer', ...); - $container->setDefinition('newsletter_manager', new Definition( - 'Acme\HelloBundle\Newsletter\NewsletterManager', + $container->setDefinition('app.newsletter_manager', new Definition( + 'AppBundle\Newsletter\NewsletterManager', array( new Reference( - 'my_mailer', + 'app.mailer', ContainerInterface::IGNORE_ON_INVALID_REFERENCE ) ) @@ -837,11 +837,12 @@ sending emails (``mailer``), or accessing information on the request (``request` You can take this a step further by using these services inside services that you've created for your application. Beginning by modifying the ``NewsletterManager`` -to use the real Symfony ``mailer`` service (instead of the pretend ``my_mailer``). +to use the real Symfony ``mailer`` service (instead of the pretend ``app.mailer``). Also pass the templating engine service to the ``NewsletterManager`` so that it can generate the email content via a template:: - namespace Acme\HelloBundle\Newsletter; + // src/AppBundle/Newsletter/NewsletterManager.php + namespace AppBundle\Newsletter; use Symfony\Component\Templating\EngineInterface; @@ -868,22 +869,22 @@ Configuring the service container is easy: .. code-block:: yaml - # src/Acme/HelloBundle/Resources/config/services.yml + # app/config/services.yml services: - newsletter_manager: - class: Acme\HelloBundle\Newsletter\NewsletterManager + app.newsletter_manager: + class: AppBundle\Newsletter\NewsletterManager arguments: ['@mailer', '@templating'] .. code-block:: xml - + - + @@ -891,16 +892,16 @@ Configuring the service container is easy: .. code-block:: php - // src/Acme/HelloBundle/Resources/config/services.php - $container->setDefinition('newsletter_manager', new Definition( - 'Acme\HelloBundle\Newsletter\NewsletterManager', + // app/config/services.php + $container->setDefinition('app.newsletter_manager', new Definition( + 'AppBundle\Newsletter\NewsletterManager', array( new Reference('mailer'), new Reference('templating'), ) )); -The ``newsletter_manager`` service now has access to the core ``mailer`` +The ``app.newsletter_manager`` service now has access to the core ``mailer`` and ``templating`` services. This is a common way to create services specific to your application that leverage the power of different services within the framework. @@ -929,7 +930,7 @@ to be used for a specific purpose. Take the following example: # app/config/services.yml services: foo.twig.extension: - class: Acme\HelloBundle\Extension\FooExtension + class: AppBundle\Extension\FooExtension public: false tags: - { name: twig.extension } @@ -946,7 +947,7 @@ to be used for a specific purpose. Take the following example: @@ -959,7 +960,7 @@ to be used for a specific purpose. Take the following example: // app/config/services.php use Symfony\Component\DependencyInjection\Definition; - $definition = new Definition('Acme\HelloBundle\Extension\FooExtension'); + $definition = new Definition('AppBundle\Extension\FooExtension'); $definition->setPublic(false); $definition->addTag('twig.extension'); $container->setDefinition('foo.twig.extension', $definition); @@ -1006,7 +1007,7 @@ its id: .. code-block:: bash - $ php app/console container:debug my_mailer + $ php app/console container:debug app.mailer Learn more ----------