Merge branch '5.0'

* 5.0:
  Backported #12892 changes to 3.4
  Fix a minor code mistake
  Fix code example for definitionList.
  some spelling updates
  [DependencyInjection] Reworded the article about factories
  Fixed a wrong reference

Author: javiereguiluz

components/string.rst

@@ -461,7 +461,7 @@ the injected slugger is the same as the request locale::
 
         public function someMethod()
         {
-            $slug = $slugger->slug('...');
+            $slug = $this->slugger->slug('...');
         }
     }
 

console/style.rst

@@ -158,8 +158,8 @@ Content Methods
         $io->definitionList(
             'This is a title',
             ['foo1' => 'bar1'],
-            ['foo2' => 'bar2']
-            ['foo3' => 'bar3']
+            ['foo2' => 'bar2'],
+            ['foo3' => 'bar3'],
             new TableSeparator(),
             'This is another title',
             ['foo4' => 'bar4']

contributing/documentation/overview.rst

@@ -292,7 +292,7 @@ Why Do my Changes Take so Long to Be Reviewed and/or Merged?
 
 Please be patient. It can take up to several days before your pull request can
 be fully reviewed. After merging the changes, it could take again several hours
-before your changes appear on the ``symfony.com`` website.
+before your changes appear on the Symfony website.
 
 Why Should I Use the Oldest Maintained Branch Instead of the Master Branch?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

create_framework/introduction.rst

@@ -63,7 +63,7 @@ Before You Start
 Reading about how to create a framework is not enough. You will have to follow
 along and actually type all the examples included in this tutorial. For that,
 you need a recent version of PHP (5.5.9 or later is good enough), a web server
-(like Apache, NGINX or PHP's built-in web server), a good knowledge of PHP and
+(like Apache, nginx or PHP's built-in web server), a good knowledge of PHP and
 an understanding of Object Oriented programming.
 
 Ready to go? Read on!

service_container/factories.rst

@@ -4,13 +4,17 @@
 Using a Factory to Create Services
 ==================================
 
-Symfony's Service Container provides a powerful way of controlling the
-creation of objects, allowing you to specify arguments passed to the constructor
-as well as calling methods and setting parameters. Sometimes, however, this
-will not provide you with everything you need to construct your objects.
-For this situation, you can use a factory to create the object and tell
-the service container to call a method on the factory rather than directly
-instantiating the class.
+Symfony's Service Container provides multiple features to control the creation
+of objects, allowing you to specify arguments passed to the constructor as well
+as calling methods and setting parameters.
+
+However, sometimes you need to apply the `factory design pattern`_ to delegate
+the object creation to some special object called "the factory". In those cases,
+the service container can call a method on your factory to create the object
+rather than directly instantiating the class.
+
+Static Factories
+----------------
 
 Suppose you have a factory that configures and returns a new ``NewsletterManager``
 object by calling the static ``createNewsletterManager()`` method::
@@ -27,9 +31,9 @@ object by calling the static ``createNewsletterManager()`` method::
         }
     }
 
-To make the ``NewsletterManager`` object available as a service, you can
-configure the service container to use the
-``NewsletterManagerStaticFactory::createNewsletterManager()`` factory method:
+To make the ``NewsletterManager`` object available as a service, use the
+``factory`` option to define which method of which class must be called to
+create its object:
 
 .. configuration-block::
 
@@ -40,7 +44,7 @@ configure the service container to use the
             # ...
 
             App\Email\NewsletterManager:
-                # call the static method
+                # the first argument is the class and the second argument is the static method
                 factory: ['App\Email\NewsletterManagerStaticFactory', 'createNewsletterManager']
 
     .. code-block:: xml
@@ -54,7 +58,7 @@ configure the service container to use the
 
             <services>
                 <service id="App\Email\NewsletterManager">
-                    <!-- call the static method -->
+                    <!-- the first argument is the class and the second argument is the static method -->
                     <factory class="App\Email\NewsletterManagerStaticFactory" method="createNewsletterManager"/>
 
                     <!-- if the factory class is the same as the service class, you can omit
@@ -77,8 +81,8 @@ configure the service container to use the
         return function(ContainerConfigurator $configurator) {
             $services = $configurator->services();
 
-            // call the static method
             $services->set(NewsletterManager::class)
+                // the first argument is the class and the second argument is the static method
                 ->factory([NewsletterManagerStaticFactory::class, 'createNewsletterManager']);
         };
 
@@ -91,11 +95,11 @@ configure the service container to use the
     the configured class name may be used by compiler passes and therefore
     should be set to a sensible value.
 
-If your factory is not using a static function to configure and create your
-service, but a regular method, you can instantiate the factory itself as a
-service too. Later, in the ":ref:`factories-passing-arguments-factory-method`"
-section, you learn how you can inject arguments in this method.
+Non-Static Factories
+--------------------
 
+If your factory is using a regular method instead of a static one to configure
+and create the service, instantiate the factory itself as a service too.
 Configuration of the service container then looks like this:
 
 .. configuration-block::
@@ -106,10 +110,12 @@ Configuration of the service container then looks like this:
         services:
             # ...
 
+            # first, create a service for the factory
             App\Email\NewsletterManagerFactory: ~
 
+            # second, use the factory service as the first argument of the 'factory'
+            # option and the factory method as the second argument
             App\Email\NewsletterManager:
-                # call a method on the specified factory service
                 factory: ['@App\Email\NewsletterManagerFactory', 'createNewsletterManager']
 
     .. code-block:: xml
@@ -122,10 +128,12 @@ Configuration of the service container then looks like this:
                 https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
+                <!-- first, create a service for the factory -->
                 <service id="App\Email\NewsletterManagerFactory"/>
 
+                <!-- second, use the factory service as the first argument of the 'factory'
+                     option and the factory method as the second argument -->
                 <service id="App\Email\NewsletterManager">
-                    <!-- call a method on the specified factory service -->
                     <factory service="App\Email\NewsletterManagerFactory"
                         method="createNewsletterManager"
                     />
@@ -144,15 +152,20 @@ Configuration of the service container then looks like this:
         return function(ContainerConfigurator $configurator) {
             $services = $configurator->services();
 
+            // first, create a service for the factory
             $services->set(NewsletterManagerFactory::class);
 
-            // call a method on the specified factory service
+            // second, use the factory service as the first argument of the 'factory'
+            // method and the factory method as the second argument
             $services->set(NewsletterManager::class)
                 ->factory([ref(NewsletterManagerFactory::class), 'createNewsletterManager']);
         };
 
 .. _factories-invokable:
 
+Invokable Factories
+-------------------
+
 Suppose you now change your factory method to ``__invoke()`` so that your
 factory service can be used as a callback::
 
@@ -230,8 +243,8 @@ Passing Arguments to the Factory Method
     that's enabled for your service.
 
 If you need to pass arguments to the factory method you can use the ``arguments``
-options. For example, suppose the ``createNewsletterManager()`` method in the previous
-example takes the ``templating`` service as an argument:
+option. For example, suppose the ``createNewsletterManager()`` method in the
+previous examples takes the ``templating`` service as an argument:
 
 .. configuration-block::
 
@@ -281,3 +294,4 @@ example takes the ``templating`` service as an argument:
             ;
         };
 
+.. _`factory design pattern`: https://en.wikipedia.org/wiki/Factory_(object-oriented_programming)

templating/hinclude.rst

@@ -10,7 +10,7 @@ performance you can use the `hinclude.js`_ JavaScript library to embed
 controllers asynchronously.
 
 First, include the `hinclude.js`_ library in your page
-ref:`linking to it <templates-link-to-assets>` from the template or adding it
+:ref:`linking to it <templates-link-to-assets>` from the template or adding it
 to your application JavaScript :doc:`using Webpack Encore </frontend>`.
 
 As the embedded content comes from another page (or controller for that matter),