From 5dc304c2eef330004df6f97a80f1a353e3fa01fb Mon Sep 17 00:00:00 2001 From: WouterJ Date: Fri, 21 Oct 2016 00:44:16 +0200 Subject: [PATCH 1/7] Bootstrap main debugging guide --- _build/redirection_map | 1 + debug.rst | 94 +++++++++++++++++++++++++++++++++++++++--- debug/debugging.rst | 92 ----------------------------------------- 3 files changed, 89 insertions(+), 98 deletions(-) delete mode 100644 debug/debugging.rst diff --git a/_build/redirection_map b/_build/redirection_map index 81af4e938fb..25abd48710e 100644 --- a/_build/redirection_map +++ b/_build/redirection_map @@ -324,6 +324,7 @@ /components/yaml/index /components/yaml /deployment/tools /deployment /install/bundles /setup/bundles +/debug/debugging /debug /form /forms /testing/simulating_authentication /testing/http_authentication /validation/group_service_resolver /form/validation_group_service_resolver diff --git a/debug.rst b/debug.rst index 49d3074b799..437ae3ff192 100644 --- a/debug.rst +++ b/debug.rst @@ -1,8 +1,90 @@ -Debugging -========= +.. index:: + single: Debugging -.. toctree:: - :maxdepth: 1 - :glob: +How to Optimize your Development Environment for Debugging +========================================================== - debug/* +When you work on a Symfony project on your local machine, you should use the +``dev`` environment (``app_dev.php`` front controller). This environment +configuration is optimized for two main purposes. + +* Give the developer accurate feedback whenever something goes wrong (provided + by the web debug toolbar, nice exception pages, profiler, ...); +* Be as similar as possible as the production environment to avoid problems + when deploying the project. + +Disabling the Bootstrap File and Class Caching +---------------------------------------------- + +To make Symfony run as fast as possible, it creates big PHP files in your cache +containing the aggregation of PHP classes your project needs for every request. +However, this behavior can confuse your IDE or your debugger. This recipe shows +you how you can tweak this caching mechanism to make it friendlier when you +need to debug code that involves Symfony classes. + +The ``app_dev.php`` front controller reads as follows by default:: + + // ... + + $loader = require_once __DIR__.'/../app/bootstrap.php.cache'; + require_once __DIR__.'/../app/AppKernel.php'; + + $kernel = new AppKernel('dev', true); + $kernel->loadClassCache(); + $request = Request::createFromGlobals(); + +To make your debugger happier, disable all PHP class caches by removing the +call to ``loadClassCache()`` and by replacing the require statements like +below:: + + // ... + + // $loader = require_once __DIR__.'/../app/bootstrap.php.cache'; + $loader = require_once __DIR__.'/../app/autoload.php'; + require_once __DIR__.'/../app/AppKernel.php'; + + $kernel = new AppKernel('dev', true); + // $kernel->loadClassCache(); + $request = Request::createFromGlobals(); + +.. tip:: + + If you disable the PHP caches, don't forget to revert after your debugging + session. + +Some IDEs do not like the fact that some classes are stored in different +locations. To avoid problems, you can either tell your IDE to ignore the PHP +cache files, or you can change the extension used by Symfony for these files:: + + $kernel->loadClassCache('classes', '.php.cache'); + +Useful Debugging Commands +------------------------- + +When developing a large application, it can be hard to keep track of all the +different services, routes and translations. Luckily, Symfony has some commands +that can help you visualize and find the information. + +``debug:container`` + Displays information about the contents of the Symfony container for all public + services. To find only those matching a name, append the name as an argument. + +``debug:config`` + Shows all configured bundles, their class and their alias. + +``debug:event-dispatcher`` + Displays information about all the registered listeners in the event dispatcher. + +``debug:router`` + Displays information about all configured routes in the application as a + table with the name, method, scheme, host and path for each route. + +``debug:translation `` + Shows a table of the translation key, the domain, the translation and the + fallback translation for all known messages, if translations exist for + the given locale. + +.. tip:: + + When in doubt how to use a console command, open the help section by + appending the ``--help`` option. diff --git a/debug/debugging.rst b/debug/debugging.rst deleted file mode 100644 index 56a377e1aeb..00000000000 --- a/debug/debugging.rst +++ /dev/null @@ -1,92 +0,0 @@ -.. index:: - single: Debugging - -How to Optimize your Development Environment for Debugging -========================================================== - -When you work on a Symfony project on your local machine, you should use the -``dev`` environment (``app_dev.php`` front controller). This environment -configuration is optimized for two main purposes: - -* Give the developer accurate feedback whenever something goes wrong (web - debug toolbar, nice exception pages, profiler, ...); - -* Be as similar as possible as the production environment to avoid problems - when deploying the project. - -Disabling the Bootstrap File and Class Caching ----------------------------------------------- - -And to make the production environment as fast as possible, Symfony creates -big PHP files in your cache containing the aggregation of PHP classes your -project needs for every request. However, this behavior can confuse your IDE -or your debugger. This recipe shows you how you can tweak this caching -mechanism to make it friendlier when you need to debug code that involves -Symfony classes. - -The ``app_dev.php`` front controller reads as follows by default:: - - // ... - - $loader = require_once __DIR__.'/../app/bootstrap.php.cache'; - require_once __DIR__.'/../app/AppKernel.php'; - - $kernel = new AppKernel('dev', true); - $kernel->loadClassCache(); - $request = Request::createFromGlobals(); - -To make your debugger happier, disable all PHP class caches by removing the -call to ``loadClassCache()`` and by replacing the require statements like -below:: - - // ... - - // $loader = require_once __DIR__.'/../app/bootstrap.php.cache'; - $loader = require_once __DIR__.'/../app/autoload.php'; - require_once __DIR__.'/../app/AppKernel.php'; - - $kernel = new AppKernel('dev', true); - // $kernel->loadClassCache(); - $request = Request::createFromGlobals(); - -.. tip:: - - If you disable the PHP caches, don't forget to revert after your debugging - session. - -Some IDEs do not like the fact that some classes are stored in different -locations. To avoid problems, you can either tell your IDE to ignore the PHP -cache files, or you can change the extension used by Symfony for these files:: - - $kernel->loadClassCache('classes', '.php.cache'); - -Useful Debugging Commands -------------------------- - -When developing a large application, it can be hard to keep track of all the -different services, routes and translations. Luckily, Symfony has some commands -that can help you visualize and find the information. - -``debug:container`` - Displays information about the contents of the Symfony container for all public - services. To find only those matching a name, append the name as an argument. - -``debug:config`` - Shows all configured bundles, their class and their alias. - -``debug:event-dispatcher`` - Displays information about all the registered listeners in the event dispatcher. - -``debug:router`` - Displays information about all configured routes in the application as a - table with the name, method, scheme, host and path for each route. - -``debug:translation `` - Shows a table of the translation key, the domain, the translation and the - fallback translation for all known messages, if translations exist for - the given locale. - -.. tip:: - - When in doubt how to use a console command, open the help section by - appending the ``--help`` option. From 4c065fde68f44c10f695dfc2201114a3e1ebd4b3 Mon Sep 17 00:00:00 2001 From: Hidde Wieringa Date: Sat, 1 Oct 2016 18:17:27 +0200 Subject: [PATCH 2/7] Added the VarDumper to the debug/debugging page Conflicts: debug/debugging.rst --- debug.rst | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/debug.rst b/debug.rst index 437ae3ff192..eee6b78109a 100644 --- a/debug.rst +++ b/debug.rst @@ -88,3 +88,28 @@ that can help you visualize and find the information. When in doubt how to use a console command, open the help section by appending the ``--help`` option. + +Using the VarDumper +------------------- + +To ease the debugging of a variable in your application, you can use the +``VarDumper`` component to dump the content of a variable. The component +provides an alternative to the PHP ``var_dump`` function, in the form of +``dump``. + +It is as easy as the code below:: + + // Create a variable with a value... + $myVar = ...; + + // ... and dump it + dump($myVar); + +.. tip:: + + The dumper is not limited to scalar values. Arrays and objects can also be + visualized using the ``VarDumper``. + +If the dumper is used on a command line, the result is a formatted string. +Otherwise, the result is a piece of HTML, which can be expanded to show nested +structures in the dumped value. From a92b74646e6fe51598ba01254ad4a7959efbfc0b Mon Sep 17 00:00:00 2001 From: WouterJ Date: Fri, 21 Oct 2016 00:53:44 +0200 Subject: [PATCH 3/7] Rewrote the VarDump section a bit --- debug.rst | 34 +++++++++++++++++++++------------- 1 file changed, 21 insertions(+), 13 deletions(-) diff --git a/debug.rst b/debug.rst index eee6b78109a..34a7bc2e1ae 100644 --- a/debug.rst +++ b/debug.rst @@ -89,27 +89,35 @@ that can help you visualize and find the information. When in doubt how to use a console command, open the help section by appending the ``--help`` option. -Using the VarDumper -------------------- +Dumping Variables with the VarDumper +------------------------------------ To ease the debugging of a variable in your application, you can use the -``VarDumper`` component to dump the content of a variable. The component -provides an alternative to the PHP ``var_dump`` function, in the form of -``dump``. +:doc:`VarDumper component ` to dump the content of a +variable. The component provides an alternative to the PHP :phpfunction:`var_dump()` +function, in the form of ``dump()``:: -It is as easy as the code below:: - - // Create a variable with a value... + // create a variable with a value $myVar = ...; - // ... and dump it + // and dump it dump($myVar); -.. tip:: - - The dumper is not limited to scalar values. Arrays and objects can also be - visualized using the ``VarDumper``. +The dumper is not limited to scalar values. Arrays and objects can also be +visualized using the VarDumper. One of the most important advantages of using +``dump()`` is a nicer and more specialized dump of objects (e.g. Doctrine +internals are filtered out when dumping a proxy entity). If the dumper is used on a command line, the result is a formatted string. Otherwise, the result is a piece of HTML, which can be expanded to show nested structures in the dumped value. + +You can also dump values from inside templates: + +.. code-block:: html+twig + + {# dumps the variable inline as HTML #} + {{ dump(myVar) }} + + {# dumps the variable to the web debug toolbar to not modify the template #} + {% dump myVar %} From c015760f6de7dbcd3db6b688c021c1f64218741c Mon Sep 17 00:00:00 2001 From: WouterJ Date: Fri, 21 Oct 2016 00:59:14 +0200 Subject: [PATCH 4/7] Added a section about interactive debugging tools --- debug.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/debug.rst b/debug.rst index 34a7bc2e1ae..928fbc34092 100644 --- a/debug.rst +++ b/debug.rst @@ -13,6 +13,17 @@ configuration is optimized for two main purposes. * Be as similar as possible as the production environment to avoid problems when deploying the project. +Using Interactive Debug Tools +----------------------------- + +Interactive debug tools allow you to walk through the code step by step, +making it easier to indentify which step is causing problems. Symfony works +with any PHP debug environment, among them: + + * Xdebug_, the most well-known PHP debugger; + * PsySH_, a PHP REPL_ (Read-eval-print loop) debugger. Use the + FidryPsyshBundle_ for a dedicated Symfony integration of PsySH. + Disabling the Bootstrap File and Class Caching ---------------------------------------------- @@ -121,3 +132,8 @@ You can also dump values from inside templates: {# dumps the variable to the web debug toolbar to not modify the template #} {% dump myVar %} + +.. _Xdebug: https://xdebug.org/ +.. _PsySH: http://psysh.org/ +.. _REPL: https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop +.. _FidryPsyshBundle: https://github.com/theofidry/PsyshBundle From bb389eeecb3b9ed7201dc5d97a0ec0f8973caead Mon Sep 17 00:00:00 2001 From: WouterJ Date: Fri, 21 Oct 2016 00:59:28 +0200 Subject: [PATCH 5/7] Moved the debug commands below again --- debug.rst | 67 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 36 insertions(+), 31 deletions(-) diff --git a/debug.rst b/debug.rst index 928fbc34092..105ebd05880 100644 --- a/debug.rst +++ b/debug.rst @@ -69,37 +69,6 @@ cache files, or you can change the extension used by Symfony for these files:: $kernel->loadClassCache('classes', '.php.cache'); -Useful Debugging Commands -------------------------- - -When developing a large application, it can be hard to keep track of all the -different services, routes and translations. Luckily, Symfony has some commands -that can help you visualize and find the information. - -``debug:container`` - Displays information about the contents of the Symfony container for all public - services. To find only those matching a name, append the name as an argument. - -``debug:config`` - Shows all configured bundles, their class and their alias. - -``debug:event-dispatcher`` - Displays information about all the registered listeners in the event dispatcher. - -``debug:router`` - Displays information about all configured routes in the application as a - table with the name, method, scheme, host and path for each route. - -``debug:translation `` - Shows a table of the translation key, the domain, the translation and the - fallback translation for all known messages, if translations exist for - the given locale. - -.. tip:: - - When in doubt how to use a console command, open the help section by - appending the ``--help`` option. - Dumping Variables with the VarDumper ------------------------------------ @@ -133,6 +102,42 @@ You can also dump values from inside templates: {# dumps the variable to the web debug toolbar to not modify the template #} {% dump myVar %} +Useful Debugging Commands +------------------------- + +When developing a large application, it can be hard to keep track of all the +different services, routes and translations. Luckily, Symfony has some commands +that can help you visualize and find the information. + +``debug:container`` + Displays information about the contents of the Symfony container for all public + services. To find only those matching a name, append the name as an argument. + +``debug:config`` + Shows all configured bundles, their class and their alias. + +``debug:event-dispatcher`` + Displays information about all the registered listeners in the event dispatcher. + +``debug:router`` + Displays information about all configured routes in the application as a + table with the name, method, scheme, host and path for each route. + +``debug:translation `` + Shows a table of the translation key, the domain, the translation and the + fallback translation for all known messages, if translations exist for + the given locale. + +.. tip:: + + When in doubt how to use a console command, open the help section by + appending the ``--help`` option. + +.. tip:: + + When in doubt how to use a console command, open the help section by + appending the ``--help`` option. + .. _Xdebug: https://xdebug.org/ .. _PsySH: http://psysh.org/ .. _REPL: https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop From 779983d42e22195f53f4e6e0a3e5e588d3e8b0c4 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sun, 19 Mar 2017 18:52:51 +0100 Subject: [PATCH 6/7] Fixes after great reviews --- .../front_controllers_and_kernel.rst | 2 +- debug.rst | 40 ++++++++++--------- 2 files changed, 23 insertions(+), 19 deletions(-) diff --git a/configuration/front_controllers_and_kernel.rst b/configuration/front_controllers_and_kernel.rst index eb925992698..1fa94755529 100644 --- a/configuration/front_controllers_and_kernel.rst +++ b/configuration/front_controllers_and_kernel.rst @@ -45,7 +45,7 @@ to `decorate`_ the kernel with additional features. Examples include: * Configuring the autoloader or adding additional autoloading mechanisms; * Adding HTTP level caching by wrapping the kernel with an instance of :ref:`AppCache `; -* Enabling (or skipping) the :doc:`ClassCache `; +* Enabling (or skipping) the :doc:`ClassCache `; * Enabling the :doc:`Debug Component `. The front controller can be chosen by requesting URLs like: diff --git a/debug.rst b/debug.rst index 105ebd05880..9d55b18ea99 100644 --- a/debug.rst +++ b/debug.rst @@ -1,28 +1,28 @@ .. index:: single: Debugging -How to Optimize your Development Environment for Debugging +How to Optimize Your Development Environment for Debugging ========================================================== When you work on a Symfony project on your local machine, you should use the ``dev`` environment (``app_dev.php`` front controller). This environment -configuration is optimized for two main purposes. +configuration is optimized for two main purposes: * Give the developer accurate feedback whenever something goes wrong (provided by the web debug toolbar, nice exception pages, profiler, ...); -* Be as similar as possible as the production environment to avoid problems - when deploying the project. +* Be as close as possible to the production environment to avoid problems when + deploying the project. Using Interactive Debug Tools ----------------------------- Interactive debug tools allow you to walk through the code step by step, -making it easier to indentify which step is causing problems. Symfony works +making it easier to identify which step is causing problems. Symfony works with any PHP debug environment, among them: - * Xdebug_, the most well-known PHP debugger; - * PsySH_, a PHP REPL_ (Read-eval-print loop) debugger. Use the - FidryPsyshBundle_ for a dedicated Symfony integration of PsySH. + * `Xdebug`_, the most well-known PHP debugger; + * `PsySH`_, a PHP `REPL`_ (Read-eval-print loop) debugger. Use the + `FidryPsyshBundle`_ for a dedicated Symfony integration of PsySH. Disabling the Bootstrap File and Class Caching ---------------------------------------------- @@ -60,8 +60,8 @@ below:: .. tip:: - If you disable the PHP caches, don't forget to revert after your debugging - session. + If you disable the PHP caches, don't forget to revert these changes after + your debugging session. Some IDEs do not like the fact that some classes are stored in different locations. To avoid problems, you can either tell your IDE to ignore the PHP @@ -74,8 +74,8 @@ Dumping Variables with the VarDumper To ease the debugging of a variable in your application, you can use the :doc:`VarDumper component ` to dump the content of a -variable. The component provides an alternative to the PHP :phpfunction:`var_dump()` -function, in the form of ``dump()``:: +variable. The component provides the ``dump()`` function, an alternative to +PHP's :phpfunction:`var_dump()` function:: // create a variable with a value $myVar = ...; @@ -86,7 +86,7 @@ function, in the form of ``dump()``:: The dumper is not limited to scalar values. Arrays and objects can also be visualized using the VarDumper. One of the most important advantages of using ``dump()`` is a nicer and more specialized dump of objects (e.g. Doctrine -internals are filtered out when dumping a proxy entity). +internals are filtered out when dumping an entity proxy). If the dumper is used on a command line, the result is a formatted string. Otherwise, the result is a piece of HTML, which can be expanded to show nested @@ -107,14 +107,14 @@ Useful Debugging Commands When developing a large application, it can be hard to keep track of all the different services, routes and translations. Luckily, Symfony has some commands -that can help you visualize and find the information. +that can help you visualize and find the information: ``debug:container`` Displays information about the contents of the Symfony container for all public - services. To find only those matching a name, append the name as an argument. + services. Append a service ID as an argument to find only those matching the ID. ``debug:config`` - Shows all configured bundles, their class and their alias. + Shows all configured bundles, their classes and their aliases. ``debug:event-dispatcher`` Displays information about all the registered listeners in the event dispatcher. @@ -123,15 +123,19 @@ that can help you visualize and find the information. Displays information about all configured routes in the application as a table with the name, method, scheme, host and path for each route. +``router:match `` + Shows the route information matching the provided path info or an error if + no route matches. + ``debug:translation `` Shows a table of the translation key, the domain, the translation and the - fallback translation for all known messages, if translations exist for + fallback translation for all known messages if translations exist for the given locale. .. tip:: When in doubt how to use a console command, open the help section by - appending the ``--help`` option. + appending the ``--help`` (``-h``) option. .. tip:: From 758a9f71d138a75f5e0b8b2ef1fc82bd387271b3 Mon Sep 17 00:00:00 2001 From: Wouter J Date: Sat, 7 Oct 2017 17:57:26 +0200 Subject: [PATCH 7/7] Removed doc on load cache class --- debug.rst | 45 --------------------------------------------- 1 file changed, 45 deletions(-) diff --git a/debug.rst b/debug.rst index 9d55b18ea99..8e08550df9f 100644 --- a/debug.rst +++ b/debug.rst @@ -24,51 +24,6 @@ with any PHP debug environment, among them: * `PsySH`_, a PHP `REPL`_ (Read-eval-print loop) debugger. Use the `FidryPsyshBundle`_ for a dedicated Symfony integration of PsySH. -Disabling the Bootstrap File and Class Caching ----------------------------------------------- - -To make Symfony run as fast as possible, it creates big PHP files in your cache -containing the aggregation of PHP classes your project needs for every request. -However, this behavior can confuse your IDE or your debugger. This recipe shows -you how you can tweak this caching mechanism to make it friendlier when you -need to debug code that involves Symfony classes. - -The ``app_dev.php`` front controller reads as follows by default:: - - // ... - - $loader = require_once __DIR__.'/../app/bootstrap.php.cache'; - require_once __DIR__.'/../app/AppKernel.php'; - - $kernel = new AppKernel('dev', true); - $kernel->loadClassCache(); - $request = Request::createFromGlobals(); - -To make your debugger happier, disable all PHP class caches by removing the -call to ``loadClassCache()`` and by replacing the require statements like -below:: - - // ... - - // $loader = require_once __DIR__.'/../app/bootstrap.php.cache'; - $loader = require_once __DIR__.'/../app/autoload.php'; - require_once __DIR__.'/../app/AppKernel.php'; - - $kernel = new AppKernel('dev', true); - // $kernel->loadClassCache(); - $request = Request::createFromGlobals(); - -.. tip:: - - If you disable the PHP caches, don't forget to revert these changes after - your debugging session. - -Some IDEs do not like the fact that some classes are stored in different -locations. To avoid problems, you can either tell your IDE to ignore the PHP -cache files, or you can change the extension used by Symfony for these files:: - - $kernel->loadClassCache('classes', '.php.cache'); - Dumping Variables with the VarDumper ------------------------------------