Merge branch '2.7' into 2.8

* 2.7:
  [#7907] add some use statements
  Updating Doctrine syntax for getRepository method
  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

Author: xabbuh

best_practices/controllers.rst

@@ -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/security.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/templates.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')
                 ),
             );
         }

bundles/best_practices.rst

@@ -471,6 +471,21 @@ API is being used. The following code, would work for *all* users::
         }
     }
 
+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/override.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
 ---------
 

components/form.rst

@@ -420,7 +420,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/http_kernel.rst

@@ -592,7 +592,7 @@ each event has their own event object:
 =====================  ================================  ===================================================================================
 Name                   ``KernelEvents`` Constant         Argument passed to the listener
 =====================  ================================  ===================================================================================
-kernel.request         ``KernelEvents::REQUEST``         :class:`Symfony\\Component\\HttpKernel\\Event\\GetResponseEvent`                    
+kernel.request         ``KernelEvents::REQUEST``         :class:`Symfony\\Component\\HttpKernel\\Event\\GetResponseEvent`
 kernel.controller      ``KernelEvents::CONTROLLER``      :class:`Symfony\\Component\\HttpKernel\\Event\\FilterControllerEvent`
 kernel.view            ``KernelEvents::VIEW``            :class:`Symfony\\Component\\HttpKernel\\Event\\GetResponseForControllerResultEvent`
 kernel.response        ``KernelEvents::RESPONSE``        :class:`Symfony\\Component\\HttpKernel\\Event\\FilterResponseEvent`
@@ -702,6 +702,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/security/authorization.rst

@@ -123,7 +123,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);
 

controller/service.rst

@@ -174,7 +174,7 @@ Symfony's base controller::
         public function indexAction($name)
         {
             return $this->render(
-                'AppBundle:Hello:index.html.twig',
+                '@App/Hello/index.html.twig',
                 array('name' => $name)
             );
         }
@@ -210,7 +210,7 @@ service and use it directly::
         public function indexAction($name)
         {
             return $this->templating->renderResponse(
-                'AppBundle:Hello:index.html.twig',
+                '@App/Hello/index.html.twig',
                 array('name' => $name)
             );
         }

doctrine.rst

@@ -400,56 +400,8 @@ Even though Doctrine now knows how to persist a ``Product`` object to the
 database, the class itself isn't really useful yet. Since ``Product`` is just
 a regular PHP class with ``private`` properties, you need to create ``public``
 getter and setter methods (e.g. ``getName()``, ``setName($name)``) in order
-to access its properties in the rest of your application's code. Fortunately,
-the following command can generate these boilerplate methods automatically:
-
-.. code-block:: terminal
-
-    $ php app/console doctrine:generate:entities AppBundle/Entity/Product
-
-This command makes sure that all the getters and setters are generated
-for the ``Product`` class. This is a safe command - you can run it over and
-over again: it only generates getters and setters that don't exist (i.e. it
-doesn't replace your existing methods).
-
-.. caution::
-
-    Keep in mind that Doctrine's entity generator produces simple getters/setters.
-    You should review the generated methods and add any logic, if necessary,
-    to suit the needs of your application.
-
-.. sidebar:: More about ``doctrine:generate:entities``
-
-    With the ``doctrine:generate:entities`` command you can:
-
-    * generate getter and setter methods in entity classes;
-
-    * generate repository classes on behalf of entities configured with the
-      ``@ORM\Entity(repositoryClass="...")`` annotation;
-
-    * generate the appropriate constructor for 1:n and n:m relations.
-
-    The ``doctrine:generate:entities`` command saves a backup of the original
-    ``Product.php`` named ``Product.php~``. In some cases, the presence of
-    this file can cause a "Cannot redeclare class" error. It can be safely
-    removed. You can also use the ``--no-backup`` option to prevent generating
-    these backup files.
-
-    Note that you don't *need* to use this command. You could also write the
-    necessary getters and setters by hand. This option simply exists to save
-    you time, since creating these methods is often a common task during
-    development.
-
-You can also generate all known entities (i.e. any PHP class with Doctrine
-mapping information) of a bundle or an entire namespace:
-
-.. code-block:: terminal
-
-    # generates all entities in the AppBundle
-    $ php app/console doctrine:generate:entities AppBundle
-
-    # generates all entities of bundles in the Acme namespace
-    $ php app/console doctrine:generate:entities Acme
+to access its properties in the rest of your application's code. Add these
+methods manually or with your own IDE.
 
 .. _doctrine-creating-the-database-tables-schema:
 
@@ -589,7 +541,7 @@ on its ``id`` value::
     public function showAction($productId)
     {
         $product = $this->getDoctrine()
-            ->getRepository('AppBundle:Product')
+            ->getRepository(Product::class)
             ->find($productId);
 
         if (!$product) {
@@ -613,18 +565,18 @@ job is to help you fetch entities of a certain class. You can access the
 repository object for an entity class via::
 
     $repository = $this->getDoctrine()
-        ->getRepository('AppBundle:Product');
+        ->getRepository(Product::class);
 
 .. note::
 
-    The ``AppBundle:Product`` string is a shortcut you can use anywhere
+    You can also use ``AppBundle:Product`` syntax. This string is a shortcut you can use anywhere
     in Doctrine instead of the full class name of the entity (i.e. ``AppBundle\Entity\Product``).
     As long as your entity lives under the ``Entity`` namespace of your bundle,
     this will work.
 
 Once you have a repository object, you can access all sorts of helpful methods::
 
-    $repository = $this->getDoctrine()->getRepository('AppBundle:Product');
+    $repository = $this->getDoctrine()->getRepository(Product::class);
 
     // query for a single product by its primary key (usually "id")
     $product = $repository->find($productId);
@@ -647,7 +599,7 @@ Once you have a repository object, you can access all sorts of helpful methods::
 You can also take advantage of the useful ``findBy()`` and ``findOneBy()`` methods
 to easily fetch objects based on multiple conditions::
 
-    $repository = $this->getDoctrine()->getRepository('AppBundle:Product');
+    $repository = $this->getDoctrine()->getRepository(Product::class);
 
     // query for a single product matching the given name and price
     $product = $repository->findOneBy(
@@ -680,10 +632,13 @@ Updating an Object
 Once you've fetched an object from Doctrine, updating it is easy. Suppose
 you have a route that maps a product id to an update action in a controller::
 
+    use AppBundle\Entity\Post;
+    // ...
+
     public function updateAction($productId)
     {
         $em = $this->getDoctrine()->getManager();
-        $product = $em->getRepository('AppBundle:Product')->find($productId);
+        $product = $em->getRepository(Product::class)->find($productId);
 
         if (!$product) {
             throw $this->createNotFoundException(
@@ -729,7 +684,7 @@ Querying for Objects
 You've already seen how the repository object allows you to run basic queries
 without any work::
 
-    $repository = $this->getDoctrine()->getRepository('AppBundle:Product');
+    $repository = $this->getDoctrine()->getRepository(Product::class);
 
     $product = $repository->find($productId);
     $product = $repository->findOneByName('Keyboard');
@@ -790,7 +745,7 @@ depends on dynamic conditions, as your code soon becomes hard to read with
 DQL as you start to concatenate strings::
 
     $repository = $this->getDoctrine()
-        ->getRepository('AppBundle:Product');
+        ->getRepository(Product::class);
 
     // createQueryBuilder() automatically selects FROM AppBundle:Product
     // and aliases it to "p"

doctrine/associations.rst

@@ -189,11 +189,8 @@ own a collection of its related ``Product`` objects.
     namespace as the targetEntity.
 
 Now that you've added new properties to both the ``Product`` and ``Category``
-classes, tell Doctrine to generate the missing getter and setter methods for you:
-
-.. code-block:: terminal
-
-    $ php app/console doctrine:generate:entities AppBundle
+classes, you must generate the missing getter and setter methods manually or
+using your own IDE.
 
 Ignore the Doctrine metadata for a moment. You now have two classes - ``Product``
 and ``Category``, with a natural many-to-one relationship. The ``Product``
@@ -276,10 +273,13 @@ 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;
+    // ...
+
     public function showAction($productId)
     {
         $product = $this->getDoctrine()
-            ->getRepository('AppBundle:Product')
+            ->getRepository(Product::class)
             ->find($productId);
 
         $categoryName = $product->getCategory()->getName();
@@ -306,7 +306,7 @@ You can also query in the other direction::
     public function showProductsAction($categoryId)
     {
         $category = $this->getDoctrine()
-            ->getRepository('AppBundle:Category')
+            ->getRepository(Category::class)
             ->find($categoryId);
 
         $products = $category->getProducts();
@@ -327,7 +327,7 @@ to the given ``Category`` object via their ``category_id`` value.
     example::
 
         $product = $this->getDoctrine()
-            ->getRepository('AppBundle:Product')
+            ->getRepository(Product::class)
             ->find($productId);
 
         $category = $product->getCategory();
@@ -388,7 +388,7 @@ object and its related ``Category`` with just one query::
     public function showAction($productId)
     {
         $product = $this->getDoctrine()
-            ->getRepository('AppBundle:Product')
+            ->getRepository(Product::class)
             ->findOneByIdJoinedToCategory($productId);
 
         $category = $product->getCategory();