Merge branch '2.8' into 3.2

* 2.8:
  [#7907] add some use statements
  Updating Doctrine syntax for getRepository method
  Reworded the tip about property_info and Symfony framework
  remove useless space
  Add information for enable property_info service
  Updating doctrine class use
  [#7909] fix some typos
  Explained the locateResource() method of HttpKernel
  Reworded the note about dump() not being available in prod
  Symfony Installer Instructions for Windows
  Typo
  Fixing a typo in the Final Thoughts section
  Stop recommending the use of "doctrine:generate:entities"
  Added a help note about translating routes
  Use a safer code sample for Twig best practices
  Use the Twig namespaced syntax for all templates
  Updated the screenshot of deprecation messages

Author: xabbuh

_images/install/deprecations-in-profiler.png

@@ -95,6 +95,7 @@ for the homepage of our app:
 
     namespace AppBundle\Controller;
 
+    use AppBundle\Entity\Post;
     use Symfony\Bundle\FrameworkBundle\Controller\Controller;
     use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
 
@@ -106,7 +107,7 @@ for the homepage of our app:
         public function indexAction()
         {
             $posts = $this->getDoctrine()
-                ->getRepository('AppBundle:Post')
+                ->getRepository(Post::class)
                 ->findLatest();
 
             return $this->render('default/index.html.twig', array(
@@ -170,7 +171,7 @@ manually. In our application, we have this situation in ``CommentController``:
     public function newAction(Request $request, $postSlug)
     {
         $post = $this->getDoctrine()
-            ->getRepository('AppBundle:Post')
+            ->getRepository(Post::class)
             ->findOneBy(array('slug' => $postSlug));
 
         if (!$post) {

best_practices/controllers.rst

@@ -226,7 +226,7 @@ more advanced use-case, you can always do the same security check in PHP:
      */
     public function editAction($id)
     {
-        $post = $this->getDoctrine()->getRepository('AppBundle:Post')
+        $post = $this->getDoctrine()->getRepository(Post::class)
             ->find($id);
 
         if (!$post) {

best_practices/security.rst

@@ -30,22 +30,20 @@ Template Locations
     Store all your application's templates in ``app/Resources/views/`` directory.
 
 Traditionally, Symfony developers stored the application templates in the
-``Resources/views/`` directory of each bundle. Then they used the logical name
-to refer to them (e.g. ``AcmeDemoBundle:Default:index.html.twig``).
+``Resources/views/`` directory of each bundle. Then they used the Twig namespaced
+path to refer to them (e.g. ``@AcmeDemo/Default/index.html.twig``).
 
 But for the templates used in your application, it's much more convenient
 to store them in the ``app/Resources/views/`` directory. For starters, this
 drastically simplifies their logical names:
 
-=================================================  ==================================
-Templates Stored inside Bundles                    Templates Stored in ``app/``
-=================================================  ==================================
-``AcmeDemoBundle:Default:index.html.twig``         ``default/index.html.twig``
-``::layout.html.twig``                             ``layout.html.twig``
-``AcmeDemoBundle::index.html.twig``                ``index.html.twig``
-``AcmeDemoBundle:Default:subdir/index.html.twig``  ``default/subdir/index.html.twig``
-``AcmeDemoBundle:Default/subdir:index.html.twig``  ``default/subdir/index.html.twig``
-=================================================  ==================================
+============================================  ==================================
+Templates Stored inside Bundles               Templates Stored in ``app/``
+============================================  ==================================
+``@AcmeDemo/index.html.twig``                 ``index.html.twig``
+``@AcmeDemo/Default/index.html.twig``         ``default/index.html.twig``
+``@AcmeDemo/Default/subdir/index.html.twig``  ``default/subdir/index.html.twig``
+============================================  ==================================
 
 Another advantage is that centralizing your templates simplifies the work
 of your designers. They don't need to look for templates in lots of directories
@@ -131,7 +129,7 @@ service in the constructor of the Twig extension:
                 new \Twig_SimpleFilter(
                     'md2html',
                     array($this, 'markdownToHtml'),
-                    array('is_safe' => array('html'))
+                    array('is_safe' => array('html'), 'pre_escape' => 'html')
                 ),
             );
         }

best_practices/templates.rst

@@ -422,6 +422,21 @@ The ``composer.json`` file should include at least the following metadata:
 In order to make it easier for developers to find your bundle, register it on
 `Packagist`_, the official repository for Composer packages.
 
+Resources
+---------
+
+If the bundle references any resources (config files, translation files, etc.),
+don't use physical paths (e.g. ``__DIR__/config/services.xml``) but logical
+paths (e.g. ``@AppBundle/Resources/config/services.xml``).
+
+The logical paths are required because of the bundle overriding mechanism that
+lets you override any resource/file of any bundle. See :ref:`http-kernel-resource-locator`
+for more details about transforming physical paths into logical paths.
+
+Beware that templates use a simplified version of the logical path shown above.
+For example, an ``index.html.twig`` template located in the ``Resources/views/Default/``
+directory of the AppBundle, is referenced as ``@App/Default/index.html.twig``.
+
 Learn more
 ----------
 

bundles/best_practices.rst

@@ -7,6 +7,14 @@ How to Override any Part of a Bundle
 This document is a quick reference for how to override different parts of
 third-party bundles.
 
+.. tip::
+
+    The bundle overriding mechanism means that you cannot use physical paths to
+    refer to bundle's resources (e.g. ``__DIR__/config/services.xml``). Always
+    use logical paths in your bundles (e.g. ``@AppBundle/Resources/config/services.xml``)
+    and call the :ref:`locateResource() method <http-kernel-resource-locator>`
+    to turn them into physical paths when needed.
+
 Templates
 ---------
 

bundles/override.rst

@@ -418,7 +418,7 @@ is created from the form factory.
                     ->add('dueDate', DateType::class)
                     ->getForm();
 
-                return $this->render('AcmeTaskBundle:Default:new.html.twig', array(
+                return $this->render('@AcmeTask/Default/new.html.twig', array(
                     'form' => $form->createView(),
                 ));
             }

components/form.rst

@@ -742,6 +742,32 @@ look like this::
         // ...
     }
 
+.. _http-kernel-resource-locator:
+
+Locating Resources
+------------------
+
+The HttpKernel component is responsible of the bundle mechanism used in Symfony
+applications. The key feature of the bundles is that they allow to override any
+resource used by the application (config files, templates, controllers,
+translation files, etc.)
+
+This overriding mechanism works because resources are referenced not by their
+physical path but by their logical path. For example, the ``services.xml`` file
+stored in the ``Resources/config/`` directory of a bundle called AppBundle is
+referenced as ``@AppBundle/Resources/config/services.xml``. This logical path
+will work when the application overrides that file and even if you change the
+directory of AppBundle.
+
+The HttpKernel component provides a method called :method:`Symfony\\Component\\HttpKernel\\Kernel::locateResource`
+which can be used to transform logical paths into physical paths::
+
+    use Symfony\Component\HttpKernel\HttpKernel;
+
+    // ...
+    $kernel = new HttpKernel($dispatcher, $resolver);
+    $path = $kernel->locateResource('@AppBundle/Resources/config/services.xml');
+
 Learn more
 ----------
 

components/http_kernel.rst

@@ -348,8 +348,17 @@ Using PHP reflection, the :class:`Symfony\\Component\\PropertyInfo\\Extractor\\R
 provides list, type and access information from setter and accessor methods.
 It can also provide return and scalar types for PHP 7+.
 
-This service is automatically registered with the ``property_info`` service in
-the Symfony Framework.
+.. note::
+
+    When using the Symfony framework, this service is automatically registered
+    when the ``property_info`` feature is enabled:
+
+    .. code-block:: yaml
+
+        # app/config/config.yml
+        framework:
+            property_info:
+                enabled: true
 
 .. code-block:: php
 

components/property_info.rst

@@ -110,7 +110,7 @@ on a "remember-me" cookie, or even authenticated anonymously?
     use Symfony\Component\Security\Core\Authentication\Token\RememberMeToken;
 
     $anonymousClass = AnonymousToken::class;
-    $rememberMeClass = RememberMeToken::Class;
+    $rememberMeClass = RememberMeToken::class;
 
     $trustResolver = new AuthenticationTrustResolver($anonymousClass, $rememberMeClass);