Merge remote-tracking branch 'origin/2.7' into 2.7

* origin/2.7: (51 commits)
  Avoid backticks in shell scripts
  Update optional_dependencies.rst
  Fix xml blocks
  [#7875] minor tweaks
  Minor fix
  Minor changes
  [#7773] fix line length
  Add helpful remarks on custom DataCollector
  Remove use of deprecated security.exception_listener.class parameter
  Update resources.rst
  Fix incoherent ut8mb4 collation in Doctrine setup
  Fix decorating service definition
  fix empty XML element
  [#7873] add missing toctree entries
  Reworded the introduction of the contributing docs
  [#7844] add XML and PHP config examples
  Property access
  [HttpFoundation] Fix clearstatcache first arg
  Explain how to provide a stack trace
  fix remaining setDefinition() call
  ...

Author: weaverryan

_includes/service_container/_my_mailer.rst.inc

@@ -28,9 +28,6 @@
 
         // app/config/services.php
         use AppBundle\Mailer;
-        use Symfony\Component\DependencyInjection\Definition;
 
-        $container->setDefinition('app.mailer', new Definition(
-            Mailer::class,
-            array('sendmail')
-        ));
+        $container->register('app.mailer', Mailer::class)
+            ->addArgument('sendmail');

bundles/best_practices.rst

@@ -348,9 +348,17 @@ The end user can provide values in any configuration file:
     .. code-block:: xml
 
         <!-- app/config/config.xml -->
-        <parameters>
-            <parameter key="acme_blog.author.email">[email protected]</parameter>
-        </parameters>
+        <?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="acme_blog.author.email">[email protected]</parameter>
+            </parameters>
+
+        </container>
 
     .. code-block:: php
 

bundles/configuration.rst

@@ -225,7 +225,7 @@ thrown)::
         $configuration = new Configuration();
 
         $config = $this->processConfiguration($configuration, $configs);
-        
+
         // you now have these 2 config keys
         // $config['twitter']['client_id'] and $config['twitter']['client_secret']
     }
@@ -424,7 +424,6 @@ Assuming the XSD file is called ``hello-1.0.xsd``, the schema location will be
 
     <!-- app/config/config.xml -->
     <?xml version="1.0" ?>
-
     <container xmlns="http://symfony.com/schema/dic/services"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:acme-hello="http://acme_company.com/schema/dic/hello"

bundles/prepend_extension.rst

@@ -12,7 +12,7 @@ users to choose to remove functionality they are not using. Creating multiple
 bundles has the drawback that configuration becomes more tedious and settings
 often need to be repeated for various bundles.
 
-It is possible to remove the disadvantage of the multiple bundle approach 
+It is possible to remove the disadvantage of the multiple bundle approach
 by enabling a single Extension to prepend the settings for any bundle.
 It can use the settings defined in the ``app/config/config.yml``
 to prepend settings just as if they had been written explicitly by
@@ -116,11 +116,21 @@ The above would be the equivalent of writing the following into the
     .. code-block:: xml
 
         <!-- app/config/config.xml -->
-        <acme-something:config use-acme-goodbye="false">
-            <acme-something:entity-manager-name>non_default</acme-something:entity-manager-name>
-        </acme-something:config>
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:acme-something="http://example.org/schema/dic/acme_something"
+            xmlns:acme-other="http://example.org/schema/dic/acme_other"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd">
 
-        <acme-other:config use-acme-goodbye="false" />
+            <acme-something:config use-acme-goodbye="false">
+                <acme-something:entity-manager-name>non_default</acme-something:entity-manager-name>
+            </acme-something:config>
+
+            <acme-other:config use-acme-goodbye="false" />
+
+        </container>
 
     .. code-block:: php
 

components/event_dispatcher.rst

@@ -22,7 +22,7 @@ answer.
 Consider the real-world example where you want to provide a plugin system
 for your project. A plugin should be able to add methods, or do something
 before or after a method is executed, without interfering with other plugins.
-This is not an easy problem to solve with single inheritance, and even if 
+This is not an easy problem to solve with single inheritance, and even if
 multiple inheritance was possible with PHP, it comes with its own drawbacks.
 
 The Symfony EventDispatcher component implements the `Mediator`_ pattern
@@ -198,7 +198,6 @@ determine which instance is passed.
     to tag services as event listeners::
 
         use Symfony\Component\DependencyInjection\ContainerBuilder;
-        use Symfony\Component\DependencyInjection\Definition;
         use Symfony\Component\DependencyInjection\ParameterBag\ParameterBag;
         use Symfony\Component\DependencyInjection\Reference;
         use Symfony\Component\EventDispatcher\ContainerAwareEventDispatcher;
@@ -208,23 +207,19 @@ determine which instance is passed.
         $containerBuilder->addCompilerPass(new RegisterListenersPass());
 
         // register the event dispatcher service
-        $containerBuilder->setDefinition('event_dispatcher', new Definition(
-            ContainerAwareEventDispatcher::class,
-            array(new Reference('service_container'))
-        ));
+        $containerBuilder->register('event_dispatcher', ContainerAwareEventDispatcher::class)
+            ->addArgument(new Reference('service_container'));
 
         // register your event listener service
-        $listener = new Definition(\AcmeListener::class);
-        $listener->addTag('kernel.event_listener', array(
-            'event' => 'acme.foo.action',
-            'method' => 'onFooAction',
-        ));
-        $containerBuilder->setDefinition('listener_service_id', $listener);
+        $containerBuilder->register('listener_service_id', \AcmeListener::class)
+            ->addTag('kernel.event_listener', array(
+                'event' => 'acme.foo.action',
+                'method' => 'onFooAction',
+            ));
 
         // register an event subscriber
-        $subscriber = new Definition(\AcmeSubscriber::class);
-        $subscriber->addTag('kernel.event_subscriber');
-        $containerBuilder->setDefinition('subscriber_service_id', $subscriber);
+        $containerBuilder->register('subscriber_service_id', \AcmeSubscriber::class)
+            ->addTag('kernel.event_subscriber');
 
     By default, the listeners pass assumes that the event dispatcher's service
     id is ``event_dispatcher``, that event listeners are tagged with the
@@ -441,7 +436,7 @@ EventDispatcher Aware Events and Listeners
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The ``EventDispatcher`` always passes the dispatched event, the event's
-name and a reference to itself to the listeners. This can lead to some advanced 
+name and a reference to itself to the listeners. This can lead to some advanced
 applications of the ``EventDispatcher`` including dispatching other events inside
 listeners, chaining events or even lazy loading listeners into the dispatcher object.
 

components/http_foundation.rst

@@ -533,7 +533,7 @@ Please note that this will not work when the ``X-Sendfile`` header is set.
 
     If you *just* created the file during this same request, the file *may* be sent
     without any content. This may be due to cached file stats that return zero for
-    the size of the file. To fix this issue, call ``clearstatcache(false, $file)``
+    the size of the file. To fix this issue, call ``clearstatcache(true, $file)``
     with the path to the binary file.
 
 .. _component-http-foundation-json-response:

components/options_resolver.rst

@@ -98,7 +98,7 @@ the ``Mailer`` class makes a mistake?
 .. code-block:: php
 
     $mailer = new Mailer(array(
-        'usernme' => 'johndoe',  // usernAme misspelled
+        'usernme' => 'johndoe',  // usernme misspelled (instead of username)
     ));
 
 No error will be shown. In the best case, the bug will appear during testing,

components/property_access.rst

@@ -259,23 +259,31 @@ can use setters, the magic ``__set()`` method or properties to set values::
             $this->lastName = $name;
         }
 
+        public function getLastName()
+        {
+            return $this->lastName;
+        }
+
+        public function getChildren()
+        {
+            return $this->children;
+        }
+
         public function __set($property, $value)
         {
             $this->$property = $value;
         }
-
-        // ...
     }
 
     $person = new Person();
 
     $accessor->setValue($person, 'firstName', 'Wouter');
-    $accessor->setValue($person, 'lastName', 'de Jong');
-    $accessor->setValue($person, 'children', array(new Person()));
+    $accessor->setValue($person, 'lastName', 'de Jong'); // setLastName is called
+    $accessor->setValue($person, 'children', array(new Person())); // __set is called
 
     var_dump($person->firstName); // 'Wouter'
     var_dump($person->getLastName()); // 'de Jong'
-    var_dump($person->children); // array(Person());
+    var_dump($person->getChildren()); // array(Person());
 
 You can also use ``__call()`` to set values but you need to enable the feature,
 see `Enable other Features`_.

components/validator/resources.rst

@@ -45,7 +45,7 @@ In this example, the validation metadata is retrieved executing the
         public static function loadValidatorMetadata(ClassMetadata $metadata)
         {
             $metadata->addPropertyConstraint('name', new Assert\NotBlank());
-            $metadata->addPropertyConstraint('name', new Asert\Length(array(
+            $metadata->addPropertyConstraint('name', new Assert\Length(array(
                 'min' => 5,
                 'max' => 20,
             )));

configuration/environments.rst

@@ -69,11 +69,22 @@ accomplished easily and transparently:
 
     .. code-block:: xml
 
-        <imports>
-            <import resource="config.xml" />
-        </imports>
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/doctrine
+                http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
 
-        <!-- ... -->
+            <imports>
+                <import resource="config.xml" />
+            </imports>
+
+            <!-- ... -->
+
+        </container>
 
     .. code-block:: php
 
@@ -104,11 +115,22 @@ configuration file:
     .. code-block:: xml
 
         <!-- app/config/config_dev.xml -->
-        <imports>
-            <import resource="config.xml" />
-        </imports>
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:webprofiler="http://symfony.com/schema/dic/webprofiler"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/webprofiler
+                http://symfony.com/schema/dic/webprofiler/webprofiler-1.0.xsd">
+
+            <imports>
+                <import resource="config.xml" />
+            </imports>
+
+            <webprofiler:config toolbar="true" />
 
-        <webprofiler:config toolbar="true" />
+        </container>
 
     .. code-block:: php
 
@@ -201,7 +223,18 @@ this code and changing the environment string.
 
         .. code-block:: xml
 
-            <doctrine:dbal logging="%kernel.debug%" />
+            <?xml version="1.0" encoding="UTF-8" ?>
+            <container xmlns="http://symfony.com/schema/dic/services"
+                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
+                xsi:schemaLocation="http://symfony.com/schema/dic/services
+                    http://symfony.com/schema/dic/services/services-1.0.xsd
+                    http://symfony.com/schema/dic/doctrine
+                    http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
+
+                <doctrine:dbal logging="%kernel.debug%" />
+
+            </container>
 
         .. code-block:: php
 
@@ -283,13 +316,24 @@ The best way to accomplish this is via a new environment called, for example,
     .. code-block:: xml
 
         <!-- app/config/config_benchmark.xml -->
-        <imports>
-            <import resource="config_prod.xml" />
-        </imports>
-
-        <framework:config>
-            <framework:profiler only-exceptions="false" />
-        </framework:config>
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony
+                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+            <imports>
+                <import resource="config_prod.xml" />
+            </imports>
+
+            <framework:config>
+                <framework:profiler only-exceptions="false" />
+            </framework:config>
+
+        </container>
 
     .. code-block:: php