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

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

..  contents::
    :local:

..  todo: Revise this chapter, for example:
          - Add Configuration backend module for TCA, Middlewares, Events, etc.
          - Add TypoScript module for an overview of parsed TypoScript

..  index::
    pair: Debugging; PHP

..  _examples-debug-php:

PHP
===

..  todo:: content is missing

..  _examples-debug-backend:

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.

In a development context you may want to set debug mode to true for extended periods. This can be achieved by altering the setting in :file:`config/system/additional.php`. To prevent deploying to production, you can use an environment variable or check the environment context before overriding the setting in :file:`config/system/settings.php`.

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:`Page TSconfig <t3tsref:pagetsconfig>`.

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.


.. _examples-debug-utility:


`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

.. _examples-debug-extbase-utility:

Extbase DebuggerUtility
=======================

Extbase's DebuggerUtility::var_dump() is a debugging function in TYPO3 that outputs detailed, human-readable information about variables, including their type and structure. It offers features like depth control and optional backtrace information to assist developers in effectively debugging complex data structures.

**Example:**

:php:`\TYPO3\CMS\Extbase\Utility\DebuggerUtility::var_dump($myVariable);`

You can also use the Extbase DebuggerUtility to debug SQL Querys for example. To do so, put the following code snippet before the execute function of your SQL query:

:php:`\TYPO3\CMS\Extbase\Utility\DebuggerUtility::var_dump($queryBuilder->getSQL());`


.. _examples-debug-fluid:

Fluid Debug ViewHelper
======================

The Fluid Debug ViewHelper is a part of the Fluid template engine and generates a HTML dump of the tagged variable. The ViewHelper can be used in any Fluid template to output the value of variables or objects in a human-readable format.

**Example:**

:html:`<f:debug>{myVariable}</f:debug>`


To display all available variables in your Fluid template, you can use the _all placeholder:

:html:`<f:debug>{_all}</f:debug>`

..  note::
    If you are debugging in a Fluid partial or a Fluid section, make sure that all variables you want to analyse are passed (defined in the arguments attribute of the render tag).

Get more information in the Fluid ViewHelper Reference :ref:`t3viewhelper:typo3-fluid-debug`


.. _examples-debug-xdebug:

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