Recommend this page to a friend! |
Classes of Dimitri Sitchet | dFramework | system/dependencies/tracy/tracy/readme.md | Download |
|
![]() Tracy - PHP debuggerIntroductionTracy library is a useful helper for everyday PHP programmers. It helps you to:
PHP is a perfect language for making hardly detectable errors because it gives great flexibility to programmers. Tracy\Debugger is more valuable because of that. It is an ultimate tool among the diagnostic ones. If you are meeting Tracy for the first time, believe me, your life starts to be divided into one before the Tracy and the one with her. Welcome to the good part! Documentation can be found on the website. If you like Tracy, please make a donation now. Thank you! Installation and requirementsThe recommended way to is via Composer:
Alternatively, you can download the whole package or tracy.phar file. | Tracy | compatible with PHP | compatible with browsers |-----------|---------------|---------- | Tracy 2.7 | PHP 7.1 ? 7.4 | Chrome 49+, Firefox 45+, MS Edge 14+, Safari 10+ and iOS Safari 10.2+ | Tracy 2.6 | PHP 7.1 ? 7.4 | Chrome 49+, Firefox 45+, MS Edge 14+, Safari 10+ and iOS Safari 10.2+ | Tracy 2.5 | PHP 5.4 ? 7.3 | Chrome 49+, Firefox 45+, MS Edge 12+, Safari 10+ and iOS Safari 10.2+ | Tracy 2.4 | PHP 5.4 ? 7.2 | Chrome 29+, Firefox 28+, IE 11+ (except AJAX), MS Edge 12+, Safari 9+ and iOS Safari 9.2+ UsageActivating Tracy is easy. Simply add these two lines of code, preferably just after library loading (like
The first thing you will notice on the website is a Debugger Bar. (If you do not see anything, it means that Tracy is running in production mode. For security reasons, Tracy is visible only on localhost.
You may force Tracy to run in development mode by passing the The Debugger BarThe 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 to the Debugger Bar. You can find interesting ones in addons or you can create your own. If you do not want to show Debugger Bar, set:
Visualization of errors and exceptionsSurely, you know how PHP reports errors: there is something like this in the page source code:
or uncaught exception:
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: 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. And you know what? Fatal errors are captured and displayed in the same way. No need to install any extension (click for live example): 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: Or they may be displayed like errors:
In order to detect misspellings when assigning to an object, we use trait Nette\SmartObject. Content Security PolicyIf your site uses Content Security Policy, you'll need to add Configuration example for Nette Framework:
Faster loadingThe basic integration is straightforward, however if you have slow blocking scripts in web page, they can slow the Tracy loading.
The solution is to place
AJAX and redirected requestsTracy is able to show Debug bar and Bluescreens for AJAX and redirected requests. You just have to start session before Tracy:
In case you use non-standard session handler, you can start Tracy immediately (in order to handle any errors), then initialize your session handler
and then inform Tracy that session is ready to use via
Opening files in the editorWhen the error page is displayed, you can click on file names and they will open in your editor with the cursor on the corresponding line. Files can also be created (action Production mode and error loggingAs 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: Production output mode suppresses all debugging information which is sent out via The output mode is set by the first parameter of If it is not specified, the default value 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. If you need to log your own messages or caught exceptions, use the method
A directory for errors logging can be set by the second parameter of the enable() method:
If you want Tracy to log PHP errors like
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:
If you use the Nette Framework, you can set this and others in the configuration file. To protect your e-mail box from flood, Tracy sends only one message and creates a file Variable dumpingEvery debugging developer is a good friend with the function
generates the output: You can also change the nesting depth by
The
Very handy alternative to
TimingAnother useful tool is the debugger stopwatch with a precision of microseconds:
Multiple measurements at once can be achieved by an optional parameter.
FireLoggerYou 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. How to do it?
Navigate to the demo page and you will see messages sent from PHP. 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.
The result looks like this: Custom LoggerWe can create a custom logger to log errors, uncatched exceptions, and also be called by
And then we activate it:
If we use the full Nette Framework, we can set it in the NEON configuration file:
PortsThis is a list of unofficial ports to other frameworks and CMS:
... feel free to be famous, create a port for your favourite platform! |