Skip to content

Commit 3229fb7

Browse files
lonnieezelllonnieezell
committed
Debugging docs
1 parent c88b73d commit 3229fb7

3 files changed

Lines changed: 196 additions & 159 deletions

File tree

‎user_guide_src/source/general/debugging.rst‎

Lines changed: 196 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,199 @@
22
Debugging Your Application
33
**************************
44

5-
TODO
5+
.. contents:: Table of Contents
6+
:depth: 3
7+
8+
================
9+
Replace var_dump
10+
================
11+
12+
While using XDebug and a good IDE can be indispensable to debug your application, sometimes a quick ``var_dump()`` is
13+
all you need. CodeIgniter makes that even better by bundling in the excellent `Kint <https://raveren.github.io/kint/>`_
14+
debugging tool for PHP. This goes way beyond your usual tool, providing many alternate pieces of data, like formatting
15+
timestamps into recognizable dates, showing you hexcodes as colors, display array data like a table for easy reading,
16+
and much, much more.
17+
18+
Enabling Kint
19+
=============
20+
21+
By default, Kint is enabled in **development** and **testing** environments only. This can be altered by modifying
22+
the ``$useKing`` value in the environment configuration section of the main **index.php** file::
23+
24+
$useKint = true;
25+
26+
Using Kint
27+
==========
28+
29+
**d()**
30+
31+
The ``d()`` method dumps all of the data it knows about the contents passed as the only parameter to the screen, and
32+
allows the script to continue executing::
33+
34+
d($_SERVER);
35+
36+
**ddd()**
37+
38+
This method is identical to ``d()``, except that it also ``dies()`` and no further code is executed this request.
39+
40+
**trace()**
41+
42+
This provides a backtrace to the current execution point, with Kint's own unique spin::
43+
44+
Kint::trace();
45+
46+
For more information, see `Kint's page <https://raveren.github.io/kint/>`_.
47+
48+
49+
=================
50+
The Debug Toolbar
51+
=================
52+
53+
The Debug Toolbar provides at-a-glance information about the current page request, including benchmark results,
54+
queries you have ran, request and response data, and more. This can all prove very useful during development
55+
to help you debug and optimize.
56+
57+
.. note:: The Debug Toolbar is still under construction with several planned features not yet implemented.
58+
59+
60+
Enabling the Toolbar
61+
====================
62+
63+
The toolbar is enabled by default in any environment _except_ production. You can turn change the environments
64+
that the toolbar is active on by editing **application/Config/App.php**::
65+
66+
public $toolbarEnabled = (ENVIRONMENT != 'production' && CI_DEBUG);
67+
68+
Choosing What to Show
69+
---------------------
70+
71+
CodeIgniter ships with several Collectors that, as the name implies, collect data to display on the toolbar. You
72+
can easily make your own to customize the toolbar. To determine which collectors are shown, again head over to
73+
the App configuration file::
74+
75+
public $toolbarCollectors = [
76+
'CodeIgniter\Debug\Toolbar\Collectors\Timers',
77+
'CodeIgniter\Debug\Toolbar\Collectors\Database',
78+
'CodeIgniter\Debug\Toolbar\Collectors\Logs',
79+
'CodeIgniter\Debug\Toolbar\Collectors\Views',
80+
'CodeIgniter\Debug\Toolbar\Collectors\Cache',
81+
'CodeIgniter\Debug\Toolbar\Collectors\Files',
82+
'CodeIgniter\Debug\Toolbar\Collectors\Routes',
83+
];
84+
85+
Comment out any collectors that you do not want to show. Add custom Collectors here by providing the fully-qualified
86+
class name. The exact collectors that appear here will affect which tabs are shown, as well as what information is
87+
shown on the Timeline.
88+
89+
The Collectors that ship with CodeIgniter are:
90+
91+
* **Timers** collects all of the benchmark data, both by the system and by your application.
92+
* **Database** Displays a list of queries that all database connections have performed, and their execution time.
93+
* **Logs** Any information that was logged will be displayed here. In long-running systems, or systems with many items being logged, this can cause memory issues and should be disabled.
94+
* **Views** Displays render time for views on the timeline, and shows any data passed to the views on a separate tab.
95+
* **Cache** Will display information about cache hits and misses, and execution times.
96+
* **Files** displays a list of all files that have been loaded during this request.
97+
* **Routes** displays information about the current route and all routes defined in the system.
98+
99+
Setting Benchmark Points
100+
========================
101+
102+
In order for the Profiler to compile and display your benchmark data you must name your mark points using specific syntax.
103+
104+
Please read the information on setting Benchmark points in the :doc:`Benchmark Library </libraries/benchmark>` page.
105+
106+
Creating Custom Collectors
107+
==========================
108+
109+
Creating custom collectors is a straightforward task. You create a new class, fully-namespaced so that the autoloader
110+
can locate it, that extends ``CodeIgniter\Debug\Toolbar\Collectors\BaseCollector``. This provides a number of methods
111+
that you can override, and has four required class properties that you must correctly set depending on how you want
112+
the Collector to work
113+
::
114+
115+
<?php namespace MyNamespace;
116+
117+
use CodeIgniter\Debug\Toolbar\Collectors\BaseCollector;
118+
119+
class MyCollector extends BaseCollector
120+
{
121+
protected $hasTimeline = false;
122+
123+
protected $hasTabContent = false;
124+
125+
protected $hasVarData = false;
126+
127+
protected $title = '';
128+
}
129+
130+
**$hasTimeline** should be set to ``true`` for any Collector that wants to display information in the toolbar's
131+
timeline. If this is true, you will need to implement the ``formatTimelineData()`` method to format and return the
132+
data for display.
133+
134+
**$hasTabContent** should be ``true`` if the Collector wants to display its own tab with custom content. If this
135+
is true, you will need to provide a ``$title``, implement the ``display()`` method to render out tab's contents,
136+
and might need to implement the ``getTitleDetails()`` method if you want to display additional information just
137+
to the right of the tab content's title.
138+
139+
**$hasVarData** should be ``true`` if this Collector wants to add additional data to the ``Vars`` tab. If this
140+
is true, you will need to implement the ``getVarData()`` method.
141+
142+
**$title** is displayed on open tabs.
143+
144+
145+
Displaying a Toolbar Tab
146+
------------------------
147+
148+
To display a toolbar tab you must:
149+
150+
1. Fill in ``$title`` with the text displayed as both the toolbar title and the tab header.
151+
2. Set ``$hasTabContent`` to ``true``.
152+
3. Implement the ``display()`` method.
153+
4. Optionally, implement the ``getTitleDetails()`` method.
154+
155+
The ``display()`` creates the HTML that is displayed within the tab itself. It does not need to worry about
156+
the title of the tab, as that is automatically handled by the toolbar. It should return a string of HTML.
157+
158+
The ``getTitleDetails()`` method should return a string that is displayed just to the right of the tab's title.
159+
it can be used to provide additional overview information. For example, the Database tab displays the total
160+
number of queries across all connections, while the Files tab displays the total number of files.
161+
162+
Providing Timeline Data
163+
-----------------------
164+
165+
To provide information to be displayed in the Timeline you must:
166+
167+
1. Set ``$hasTimeline`` to ``true``.
168+
2. Implement the ``formatTimelineData()`` method.
169+
170+
The ``formatTimelineData()`` method must return an array of arrays formatted in a way that the timeline can use
171+
it to sort it correctly and display the correct information. The inner arrays must include the following information::
172+
173+
$data[] = [
174+
'name' => '', // Name displayed on the left of the timeline
175+
'component' => '', // Name of the Component listed in the middle of timeline
176+
'start' => 0.00, // start time, like microtime(true)
177+
'duration' => 0.00 // duration, like mircrotime(true) - microtime(true)
178+
];
179+
180+
Providing Vars
181+
--------------
182+
183+
To add data to the Vars tab you must:
184+
185+
1. Set ``$hasVarData`` to ``true``
186+
2. Implement ``getVarData()`` method.
187+
188+
The ``getVarData()`` method should return an array containing arrays of key/value pairs to display. The name of the
189+
outer array's key is the name of the section on the Vars tab.::
190+
191+
$data = [
192+
'section 1' => [
193+
'foo' => 'bar,
194+
'bar' => 'baz'
195+
],
196+
'section 2' => [
197+
'foo' => 'bar,
198+
'bar' => 'baz'
199+
]
200+
];

‎user_guide_src/source/general/index.rst‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,6 @@ General Topics
1717
logging
1818
errors
1919
debugging
20-
profiling
2120
cli
2221
managing_apps
2322
environments

‎user_guide_src/source/general/profiling.rst‎

Lines changed: 0 additions & 157 deletions
This file was deleted.

0 commit comments

Comments
 (0)