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/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 49d3074b799..8e08550df9f 100644 --- a/debug.rst +++ b/debug.rst @@ -1,8 +1,103 @@ -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 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 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. + +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 the ``dump()`` function, an alternative to +PHP's :phpfunction:`var_dump()` function:: + + // create a variable with a value + $myVar = ...; + + // and dump it + dump($myVar); + +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 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 +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 %} + +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. Append a service ID as an argument to find only those matching the ID. + +``debug:config`` + Shows all configured bundles, their classes and their aliases. + +``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. + +``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 + the given locale. + +.. tip:: + + When in doubt how to use a console command, open the help section by + appending the ``--help`` (``-h``) 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 +.. _FidryPsyshBundle: https://github.com/theofidry/PsyshBundle 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.