From e74bbc9606aa4d9a443bf3f7e51af8238fe5564f Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Thu, 28 May 2015 20:50:20 -0400 Subject: [PATCH 1/4] Adding a new entry about deprecation warnings --- cookbook/map.rst.inc | 1 + cookbook/upgrade/deprecation_warnings.rst | 56 +++++++++++++++++++++++ cookbook/upgrade/index.rst | 1 + 3 files changed, 58 insertions(+) create mode 100644 cookbook/upgrade/deprecation_warnings.rst diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc index 4316f0de726..691c9a71d73 100644 --- a/cookbook/map.rst.inc +++ b/cookbook/map.rst.inc @@ -224,6 +224,7 @@ * :doc:`/cookbook/upgrade/patch_version` * :doc:`/cookbook/upgrade/minor_version` * :doc:`/cookbook/upgrade/major_version` + * :doc:`/cookbook/upgrade/deprecation_warnings` * :doc:`/cookbook/validation/index` diff --git a/cookbook/upgrade/deprecation_warnings.rst b/cookbook/upgrade/deprecation_warnings.rst new file mode 100644 index 00000000000..8526f158564 --- /dev/null +++ b/cookbook/upgrade/deprecation_warnings.rst @@ -0,0 +1,56 @@ +What do these "XXX is deprecated " E_USER_DEPRECATED Warnings mean? +=================================================================== + +Starting in Symfony 2.7, if you use a deprecated class, function or option, +Symfony triggers an ``E_USER_DEPRECATED`` error. Internally, that looks something +like this:: + + trigger_error( + 'The fooABC method is deprecated since version 2.4 and will be removed in 3.0.', + E_USER_DEPRECATED + ); + +This is great, because you can check your logs to know what needs to change +before you upgrade. In the Symfony Framework, the number of deprecated calls +shows up in the web debug toolbar. And if you install the `phpunit-bridge`_, +you can get a report of deprecated calls after running your tests. + +How can I Silence the Warnings? +------------------------------- + +As useful as these are, you don't want them to show up while developing and +you may also want to silence them on production to avoid filling up your +error logs. To do that, add ``~E_USER_DEPRECATED`` to your ``error_reporting`` +setting in ``php.ini``: + +.. code-block:: ini + + ; before + error_reporting = E_ALL + ; after + error_reporting = E_ALL & ~E_USER_DEPRECATED + +Alternatively, you can set this directly in bootstrap of your project:: + + error_reporting(error_reporting() & ~E_USER_DEPRECATED); + +How can I Fix the Warnings? +--------------------------- + +Of course ultimately, you want to stop using the deprecated functionality. +Sometimes, this is easy: the warning might tell you exactly what to change. + +But other times, the warning might be un-clear: a setting somewhere might +cause a class deeper to trigger the warning. In this case, the core team +does its best to give a clear message, but you may need to research that +warning further. + +And sometimes, the warning may come from a third-party library or bundle +that you're using. If that's true, there's a good chance that those deprecations +have already been updated. In that case, upgrade the library to fix them. + +Once all the deprecation warnings are gone, you can upgrade without a lot +more confidence. + +.. _`phpunit-bridge`: https://github.com/symfony/phpunit-bridge + diff --git a/cookbook/upgrade/index.rst b/cookbook/upgrade/index.rst index b943f2ae32a..3a37aa78a61 100644 --- a/cookbook/upgrade/index.rst +++ b/cookbook/upgrade/index.rst @@ -16,3 +16,4 @@ There are three types of upgrades, all needing a little different preparation: /cookbook/upgrade/patch_version /cookbook/upgrade/minor_version /cookbook/upgrade/major_version + /cookbook/upgrade/deprecation_warnings From 702394e78ffd00c09aa21a506ca65d16e2fcd0f0 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Fri, 29 May 2015 09:47:33 -0400 Subject: [PATCH 2/4] Tweaks thanks to Mr @javiereguiluz --- cookbook/upgrade/deprecation_warnings.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/cookbook/upgrade/deprecation_warnings.rst b/cookbook/upgrade/deprecation_warnings.rst index 8526f158564..7c22a91c899 100644 --- a/cookbook/upgrade/deprecation_warnings.rst +++ b/cookbook/upgrade/deprecation_warnings.rst @@ -40,16 +40,15 @@ How can I Fix the Warnings? Of course ultimately, you want to stop using the deprecated functionality. Sometimes, this is easy: the warning might tell you exactly what to change. -But other times, the warning might be un-clear: a setting somewhere might -cause a class deeper to trigger the warning. In this case, the core team -does its best to give a clear message, but you may need to research that -warning further. +But other times, the warning might be unclear: a setting somewhere might +cause a class deeper to trigger the warning. In this case, Symfony does its +best to give a clear message, but you may need to research that warning further. And sometimes, the warning may come from a third-party library or bundle that you're using. If that's true, there's a good chance that those deprecations have already been updated. In that case, upgrade the library to fix them. -Once all the deprecation warnings are gone, you can upgrade without a lot +Once all the deprecation warnings are gone, you can upgrade with a lot more confidence. .. _`phpunit-bridge`: https://github.com/symfony/phpunit-bridge From 060fe0340111718ba1874cac773749c1182c3a7f Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Fri, 29 May 2015 10:18:17 -0400 Subject: [PATCH 3/4] Added a section about the framework --- cookbook/upgrade/deprecation_warnings.rst | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/cookbook/upgrade/deprecation_warnings.rst b/cookbook/upgrade/deprecation_warnings.rst index 7c22a91c899..7f1ef585fca 100644 --- a/cookbook/upgrade/deprecation_warnings.rst +++ b/cookbook/upgrade/deprecation_warnings.rst @@ -20,7 +20,26 @@ How can I Silence the Warnings? As useful as these are, you don't want them to show up while developing and you may also want to silence them on production to avoid filling up your -error logs. To do that, add ``~E_USER_DEPRECATED`` to your ``error_reporting`` +error logs. + +In the Symfony Framework +~~~~~~~~~~~~~~~~~~~~~~~~ + +In the Symfony Framework, ``~E_USER_DEPRECATED`` is added to ``app/bootstrap.php.cache`` +automatically, but you need at least version 2.3.14 or 3.0.21 of the +`SensioDistributionBundle`_. So, you may need to upgrade: + +.. code-block:: bash + + composer update sensio/distribution-bundle + +Once you've updated, the ``bootstrap.php.cache`` file is rebuilt automatically. +At the top, you should see a line adding ``~E_USER_DEPRECATED``. + +Outside of the Symfony Framework +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To do that, add ``~E_USER_DEPRECATED`` to your ``error_reporting`` setting in ``php.ini``: .. code-block:: ini @@ -52,4 +71,4 @@ Once all the deprecation warnings are gone, you can upgrade with a lot more confidence. .. _`phpunit-bridge`: https://github.com/symfony/phpunit-bridge - +.. _`SensioDistributionBundle`: https://github.com/sensiolabs/SensioDistributionBundle From 1e8b75fbf18c7ea54a983c5dc58bfce1d0e028e6 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Fri, 29 May 2015 10:20:42 -0400 Subject: [PATCH 4/4] Fix thanks to Wouter --- cookbook/upgrade/deprecation_warnings.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/upgrade/deprecation_warnings.rst b/cookbook/upgrade/deprecation_warnings.rst index 7f1ef585fca..12e6c21c7e9 100644 --- a/cookbook/upgrade/deprecation_warnings.rst +++ b/cookbook/upgrade/deprecation_warnings.rst @@ -31,7 +31,7 @@ automatically, but you need at least version 2.3.14 or 3.0.21 of the .. code-block:: bash - composer update sensio/distribution-bundle + $ composer update sensio/distribution-bundle Once you've updated, the ``bootstrap.php.cache`` file is rebuilt automatically. At the top, you should see a line adding ``~E_USER_DEPRECATED``.