Merge branch '2.8'

* 2.8:
  Ensure that the entity is updated.
  Update lazy_services.rst
  Update templating.rst
  Additional little check to show how we're assumign the User object is the User entity
  Moved mongodb article and cleanup
  Fixing remaining reference of old emplacement of pdo_session_storage page due to the rebase
  Move some articles from wrong sections, updated indexs
  Move some articles from wrong sections
  [symfony#5374] Add deprecation notice in 2.7
  fix YAML syntax highlighting
  Improve and simplify the contributing instructions about tests
  Some fixes for bundle best practices
  Fix Major upgrade article for 2.7.1 changes
  [symfony#5413] Backporting changes to 2.3
  Added caution notes about the deprecation of container scopes

Author: weaverryan

Diff for: book/templating.rst

@@ -1224,7 +1224,7 @@ automatically:
 
 .. versionadded:: 2.6
     The global ``app.security`` variable (or the ``$app->getSecurity()``
-    method in PHP templates) is deprecated as of Symfony 2.6. Use ``app.user`` 
+    method in PHP templates) is deprecated as of Symfony 2.6. Use ``app.user``
     (``$app->getUser()``) and ``is_granted()`` (``$view['security']->isGranted()``)
     instead.
 
@@ -1595,16 +1595,16 @@ is ``true``. By default this means that the variables will be dumped in the
 Syntax Checking
 ---------------
 
-You can check for syntax errors in Twig templates using the ``twig:lint``
+You can check for syntax errors in Twig templates using the ``lint:twig``
 console command:
 
 .. code-block:: bash
 
     # You can check by filename:
-    $ php app/console twig:lint app/Resources/views/article/recent_list.html.twig
+    $ php app/console lint:twig app/Resources/views/article/recent_list.html.twig
 
     # or by directory:
-    $ php app/console twig:lint app/Resources/views
+    $ php app/console lint:twig app/Resources/views
 
 .. _template-formats:
 

Diff for: components/dependency_injection/lazy_services.rst

@@ -40,7 +40,7 @@ the `ProxyManager bridge`_:
 
     .. code-block:: bash
 
-        $ php composer.phar require ocramius/proxy-manager:~1.0
+        $ composer require ocramius/proxy-manager:~1.0
 
     Afterwards compile your container and check to make sure that you get
     a proxy for your lazy services.

Diff for: contributing/code/tests.rst

@@ -3,54 +3,32 @@
 Running Symfony Tests
 =====================
 
-Before submitting a :doc:`patch <patches>` for inclusion, you need to run the
-Symfony test suite to check that you have not broken anything.
+The Symfony project uses a third-party service which automatically runs tests
+for any submitted :doc:`patch <patches>`. If the new code breaks any test,
+the pull request will show an error message with a link to the full error details.
 
-PHPUnit
--------
+In any case, it's a good practice to run tests locally before submitting a
+:doc:`patch <patches>` for inclusion, to check that you have not broken anything.
 
-To run the Symfony test suite, `install PHPUnit`_ 4.2 (or later) first.
+.. _phpunit:
+.. _dependencies_optional:
 
-Dependencies (optional)
------------------------
+Before Running the Tests
+------------------------
 
-To run the entire test suite, including tests that depend on external
-dependencies, Symfony needs to be able to autoload them. By default, they are
-autoloaded from ``vendor/`` under the main root directory (see
-``autoload.php.dist``).
-
-The test suite needs the following third-party libraries:
-
-* Doctrine
-* Swift Mailer
-* Twig
-* Monolog
-
-To install them all, use `Composer`_:
-
-Step 1: :doc:`Install Composer globally </cookbook/composer>`
-
-Step 2: Install vendors.
+To run the Symfony test suite, `install PHPUnit`_ 4.2 (or later) first. Then,
+install the external dependencies used during the tests, such as Doctrine, Twig
+and Monolog. To do so, :doc:`install Composer </cookbook/composer>` and execute
+the following:
 
 .. code-block:: bash
 
     $ composer install
 
-.. note::
-
-    Note that the script takes some time to finish.
+.. _running:
 
-After installation, you can update the vendors to their latest version with
-the follow command:
-
-.. code-block:: bash
-
-    $ composer update
-
-Running
--------
-
-First, update the vendors (see above).
+Running the Tests
+-----------------
 
 Then, run the test suite from the Symfony root directory with the following
 command:
@@ -59,40 +37,17 @@ command:
 
     $ phpunit
 
-The output should display ``OK``. If not, you need to figure out what's going on
-and if the tests are broken because of your modifications.
+The output should display ``OK``. If not, read the reported errors to figure out
+what's going on and if the tests are broken because of the new code.
 
 .. tip::
 
-    If you want to test a single component type its path after the ``phpunit``
-    command, e.g.:
+    The entire Symfony suite can take up to several minutes to complete. If you
+    want to test a single component, type its path after the ``phpunit`` command,
+    e.g.:
 
     .. code-block:: bash
 
         $ phpunit src/Symfony/Component/Finder/
 
-.. tip::
-
-    Run the test suite before applying your modifications to check that they
-    run fine on your configuration.
-
-Code Coverage
--------------
-
-If you add a new feature, you also need to check the code coverage by using
-the ``coverage-html`` option:
-
-.. code-block:: bash
-
-    $ phpunit --coverage-html=cov/
-
-Check the code coverage by opening the generated ``cov/index.html`` page in a
-browser.
-
-.. tip::
-
-    The code coverage only works if you have Xdebug enabled and all
-    dependencies installed.
-
-.. _install PHPUnit: https://phpunit.de/manual/current/en/installation.html
-.. _`Composer`: https://getcomposer.org/
+.. _`install PHPUnit`: https://phpunit.de/manual/current/en/installation.html

Diff for: cookbook/bundles/best_practices.rst

@@ -146,7 +146,7 @@ class name is ``Acme\BlogBundle\Controller\ContentController``.
 All classes and files must follow the :doc:`Symfony coding standards </contributing/code/standards>`.
 
 Some classes should be seen as facades and should be as short as possible, like
-Commands, Helpers, Listeners, and Controllers.
+Commands, Helpers, Listeners and Controllers.
 
 Classes that connect to the event dispatcher should be suffixed with
 ``Listener``.
@@ -159,7 +159,7 @@ Vendors
 A bundle must not embed third-party PHP libraries. It should rely on the
 standard Symfony autoloading instead.
 
-A bundle should not embed third-party libraries written in JavaScript, CSS, or
+A bundle should not embed third-party libraries written in JavaScript, CSS or
 any other language.
 
 Tests
@@ -175,6 +175,7 @@ the ``Tests/`` directory. Tests should follow the following principles:
 * The tests should cover at least 95% of the code base.
 
 .. note::
+
    A test suite must not contain ``AllTests.php`` scripts, but must rely on the
    existence of a ``phpunit.xml.dist`` file.
 

Diff for: cookbook/configuration/index.rst

@@ -9,8 +9,6 @@ Configuration
     using_parameters_in_dic
     front_controllers_and_kernel
     external_parameters
-    pdo_session_storage
     apache_router
     web_server_configuration
     configuration_organization
-    mongodb_session_storage

Diff for: cookbook/console/console_command.rst

@@ -82,6 +82,11 @@ for details.
 Getting Services from the Service Container
 -------------------------------------------
 
+.. caution::
+
+    The "container scopes" concept explained in this section has been deprecated
+    in Symfony 2.8 and it will be removed in Symfony 3.0.
+
 By using :class:`Symfony\\Bundle\\FrameworkBundle\\Command\\ContainerAwareCommand`
 as the base class for the command (instead of the more basic
 :class:`Symfony\\Component\\Console\\Command\\Command`), you have access to the

Diff for: cookbook/controller/error_pages.rst

@@ -302,7 +302,7 @@ before, but also requires a thorough understanding of Symfony internals. Suppose
 that your code throws specialized exceptions with a particular meaning to your
 application domain.
 
-:doc:`Writing your own event listener </cookbook/service_container/event_listener>`
+:doc:`Writing your own event listener </cookbook/event_dispatcher/event_listener>`
 for the ``kernel.exception`` event allows you to have a closer look at the exception
 and take different actions depending on it. Those actions might include logging
 the exception, redirecting the user to another page or rendering specialized

Diff for: cookbook/doctrine/file_uploads.rst

@@ -494,6 +494,7 @@ property, instead of the actual filename::
             if (is_file($this->getAbsolutePath())) {
                 // store the old name to delete after the update
                 $this->temp = $this->getAbsolutePath();
+                $this->path = null;
             } else {
                 $this->path = 'initial';
             }

Diff for: cookbook/doctrine/index.rst

@@ -14,4 +14,6 @@ Doctrine
     resolve_target_entity
     mapping_model_classes
     registration_form
+    pdo_session_storage
+    mongodb_session_storage
     console

Diff for: cookbook/configuration/mongodb_session_storage.rst renamed to cookbook/doctrine/mongodb_session_storage.rst

@@ -30,12 +30,12 @@ need to change/add some parameters in the main configuration file:
             mongo_client:
                 class: MongoClient
                 # if using a username and password
-                arguments: [mongodb://%mongodb_username%:%mongodb_password%@%mongodb_host%:27017]
+                arguments: ["mongodb://%mongodb_username%:%mongodb_password%@%mongodb_host%:27017"]
                 # if not using a username and password
-                arguments: [mongodb://%mongodb_host%:27017]
+                arguments: ["mongodb://%mongodb_host%:27017"]
             session.handler.mongo:
                 class: Symfony\Component\HttpFoundation\Session\Storage\Handler\MongoDbSessionHandler
-                arguments: [@mongo_client, %mongo.session.options%]
+                arguments: ["@mongo_client", "%mongo.session.options%"]
 
     .. code-block:: xml
 
@@ -168,4 +168,4 @@ From the `MongoDB shell`_:
     db.session.ensureIndex( { "expireAt": 1 }, { expireAfterSeconds: 0 } )
 
 .. _installed and configured a MongoDB server: http://docs.mongodb.org/manual/installation/
-.. _MongoDB shell: http://docs.mongodb.org/v2.2/tutorial/getting-started-with-the-mongo-shell/
+.. _MongoDB shell: http://docs.mongodb.org/v2.2/tutorial/getting-started-with-the-mongo-shell/

Diff for: cookbook/configuration/pdo_session_storage.rst renamed to cookbook/doctrine/pdo_session_storage.rst

@@ -102,7 +102,7 @@ Creating an Event Listener
 
 Next, you'll need to create an event listener, which will hold the logic
 that you want executed before your controllers. If you're not familiar with
-event listeners, you can learn more about them at :doc:`/cookbook/service_container/event_listener`::
+event listeners, you can learn more about them at :doc:`/cookbook/event_dispatcher/event_listener`::
 
     // src/AppBundle/EventListener/TokenListener.php
     namespace AppBundle\EventListener;

Diff for: cookbook/event_dispatcher/before_after_filters.rst

@@ -4,6 +4,7 @@ Event Dispatcher
 .. toctree::
     :maxdepth: 2
 
+    event_listener
     before_after_filters
     class_extension
     method_behavior

Diff for: cookbook/service_container/event_listener.rst renamed to cookbook/event_dispatcher/event_listener.rst

@@ -242,7 +242,7 @@ option of your handler to ``rotating_file``:
             handlers:
                 main:
                     type:  rotating_file
-                    path:  %kernel.logs_dir%/%kernel.environment%.log
+                    path:  "%kernel.logs_dir%/%kernel.environment%.log"
                     level: debug
                     # max number of log files to keep
                     # defaults to zero, which means infinite files

Diff for: cookbook/event_dispatcher/index.rst

@@ -34,11 +34,11 @@
   * :doc:`/cookbook/configuration/using_parameters_in_dic`
   * :doc:`/cookbook/configuration/front_controllers_and_kernel`
   * :doc:`/cookbook/configuration/external_parameters`
-  * :doc:`/cookbook/configuration/pdo_session_storage`
   * :doc:`/cookbook/configuration/apache_router`
   * :doc:`/cookbook/configuration/web_server_configuration`
   * :doc:`/cookbook/configuration/configuration_organization`
-  * :doc:`/cookbook/configuration/mongodb_session_storage`
+  * (Doctrine) :doc:`/cookbook/doctrine/pdo_session_storage`
+  * (Doctrine) :doc:`/cookbook/doctrine/mongodb_session_storage`
 
 * :doc:`/cookbook/console/index`
 
@@ -78,8 +78,9 @@
   * :doc:`/cookbook/doctrine/resolve_target_entity`
   * :doc:`/cookbook/doctrine/mapping_model_classes`
   * :doc:`/cookbook/doctrine/registration_form`
+  * :doc:`/cookbook/doctrine/pdo_session_storage`
+  * :doc:`/cookbook/doctrine/mongodb_session_storage`
   * :doc:`/cookbook/doctrine/console`
-  * (configuration) :doc:`/cookbook/configuration/pdo_session_storage`
 
 * :doc:`/cookbook/email/index`
 
@@ -95,7 +96,7 @@
   * :doc:`/cookbook/event_dispatcher/before_after_filters`
   * :doc:`/cookbook/event_dispatcher/class_extension`
   * :doc:`/cookbook/event_dispatcher/method_behavior`
-  * (service container) :doc:`/cookbook/service_container/event_listener`
+  * :doc:`/cookbook/event_dispatcher/event_listener`
 
 * :doc:`/cookbook/expression/index`
 
@@ -113,8 +114,8 @@
   * :doc:`/cookbook/form/unit_testing`
   * :doc:`/cookbook/form/use_empty_data`
   * :doc:`/cookbook/form/direct_submit`
-  * (validation) :doc:`/cookbook/validation/custom_constraint`
-  * (doctrine) :doc:`/cookbook/doctrine/file_uploads`
+  * (Validation) :doc:`/cookbook/validation/custom_constraint`
+  * (Doctrine) :doc:`/cookbook/doctrine/file_uploads`
 
 * :doc:`/cookbook/frontend/index`
 
@@ -190,9 +191,9 @@
 
 * :doc:`/cookbook/service_container/index`
 
-  * :doc:`/cookbook/service_container/event_listener`
   * :doc:`/cookbook/service_container/scopes`
   * :doc:`/cookbook/service_container/compiler_passes`
+  * (Event Dispatcher) :doc:`/cookbook/event_dispatcher/event_listener`
 
 * :doc:`/cookbook/session/index`
 
@@ -201,10 +202,11 @@
   * :doc:`/cookbook/session/sessions_directory`
   * :doc:`/cookbook/session/php_bridge`
   * :doc:`/cookbook/session/limit_metadata_writes`
-  * (configuration) :doc:`/cookbook/configuration/pdo_session_storage`
-  * (configuration) :doc:`/cookbook/configuration/mongodb_session_storage`
+  * (Doctrine) :doc:`/cookbook/doctrine/pdo_session_storage`
+  * (Doctrine) :doc:`/cookbook/doctrine/mongodb_session_storage`
   * :doc:`/cookbook/session/avoid_session_start`
 
+
 * **PSR-7**
 
   * :doc:`/cookbook/psr7`

Diff for: cookbook/logging/monolog.rst

@@ -71,6 +71,7 @@ edit a particular object. Here's an example implementation:
     namespace AppBundle\Security\Authorization\Voter;
 
     use Symfony\Component\Security\Core\Authorization\Voter\AbstractVoter;
+    use AppBundle\Entity\User;
     use Symfony\Component\Security\Core\User\UserInterface;
 
     class PostVoter extends AbstractVoter
@@ -95,6 +96,13 @@ edit a particular object. Here's an example implementation:
                 return false;
             }
 
+            // double-check that the User object is the expected entity.
+            // It always will be, unless there is some misconfiguration of the
+            // security system.
+            if (!$user instanceof User) {
+                throw new \LogicException('The user is somehow not our User class!');
+            }
+
             switch($attribute) {
                 case self::VIEW:
                     // the data object could have for example a method isPrivate()

Diff for: cookbook/map.rst.inc

@@ -4,6 +4,5 @@ Service Container
 .. toctree::
     :maxdepth: 2
 
-    event_listener
     scopes
     compiler_passes

Diff for: cookbook/security/voters.rst

@@ -4,6 +4,11 @@
 How to Work with Scopes
 =======================
 
+.. caution::
+
+    The "container scopes" concept explained in this article has been deprecated
+    in Symfony 2.8 and it will be removed in Symfony 3.0.
+
 This article is all about scopes, a somewhat advanced topic related to the
 :doc:`/book/service_container`. If you've ever gotten an error mentioning
 "scopes" when creating services, then this article is for you.