Merge branch '2.8' into 3.3

* 2.8: (25 commits)
  [#8231] fix reStructuredText syntax
  Specified import order of config files
  [#7981] revert some changes
  Update upload_file.rst
  Added a missing redirection
  Update validation_group_service_resolver.rst
  Update redirection_map
  Update button_based_validation.rst
  Delete group_service_resolver.rst
  Create validation_group_service_resolver.rst
  [#8290] fix minor typo
  Update the setfacl description.
  Update events.rst
  Fixed a minor syntax issue
  Update phpunit_bridge.rst
  First parameter to uniqid must be a string
  fix #8321 minor changes in Serializer Component
  Update filesystem.rst
  Update associations.rst
  Update proxy_examples.rst
  ...

Author: xabbuh

_build/redirection_map

@@ -262,7 +262,7 @@
 /cookbook/upgrade/minor_version /setup/upgrade_major
 /cookbook/upgrade/patch_version /upgrade/bundles
 /cookbook/validation/custom_constraint /validation/custom_constraint
-/cookbook/validation/group_service_resolver /validation/group_service_resolver
+/cookbook/validation/group_service_resolver /form/validation_group_service_resolver
 /cookbook/validation/index /validation
 /cookbook/validation/severity /validation/severity
 /cookbook/web_server/built_in /setup/built_in_web_server
@@ -287,6 +287,7 @@
 /components/debug/introduction /components/debug
 /components/debug/index /components/debug
 /components/dependency_injection/advanced /service_container/alias_private
+/components/dependency_injection/autowiring /service_container/autowiring
 /components/dependency_injection/definitions /service_container/definitions
 /components/dependency_injection/introduction /components/dependency_injection
 /components/dependency_injection/index /components/dependency_injection
@@ -310,6 +311,7 @@
 /components/form/type_guesser /form/type_guesser
 /components/http_foundation/index /components/http_foundation
 /components/http_foundation/introduction /components/http_foundation
+/components/http_foundation/trusting_proxies /request/load_balancer_reverse_proxy
 /components/http_kernel/introduction /components/http_kernel
 /components/http_kernel/index /components/http_kernel
 /components/property_access/introduction /components/property_access
@@ -331,12 +333,11 @@
 /components/yaml/index /components/yaml
 /deployment/tools /deployment
 /install/bundles /setup/bundles
+/event_dispatcher/class_extension /event_dispatcher
 /form /forms
 /form/use_virtual_forms /form/inherit_data_option
-/testing/simulating_authentication /testing/http_authentication
-/components/dependency_injection/autowiring /service_container/autowiring
-/event_dispatcher/class_extension /event_dispatcher
 /security/target_path /security
 /service_container/third_party /service_container
 /templating/templating_service /templates
-/components/http_foundation/trusting_proxies /request/load_balancer_reverse_proxy
+/testing/simulating_authentication /testing/http_authentication
+/validation/group_service_resolver /form/validation_group_service_resolver

components/filesystem.rst

@@ -64,6 +64,13 @@ On POSIX filesystems, directories are created with a default mode value
 
     This function ignores already existing directories.
 
+.. note::
+
+    The directory permissions are affected by the current `umask`_.
+    Set the umask for your webserver, use PHP's :phpfunction:`umask`
+    function or use the :phpfunction:`chmod` function after the
+    directory has been created.
+
 exists
 ~~~~~~
 
@@ -320,3 +327,4 @@ Learn More
     filesystem/*
 
 .. _`Packagist`: https://packagist.org/packages/symfony/filesystem
+.. _`umask`: https://en.wikipedia.org/wiki/Umask

components/phpunit_bridge.rst

@@ -224,14 +224,14 @@ If you have this kind of time-related tests::
             sleep(10);
             $duration = $stopwatch->stop('event_name')->getDuration();
 
-            $this->assertEquals(10, $duration);
+            $this->assertEquals(10000, $duration);
         }
     }
 
 You used the :doc:`Symfony Stopwatch Component </components/stopwatch>` to
 calculate the duration time of your process, here 10 seconds. However, depending
 on the load of the server or the processes running on your local machine, the
-``$duration`` could for example be `10.000023s` instead of `10s`.
+``$duration`` could for example be ``10.000023s`` instead of ``10s``.
 
 This kind of tests are called transient tests: they are failing randomly
 depending on spurious and external circumstances. They are often cause trouble

components/serializer.rst

@@ -418,9 +418,9 @@ and :class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer`::
     $obj->name = 'Acme Inc.';
     $obj->address = '123 Main Street, Big City';
 
-    $json = $serializer->serialize($obj);
+    $json = $serializer->serialize($obj, 'json');
     // {"org_name": "Acme Inc.", "org_address": "123 Main Street, Big City"}
-    $objCopy = $serializer->deserialize($json);
+    $objCopy = $serializer->deserialize($json, Company::class, 'json');
     // Same data as $obj
 
 .. _using-camelized-method-names-for-underscored-attributes:

controller/upload_file.rst

@@ -329,6 +329,7 @@ automatically upload the file when persisting the entity::
     class BrochureUploadListener
     {
         private $uploader;
+        private $fileName;
 
         public function __construct(FileUploader $uploader)
         {
@@ -359,11 +360,10 @@ automatically upload the file when persisting the entity::
             $file = $entity->getBrochure();
 
             // only upload new files
-            if (!$file instanceof UploadedFile) {
-                return;
+            if ($file instanceof UploadedFile) {
+                $fileName = $this->uploader->upload($file);
             }
 
-            $fileName = $this->uploader->upload($file);
             $entity->setBrochure($fileName);
         }
     }

deployment/platformsh.rst

@@ -126,12 +126,14 @@ following file (it's your role to add this file to your code base)::
     # Store session into /tmp.
     ini_set('session.save_path', '/tmp/sessions');
 
-Make sure this file is listed in your *imports*:
+Make sure this file is listed in your *imports* (after the default ``parameters.yml``
+file):
 
 .. code-block:: yaml
 
     # app/config/config.yml
     imports:
+        - { resource: parameters.yml }
         - { resource: parameters_platform.php }
 
 Deploy your Application

doctrine/associations.rst

@@ -273,7 +273,7 @@ When you need to fetch associated objects, your workflow looks just like it
 did before. First, fetch a ``$product`` object and then access its related
 ``Category`` object::
 
-    use AppBundle\Entity\Post;
+    use AppBundle\Entity\Product;
     // ...
 
     public function showAction($productId)

form/button_based_validation.rst

@@ -36,4 +36,4 @@ large or whether you tried to submit text in a number field.
 .. seealso::
 
     To see how to use a service to resolve ``validation_groups`` dynamically
-    read the :doc:`/validation/group_service_resolver` article.
+    read the :doc:`/form/validation_group_service_resolver` article.

form/create_custom_field_type.rst

@@ -251,7 +251,7 @@ Using the Field Type
 You can now use your custom field type immediately, simply by creating a
 new instance of the type in one of your forms::
 
-    // src/AppBundle/Form/Type/AuthorType.php
+    // src/AppBundle/Form/Type/OrderType.php
     namespace AppBundle\Form\Type;
 
     use Symfony\Component\Form\AbstractType;

form/data_transformers.rst

@@ -23,7 +23,7 @@ Simple Example: Transforming String Tags from User Input to an Array
 
 Suppose you have a Task form with a tags ``text`` type::
 
-    // src/AppBundle/Form/TaskType.php
+    // src/AppBundle/Form/Type/TaskType.php
     namespace AppBundle\Form\Type;
 
     use AppBundle\Entity\Task;
@@ -56,7 +56,7 @@ This is a *perfect* time to attach a custom data transformer to the ``tags``
 field. The easiest way to do this is with the :class:`Symfony\\Component\\Form\\CallbackTransformer`
 class::
 
-    // src/AppBundle/Form/TaskType.php
+    // src/AppBundle/Form/Type/TaskType.php
     namespace AppBundle\Form\Type;
 
     use Symfony\Component\Form\CallbackTransformer;
@@ -120,7 +120,7 @@ issue number.
 
 Start by setting up the text field like normal::
 
-    // src/AppBundle/Form/TaskType.php
+    // src/AppBundle/Form/Type/TaskType.php
     namespace AppBundle\Form\Type;
 
     use AppBundle\Entity\Task;
@@ -250,7 +250,7 @@ Next, you need to use the ``IssueToNumberTransformer`` object inside if ``TaskTy
 and add it to the ``issue`` field. No problem! Just add a ``__construct()`` method
 and type-hint the new class::
 
-    // src/AppBundle/Form/TaskType.php
+    // src/AppBundle/Form/Type/TaskType.php
     namespace AppBundle\Form\Type;
 
     use AppBundle\Form\DataTransformer\IssueToNumberTransformer;
@@ -374,7 +374,7 @@ have the data transformer *and* a nice default value for the ``invalid_message``
 As long as you're using :ref:`autowire <services-autowire>` and
 :ref:`autoconfigure <services-autoconfigure>`, you can start using the form immediately::
 
-    // src/AppBundle/Form/TaskType.php
+    // src/AppBundle/Form/Type/TaskType.php
     namespace AppBundle\Form\Type;
 
     use AppBundle\Form\DataTransformer\IssueToNumberTransformer;

form/dynamic_form_modification.rst

@@ -260,7 +260,7 @@ Customizing the Form Type
 Now that you have all the basics in place you can take advantage of the ``TokenStorageInterface``
 and fill in the listener logic::
 
-    // src/AppBundle/FormType/FriendMessageFormType.php
+    // src/AppBundle/Form/Type/FriendMessageFormType.php
 
     use AppBundle\Entity\User;
     use Doctrine\ORM\EntityRepository;

form/events.rst

@@ -304,6 +304,7 @@ callback for better readability::
 
     use Symfony\Component\Form\Extension\Core\Type\TextType;
     use Symfony\Component\Form\Extension\Core\Type\CheckboxType;
+    use Symfony\Component\Form\FormEvent;
     use Symfony\Component\Form\FormEvents;
 
     // ...
@@ -391,9 +392,9 @@ Event subscribers have different uses:
 
 To register the event subscriber, use the ``addEventSubscriber()`` method::
 
+    use AppBundle\Form\EventListener\AddEmailFieldListener;
     use Symfony\Component\Form\Extension\Core\Type\TextType;
     use Symfony\Component\Form\Extension\Core\Type\CheckboxType;
-        use AppBundle\Form\EventListener\AddEmailFieldListener;
 
     // ...
 

validation/group_service_resolver.rst renamed to form/validation_group_service_resolver.rst

@@ -1,5 +1,5 @@
-How to Dynamically Configure Validation Groups
-==============================================
+How to Dynamically Configure Form Validation Groups
+===================================================
 
 Sometimes you need advanced logic to determine the validation groups. If they
 can't be determined by a simple callback, you can use a service. Create a
@@ -47,7 +47,7 @@ Then in your form, inject the resolver and set it as the ``validation_groups``.
     namespace AppBundle\Form;
 
     use AppBundle\Validator\ValidationGroupResolver;
-    use Symfony\Component\Form\AbstractType;
+    use Symfony\Component\Form\AbstractType
     use Symfony\Component\OptionsResolver\OptionsResolver;
 
     class MyClassType extends AbstractType

logging/processors.rst

@@ -18,14 +18,14 @@ using a processor.
 
 .. code-block:: php
 
-    namespace AppBundle;
+    namespace AppBundle\Logger;
 
     use Symfony\Component\HttpFoundation\Session\SessionInterface;
 
     class SessionRequestProcessor
     {
         private $session;
-        private $token;
+        private $sessionId;
 
         public function __construct(SessionInterface $session)
         {
@@ -34,15 +34,15 @@ using a processor.
 
         public function processRecord(array $record)
         {
-            if (null === $this->token) {
-                try {
-                    $this->token = substr($this->session->getId(), 0, 8);
-                } catch (\RuntimeException $e) {
-                    $this->token = '????????';
-                }
-                $this->token .= '-' . substr(uniqid(), -8);
+            if (!$this->session->isStarted()) {
+                return $record;
             }
-            $record['extra']['token'] = $this->token;
+
+            if (!$this->sessionId) {
+                $this->sessionId = substr($this->session->getId(), 0, 8) ?: '????????';
+            }
+
+            $record['extra']['token'] = $this->sessionId.'-'.substr(uniqid('', true), -8);
 
             return $record;
         }
@@ -62,7 +62,7 @@ information:
                 arguments:
                     - "[%%datetime%%] [%%extra.token%%] %%channel%%.%%level_name%%: %%message%% %%context%% %%extra%%\n"
 
-            AppBundle\SessionRequestProcessor:
+            AppBundle\Logger\SessionRequestProcessor:
                 autowire: true
                 tags:
                     - { name: monolog.processor, method: processRecord }
@@ -86,7 +86,7 @@ information:
                     <argument>[%%datetime%%] [%%extra.token%%] %%channel%%.%%level_name%%: %%message%% %%context%% %%extra%%&#xA;</argument>
                 </service>
 
-                <service id="AppBundle\SessionRequestProcessor" autowire="true">
+                <service id="AppBundle\Logger\SessionRequestProcessor" autowire="true">
                     <tag name="monolog.processor" method="processRecord" />
                 </service>
             </services>
@@ -95,7 +95,7 @@ information:
     .. code-block:: php
 
         // app/config/services.php
-        use AppBundle\SessionRequestProcessor;
+        use AppBundle\Logger\SessionRequestProcessor;
         use Monolog\Formatter\LineFormatter;
 
         $container
@@ -139,7 +139,7 @@ Finally, set the formatter to be used on whatever handler you want:
                     type="stream"
                     path="%kernel.logs_dir%/%kernel.environment%.log"
                     level="debug"
-                    formatter="monolog.formatter.session_request"
+                    formatter="app.logger.session_request_processor"
                 />
             </monolog:config>
         </container>
@@ -153,7 +153,7 @@ Finally, set the formatter to be used on whatever handler you want:
                     'type'      => 'stream',
                     'path'      => '%kernel.logs_dir%/%kernel.environment%.log',
                     'level'     => 'debug',
-                    'formatter' => 'monolog.formatter.session_request',
+                    'formatter' => 'app.logger.session_request_processor',
                 ),
             ),
         ));
@@ -174,7 +174,7 @@ the ``monolog.processor`` tag:
 
         # app/config/config.yml
         services:
-            AppBundle\SessionRequestProcessor:
+            AppBundle\Logger\SessionRequestProcessor:
                 autowire: true
                 tags:
                     - { name: monolog.processor, method: processRecord, handler: main }
@@ -192,7 +192,7 @@ the ``monolog.processor`` tag:
                 http://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
 
             <services>
-                <service id="AppBundle\SessionRequestProcessor" autowire="true">
+                <service id="AppBundle\Logger\SessionRequestProcessor" autowire="true">
                     <tag name="monolog.processor" method="processRecord" handler="main" />
                 </service>
             </services>
@@ -219,7 +219,7 @@ the ``monolog.processor`` tag:
 
         # app/config/config.yml
         services:
-            AppBundle\SessionRequestProcessor:
+            AppBundle\Logger\SessionRequestProcessor:
                 autowire: true
                 tags:
                     - { name: monolog.processor, method: processRecord, channel: main }
@@ -237,7 +237,7 @@ the ``monolog.processor`` tag:
                 http://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
 
             <services>
-                <service id="AppBundle\SessionRequestProcessor" autowire="true">
+                <service id="AppBundle\Logger\SessionRequestProcessor" autowire="true">
                     <tag name="monolog.processor" method="processRecord" channel="main" />
                 </service>
             </services>

security/entity_provider.rst

@@ -83,7 +83,7 @@ For this entry, suppose that you already have a ``User`` entity inside an
         {
             $this->isActive = true;
             // may not be needed, see section on salt below
-            // $this->salt = md5(uniqid(null, true));
+            // $this->salt = md5(uniqid('', true));
         }
 
         public function getUsername()

security/impersonating_user.rst

@@ -101,7 +101,7 @@ to show a link to exit impersonation:
             </a>
         <?php endif ?>
 
-In some cases you may need to get the object that represents the impersonating
+In some cases you may need to get the object that represents the impersonator
 user rather than the impersonated user. Use the following snippet to iterate
 over the user's roles until you find one that a ``SwitchUserRole`` object::
 
@@ -113,7 +113,7 @@ over the user's roles until you find one that a ``SwitchUserRole`` object::
     if ($authChecker->isGranted('ROLE_PREVIOUS_ADMIN')) {
         foreach ($tokenStorage->getToken()->getRoles() as $role) {
             if ($role instanceof SwitchUserRole) {
-                $impersonatingUser = $role->getSource()->getUser();
+                $impersonatorUser = $role->getSource()->getUser();
                 break;
             }
         }

session/proxy_examples.rst

@@ -33,6 +33,7 @@ Symfony to use your session handler instead of the default one:
         <?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">