The Debug Toolbar

Relevant source files

The following files were used as context for generating this wiki page:

• source/testing/debugging.rst
• source/general/configuration.rst
• source/general/errors.rst
• source/installation/running.rst
• source/libraries/curlrequest.rst
• README.md

The CodeIgniter Debug Toolbar provides a comprehensive overview of the current page request, including performance metrics and application state. When enabled, it appears as a small icon at the bottom of the page in a development environment. Clicking the icon reveals a detailed toolbar with multiple tabs, each offering insights into different aspects of the application's execution, such as database queries, logs, loaded files, and route details. It is an indispensable tool for debugging and optimization during development.

The toolbar is designed to be extensible through "Collectors," which gather specific types of data for display. Developers can create custom collectors to monitor application-specific information, integrating seamlessly with the existing toolbar interface.

Sources: source/testing/debugging.rst:3-13

Enabling the Toolbar

The Debug Toolbar is enabled by default when the CI_ENVIRONMENT is set to development. It will not be displayed in testing or production environments to avoid exposing sensitive information and impacting performance.

The primary mechanism for enabling the toolbar involves the CI_ENVIRONMENT variable, typically set in the .env file.

CI_ENVIRONMENT = development

The toolbar's behavior is managed by the after filter CodeIgniter\Filters\DebugToolbar, which is automatically applied in the development environment. This filter injects the necessary HTML, CSS, and JavaScript into the final response body before it is sent to the browser.

Sources: source/testing/debugging.rst:15-21, source/installation/running.rst:10-14

The following diagram illustrates the process of how the toolbar is enabled and rendered.

This flowchart shows that the Debug Toolbar filter is only applied when the application is in the development environment.

Sources: source/testing/debugging.rst:15-21

Toolbar Configuration

The toolbar's settings are located in the configuration file app/Config/Toolbar.php. This file allows you to control which collectors are active and manage other toolbar settings.

Sources: source/testing/debugging.rst:23-25

Key Configuration Options

Property	Type	Description	Default
$collectors	array	An array of collector class names to be used. The order determines the display order of the tabs.	See Default Collectors
$maxHistory	int	The maximum number of previous requests to save in the "History" tab.	20
$views	array	An array of toolbar view files. Allows for customization of the toolbar's appearance.	Default view paths
$maxQueries	int	The maximum number of database queries to store. 0 means no limit.	100

Sources: source/testing/debugging.rst:23-35

Default Collectors

The toolbar gathers information using a set of default "Collectors". Each collector is responsible for a specific type of data.

Collector	Description
Timers	Collects benchmark data, showing the time taken for various parts of the application to execute.
Database	Displays all database queries executed for the current request, including execution time.
Logs	Shows any information logged using the Log Class.
Views	Renders a timeline of view rendering, including data passed to the views.
Cache	Displays information about cache hits and misses.
Files	Lists all PHP files that have been loaded during the request.
Routes	Shows details about the current route and lists all defined routes in the application.

• Events | Displays all events that have been triggered during the current request. |
  | History | Provides a history of previous requests and allows you to view their toolbar data. |

The CURLRequest collector is also available and shows information about requests made via the CURLRequest library.

Sources: source/testing/debugging.rst:37-59, source/libraries/curlrequest.rst:29-31

Displaying Custom Data

You can add your own data to the toolbar for debugging purposes using the toolbar() helper function. This function accepts a variable and an optional key, and the data will be displayed in the "Vars" tab.

// Simple variable
toolbar($myVar);

// With a specific key
toolbar($myVar, 'my-key');

The "Vars" tab will then display the contents of $myVar, labeled appropriately. This is useful for inspecting the state of variables at specific points in your code without interrupting execution.

Sources: source/testing/debugging.rst:61-75

Creating Custom Collectors

The toolbar can be extended by creating custom collectors to display application-specific data.

Collector Class Structure

A custom collector must extend CodeIgniter\Debug\Toolbar\Collectors\BaseCollector and implement specific properties and methods.

The following class diagram shows the key components of the BaseCollector that a custom collector would implement.

Implementation Steps

1. Create the Collector Class: Create a new class that extends CodeIgniter\Debug\Toolbar\Collectors\BaseCollector.
2. Set Properties:
   • $hasTimeline: Set to true if your collector will add data to the timeline.
   • $hasTabContent: Set to true to create a new tab in the toolbar.
   • $hasVarData: Set to true if you want to format data in the "Vars" tab.
   • $title: The title of the tab.
3. Implement Methods:
   • display(): Returns the HTML content for your custom tab.
   • getTitleDetails(): Returns a string displayed when hovering over the tab title.
   • getBadgeValue(): Returns a number to display in a badge on the tab title.
4. Register the Collector: Add the fully namespaced class name to the $collectors array in app/Config/Toolbar.php.

The following flowchart outlines the process for creating and registering a custom collector.

Toolbar and Content Security Policy (CSP)

If you have enabled Content Security Policy (CSP), you must configure it to allow the Debug Toolbar to function correctly. The toolbar injects inline scripts and styles into the page, which are often blocked by default CSP rules.

To permit the toolbar's resources, you need to add 'unsafe-inline' to the script-src and style-src directives in your CSP configuration.

Example CSP Header:
Content-Security-Policy: script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'

Failure to do so will prevent the toolbar from rendering and functioning as expected.

Sources: source/testing/debugging.rst:135-141

Summary

The Debug Toolbar is a powerful, integrated tool for CodeIgniter 4 development. It provides immediate feedback on application performance and state through a series of collectors. Its extensibility allows developers to tailor it to specific debugging needs by creating custom collectors. Proper configuration, especially in relation to environment settings and Content Security Policy, is crucial for its operation.

Sources: source/testing/debugging.rst