Merge branch '4.0' into 4.1

* 4.0:
  Codefence ClassMetadataFactory
  Document the required ClassMetadataFactory
  Update framework.rst
  Fixed the preferred_choices option for Enttiy type
  Mentioned the 767 bytes index limit and its solution
  Refactor a security code example to make it easier to understand
  Remove deleted RoleInterface
  Fix How to dynamically Generate Forms Based on user Data
  Fixed the default value of php_errors.log option

Author: javiereguiluz

components/asset.rst

@@ -161,7 +161,7 @@ In those cases, use the
     use Symfony\Component\Asset\Package;
     use Symfony\Component\Asset\VersionStrategy\JsonManifestVersionStrategy;
 
-    $package = new Package(new JsonManifestVersionStrategy(__DIR__'./rev-manifest.json'));
+    $package = new Package(new JsonManifestVersionStrategy(__DIR__.'/rev-manifest.json'));
 
     echo $package->getUrl('css/app.css');
     // result: build/css/app.b916426ea1d10021f3f17ce8031f93c2.css

components/security/authorization.rst

@@ -167,12 +167,11 @@ role::
 Roles
 -----
 
-Roles are objects that give expression to a certain right the user has.
-The only requirement is that they implement :class:`Symfony\\Component\\Security\\Core\\Role\\RoleInterface`,
-which means they should also have a :method:`Symfony\\Component\\Security\\Core\\Role\\RoleInterface::getRole`
-method that returns a string representation of the role itself. The default
-:class:`Symfony\\Component\\Security\\Core\\Role\\Role` simply returns its
-first constructor argument::
+Roles are objects that give expression to a certain right the user has. The only
+requirement is that they must define a ``getRole()`` method that returns a
+string representation of the role itself. To do so, you can optionally extend
+from the default :class:`Symfony\\Component\\Security\\Core\\Role\\Role` class,
+which returns its first constructor argument in this method::
 
     use Symfony\Component\Security\Core\Role\Role;
 

components/serializer.rst

@@ -165,10 +165,15 @@ needs three parameters:
 #. The name of the class this information will be decoded to
 #. The encoder used to convert that information into an array
 
-By default, additional attributes that are not mapped to the denormalized
-object will be ignored by the Serializer component. Set the ``allow_extra_attributes``
-key of the deserialization context to ``false`` to let the serializer throw
-an exception when additional attributes are passed::
+.. versionadded:: 3.3
+    Support for the ``allow_extra_attributes`` key in the context was introduced
+    in Symfony 3.3.
+
+By default, additional attributes that are not mapped to the denormalized object
+will be ignored by the Serializer component. If you prefer to throw an exception
+when this happens, set the ``allow_extra_attributes`` context option to
+``false`` and provide an object that implements ``ClassMetadataFactoryInterface``
+when constructing the normalizer::
 
     $data = <<<EOF
     <person>
@@ -180,6 +185,9 @@ an exception when additional attributes are passed::
 
     // this will throw a Symfony\Component\Serializer\Exception\ExtraAttributesException
     // because "city" is not an attribute of the Person class
+    $classMetadataFactory = new ClassMetadataFactory(new AnnotationLoader(new AnnotationReader()));
+    $normalizer = new ObjectNormalizer($classMetadataFactory);
+    $serializer = new Serializer(array($normalizer));
     $person = $serializer->deserialize($data, 'Acme\Person', 'xml', array(
         'allow_extra_attributes' => false,
     ));

doctrine.rst

@@ -155,6 +155,15 @@ Woh! You now have a new ``src/Entity/Product.php`` file::
     Confused why the price is an integer? Don't worry: this is just an example.
     But, storing prices as integers (e.g. 100 = $1 USD) can avoid rounding issues.
 
+.. caution::
+
+    MySQL sets a `limit of 767 bytes for the index key prefix`_. When using
+    ``utf8mb4``, string columns with 255 character length surpass that limit.
+    This means that any column of type ``string`` and ``unique=true`` must
+    set its maximum ``length`` to ``190``. Otherwise, you'll see this error:
+    *"[PDOException] SQLSTATE[42000]: Syntax error or access violation:
+    1071 Specified key was too long; max key length is 767 bytes"*.
+
 This class is called an "entity". And soon, you'll be able to save and query Product
 objects to a ``product`` table in your database. Each property in the ``Product``
 entity can be mapped to a column in that table. This is usually done with annotations:
@@ -741,3 +750,4 @@ Learn more
 .. _`NativeQuery`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/native-sql.html
 .. _`SensioFrameworkExtraBundle`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/index.html
 .. _`ParamConverter`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
+.. _`limit of 767 bytes for the index key prefix`: https://dev.mysql.com/doc/refman/5.6/en/innodb-restrictions.html

form/dynamic_form_modification.rst

@@ -243,15 +243,6 @@ service into the form type so you can get the current user object::
         $this->security = $security;
     }
 
-.. note::
-
-    You might wonder, now that you have access to the ``User`` object, why not
-    just use it directly in ``buildForm()`` and omit the event listener? This is
-    because doing so in the ``buildForm()`` method would result in the whole
-    form type being modified and not just this one form instance. This may not
-    usually be a problem, but technically a single form type could be used on a
-    single request to create many forms or fields.
-
 Customizing the Form Type
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -292,37 +283,41 @@ security helper to fill in the listener logic::
                 );
             }
 
-            $builder->addEventListener(
-                FormEvents::PRE_SET_DATA,
-                function (FormEvent $event) use ($user) {
-                    $form = $event->getForm();
-
-                    $formOptions = array(
-                        'class'         => User::class,
-                        'choice_label'  => 'fullName',
-                        'query_builder' => function (EntityRepository $userRepository) use ($user) {
-                            // build a custom query
-                            // return $userRepository->createQueryBuilder('u')->addOrderBy('fullName', 'DESC');
-
-                            // or call a method on your repository that returns the query builder
-                            // return $userRepository->createOrderByFullNameQueryBuilder();
-                        },
-                    );
-
-                    // create the field, this is similar the $builder->add()
-                    // field name, field type, data, options
-                    $form->add('friend', EntityType::class, $formOptions);
+            $builder->addEventListener(FormEvents::PRE_SET_DATA, function (FormEvent $event) use ($user) {
+                if (null !== $event->getData()->getFriend()) {
+                    // we don't need to add the friend field because
+                    // the message will be addressed to a fixed friend
+                    return;
                 }
-            );
+
+                $form = $event->getForm();
+
+                $formOptions = array(
+                    'class' => User::class,
+                    'choice_label' => 'fullName',
+                    'query_builder' => function (UserRepository $userRepository) use ($user) {
+                        // call a method on your repository that returns the query builder
+                        // return $userRepository->createFriendsQueryBuilder($user);
+                    },
+                );
+
+                // create the field, this is similar the $builder->add()
+                // field name, field type, field options
+                $form->add('friend', EntityType::class, $formOptions);
+            });
         }
 
         // ...
     }
 
 .. note::
 
-    The ``multiple`` and ``expanded`` form options will default to false
-    because the type of the friend field is ``EntityType::class``.
+    You might wonder, now that you have access to the ``User`` object, why not
+    just use it directly in ``buildForm()`` and omit the event listener? This is
+    because doing so in the ``buildForm()`` method would result in the whole
+    form type being modified and not just this one form instance. This may not
+    usually be a problem, but technically a single form type could be used on a
+    single request to create many forms or fields.
 
 Using the Form
 ~~~~~~~~~~~~~~

reference/configuration/framework.rst

@@ -160,6 +160,7 @@ Configuration
 * `test`_
 * `translator`_
 
+  * :ref:`default_path <reference-translator-default_path>`
   * :ref:`enabled <reference-translator-enabled>`
   * `fallbacks`_
   * `logging`_
@@ -1542,6 +1543,19 @@ paths
 This option allows to define an array of paths where the component will look
 for translation files.
 
+.. _reference-translator-default_path:
+
+default_path
+............
+
+.. versionadded:: 3.4
+    The ``default_path`` option was introduced in Symfony 3.4.
+
+**type**: ``string`` **default**: ``%kernel.project_dir%/translations``
+
+This option allows to define the path where the application translations files
+are stored.
+
 property_access
 ~~~~~~~~~~~~~~~
 
@@ -1774,7 +1788,7 @@ php_errors
 log
 ...
 
-**type**: ``boolean|int`` **default**: ``false``
+**type**: ``boolean|int`` **default**: ``%kernel.debug%``
 
 Use the application logger instead of the PHP logger for logging PHP errors.
 When an integer value is used, it also sets the log level. Those integer

reference/forms/types/entity.rst

@@ -273,12 +273,33 @@ These options inherit from the :doc:`ChoiceType </reference/forms/types/choice>`
 
 .. include:: /reference/forms/types/options/placeholder.rst.inc
 
-.. include:: /reference/forms/types/options/preferred_choices.rst.inc
+preferred_choices
+~~~~~~~~~~~~~~~~~
 
-.. note::
+**type**: ``array`` or ``callable`` **default**: ``array()``
+
+This option allows you to move certain choices to the top of your list with a visual
+separator between them and the rest of the options. This option expects an array
+of entity objects::
+
+    use AppBundle\Entity\User;
+    use Symfony\Bridge\Doctrine\Form\Type\EntityType;
+    // ...
+
+    $builder->add('users', EntityType::class, array(
+        'class' => User::class,
+        // this method must return an array of User entities
+        'preferred_choices' => $group->getPreferredUsers(),
+    ));
+
+The preferred choices are only meaningful when rendering a ``select`` element
+(i.e. ``expanded`` false). The preferred choices and normal choices are separated
+visually by a set of dotted lines (i.e. ``-------------------``). This can be customized
+when rendering the field:
+
+.. code-block:: twig
 
-    This option expects an array of entity objects (that's actually the same as with
-    the ``ChoiceType`` field, which requires an array of the preferred "values").
+    {{ form_widget(form.publishAt, { 'separator': '=====' }) }}
 
 .. include:: /reference/forms/types/options/choice_type_translation_domain.rst.inc
 

security/custom_provider.rst

@@ -133,21 +133,7 @@ Here's an example of how this might look::
     {
         public function loadUserByUsername($username)
         {
-            // make a call to your webservice here
-            $userData = ...
-            // pretend it returns an array on success, false if there is no user
-
-            if ($userData) {
-                $password = '...';
-
-                // ...
-
-                return new WebserviceUser($username, $password, $salt, $roles);
-            }
-
-            throw new UsernameNotFoundException(
-                sprintf('Username "%s" does not exist.', $username)
-            );
+            return $this->fetchUser($username);
         }
 
         public function refreshUser(UserInterface $user)
@@ -158,13 +144,32 @@ Here's an example of how this might look::
                 );
             }
 
-            return $this->loadUserByUsername($user->getUsername());
+            return $this->fetchUser($username);
         }
 
         public function supportsClass($class)
         {
             return WebserviceUser::class === $class;
         }
+
+        private function fetchUser($username)
+        {
+            // make a call to your webservice here
+            $userData = ...
+            // pretend it returns an array on success, false if there is no user
+
+            if ($userData) {
+                $password = '...';
+
+                // ...
+
+                return new WebserviceUser($username, $password, $salt, $roles);
+            }
+
+            throw new UsernameNotFoundException(
+                sprintf('Username "%s" does not exist.', $username)
+            );
+        }
     }
 
 Create a Service for the User Provider