..  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.

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