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 [#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 [#5413] Backporting changes to 2.3 Added caution notes about the deprecation of container scopes
symfony · Aug 8, 2015 · ee7f14f · ee7f14f
2 parents fceaa9f + eafdb8c
commit ee7f14f
Show file tree

Hide file tree

Showing 27 changed files with 116 additions and 108 deletions.
diff --git a/book/templating.rst b/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 --git a/components/dependency_injection/lazy_services.rst b/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 --git a/contributing/code/tests.rst b/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 --git a/cookbook/bundles/best_practices.rst b/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 --git a/cookbook/configuration/index.rst b/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 --git a/cookbook/console/console_command.rst b/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 --git a/cookbook/controller/error_pages.rst b/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 --git a/cookbook/doctrine/file_uploads.rst b/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 --git a/cookbook/doctrine/index.rst b/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 --git a/...configuration/mongodb_session_storage.rst → ...book/doctrine/mongodb_session_storage.rst b/...configuration/mongodb_session_storage.rst → ...book/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 --git a/...ook/configuration/pdo_session_storage.rst → cookbook/doctrine/pdo_session_storage.rst b/...ook/configuration/pdo_session_storage.rst → cookbook/doctrine/pdo_session_storage.rst
diff --git a/cookbook/event_dispatcher/before_after_filters.rst b/cookbook/event_dispatcher/before_after_filters.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 --git a/...book/service_container/event_listener.rst → cookbook/event_dispatcher/event_listener.rst b/...book/service_container/event_listener.rst → cookbook/event_dispatcher/event_listener.rst
diff --git a/cookbook/event_dispatcher/index.rst b/cookbook/event_dispatcher/index.rst
@@ -4,6 +4,7 @@ Event Dispatcher
 .. toctree::
     :maxdepth: 2
 
+    event_listener
     before_after_filters
     class_extension
     method_behavior
diff --git a/cookbook/logging/monolog.rst b/cookbook/logging/monolog.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 --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc
@@ -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 --git a/cookbook/security/voters.rst b/cookbook/security/voters.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 --git a/cookbook/service_container/index.rst b/cookbook/service_container/index.rst
@@ -4,6 +4,5 @@ Service Container
 .. toctree::
     :maxdepth: 2
 
-    event_listener
     scopes
     compiler_passes
diff --git a/cookbook/service_container/scopes.rst b/cookbook/service_container/scopes.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.