Merge branch '3.3' into 3.4

* 3.3: (36 commits)
  [symfony#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
  Fixed the parse() method in the ExpressionLanguage AST examples
  [symfony#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
  Updated the screenshot of exceptions in dev environment
  Typo
  Fixing a typo in the Final Thoughts section
  Stop recommending the use of "doctrine:generate:entities"
  Use "null" so the lock is named automatically
  incorrect session short description
  Use of Setters and Getters
  Small mistype edits
  Changed text how to get button label
  ...

Author: xabbuh

_images/controller/error_pages/exceptions-in-dev-environment.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 Symfony\Component\Routing\Annotation\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(
@@ -186,7 +187,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) {

_images/install/deprecations-in-profiler.png

@@ -228,7 +228,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')
+            ->getRepository(Post::class)
             ->find($id);
 
         if (!$post) {

best_practices/controllers.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
@@ -121,7 +119,7 @@ class 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/security.rst

@@ -429,6 +429,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
 ----------
 

best_practices/templates.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/best_practices.rst

@@ -396,10 +396,19 @@ given text. This method is especially useful because you can use it to return
 a :class:`Symfony\\Component\\DomCrawler\\Form` object that represents the
 form that the button lives in::
 
-    $form = $crawler->selectButton('validate')->form();
+    // button example: <button id="my-super-button" type="submit">My super button</button>
+    
+    // you can get button by its label
+    $form = $crawler->selectButton('My super button')->form();
+    
+    // or by button id (#my-super-button) if the button doesn't have a label
+    $form = $crawler->selectButton('my-super-button')->form();
+    
+    // or you can filter the whole form, for example a form has a class attribute: <form class="form-vertical" method="POST">
+    $crawler->filter('.form-vertical')->form();
 
     // or "fill" the form fields with data
-    $form = $crawler->selectButton('validate')->form(array(
+    $form = $crawler->selectButton('my-super-button')->form(array(
         'name' => 'Ryan',
     ));
 

bundles/override.rst

@@ -21,7 +21,7 @@ method after parsing any expression to get its AST::
     use Symfony\Component\ExpressionLanguage\ExpressionLanguage;
 
     $ast = (new ExpressionLanguage())
-        ->parse('1 + 2')
+        ->parse('1 + 2', array())
         ->getNodes()
     ;
 
@@ -41,7 +41,7 @@ method to turn the AST into an array::
     // ...
 
     $astAsArray = (new ExpressionLanguage())
-        ->parse('1 + 2')
+        ->parse('1 + 2', array())
         ->getNodes()
         ->toArray()
     ;

components/dom_crawler.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/expression_language/ast.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/form.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/http_kernel.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);
 

components/property_info.rst

@@ -30,7 +30,7 @@ that adds two convenient methods to lock and release commands::
             }
 
             // If you prefer to wait until the lock is released, use this:
-            // $this->lock(true);
+            // $this->lock(null, true);
 
             // ...
 

components/security/authorization.rst

@@ -453,8 +453,8 @@ Managing the Session
 --------------------
 
 Symfony provides a nice session object that you can use to store information
-about the user between requests. By default, Symfony stores the attributes in a
-cookie by using native PHP sessions.
+about the user between requests. By default, Symfony stores the token in a
+cookie and writes the attributes to a file by using native PHP sessions.
 
 .. versionadded:: 3.3
     The ability to request a ``Session`` instance in controllers was introduced

console/lockable_trait.rst

@@ -239,7 +239,7 @@ logic to a separate service::
         {
             $fileName = md5(uniqid()).'.'.$file->guessExtension();
 
-            $file->move($this->targetDir, $fileName);
+            $file->move($this->getTargetDir(), $fileName);
 
             return $fileName;
         }

controller.rst

@@ -445,56 +445,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 bin/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 bin/console doctrine:generate:entities AppBundle
-
-    # generates all entities of bundles in the Acme namespace
-    $ php bin/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:
 
@@ -637,7 +589,7 @@ on its ``id`` value::
     public function showAction($productId)
     {
         $product = $this->getDoctrine()
-            ->getRepository('AppBundle:Product')
+            ->getRepository(Product::class)
             ->find($productId);
 
         if (!$product) {
@@ -660,18 +612,19 @@ as its "repository". You can think of a repository as a PHP class whose only
 job is to help you fetch entities of a certain class. You can access the
 repository object for an entity class via::
 
-    $repository = $em->getRepository('AppBundle:Product');
+    $repository = $this->getDoctrine()
+        ->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 = $em->getRepository('AppBundle:Product');
+    $repository = $this->getDoctrine()->getRepository(Product::class);
 
     // query for a single product by its primary key (usually "id")
     $product = $repository->find($productId);
@@ -694,7 +647,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 = $em->getRepository('AppBundle:Product');
+    $repository = $this->getDoctrine()->getRepository(Product::class);
 
     // query for a single product matching the given name and price
     $product = $repository->findOneBy(
@@ -727,11 +680,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)
     {
-        $product = $this->getDoctrine()
-            ->getRepository('AppBundle:Product')
-            ->find($productId);
+        $em = $this->getDoctrine()->getManager();
+        $product = $em->getRepository(Product::class)->find($productId);
 
         if (!$product) {
             throw $this->createNotFoundException(
@@ -777,7 +732,7 @@ Querying for Objects
 You've already seen how the repository object allows you to run basic queries
 without any work::
 
-    $repository = $em->getRepository('AppBundle:Product');
+    $repository = $this->getDoctrine()->getRepository(Product::class);
 
     $product = $repository->find($productId);
     $product = $repository->findOneByName('Keyboard');
@@ -836,7 +791,8 @@ Instead of writing a DQL string, you can use a helpful object called the
 depends on dynamic conditions, as your code soon becomes hard to read with
 DQL as you start to concatenate strings::
 
-    $repository = $em->getRepository('AppBundle:Product');
+    $repository = $this->getDoctrine()
+        ->getRepository(Product::class);
 
     // createQueryBuilder() automatically selects FROM AppBundle:Product
     // and aliases it to "p"