You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Tracy library is a useful PHP everyday programmer's helper. It helps you to:
10
+
Tracy library is a useful helper for everyday PHP programmers. It helps you to:
11
11
12
12
- quickly detect and correct errors
13
13
- log errors
14
14
- dump variables
15
-
- measure the time
15
+
- measure execution time of scripts/queries
16
+
- see memory consumption
16
17
17
18
18
19
PHP is a perfect language for making hardly detectable errors because it gives a great flexibility to programmers. Tracy\Debugger is more valuable because of that. It is a ultimate tool among the diagnostic ones.
19
20
If you are meeting Tracy the first time, believe me, your life starts to be divided one before the Tracy and the one with her.
20
21
Welcome to the good part!
21
22
23
+
24
+
Installation and requirements
25
+
-----------------------------
26
+
22
27
The best way how to install Tracy is to [download a latest package](https://github.com/nette/tracy/releases) or use a Composer:
23
28
24
29
```
25
30
php composer.phar require tracy/tracy
26
31
```
27
32
28
-
It is easy to activate Tracy. Preferably immediately after library loading (using `require 'src/tracy.php'` or via Composer) add code:
33
+
Tracy requires PHP version 5.3.0 or newer (master requires PHP 5.6).
34
+
35
+
36
+
Usage
37
+
-----
38
+
39
+
Activating Tracy is easy. Simply add these two lines of code, preferably just after library loading (using `require 'src/tracy.php'` or via Composer):
29
40
30
41
```php
31
42
use Tracy\Debugger;
32
43
33
44
Debugger::enable();
34
45
```
35
46
36
-
The first thing you notice on the web site is a Debugger Bar.
47
+
The first thing you will notice on the website is a Debugger Bar.
37
48
38
49
39
50
Debugger Bar
40
51
------------
41
52
42
-
The Debugger Bar is a floating panel. It is displayed in the bottom right corner of a page. You can move it by the mouse. It will remember its position after the page reloading.
53
+
The Debugger Bar is a floating panel. It is displayed in the bottom right corner of a page. You can move it using the mouse. It will remember its position after the page reloading.
You can add other useful panels into the Debugger Bar.
57
+
You can add other useful panels into the Debugger Bar. You can find interesing ones in [Addons](https://addons.nette.org) or you can create your own.
47
58
48
59
49
60
Visualization of errors and exceptions
@@ -52,38 +63,35 @@ Visualization of errors and exceptions
52
63
Surely, you know how PHP reports errors: there is something like this in the page source code:
53
64
54
65
```pre
55
-
<b>Parse error</b>: syntax error, unexpected T_STRING in <b>SignPresenter.php</b> on line <b>6</b>
66
+
<b>Parse error</b>: syntax error, unexpected '}' in <b>HomepagePresenter.php</b> on line <b>15</b>
56
67
```
57
68
58
69
or uncaught exception:
59
70
60
71
```pre
61
-
<b>Fatal error</b>: Uncaught exception 'Nette\Security\AuthenticationException' with message 'The password is incorrect.' in W:\examples\CD-collection\app\model\Authenticator.php:38
72
+
<b>Fatal error</b>: Uncaught Nette\MemberAccessException: Call to undefined method Nette\Application\UI\Form::addTest()? in /sandbox/vendor/nette/utils/src/Utils/ObjectMixin.php:100
#8 W:\Nette\Application\UI\Presenter.php(320): Nette\Application\UI in <b>W:\examples\CD-collection\app\model\Authenticator.php</b> on line <b>38</b><br />
#5 /sandbox/temp/cache/latte/15206b353f351f6bfca2c36cc.php(17): Nette\ComponentModel\Co in <b>/sandbox/vendor/nette/utils/src/Utils/ObjectMixin.php</b> on line <b>100</b><br />
72
80
```
73
81
74
-
It is not so easy to navigate throw this output. If you enable the Tracy, errors or exceptions are displayed completely in a different form:
82
+
It is not so easy to navigate through this output. If you enable Tracy, both errors and exceptions are displayed in a completely different form:
75
83
76
84
[](https://nette.github.io/tracy/tracy-exception.html)
77
85
78
86
The error message literally screams. You can see a part of the source code with the highlighted line where the error occurred. A message clearly explains an error. The entire site is [interactive, try it](https://nette.github.io/tracy/tracy-exception.html).
79
87
80
-
And you know what? A fatal errors are captured and displayed in the same way. No need to install any extension (click for live example):
88
+
And you know what? Fatal errors are captured and displayed in the same way. No need to install any extension (click for live example):
81
89
82
90
[](https://nette.github.io/tracy/tracy-error.html)
83
91
84
-
Errors like a typo in a variable name or an attempt to open a nonexistent file generate reports of E_NOTICE or E_WARNING level. These can be easily overlooked and/or can be completly hidden in a web page graphic layout. Let Tracy to manage them:
92
+
Errors like a typo in a variable name or an attempt to open a nonexistent file generate reports of E_NOTICE or E_WARNING level. These can be easily overlooked and/or can be completely hidden in a web page graphic layout. Let Tracy manage them:
85
93
86
-
94
+
[](https://nette.github.io/tracy/tracy-debug-bar.html)
As you can see, Tracy is quite eloquent. It is appreciated in a development environment, but on a production server it would cause disaster. There cannot be listed any debugging information. Therefore Tracy has an environment autodetection and logging functionality. Instead of showing self, Tracy stores information into log file and shows a server error with user-comprehensible message to visitor:
108
+
As you can see, Tracy is quite eloquent. It is appreciated in a development environment, but on a production server it would cause a disaster. Any debugging information cannot be listed there. Therefore Tracy has an environment autodetection and logging functionality. Instead of showing herself, Tracy stores information into a log file and shows the visitor a user-comprehensible server error message:
An output mode suppresses all debugging information which are sent out via `Debugger::dump()` or `Debugger::fireLog()`, and of course all error messages generated by PHP. So, if you forget `Debugger::dump($obj)` in the source code, you do not have to worry about it on a production server. Nothing will be listed.
112
+
Production output mode suppresses all debugging information which is sent out via `Debugger::dump()` or `Debugger::fireLog()`, and of course all error messages generated by PHP. So, even if you forget `Debugger::dump($obj)` in the source code, you do not have to worry about it on your production server. Nothing will be seen.
105
113
106
-
The output mode is switched by the first parameter of `Debugger::enable()`. You can specify either a constant `Debugger::PRODUCTION` or `Debugger::DEVELOPMENT`.
114
+
The output mode is set by the first parameter of `Debugger::enable()`. You can specify either a constant `Debugger::PRODUCTION` or `Debugger::DEVELOPMENT`.
107
115
108
-
If it is not specified, the default value `Debugger::DETECT` is used. In this case the system detects a server by IP address. The production mode is choosed if an application is accessed via public IP address. A local IP address leads to development mode. It is not necessary to set the mode in most cases. The mode is correctly recognized when you are launching the application on your local server or in production.
116
+
If it is not specified, the default value `Debugger::DETECT` is used. In this case the system detects a server by IP address. The production mode is chosen if an application is accessed via public IP address. A local IP address leads to development mode. It is not necessary to set the mode in most cases. The mode is correctly recognized when you are launching the application on your local server or in production.
109
117
110
-
In the production mode, Tracy automatically capture all errors and exceptions into a text log. Unless you specify otherwise, it will be a set of log/error.log. This error logging is extremely useful. Imagine, that all users of your application are actually betatesters. They are doing cutting-edge work for free when hunting bugs and you would be silly if you threw away their valuable reports to a recycle bin unnoticed.
118
+
In the production mode, Tracy automatically captures all errors and exceptions into a text log. Unless you specify otherwise, it will be stored in log/error.log. This error logging is extremely useful. Imagine, that all users of your application are actually betatesters. They are doing cutting-edge work for free when hunting bugs and you would be silly if you threw away their valuable reports to a recycle bin unnoticed.
111
119
112
-
If you need a own messages logging or you caught an exception, use the method `log()`:
120
+
If you need to log your own messages or caught exceptions, use the method `log()`:
113
121
114
122
```php
115
123
Debugger::log('Unexpected error'); // text message
@@ -119,52 +127,77 @@ try {
119
127
} catch (Exception $e) {
120
128
Debugger::log($e); // log exception
121
129
// or
122
-
Debugger::log($e, Debugger::ERROR) // sends also an email notification
130
+
Debugger::log($e, Debugger::ERROR) // also sends an email notification
123
131
}
124
132
```
125
133
126
-
A directory for errors logging can be set by the second parameter of enable() method:
134
+
A directory for errors logging can be set by the second parameter of the enable() method:
For a real professional is the error log a key source of information and he wants to be noticed about any new error immediately. Tracy helps him. She is capable to send an email on every new error record. The variable $email identify where to send the e-mails:
140
+
If you want Tracy to log PHP errors like `E_NOTICE` or `E_WARNING` with detailed information (HTML report), set `Debugger::$logSeverity`:
141
+
142
+
```php
143
+
Debugger::$logSeverity = E_NOTICE | E_WARNING;
144
+
```
145
+
146
+
For a real professional the error log is a crucial source of information and he or she wants to be notified about any new error immediately. Tracy helps him. She is capable of sending an email for every new error record. The variable $email identifies where to send these e-mails:
133
147
134
148
```php
135
149
Debugger::$email = 'admin@example.com';
136
150
```
137
151
138
-
To protect your e-mail box from flood, Tracy sends **the only one message** and creates a file `email-sent`. When developer receives an e-mail notification, he checks the log, corrects application and deletes the monitoring file. It activates the e-mails sending back.
152
+
To protect your e-mail box from flood, Tracy sends **only one message** and creates a file `email-sent`. When a developer receives the e-mail notification, he checks the log, corrects his application and deletes the `email-sent`monitoring file. This activates the e-mail sending again.
139
153
140
154
141
-
Variables dumping
155
+
Variable dumping
142
156
-----------------
143
157
144
-
Each debugging developer is a good friend with the function `var_dump` which lists a content of a variable in detail. Unfortunately, the output is without HTML formatting and decants dump into a single line of HTML code. Not to mention an context escaping. It is necessary replace the `var_dump` by a handier function. That is just `Debugger::dump()`.
158
+
Every debugging developer is a good friend with the function `var_dump`, which lists all contents of any variable in detail. Unfortunately, its output is without HTML formatting and outputs the dump into a single line of HTML code, not to mention context escaping. It is necessary to replace the `var_dump` by a handier function. That is just what `Debugger::dump()` is.
145
159
146
160
```php
147
161
$arr = array(10, 20.2, TRUE, NULL, 'hello');
148
162
149
-
Debugger::dump($arr);
150
-
// including namespace Tracy\Debugger::dump($arr);
You can also change the nesting depth by `Debugger::$maxDepth` and displayed strings length by `Debugger::$maxLen`. Naturally, lower values accelerates Tracy rendering.
171
+
You can also change the nesting depth by `Debugger::$maxDepth` and displayed strings length by `Debugger::$maxLen`. Naturally, lower values accelerate Tracy rendering.
158
172
159
173
```php
160
174
Debugger::$maxDepth = 2; // default: 3
161
175
Debugger::$maxLen = 50; // default: 150
162
176
```
163
177
178
+
The `dump()` function can display other useful information. `Tracy\Dumper::LOCATION_SOURCE` adds tooltip with path to the file, where the function was called. `Tracy\Dumper::LOCATION_LINK` adds a link to the file. `Tracy\Dumper::LOCATION_CLASS` adds a tooltip to every dumped object containing path to the file, in which the object's class is defined. All these constants can be set in `Debugger::$showLocation` variable before calling the `dump()`. You can set multiple values at once using the `|` operator.
179
+
180
+
```php
181
+
Debugger::$showLocation = Tracy\Dumper::LOCATION_SOURCE; // Shows path to where the dump() was called
182
+
Debugger::$showLocation = Tracy\Dumper::LOCATION_CLASS | Tracy\Dumper::LOCATION_LINK; // Shows both paths to the classes and link to where the dump() was called
183
+
Debugger::$showLocation = FALSE; // Hides additional location information
184
+
Debugger::$showLocation = TRUE; // Shows all additional location information
185
+
```
186
+
187
+
Very handy alternative to `Debugger::dump()` is `Debugger::barDump()`. This allows us to dump variables in Debugger Bar. This is useful, because dumps don't mess up the output and we can also add a title to the dump.
188
+
189
+
```php
190
+
Debugger::barDump([2, 4, 6, 8], 'even numbers up to ten');
191
+
Debugger::barDump([1, 3, 5, 7, 9], 'odd numbers up to ten');
echo Debugger::timer(); // elapsed time in seconds
198
231
```
199
232
200
233
201
-
Firebug and FireLogger
202
-
----------------------
234
+
FireLogger
235
+
----------
203
236
204
-
You cannot send debugging information to the browser window always. This applies to Ajax requests, or generating XML files to output. In such cases, you can send the messages by a separate channel into Firebug. Error, Notice and Warning levels are sent to Firebug window automatically. It is also possible to log suppressed exceptions in running application when attention to them is important.
237
+
You cannot always send debugging information to the browser window. This applies to AJAX requests, or generating XML files to output. In such cases, you can send the messages by a separate channel into FireLogger. Error, Notice and Warning levels are sent to FireLogger window automatically. It is also possible to log suppressed exceptions in running application when attention to them is important.
- restart browser, turn on Firebug (key F12) and enable network (Net) and Logger panels
241
+
Firefox:
242
+
- install extension [Firebug](http://getfirebug.com/) and [FireLogger](https://addons.mozilla.org/cs/firefox/addon/firelogger/)
243
+
- turn on Firebug (using F12 key), enable tabs Net and Logger (stay on Logger)
244
+
245
+
Chrome:
246
+
- install extension [FireLogger for Chrome](https://chrome.google.com/webstore/detail/firelogger-for-chrome/hmagilfopmdjkeomnjpchokglfdfjfeh)
247
+
- turn on Chrome DevTools (using Ctrl-Shift-I key) and open Console
212
248
213
-
... Open our utility panel and click on the Console. Ha!, error message has been moved there.
249
+
Navigate to [demo page](https://examples.nette.org/tracy/)and you will see messages sent from PHP.
214
250
215
-
Because the Tracy\Debugger communicates with Firebug via an HTTP headers, you must call the logging function before the PHP script sends anything to the output. It is also possible to enable the output buffering and delay the output.
251
+
Because Tracy\Debugger communicates with FireLogger via HTTP headers, you must call the logging function before the PHP script sends anything to output. It is also possible to enable output buffering and delay the output.
216
252
217
253
```php
218
254
use Tracy\Debugger;
219
255
220
-
Debugger::fireLog('Hello World'); // render string into Firebug console
256
+
Debugger::fireLog('Hello World'); // send string into FireLogger console
221
257
222
258
Debugger::fireLog($_SERVER); // or even arrays and objects
223
259
@@ -226,4 +262,4 @@ Debugger::fireLog(new Exception('Test Exception')); // or exceptions
0 commit comments