diff --git a/book/templating.rst b/book/templating.rst index e1159069d71..19ecf3fa61a 100644 --- 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 index 3ed6fb33678..fa6d81968bd 100644 --- 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 index 6e14a9d412f..913c5419b71 100644 --- a/contributing/code/tests.rst +++ b/contributing/code/tests.rst @@ -3,54 +3,32 @@ Running Symfony Tests ===================== -Before submitting a :doc:`patch ` 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 `. 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 ` 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 ` - -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 ` 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 index 61b6fdfe6e1..9fc57318404 100644 --- 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 `. 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 index 8bac5cf43be..11838c6fa38 100644 --- 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 \ No newline at end of file diff --git a/cookbook/controller/error_pages.rst b/cookbook/controller/error_pages.rst index 1b4bc784dff..64b3760ac6e 100644 --- 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 ` +:doc:`Writing your own 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 index 0282086c165..f1e677c2f6e 100644 --- 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 index a62c736db11..d14ecb20536 100644 --- 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/cookbook/configuration/mongodb_session_storage.rst b/cookbook/doctrine/mongodb_session_storage.rst similarity index 96% rename from cookbook/configuration/mongodb_session_storage.rst rename to cookbook/doctrine/mongodb_session_storage.rst index c2f912e8b9e..5b2811fab8f 100644 --- a/cookbook/configuration/mongodb_session_storage.rst +++ b/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/ \ No newline at end of file +.. _MongoDB shell: http://docs.mongodb.org/v2.2/tutorial/getting-started-with-the-mongo-shell/ diff --git a/cookbook/configuration/pdo_session_storage.rst b/cookbook/doctrine/pdo_session_storage.rst similarity index 100% rename from cookbook/configuration/pdo_session_storage.rst rename to cookbook/doctrine/pdo_session_storage.rst diff --git a/cookbook/event_dispatcher/before_after_filters.rst b/cookbook/event_dispatcher/before_after_filters.rst index d1c5acddbf8..2b7d25d6a9d 100644 --- 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/cookbook/service_container/event_listener.rst b/cookbook/event_dispatcher/event_listener.rst similarity index 100% rename from cookbook/service_container/event_listener.rst rename to cookbook/event_dispatcher/event_listener.rst diff --git a/cookbook/event_dispatcher/index.rst b/cookbook/event_dispatcher/index.rst index 8dfe9a541f4..27a9adfcc3d 100644 --- 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 index 5ebe688433a..64646d4663b 100644 --- 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 index b7563d7f6b8..8049b6b320d 100644 --- 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 index 9a4f7a78db9..9a2a4c6a244 100644 --- 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 index be8ad17868b..f66a455b788 100644 --- 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/session/locale_sticky_session.rst b/cookbook/session/locale_sticky_session.rst index 239086b8e4e..978ab473764 100644 --- a/cookbook/session/locale_sticky_session.rst +++ b/cookbook/session/locale_sticky_session.rst @@ -14,7 +14,7 @@ Creating a LocaleListener ------------------------- To simulate that the locale is stored in a session, you need to create and -register a :doc:`new event listener `. +register a :doc:`new event listener `. The listener will look something like this. Typically, ``_locale`` is used as a routing parameter to signify the locale, though it doesn't really matter how you determine the desired locale from the request:: @@ -171,7 +171,7 @@ Then register the listener: services: app.user_locale_listener: class: AppBundle\EventListener\UserLocaleListener - arguments: [@session] + arguments: ["@session"] tags: - { name: kernel.event_listener, event: security.interactive_login, method: onInteractiveLogin } diff --git a/cookbook/session/sessions_directory.rst b/cookbook/session/sessions_directory.rst index 5ecc133ae9f..3b62b62cb95 100644 --- a/cookbook/session/sessions_directory.rst +++ b/cookbook/session/sessions_directory.rst @@ -94,8 +94,8 @@ that your current sessions aren't lost when you clear Symfony's cache. method of session management available within Symfony. See :doc:`/components/http_foundation/session_configuration` for a discussion of session save handlers. There are also entries in the cookbook - about storing sessions in a :doc:`relational database ` - or a :doc:`NoSQL database `. + about storing sessions in a :doc:`relational database ` + or a :doc:`NoSQL database `. To change the directory in which Symfony saves session data, you only need change the framework configuration. In this example, you will change the diff --git a/cookbook/upgrade/major_version.rst b/cookbook/upgrade/major_version.rst index d83aa966893..86dd434c907 100644 --- a/cookbook/upgrade/major_version.rst +++ b/cookbook/upgrade/major_version.rst @@ -59,17 +59,17 @@ more confidence. Deprecations in PHPUnit ~~~~~~~~~~~~~~~~~~~~~~~ -By default, PHPUnit will handle deprecation notices as real errors. This means -that all tests are aborted because it uses a BC layer. +When you run your tests using PHPUnit, no deprecation notices are shown. +To help you here, Symfony provides a PHPUnit bridge. This bridge will show +you a nice summary of all deprecation notices at the end of the test report. -To make sure this doesn't happen, you can install the PHPUnit bridge: +All you need to do is install the PHPUnit bridge: .. code-block:: bash $ composer require --dev symfony/phpunit-bridge -Now, your tests execute normally and a nice summary of the deprecation notices -is displayed at the end of the test report: +Now, you can start fixing the notices: .. code-block:: text @@ -87,12 +87,36 @@ is displayed at the end of the test report: 2x in PageAdminTest::testPageList from Symfony\Cmf\SimpleCmsBundle\Tests\WebTest\Admin 1x in PageAdminTest::testPageEdit from Symfony\Cmf\SimpleCmsBundle\Tests\WebTest\Admin +Once you fixed them all, the command ends with ``0`` (success) and you're +done! + +.. sidebar:: Using the Weak Deprecations Mode + + Sometimes, you can't fix all deprecations (e.g. something was deprecated + in 2.6 and you still need to support 2.3). In these cases, you can still + use the bridge to fix as many deprecations as possible and then switch + to the weak test mode to make your tests pass again. You can do this by + using the ``SYMFONY_DEPRECATIONS_HELPER`` env variable: + + .. code-block:: xml + + + + + + + + + + + (you can also execute the command like ``SYMFONY_DEPRECATIONS_HELPER=weak phpunit``). + .. _upgrade-major-symfony-composer: 2) Update to the New Major Version via Composer ----------------------------------------------- -If your code is deprecation free, you can update the Symfony library via +Once your code is deprecation free, you can update the Symfony library via Composer by modifying your ``composer.json`` file: .. code-block:: json @@ -103,14 +127,14 @@ Composer by modifying your ``composer.json`` file: "require": { "symfony/symfony": "3.0.*", }, - "...": "...", + "...": "..." } Next, use Composer to download new versions of the libraries: .. code-block:: bash - $ composer update symfony/symfony + $ composer update --with-dependencies symfony/symfony .. include:: /cookbook/upgrade/_update_dep_errors.rst.inc diff --git a/redirection_map b/redirection_map index 3176d128e9e..bea56526ac1 100644 --- a/redirection_map +++ b/redirection_map @@ -49,3 +49,6 @@ /cmf/cookbook/creating_a_cms/the-frontend /cmf/tutorial/the-frontend /cookbook/upgrading /cookbook/upgrade/index /cookbook/security/voters_data_permission /cookbook/security/voters +/cookbook/configuration/pdo_session_storage /cookbook/doctrine/pdo_session_storage +/cookbook/configuration/mongodb_session_storage /cookbook/doctrine/mongodb_session_storage +/cookbook/service_container/event_listener /cookbook/event_dispatcher/event_listener diff --git a/reference/configuration/doctrine.rst b/reference/configuration/doctrine.rst index 1a329f7aa57..3ca1929d53d 100644 --- a/reference/configuration/doctrine.rst +++ b/reference/configuration/doctrine.rst @@ -601,7 +601,7 @@ namespace in the ``src/Entity`` directory and gives them an ``App`` alias # ... SomeEntityNamespace: type: annotation - dir: %kernel.root_dir%/../src/Entity + dir: "%kernel.root_dir%/../src/Entity" is_bundle: false prefix: App\Entity alias: App diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index 8732bddb03f..a7e502e9b75 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -726,7 +726,7 @@ installation. .. seealso:: You can see an example of the usage of this in - :doc:`/cookbook/configuration/pdo_session_storage`. + :doc:`/cookbook/doctrine/pdo_session_storage`. name .... diff --git a/reference/dic_tags.rst b/reference/dic_tags.rst index 68d601b4cf3..800d409f226 100644 --- a/reference/dic_tags.rst +++ b/reference/dic_tags.rst @@ -639,7 +639,7 @@ kernel.event_listener This tag allows you to hook your own classes into Symfony's process at different points. -For a full example of this listener, read the :doc:`/cookbook/service_container/event_listener` +For a full example of this listener, read the :doc:`/cookbook/event_dispatcher/event_listener` cookbook entry. Core Event Listener Reference diff --git a/reference/twig_reference.rst b/reference/twig_reference.rst index 65b866e54a3..55e55195f2c 100644 --- a/reference/twig_reference.rst +++ b/reference/twig_reference.rst @@ -104,9 +104,9 @@ asset **type**: ``string`` ``packageName`` **type**: ``string`` | ``null`` **default**: ``null`` -``absolute`` +``absolute`` (deprecated as of 2.7) **type**: ``boolean`` **default**: ``false`` -``version`` +``version`` (deprecated as of 2.7) **type**: ``string`` **default** ``null`` Returns a public path to ``path``, which takes into account the base path