Merge remote-tracking branch 'upstream/3.3' into 3.3

Author: javiereguiluz

best_practices/business-logic.rst

@@ -283,7 +283,7 @@ looking for mapping information:
          *      mappedBy="post",
          *      orphanRemoval=true
          * )
-         * @ORM\OrderBy({"publishedAt" = "ASC"})
+         * @ORM\OrderBy({"publishedAt"="ASC"})
          */
         private $comments;
 
@@ -359,6 +359,10 @@ were defined by the PHP community. You can learn more about
 use the `PHP-CS-Fixer`_, which is a command-line utility that can fix the
 coding standards of an entire codebase in a matter of seconds.
 
+----
+
+Next: :doc:`/best_practices/controllers`
+
 .. _`full definition`: https://en.wikipedia.org/wiki/Business_logic
 .. _`Doctrine project`: http://www.doctrine-project.org/
 .. _`fixture class`: https://symfony.com/doc/current/bundles/DoctrineFixturesBundle/index.html#writing-simple-fixtures

best_practices/configuration.rst

@@ -215,5 +215,9 @@ through environment variables:
     was added in Symfony 3.2. Prior to version 3.2, you needed to use the
     :doc:`special SYMFONY__ variables </configuration/external_parameters>`.
 
+----
+
+Next: :doc:`/best_practices/business-logic`
+
 .. _`feature toggles`: https://en.wikipedia.org/wiki/Feature_toggle
 .. _`constant() function`: http://twig.sensiolabs.org/doc/functions/constant.html

best_practices/controllers.rst

@@ -182,7 +182,7 @@ manually. In our application, we have this situation in ``CommentController``:
 .. code-block:: php
 
     /**
-     * @Route("/comment/{postSlug}/new", name = "comment_new")
+     * @Route("/comment/{postSlug}/new", name="comment_new")
      */
     public function newAction(Request $request, $postSlug)
     {
@@ -208,8 +208,8 @@ flexible:
     use Symfony\Component\HttpFoundation\Request;
 
     /**
-     * @Route("/comment/{postSlug}/new", name = "comment_new")
-     * @ParamConverter("post", options={"mapping": {"postSlug": "slug"}})
+     * @Route("/comment/{postSlug}/new", name="comment_new")
+     * @ParamConverter("post", options={"mapping"={"postSlug"="slug"}})
      */
     public function newAction(Request $request, Post $post)
     {
@@ -227,4 +227,8 @@ If you need to execute some code before or after the execution of your controlle
 you can use the EventDispatcher component to
 :doc:`set up before and after filters </event_dispatcher/before_after_filters>`.
 
+----
+
+Next: :doc:`/best_practices/templates`
+
 .. _`ParamConverter`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html

best_practices/creating-the-project.rst

@@ -168,6 +168,10 @@ structure of Symfony, you can
 :doc:`override the location of the main directories </configuration/override_dir_structure>`:
 ``cache/``, ``logs/`` and ``web/``.
 
+----
+
+Next: :doc:`/best_practices/configuration`
+
 .. _`Composer`: https://getcomposer.org/
 .. _`Phar extension`: http://php.net/manual/en/intro.phar.php
 .. _`public checksums repository`: https://github.com/sensiolabs/checksums

best_practices/forms.rst

@@ -207,3 +207,7 @@ handle everything.
 Second, is it required to call ``$form->isSubmitted()`` in the ``if`` statement
 before calling ``isValid()``. Calling ``isValid()`` with an unsubmitted form
 is deprecated since version 3.2 and will throw an exception in 4.0.
+
+----
+
+Next: :doc:`/best_practices/i18n`

best_practices/i18n.rst

@@ -93,4 +93,8 @@ English in the application would be:
         </file>
     </xliff>
 
+----
+
+Next: :doc:`/best_practices/security`
+
 .. _`JMSTranslationBundle`: https://github.com/schmittjoh/JMSTranslationBundle

best_practices/introduction.rst

@@ -98,5 +98,9 @@ practices**. The reasons for not doing it are various:
 * The amount of work spent on this could be better dedicated to improving
   your tests or adding features that provide real value to the end users.
 
+----
+
+Next: :doc:`/best_practices/creating-the-project`
+
 .. _`Fabien Potencier`: https://connect.sensiolabs.com/profile/fabpot
 .. _`download and install`: https://symfony.com/download

best_practices/security.rst

@@ -389,6 +389,10 @@ If your company uses a user login method not supported by Symfony, you can
 develop :doc:`your own user provider </security/custom_provider>` and
 :doc:`your own authentication provider </security/custom_authentication_provider>`.
 
+----
+
+Next: :doc:`/best_practices/web-assets`
+
 .. _`ParamConverter`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
 .. _`@Security annotation`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/security.html
 .. _`FOSUserBundle`: https://github.com/FriendsOfSymfony/FOSUserBundle

best_practices/templates.rst

@@ -150,5 +150,9 @@ If you're using the :ref:`default services.yml configuration <service-container-
 you're done! Symfony will automatically know about your new service and tag it to
 be used as a Twig extension.
 
+----
+
+Next: :doc:`/best_practices/forms`
+
 .. _`Twig`: http://twig.sensiolabs.org/
 .. _`Parsedown`: http://parsedown.org/

best_practices/web-assets.rst

@@ -95,4 +95,8 @@ with Assetic to reduce their size before serving them to the user. Check out
 the `official Assetic documentation`_ to learn more about all the available
 features.
 
+----
+
+Next: :doc:`/best_practices/tests`
+
 .. _`official Assetic documentation`: https://github.com/kriswallsmith/assetic

components/config/definition.rst

@@ -228,6 +228,9 @@ Before defining the children of an array node, you can provide options like:
     If called (with ``false``), keys with dashes are *not* normalized to underscores.
     It is recommended to use this with prototype nodes where the user will define
     a key-value map, to avoid an unnecessary transformation.
+``ignoreExtraKeys()``
+    Allows extra config keys to be specified under an array without
+    throwing an exception.
 
 A basic prototyped array configuration can be defined as follows::
 

components/http_foundation.rst

@@ -297,7 +297,7 @@ PHP callable that is able to create an instance of your ``Request`` class::
         array $server = array(),
         $content = null
     ) {
-        return SpecialRequest::create(
+        return new SpecialRequest(
             $query,
             $request,
             $attributes,

configuration/override_dir_structure.rst

@@ -104,7 +104,7 @@ define your own templates directory (or directories):
         # app/config/config.yml
         twig:
             # ...
-            paths: ["%kernel.root_dir%/../templates"]
+            paths: ["%kernel.project_dir%/templates"]
 
     .. code-block:: xml
 
@@ -119,7 +119,7 @@ define your own templates directory (or directories):
                 http://symfony.com/schema/dic/twig/twig-1.0.xsd">
 
             <twig:config>
-                <twig:path>%kernel.root_dir%/../templates</twig:path>
+                <twig:path>%kernel.project_dir%/templates</twig:path>
             </twig:config>
 
         </container>
@@ -129,7 +129,7 @@ define your own templates directory (or directories):
         // app/config/config.php
         $container->loadFromExtension('twig', array(
             'paths' => array(
-                '%kernel.root_dir%/../templates',
+                '%kernel.project_dir%/templates',
             ),
         ));
 
@@ -197,7 +197,7 @@ You also need to change the ``extra.symfony-web-dir`` option in the
                     http://symfony.com/schema/dic/assetic/assetic-1.0.xsd">
 
                 <!-- ... -->
-                <assetic:config read-from="%kernel.root_dir%/../../public_html" />
+                <assetic:config read-from="%kernel.project_dir%/../public_html" />
 
             </container>
 

contributing/code/core_team.rst

@@ -81,7 +81,10 @@ Active Core Members
     components and the SecurityBundle_;
 
   * **Maxime Steinhausser** (`ogizanagi`_) can merge into Config_, Console_,
-    Form_, Serializer_, DependencyInjection_, and HttpKernel_ components.
+    Form_, Serializer_, DependencyInjection_, and HttpKernel_ components;
+
+  * **Tobias Nyholm** (`Nyholm`) manages the official and contrib recipes
+    repositories.
 
 * **Deciders** (``@symfony/deciders`` on GitHub):
 
@@ -223,4 +226,4 @@ discretion of the **Project Leader**.
 .. _`lyrixx`: https://github.com/lyrixx/
 .. _`chalasr`: https://github.com/chalasr/
 .. _`ogizanagi`: https://github.com/ogizanagi/
-.. _`csarrazi`: https://github.com/csarrazi/
+.. _`Nyholm`: https://github.com/Nyholm

contributing/code/patches.rst

@@ -157,6 +157,22 @@ Then create a new branch off the ``2.7`` branch to work on the bugfix:
 The above checkout commands automatically switch the code to the newly created
 branch (check the branch you are working on with ``git branch``).
 
+Use your Branch in an Existing Project
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want to test your code in an existing project that uses ``symfony/symfony``
+or Symfony components, you can use the ``link`` utility provided in the Git repository
+you cloned previously.
+This tool scans the ``vendor/`` directory of your project, finds Symfony packages it
+uses, and replaces them by symbolic links to the ones in the Git repository.
+
+.. code-block:: terminal
+
+    $ php link /path/to/your/project
+
+Before running the ``link`` command, be sure that the dependencies of the project you
+want to debug are installed by running ``composer install`` inside it.
+
 Work on your Patch
 ~~~~~~~~~~~~~~~~~~
 

controller/upload_file.rst

@@ -108,7 +108,7 @@ to :doc:`customize form rendering </form/form_customization>`):
 Finally, you need to update the code of the controller that handles the form::
 
     // src/AppBundle/Controller/ProductController.php
-    namespace AppBundle\ProductController;
+    namespace AppBundle\Controller;
 
     use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
     use Symfony\Bundle\FrameworkBundle\Controller\Controller;

deployment.rst

@@ -78,13 +78,15 @@ Using Build Scripts and other Tools
 There are also tools to help ease the pain of deployment. Some of them have been
 specifically tailored to the requirements of Symfony.
 
-`Capistrano`_ with `Symfony plugin`_
-    `Capistrano`_ is a remote server automation and deployment tool written in Ruby.
-    `Symfony plugin`_ is a plugin to ease Symfony related tasks, inspired by `Capifony`_
-    (which works only with Capistrano 2).
+`EasyDeployBundle`_
+    A Symfony bundle that adds easy deploy tools to your application.
 
-`sf2debpkg`_
-    Helps you build a native Debian package for your Symfony project.
+`Deployer`_
+    This is another native PHP rewrite of Capistrano, with some ready recipes for
+    Symfony.
+
+`Ansistrano`_
+    An Ansible role that allows you to configure a powerful deploy via YAML files.
 
 `Magallanes`_
     This Capistrano-like deployment tool is built in PHP, and may be easier
@@ -94,13 +96,14 @@ specifically tailored to the requirements of Symfony.
     This Python-based library provides a basic suite of operations for executing
     local or remote shell commands and uploading/downloading files.
 
-`Deployer`_
-    This is another native PHP rewrite of Capistrano, with some ready recipes for
-    Symfony.
+`Capistrano`_ with `Symfony plugin`_
+    `Capistrano`_ is a remote server automation and deployment tool written in Ruby.
+    `Symfony plugin`_ is a plugin to ease Symfony related tasks, inspired by `Capifony`_
+    (which works only with Capistrano 2).
+
+`sf2debpkg`_
+    Helps you build a native Debian package for your Symfony project.
 
-Bundles
-    There are some `bundles that add deployment features`_ directly into your
-    Symfony console.
 
 Basic scripting
     You can of course use shell, `Ant`_ or any other build tool to script
@@ -241,11 +244,12 @@ kernel and return your project's root directory::
 .. _`Capistrano`: http://capistranorb.com/
 .. _`sf2debpkg`: https://github.com/liip/sf2debpkg
 .. _`Fabric`: http://www.fabfile.org/
+.. _`Ansistrano`: https://ansistrano.com/
 .. _`Magallanes`: https://github.com/andres-montanez/Magallanes
 .. _`Ant`: http://blog.sznapka.pl/deploying-symfony2-applications-with-ant
-.. _`bundles that add deployment features`: https://github.com/search?utf8=✓&q=topic%3Asymfony-bundle+topic%3Adeploy&type=Repositories&ref=searchresults
 .. _`Memcached`: http://memcached.org/
 .. _`Redis`: http://redis.io/
 .. _`Symfony plugin`: https://github.com/capistrano/symfony/
 .. _`Deployer`: http://deployer.org/
 .. _`Git Tagging`: https://git-scm.com/book/en/v2/Git-Basics-Tagging
+.. _`EasyDeployBundle`: https://github.com/EasyCorp/easy-deploy-bundle

doctrine/event_listeners_subscribers.rst

@@ -102,14 +102,14 @@ a ``postPersist()`` method, which will be called when the event is dispatched::
     {
         public function postPersist(LifecycleEventArgs $args)
         {
-            $object = $args->getObject();
+            $entity = $args->getEntity();
 
             // only act on some "Product" entity
-            if (!$object instanceof Product) {
+            if (!$entity instanceof Product) {
                 return;
             }
 
-            $objectManager = $args->getObjectManager();
+            $entityManager = $args->getEntityManager();
             // ... do something with the Product
         }
     }
@@ -166,7 +166,7 @@ interface and have an event method for each event it subscribes to::
 
         public function index(LifecycleEventArgs $args)
         {
-            $entity = $args->getObject();
+            $entity = $args->getEntity();
 
             // perhaps you only want to act on some "Product" entity
             if ($entity instanceof Product) {

event_dispatcher.rst

@@ -64,8 +64,8 @@ The most common way to listen to an event is to register an **event listener**::
 
     Each event receives a slightly different type of ``$event`` object. For
     the ``kernel.exception`` event, it is :class:`Symfony\\Component\\HttpKernel\\Event\\GetResponseForExceptionEvent`.
-    To see what type of object each event listener receives, see :class:`Symfony\\Component\\HttpKernel\\KernelEvents`
-    or the documentation about the specific event you're listening to.
+    Check out the :doc:`Symfony events reference </reference/events>` to see
+    what type of object each event provides.
 
 Now that the class is created, you just need to register it as a service and
 notify Symfony that it is a "listener" on the ``kernel.exception`` event by

form/events.rst

@@ -282,7 +282,7 @@ Creating and binding an event listener to the form is very easy::
                 return;
             }
 
-            // Check whether the user has chosen to display his email or not.
+            // Check whether the user has chosen to display their email or not.
             // If the data was submitted previously, the additional value that is
             // included in the request variables needs to be removed.
             if (true === $user['show_email']) {
@@ -363,7 +363,7 @@ Event subscribers have different uses:
             $form = $event->getForm();
 
             // Check whether the user from the initial data has chosen to
-            // display his email or not.
+            // display their email or not.
             if (true === $user->isShowEmail()) {
                 $form->add('email', EmailType::class);
             }
@@ -378,7 +378,7 @@ Event subscribers have different uses:
                 return;
             }
 
-            // Check whether the user has chosen to display his email or not.
+            // Check whether the user has chosen to display their email or not.
             // If the data was submitted previously, the additional value that
             // is included in the request variables needs to be removed.
             if (true === $user['show_email']) {

form/without_class.rst

@@ -63,7 +63,7 @@ an array.
 Adding Validation
 -----------------
 
-The only missing piece is validation. Usually, when you call ``$form->isValid()``,
+The only missing piece is validation. Usually, when you call ``$form->handleRequest($request)``,
 the object is validated by reading the constraints that you applied to that
 class. If your form is mapped to an object (i.e. you're using the ``data_class``
 option or passing an object to your form), this is almost always the approach

frontend/encore/css-preprocessors.rst

@@ -32,7 +32,7 @@ can also pass options to ``sass-loader``:
 
     Encore
         // ...
-        .enableSassLoader(function(sassOptions) {
+        .enableSassLoader(function(options) {
             // https://github.com/sass/node-sass#options
             // options.includePaths = [...]
         });

frontend/encore/installation.rst

@@ -11,16 +11,23 @@ Then, install Encore into your project with Yarn:
 
 .. note::
 
-    If you want to use `npm`_ instead of `yarn`_, replace ``yarn add xxx --dev`` by
-    ``npm install xxx --save-dev``.
+    If you want to use `npm`_ instead of `yarn`_:
+
+    .. code-block:: terminal
+
+        $ npm install @symfony/webpack-encore --save-dev
 
 .. tip::
 
-    If you are using Flex for your project, you can install Encore via:
+    If you are using Flex for your project, you can initialize your project for Encore via:
 
     .. code-block:: terminal
 
         $ composer require encore
+        $ yarn install
+
+    This will create a ``webpack.config.js`` file, add the ``assets/`` directory, and add ``node_modules/`` to
+    ``.gitignore``.
 
 This command creates (or modifies) a ``package.json`` file and downloads dependencies
 into a ``node_modules/`` directory. When using Yarn, a file called ``yarn.lock``