..  include:: /Includes.rst.txt
..  index:: ! Debugging
..  _examples-debug:

=========
Debugging
=========

..  contents::
    :local:

..  todo: Revise this chapter, for example:
          - Add Extbase's DebuggerUtility::var_dump()
          - Add Fluid's f:debug ViewHelper
          - Add Configuration backend module for TCA, Middlewares, Events, etc.
          - Add TypoScript module for an overview of parsed TypoScript

..  index::
    pair: Debugging; PHP

PHP
===

Xdebug
------

First of all: best practice to debug PHP code is using an IDE (like `PhpStorm`_
or `Visual Studio Code`_) with `Xdebug`_. Advantages are:

*   You can investigate the values of variables and class properties when
    setting a breakpoint.
*   You can move forward line by line and see how the variables and properties
    change.
*   You can also step into calling methods and functions.
*   You see the calling code as a stack trace.


..  seealso::
    *   `Configure Xdebug in PhpStorm`_
    *   `Configure Xdebug in Visual Studio Code`_

..  _PhpStorm: https://www.jetbrains.com/phpstorm/
..  _Visual Studio Code: https://code.visualstudio.com/
..  _Xdebug: https://xdebug.org/
..  _Configure Xdebug in PhpStorm: https://www.jetbrains.com/help/phpstorm/configuring-xdebug.html
..  _Configure Xdebug in Visual Studio Code: https://tommcfarlin.com/xdebug-in-visual-studio-code/


..  index::
    GlobalDebugFunctions
    DebugUtility
    TYPO3_CONF_VARS; SYS devIPmask

`DebugUtility::debug()`
-----------------------

The TYPO3 Core provides a simple :php:`debug()` (defined in
:file:`EXT:core/Classes/Core/GlobalDebugFunctions.php`). It wraps around
:php:`\TYPO3\CMS\Core\Utility\DebugUtility::debug()` and will output debug
information only if it matches a set of IP addresses (defined in
:ref:`$GLOBALS['TYPO3_CONF_VARS']['SYS']['devIPmask'] <typo3ConfVars_sys_devIPmask>`).

For example, the following code:

..  include:: /CodeSnippets/Debugging/DebugCookies.rst.txt

will produce such an output:

..  include:: /Images/AutomaticScreenshots/Examples/Debugging/DebugOutput.rst.txt

In general, look at class :php:`\TYPO3\CMS\Core\Utility\DebugUtility` for useful
debugging tools.

..  index::
    pair: Debugging; Backend
    TYPO3_CONF_VARS; BE debug

TYPO3 backend debug mode
========================

To display additional debug information in the backend, set
:ref:`$GLOBALS['TYPO3_CONF_VARS']['BE']['debug'] <typo3ConfVars_be_debug>`
in :file:`config/system/settings.php` and log in with an administrator
account.

It shows for example the names of fields and in case of select, radio and
checkbox fields the values in addition, which are generated by the
:ref:`FormEngine <FormEngine>`. These can be used to set access permissions or
configuration using :ref:`TSconfig <t3tsconfig:start>`.

If :doc:`EXT:lowlevel <ext_lowlevel:Index>` is installed, the name of the
database table or field is appended to the select options in the
:guilabel:`System > DB Check > Full Search` module.

Additionally, in debug mode, the page renderer does not compress or concatenate
JavaScript or CSS resources.