mirror of
https://github.com/maximebf/php-debugbar.git
synced 2025-06-11 16:41:01 +02:00
1120 lines
51 KiB
HTML
1120 lines
51 KiB
HTML
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
|
<title>PHP Debug Bar</title>
|
|
<link rel="canonical" href="https://php-debugbar.com/docs/" />
|
|
|
|
<link type="text/css" rel="stylesheet" href="/docs/assets/css/reset.css">
|
|
<link type="text/css" rel="stylesheet" href="http://yandex.st/highlightjs/6.1/styles/sunburst.min.css">
|
|
<link type="text/css" rel="stylesheet" href="/docs/assets/css/docs.css">
|
|
<link type="text/css" rel="stylesheet" href="/docs/assets/css/print.css" media="print">
|
|
<link type="text/css" rel="stylesheet" href="style.css">
|
|
|
|
<script type="text/javascript" src="/docs/assets/js/jquery-1.10.1.min.js"></script>
|
|
<script type="text/javascript" src="http://yandex.st/highlightjs/6.1/highlight.min.js"></script>
|
|
<script type="text/javascript" src="/docs/assets/js/lunr.min.js"></script>
|
|
|
|
|
|
|
|
<script type="text/javascript">var BASE_URL = "/docs/";</script>
|
|
<script type="text/javascript" src="/docs/assets/js/viewer.js"></script>
|
|
|
|
|
|
</head>
|
|
<body>
|
|
<div id="page">
|
|
<a name="top" />
|
|
<header id="header">
|
|
<h1><a href="/docs/">PHP Debug Bar</a></h1>
|
|
</header>
|
|
|
|
|
|
<div id="sidebar">
|
|
<form action="/docs/search.html"><input id="search" type="text" placeholder="Search" name="q" /></form>
|
|
<nav id="toc">
|
|
|
|
<ol>
|
|
|
|
<li>
|
|
<a href="/docs/readme.html#php-debug-bar">PHP Debug Bar</a>
|
|
|
|
|
|
<ol>
|
|
|
|
<li>
|
|
<a href="/docs/readme.html#installation">Installation</a>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/readme.html#quick-start">Quick start</a>
|
|
|
|
</li>
|
|
|
|
</ol>
|
|
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/data-collectors.html#collecting-data">Collecting Data</a>
|
|
|
|
|
|
<ol>
|
|
|
|
<li>
|
|
<a href="/docs/data-collectors.html#using-collectors">Using collectors</a>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/data-collectors.html#creating-collectors">Creating collectors</a>
|
|
|
|
</li>
|
|
|
|
</ol>
|
|
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/rendering.html#rendering">Rendering</a>
|
|
|
|
|
|
<ol>
|
|
|
|
<li>
|
|
<a href="/docs/rendering.html#assets">Assets</a>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/rendering.html#managing-jquery-conflicts">Managing jQuery conflicts</a>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/rendering.html#the-javascript-object">The javascript object</a>
|
|
|
|
</li>
|
|
|
|
</ol>
|
|
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/ajax-and-stack.html#ajax-and-stacked-data">AJAX and Stacked data</a>
|
|
|
|
|
|
<ol>
|
|
|
|
<li>
|
|
<a href="/docs/ajax-and-stack.html#ajax">AJAX</a>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/ajax-and-stack.html#stacked-data">Stacked data</a>
|
|
|
|
</li>
|
|
|
|
</ol>
|
|
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/base-collectors.html#base-collectors">Base collectors</a>
|
|
|
|
|
|
<ol>
|
|
|
|
<li>
|
|
<a href="/docs/base-collectors.html#messages">Messages</a>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/base-collectors.html#timedata">TimeData</a>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/base-collectors.html#exceptions">Exceptions</a>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/base-collectors.html#pdo">PDO</a>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/base-collectors.html#requestdata">RequestData</a>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/base-collectors.html#config">Config</a>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/base-collectors.html#aggregatedcollector">AggregatedCollector</a>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/base-collectors.html#others">Others</a>
|
|
|
|
</li>
|
|
|
|
</ol>
|
|
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/bridge-collectors.html#bridge-collectors">Bridge collectors</a>
|
|
|
|
|
|
<ol>
|
|
|
|
<li>
|
|
<a href="/docs/bridge-collectors.html#cachecache">CacheCache</a>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/bridge-collectors.html#doctrine">Doctrine</a>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/bridge-collectors.html#monolog">Monolog</a>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/bridge-collectors.html#propel">Propel</a>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/bridge-collectors.html#slim">Slim</a>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/bridge-collectors.html#swift-mailer">Swift Mailer</a>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/bridge-collectors.html#twig">Twig</a>
|
|
|
|
</li>
|
|
|
|
</ol>
|
|
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/data-formatter.html#data-formatter">Data Formatter</a>
|
|
|
|
|
|
<ol>
|
|
|
|
</ol>
|
|
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/storage.html#storage">Storage</a>
|
|
|
|
|
|
<ol>
|
|
|
|
<li>
|
|
<a href="/docs/storage.html#available-storage">Available storage</a>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/storage.html#creating-your-own-storage">Creating your own storage</a>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/storage.html#request-id-generator">Request ID generator</a>
|
|
|
|
</li>
|
|
|
|
</ol>
|
|
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/openhandler.html#open-handler">Open handler</a>
|
|
|
|
|
|
<ol>
|
|
|
|
</ol>
|
|
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/http-drivers.html#http-drivers">HTTP drivers</a>
|
|
|
|
|
|
<ol>
|
|
|
|
</ol>
|
|
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/javascript-bar.html#javascript-bar">Javascript Bar</a>
|
|
|
|
|
|
<ol>
|
|
|
|
<li>
|
|
<a href="/docs/javascript-bar.html#tabs-and-indicators">Tabs and indicators</a>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/javascript-bar.html#data-mapping">Data mapping</a>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/javascript-bar.html#datasets">Datasets</a>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/javascript-bar.html#widgets">Widgets</a>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/javascript-bar.html#custom-tabs-and-indicators">Custom tabs and indicators</a>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
<a href="/docs/javascript-bar.html#openhandler">OpenHandler</a>
|
|
|
|
</li>
|
|
|
|
</ol>
|
|
|
|
|
|
</li>
|
|
|
|
</ol>
|
|
|
|
</nav>
|
|
|
|
<nav id="links">
|
|
<ul>
|
|
|
|
</ul>
|
|
</nav>
|
|
|
|
</div>
|
|
|
|
<div id="content">
|
|
<a name="php-debug-bar"></a><h1>PHP Debug Bar</h1>
|
|
<p><a href="https://packagist.org/packages/maximebf/debugbar"><img src="https://poser.pugx.org/maximebf/debugbar/v/stable.png" alt="Latest Stable Version"></a> <a href="https://travis-ci.org/maximebf/php-debugbar"><img src="https://travis-ci.org/maximebf/php-debugbar.png?branch=master" alt="Build Status"></a></p>
|
|
<p>Displays a debug bar in the browser with information from php.
|
|
No more <code>var_dump()</code> in your code!</p>
|
|
<p><img src="https://raw.github.com/maximebf/php-debugbar/master/docs/screenshot.png" alt="Screenshot"></p>
|
|
<p><strong>Features:</strong></p>
|
|
<ul>
|
|
<li>Generic debug bar</li>
|
|
<li>Easy to integrate with any project</li>
|
|
<li>Clean, fast and easy to use interface</li>
|
|
<li>Handles AJAX request</li>
|
|
<li>Includes generic data collectors and collectors for well known libraries</li>
|
|
<li>The client side bar is 100% coded in javascript</li>
|
|
<li>Easily create your own collectors and their associated view in the bar</li>
|
|
<li>Save and re-open previous requests</li>
|
|
<li><a href="http://phpdebugbar.com/docs">Very well documented</a></li>
|
|
</ul>
|
|
<p>Includes collectors for:</p>
|
|
<ul>
|
|
<li><a href="http://php.net/manual/en/book.pdo.php">PDO</a></li>
|
|
<li><a href="http://maximebf.github.io/CacheCache/">CacheCache</a></li>
|
|
<li><a href="http://doctrine-project.org">Doctrine</a></li>
|
|
<li><a href="https://github.com/Seldaek/monolog">Monolog</a></li>
|
|
<li><a href="http://propelorm.org/">Propel</a></li>
|
|
<li><a href="http://slimframework.com">Slim</a></li>
|
|
<li><a href="http://swiftmailer.org/">Swift Mailer</a></li>
|
|
<li><a href="http://twig.sensiolabs.org/">Twig</a></li>
|
|
</ul>
|
|
<p>Checkout the <a href="https://github.com/maximebf/php-debugbar/tree/master/demo">demo</a> for
|
|
examples and <a href="http://phpdebugbar.com">phpdebugbar.com</a> for a live example.</p>
|
|
<p>Integrations with other frameworks:</p>
|
|
<ul>
|
|
<li><a href="https://github.com/barryvdh/laravel-debugbar">Laravel</a></li>
|
|
<li><a href="http://atomikframework.com/docs/error-log-debug.html#debug-bar">Atomik</a></li>
|
|
<li><a href="http://xoops.org/modules/news/article.php?storyid=6538">XOOPS</a></li>
|
|
<li><a href="https://github.com/snapshotpl/ZfSnapPhpDebugBar">Zend Framework 2</a></li>
|
|
</ul>
|
|
<p><em>(drop me a message or submit a PR to add your DebugBar related project here)</em></p>
|
|
<a name="installation"></a><h2>Installation</h2>
|
|
<p>The best way to install DebugBar is using <a href="http://getcomposer.org">Composer</a>
|
|
with the following requirement:</p>
|
|
<pre><code class="lang-JSON">{
|
|
"require": {
|
|
"maximebf/debugbar": ">=1.0.0"
|
|
}
|
|
}</code></pre>
|
|
<p>If you are cloning the repository, you'll need to run <code>composer install</code>.</p>
|
|
<a name="quick-start"></a><h2>Quick start</h2>
|
|
<p>DebugBar is very easy to use and you can add it to any of your projects in no time.
|
|
The easiest way is using the <code>render()</code> functions</p>
|
|
<pre><code class="lang-PHP"><?php
|
|
use DebugBar\StandardDebugBar;
|
|
|
|
$debugbar = new StandardDebugBar();
|
|
$debugbarRenderer = $debugbar->getJavascriptRenderer();
|
|
|
|
$debugbar["messages"]->addMessage("hello world!");
|
|
?>
|
|
<html>
|
|
<head>
|
|
<?php echo $debugbarRenderer->renderHead() ?>
|
|
</head>
|
|
<body>
|
|
...
|
|
<?php echo $debugbarRenderer->render() ?>
|
|
</body>
|
|
</html></code></pre>
|
|
<p>The DebugBar uses DataCollectors to collect data from your PHP code. Some of them are
|
|
automated but others are manual. Use the <code>DebugBar</code> like an array where keys are the
|
|
collector names. In our previous example, we add a message to the <code>MessagesCollector</code>:</p>
|
|
<pre><code class="lang-PHP">$debugbar["messages"]->addMessage("hello world!");</code></pre>
|
|
<p><code>StandardDebugBar</code> activates the following collectors:</p>
|
|
<ul>
|
|
<li><code>MemoryCollector</code> (<em>memory</em>)</li>
|
|
<li><code>MessagesCollector</code> (<em>messages</em>)</li>
|
|
<li><code>PhpInfoCollector</code> (<em>php</em>)</li>
|
|
<li><code>RequestDataCollector</code> (<em>request</em>)</li>
|
|
<li><code>TimeDataCollector</code> (<em>time</em>)</li>
|
|
<li><code>ExceptionsCollector</code> (<em>exceptions</em>)</li>
|
|
</ul>
|
|
<p>Learn more about DebugBar in the <a href="http://phpdebugbar.com/docs">docs</a>.</p>
|
|
|
|
<a name="php-debug-bar"></a><h1>PHP Debug Bar</h1>
|
|
<p><a href="https://packagist.org/packages/maximebf/debugbar"><img src="https://poser.pugx.org/maximebf/debugbar/v/stable.png" alt="Latest Stable Version"></a> <a href="https://travis-ci.org/maximebf/php-debugbar"><img src="https://travis-ci.org/maximebf/php-debugbar.png?branch=master" alt="Build Status"></a></p>
|
|
<p>Displays a debug bar in the browser with information from php.
|
|
No more <code>var_dump()</code> in your code!</p>
|
|
<p><img src="https://raw.github.com/maximebf/php-debugbar/master/docs/screenshot.png" alt="Screenshot"></p>
|
|
<p><strong>Features:</strong></p>
|
|
<ul>
|
|
<li>Generic debug bar</li>
|
|
<li>Easy to integrate with any project</li>
|
|
<li>Clean, fast and easy to use interface</li>
|
|
<li>Handles AJAX request</li>
|
|
<li>Includes generic data collectors and collectors for well known libraries</li>
|
|
<li>The client side bar is 100% coded in javascript</li>
|
|
<li>Easily create your own collectors and their associated view in the bar</li>
|
|
<li>Save and re-open previous requests</li>
|
|
<li><a href="http://phpdebugbar.com/docs">Very well documented</a></li>
|
|
</ul>
|
|
<p>Includes collectors for:</p>
|
|
<ul>
|
|
<li><a href="http://php.net/manual/en/book.pdo.php">PDO</a></li>
|
|
<li><a href="http://maximebf.github.io/CacheCache/">CacheCache</a></li>
|
|
<li><a href="http://doctrine-project.org">Doctrine</a></li>
|
|
<li><a href="https://github.com/Seldaek/monolog">Monolog</a></li>
|
|
<li><a href="http://propelorm.org/">Propel</a></li>
|
|
<li><a href="http://slimframework.com">Slim</a></li>
|
|
<li><a href="http://swiftmailer.org/">Swift Mailer</a></li>
|
|
<li><a href="http://twig.sensiolabs.org/">Twig</a></li>
|
|
</ul>
|
|
<p>Checkout the <a href="https://github.com/maximebf/php-debugbar/tree/master/demo">demo</a> for
|
|
examples and <a href="http://phpdebugbar.com">phpdebugbar.com</a> for a live example.</p>
|
|
<p>Integrations with other frameworks:</p>
|
|
<ul>
|
|
<li><a href="https://github.com/barryvdh/laravel-debugbar">Laravel</a></li>
|
|
<li><a href="http://atomikframework.com/docs/error-log-debug.html#debug-bar">Atomik</a></li>
|
|
<li><a href="http://xoops.org/modules/news/article.php?storyid=6538">XOOPS</a></li>
|
|
<li><a href="https://github.com/snapshotpl/ZfSnapPhpDebugBar">Zend Framework 2</a></li>
|
|
</ul>
|
|
<p><em>(drop me a message or submit a PR to add your DebugBar related project here)</em></p>
|
|
<a name="installation"></a><h2>Installation</h2>
|
|
<p>The best way to install DebugBar is using <a href="http://getcomposer.org">Composer</a>
|
|
with the following requirement:</p>
|
|
<pre><code class="lang-JSON">{
|
|
"require": {
|
|
"maximebf/debugbar": ">=1.0.0"
|
|
}
|
|
}</code></pre>
|
|
<p>If you are cloning the repository, you'll need to run <code>composer install</code>.</p>
|
|
<a name="quick-start"></a><h2>Quick start</h2>
|
|
<p>DebugBar is very easy to use and you can add it to any of your projects in no time.
|
|
The easiest way is using the <code>render()</code> functions</p>
|
|
<pre><code class="lang-PHP"><?php
|
|
use DebugBar\StandardDebugBar;
|
|
|
|
$debugbar = new StandardDebugBar();
|
|
$debugbarRenderer = $debugbar->getJavascriptRenderer();
|
|
|
|
$debugbar["messages"]->addMessage("hello world!");
|
|
?>
|
|
<html>
|
|
<head>
|
|
<?php echo $debugbarRenderer->renderHead() ?>
|
|
</head>
|
|
<body>
|
|
...
|
|
<?php echo $debugbarRenderer->render() ?>
|
|
</body>
|
|
</html></code></pre>
|
|
<p>The DebugBar uses DataCollectors to collect data from your PHP code. Some of them are
|
|
automated but others are manual. Use the <code>DebugBar</code> like an array where keys are the
|
|
collector names. In our previous example, we add a message to the <code>MessagesCollector</code>:</p>
|
|
<pre><code class="lang-PHP">$debugbar["messages"]->addMessage("hello world!");</code></pre>
|
|
<p><code>StandardDebugBar</code> activates the following collectors:</p>
|
|
<ul>
|
|
<li><code>MemoryCollector</code> (<em>memory</em>)</li>
|
|
<li><code>MessagesCollector</code> (<em>messages</em>)</li>
|
|
<li><code>PhpInfoCollector</code> (<em>php</em>)</li>
|
|
<li><code>RequestDataCollector</code> (<em>request</em>)</li>
|
|
<li><code>TimeDataCollector</code> (<em>time</em>)</li>
|
|
<li><code>ExceptionsCollector</code> (<em>exceptions</em>)</li>
|
|
</ul>
|
|
<p>Learn more about DebugBar in the <a href="http://phpdebugbar.com/docs">docs</a>.</p>
|
|
|
|
<a name="collecting-data"></a><h1>Collecting Data</h1>
|
|
<a name="using-collectors"></a><h2>Using collectors</h2>
|
|
<p>Collectors can be added to your debug bar using <code>addCollector()</code>.</p>
|
|
<pre><code>$debugbar = new DebugBar();
|
|
$debugbar->addCollector(new DataCollector\RequestDataCollector());</code></pre>
|
|
<p>Each collector as a unique name as defined by its <code>getName()</code> method. You can
|
|
access collectors using <code>getCollector($name)</code>.</p>
|
|
<pre><code>$debugbar->addCollector(new DataCollector\MessagesCollector());
|
|
$debugbar->getCollector('messages')->addMessage("foobar");
|
|
// or:
|
|
$debugbar['messages']->addMessage("foobar");</code></pre>
|
|
<p>Data will be collected from them when the debug bar is rendered. You can however
|
|
collect the data earlier using <code>collect()</code>.</p>
|
|
<pre><code>$debugbar->collect();</code></pre>
|
|
<a name="creating-collectors"></a><h2>Creating collectors</h2>
|
|
<p>Collectors must implement the <code>DebugBar\DataCollector\DataCollectorInterface</code>. They
|
|
may subclass <code>DebugBar\DataCollector\DataCollector</code> which provides utility methods.</p>
|
|
<p>Collectors must provide a <code>getName()</code> function returning their unique name and a
|
|
<code>collect()</code> function returning some json-encodable data. The latter will be called at the
|
|
same time the <code>DebugBar::collect()</code> method is called.</p>
|
|
<pre><code>class MyDataCollector extends DebugBar\DataCollector\DataCollector
|
|
{
|
|
public function collect()
|
|
{
|
|
return array("uniqid" => uniqid());
|
|
}
|
|
|
|
public function getName()
|
|
{
|
|
return 'mycollector';
|
|
}
|
|
}
|
|
|
|
$debugbar->addCollector(new MyDataCollector());</code></pre>
|
|
<p>This however won't show anything in the debug bar as no information are provided
|
|
on how to display these data. You could do that manually as you'll see in later chapter
|
|
or implement the <code>DebugBar\DataSource\Renderable</code> interface.</p>
|
|
<p>To implement it, you must define a <code>getWidgets()</code> function which returns an array
|
|
of key/value pairs where key are control names and values control options as defined
|
|
in <code>JavascriptRenderer::addControl($name, $options)</code> (see Rendering chapter).</p>
|
|
<pre><code>class MyDataCollector extends DebugBar\DataCollector\DataCollector implements DebugBar\DataCollector\Renderable
|
|
{
|
|
// ...
|
|
|
|
public function getWidgets()
|
|
{
|
|
return array(
|
|
"mycollector" => array(
|
|
"icon" => "cogs",
|
|
"tooltip" => "uniqid()",
|
|
"map" => "uniqid",
|
|
"default" => "''"
|
|
)
|
|
);
|
|
}
|
|
}</code></pre>
|
|
<p>This will have the result of adding a new indicator to the debug bar.</p>
|
|
<p>When implementing the Renderable interface, you may use widgets which are not provided
|
|
with the default install. You can add new assets by implementing the <code>DebugBar\DataCollector\AssetProvider</code> interface.</p>
|
|
<p>to implement it, you must define the <code>getAssets()</code> method. It must return an array with the
|
|
following keys:</p>
|
|
<ul>
|
|
<li>base_path: base path of assets (optional, if omitted or null, will use the base path of the JavascriptRenderer)</li>
|
|
<li>base_url: base url of assets (optional, same as base_path)</li>
|
|
<li>css: an array of css filenames</li>
|
|
<li>js: an array of javascript filenames</li>
|
|
</ul>
|
|
<p>Example:</p>
|
|
<pre><code>class MyDbCollector extends DebugBar\DataCollector\DataCollector implements DebugBar\DataCollector\Renderable, DebugBar\DataCollector\AssetProvider
|
|
{
|
|
// ...
|
|
|
|
public function getWidgets()
|
|
{
|
|
return array(
|
|
"database" => array(
|
|
"icon" => "inbox",
|
|
"widget" => "PhpDebugBar.Widgets.SQLQueriesWidget",
|
|
"map" => "pdo",
|
|
"default" => "[]"
|
|
)
|
|
);
|
|
}
|
|
|
|
public function getAssets()
|
|
{
|
|
return array(
|
|
'css' => 'widgets/sqlqueries/widget.css',
|
|
'js' => 'widgets/sqlqueries/widget.js'
|
|
);
|
|
}
|
|
}</code></pre>
|
|
|
|
<a name="rendering"></a><h1>Rendering</h1>
|
|
<p>Rendering is performed using the `DebugBar\JavascriptRenderer̀ class. It contains
|
|
all the useful functions to included the needed assets and generate a debug bar.</p>
|
|
<pre><code>$renderer = $debugbar->getJavascriptRenderer();</code></pre>
|
|
<a name="assets"></a><h2>Assets</h2>
|
|
<p>The debug bar relies on some css and javascript files which needs to be included
|
|
into your webpage. They are located in the <em>src/DebugBar/Resources</em> folder.
|
|
This can be done in four ways:</p>
|
|
<ul>
|
|
<li>Using <code>JavascriptRenderer::renderHead()</code> which will returns a string with
|
|
the needed script and link tags</li>
|
|
<li>Using <a href="https://github.com/kriswallsmith/assetic">Assetic</a> and
|
|
<code>JavascriptRenderer::getAsseticCollection()</code></li>
|
|
<li>Dumping the assets yourself using <code>JavascriptRenderer::dumpCssAssets()</code> and
|
|
<code>JavascriptRenderer::dumpJsAssets()</code></li>
|
|
<li>Retrieving the list filenames of assets using <code>JavascriptRenderer::getAssets()</code>
|
|
and doing something with it</li>
|
|
</ul>
|
|
<p>I would recommend using the second method as Assetic is a very powerful asset
|
|
manager but the other methods are provided to quickly integrate the debug bar
|
|
into any projects.</p>
|
|
<p>You can define the base url of your assets using <code>setBaseUrl()</code>. This is needed
|
|
in 99% of cases.</p>
|
|
<p>Using <code>renderHead()</code>:</p>
|
|
<pre><code><html>
|
|
<head>
|
|
...
|
|
<?php echo $renderer->renderHead() ?>
|
|
...
|
|
</head>
|
|
...
|
|
</html></code></pre>
|
|
<p>Using Assetic:</p>
|
|
<pre><code>list($cssCollection, $jsCollection) = $renderer->getAsseticCollection();</code></pre>
|
|
<p>Dumping the assets:</p>
|
|
<pre><code>header('Content-Type', 'text/javascript');
|
|
$renderer->dumpJsAssets();</code></pre>
|
|
<p>Retrieving the assets:</p>
|
|
<pre><code>list($cssFiles, $jsFiles) = $renderer->getAssets();</code></pre>
|
|
<p>Note that you can only use the debug bar assets and manage the dependencies by yourself
|
|
using <code>$renderer->setIncludeVendors(false)</code>. Instead of false, <em>css</em> or <em>js</em> may be used
|
|
to only include css or js assets of vendors.</p>
|
|
<a name="managing-jquery-conflicts"></a><h2>Managing jQuery conflicts</h2>
|
|
<p>When the debug bar script is included, it will be bound to the current jQuery object.
|
|
The default action is to call <code>jQuery.noConflict(true)</code> after this is done.</p>
|
|
<p>This has two implications:</p>
|
|
<ul>
|
|
<li>jQuery won't be available anymore if you didn't include your own version
|
|
before including the debug bar's vendors</li>
|
|
<li>your own version will be restored.</li>
|
|
</ul>
|
|
<p>If you use <code>JavascriptRenderer::setIncludeVendors()</code> to disable the inclusion of js
|
|
vendors (ie. jquery), <code>jQuery.noConflict(true)</code> won't be called.</p>
|
|
<p>You can manage whether <code>jQuery.noConflict(true)</code> should be called or not using
|
|
<code>JavascriptRenderer::setEnableJqueryNoConflict()</code>.</p>
|
|
<a name="the-javascript-object"></a><h2>The javascript object</h2>
|
|
<p>The renderer will generate all the needed code for your debug bar. This means
|
|
initializing the DebugBar js object, adding tabs and indicators, defining a data map, etc...</p>
|
|
<p>Data collectors can provide their own controls when implementing the
|
|
<code>DebugBar\DataCollector\Renderable</code> interface as explained in the Collecting Data chapter.</p>
|
|
<p>Thus in almost all cases, you should only have to use <code>render()</code> right away:</p>
|
|
<pre><code><html>
|
|
...
|
|
<body>
|
|
<?php echo $renderer->render() ?>
|
|
</body>
|
|
</html></code></pre>
|
|
<p>This will print the initialization code for the toolbar and the dataset for the request.
|
|
When you are performing AJAX requests, you do not want to initialize a new toolbar but
|
|
add the dataset to the existing one. You can disable initialization using ̀false<code>as
|
|
the first argument of ̀render()</code>.</p>
|
|
<pre><code><p>my ajax content</p>
|
|
<?php echo $renderer->render(false) ?></code></pre>
|
|
<a name="controlling-object-initialization"></a><h3>Controlling object initialization</h3>
|
|
<p>You can further control the initialization of the javascript object using <code>setInitialization()</code>.
|
|
It takes a bitwise value made out of the constants ̀INITIALIZE_CONSTRUCTOR<code>and</code>INITIALIZE_CONTROLS<code>.
|
|
The first one controls whether to initialize the variable (ie.</code>var debugbar = new DebugBar()`). The
|
|
second one whether to initialize all the controls (ie. adding tab and indicators as well as data mapping).</p>
|
|
<p>You can also control the class name of the object using <code>setJavascriptClass()</code> and the name of
|
|
the instance variable using <code>setVariableName()</code>.</p>
|
|
<p>Let's say you have subclassed <code>PhpDebugBar.DebugBar</code> in javascript to do your own initialization.
|
|
Your new object is called <code>MyDebugBar</code>.</p>
|
|
<pre><code>$renderer->setJavascriptClass("MyDebugBar");
|
|
$renderer->setInitialization(JavascriptRenderer::INITIALIZE_CONSTRUCTOR);
|
|
// ...
|
|
echo $renderer->render();</code></pre>
|
|
<p>This has the result of printing:</p>
|
|
<pre><code><script type="text/javascript">
|
|
var phpdebugbar = new MyDebugBar();
|
|
phpdebugbar.addDataSet({ ... });
|
|
</script></code></pre>
|
|
<p>Using <code>setInitialization(0)</code> will only render the addDataSet part.</p>
|
|
<a name="defining-controls"></a><h3>Defining controls</h3>
|
|
<p>Controls can be manually added to the debug bar using <code>addControl($name, $options)</code>. You should read
|
|
the Javascript bar chapter before this section.</p>
|
|
<p><code>$name</code> will be the name of your control and <code>$options</code> is a key/value pair array with these
|
|
possible values:</p>
|
|
<ul>
|
|
<li><em>icon</em>: icon name</li>
|
|
<li><em>tooltip</em>: string</li>
|
|
<li><em>widget</em>: widget class name</li>
|
|
<li><em>map</em>: a property name from the data to map the control to</li>
|
|
<li><em>default</em>: a js string, default value of the data map</li>
|
|
<li><em>tab</em>: class name of the tab object (to use a custom tab object)</li>
|
|
<li><em>indicator</em>: class name of the indicator object (to use a custom indicator object)</li>
|
|
<li><em>position</em>: position of the indicator ('left' of 'right', default to 'right')</li>
|
|
</ul>
|
|
<p>At least <em>icon</em> or <em>widget</em> are needed (unless <em>tab</em> or <em>indicator</em> are specified). If <em>widget</em> is
|
|
specified, a tab will be created, otherwise an indicator. Any other options is also passed to the tab
|
|
or indicator.</p>
|
|
<pre><code>$renderer->addControl('messages', array(
|
|
"widget" => "PhpDebugBar.Widgets.MessagesWidget",
|
|
"map" => "messages",
|
|
"default" => "[]"
|
|
));</code></pre>
|
|
<p>You can disable a control using <code>disableControl($name)</code> and ignore any controls provided by
|
|
a collector using <code>ignoreCollector($name)</code>.</p>
|
|
|
|
<a name="ajax-and-stacked-data"></a><h1>AJAX and Stacked data</h1>
|
|
<a name="ajax"></a><h2>AJAX</h2>
|
|
<p>As mentioned in the previous chapter, if you are performing AJAX requests
|
|
which return HTML content, you can use <code>JavascriptRenderer::render(false)</code>.</p>
|
|
<p>In the case you are sending back non-HTML data (eg: JSON), the DebugBar can
|
|
send data to the client using HTTP headers using the <code>sendDataInHeaders()</code> method
|
|
(no need to use the <code>JavascriptRenderer</code>):</p>
|
|
<pre><code>$debugbar = new DebugBar();
|
|
// ...
|
|
$debugbar->sendDataInHeaders();</code></pre>
|
|
<p>On the client side, an instance of <code>PhpDebugBar.AjaxHandler</code> will
|
|
parse the headers and add the dataset to the debugbar.</p>
|
|
<p>The AjaxHandler automatically binds to jQuery's <em>ajaxComplete</em> event
|
|
so if you are using jQuery, you have nothing to configure.</p>
|
|
<p>If you're not using jQuery, you can call <code>AjaxHandler.handle(xhr)</code>.
|
|
If you are using the <code>JavascriptRenderer</code> initialization, the instance
|
|
of <code>AjaxHandler</code> is stored in the <code>ajaxHandler</code> property of the <code>DebugBar</code> object.</p>
|
|
<pre><code>debugbar.ajaxHandler.handle(xhr);</code></pre>
|
|
<p>If you are sending a lot of data through headers, it may cause problems
|
|
with your browser. Instead you can use a storage handler (see Storage chapter)
|
|
and the open handler (see Open Handler chapter) to load the data after an ajax
|
|
request. Use true as the first argument of <code>sendDataInHeaders()</code>.</p>
|
|
<pre><code>$debugbar = new DebugBar();
|
|
|
|
// define a storage
|
|
$debugbar->setStorage(new DebugBar\Storage\FileStorage('/path/to/storage'));
|
|
|
|
// define the open handler url
|
|
$renderer = $debugbar->getJavascriptRenderer();
|
|
$renderer->setOpenHandlerUrl('open.php');
|
|
|
|
// ...
|
|
|
|
$debugbar->sendDataInHeaders(true);</code></pre>
|
|
<a name="stacked-data"></a><h2>Stacked data</h2>
|
|
<p>Some times you need to collect data about a request but the page won't actually
|
|
be displayed. The best example of that is during a redirect. You can use the
|
|
debug bar storage mechanism to store the data and re-open it later but it can
|
|
be cumbersome while testing a redirect page.</p>
|
|
<p>The solution is to use stacked data. The debug bar can temporarily store the
|
|
collected data in the session until the next time it will be displayed.
|
|
Simply call <code>DebugBar::stackData()</code> instead of rendering the debug bar.</p>
|
|
<p>PHP's session must be started before using this feature.</p>
|
|
<p>Note: The stacked data feature will use the storage mechanism if it's enabled
|
|
instead of storing the data in the session.</p>
|
|
<pre><code>$debugbar = new DebugBar();
|
|
// ...
|
|
$debugbar->stackData();</code></pre>
|
|
<p>Stacked data are rendered each time the debug bar is rendered using the
|
|
<code>JavascriptRenderer</code>.</p>
|
|
|
|
<a name="base-collectors"></a><h1>Base collectors</h1>
|
|
<p>Collectors provided in the <code>DebugBar\DataCollector</code> namespace.</p>
|
|
<a name="messages"></a><h2>Messages</h2>
|
|
<p>Provides a way to log messages (compatible with <a href="https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md">PSR-3 logger</a>).</p>
|
|
<pre><code>$debugbar->addCollector(new DebugBar\DataCollector\MessagesCollector());
|
|
$debugbar['messages']->info('hello world');</code></pre>
|
|
<p>You can have multiple messages collector by naming them:</p>
|
|
<pre><code>$debugbar->addCollector(new MessagesCollector('io_ops'));
|
|
$debugbar['io_ops']->info('opening files');</code></pre>
|
|
<p>You can aggregate messages collector into other to have a unified view:</p>
|
|
<pre><code>$debugbar['messages']->aggregate($debugbar['io_ops']);</code></pre>
|
|
<p>If you don't want to create a standalone tab in the debug bar but still be able
|
|
to log messages from a different collector, you don't have to add the collector
|
|
to the debug bar:</p>
|
|
<pre><code>$debugbar['messages']->aggregate(new MessagesCollector('io_ops'));</code></pre>
|
|
<a name="timedata"></a><h2>TimeData</h2>
|
|
<p>Provides a way to log total execution time as well as taking "measures" (ie. measure the execution time of a particular operation).</p>
|
|
<pre><code>$debugbar->addCollector(new DebugBar\DataCollector\TimeDataCollector());
|
|
|
|
$debugbar['time']->startMeasure('longop', 'My long operation');
|
|
sleep(2);
|
|
$debugbar['time']->stopMeasure('longop');
|
|
|
|
$debugbar['time']->measure('My long operation', function() {
|
|
sleep(2);
|
|
});</code></pre>
|
|
<p>Displays the measures on a timeline</p>
|
|
<a name="exceptions"></a><h2>Exceptions</h2>
|
|
<p>Display exceptions</p>
|
|
<pre><code>$debugbar->addCollector(new DebugBar\DataCollector\ExceptionsCollector());
|
|
|
|
try {
|
|
throw new Exception('foobar');
|
|
} catch (Exception $e) {
|
|
$debugbar['exceptions']->addException($e);
|
|
}</code></pre>
|
|
<a name="pdo"></a><h2>PDO</h2>
|
|
<p>Logs SQL queries. You need to wrap your <code>PDO</code> object into a <code>DebugBar\DataCollector\PDO\TraceablePDO</code> object.</p>
|
|
<pre><code>$pdo = new DebugBar\DataCollector\PDO\TraceablePDO(new PDO('sqlite::memory:'));
|
|
$debugbar->addCollector(new DebugBar\DataCollector\PDO\PDOCollector($pdo));</code></pre>
|
|
<p>You can even log queries from multiple <code>PDO</code> connections:</p>
|
|
<pre><code>$pdoRead = new DebugBar\DataCollector\PDO\TraceablePDO(new PDO('sqlite::memory:'));
|
|
$pdoWrite = new DebugBar\DataCollector\PDO\TraceablePDO(new PDO('sqlite::memory:'));
|
|
|
|
$pdoCollector = new DebugBar\DataCollector\PDO\PDOCollector();
|
|
$pdoCollector->addConnection($pdoRead, 'read-db');
|
|
$pdoCollector->addConnection($pdoWrite, 'write-db');
|
|
|
|
$debugbar->addCollector($pdoCollector);</code></pre>
|
|
<a name="requestdata"></a><h2>RequestData</h2>
|
|
<p>Collects the data of PHP's global variables</p>
|
|
<pre><code>$debugbar->addCollector(new DebugBar\DataCollector\RequestDataCollector());</code></pre>
|
|
<a name="config"></a><h2>Config</h2>
|
|
<p>Used to display any key/value pairs array</p>
|
|
<pre><code>$data = array('foo' => 'bar');
|
|
$debugbar->addCollector(new DebugBar\DataCollector\ConfigCollector($data));</code></pre>
|
|
<p>You can provide a different name for this collector in the second argument of the constructor.</p>
|
|
<a name="aggregatedcollector"></a><h2>AggregatedCollector</h2>
|
|
<p>Aggregates multiple collectors. Do not provide any widgets, you have to add your own controls.</p>
|
|
<pre><code>$debugbar->addCollector(new DebugBar\DataCollector\AggregatedCollector('all_messages', 'messages', 'time'));
|
|
$debugbar['all_messages']->addCollector($debugbar['messages']);
|
|
$debugbar['all_messages']->addCollector(new MessagesCollector('mails'));
|
|
$debugbar['all_messages']['mails']->addMessage('sending mail');
|
|
|
|
$renderer = $debugbar->getJavascriptRenderer();
|
|
$renderer->addControl('all_messages', array(
|
|
'widget' => 'PhpDebugBar.Widgets.MessagesWidget',
|
|
'map' => 'all_messages',
|
|
'default' => '[]';
|
|
));</code></pre>
|
|
<a name="others"></a><h2>Others</h2>
|
|
<p>Misc collectors which you can just register:</p>
|
|
<ul>
|
|
<li><code>MemoryCollector</code> (<em>memory</em>): Display memory usage</li>
|
|
<li><code>PhpInfoCollector</code> (<em>php</em>): PHP version number</li>
|
|
</ul>
|
|
|
|
<a name="bridge-collectors"></a><h1>Bridge collectors</h1>
|
|
<p>DebugBar comes with some "bridge" collectors. This collectors provides a way to integrate
|
|
other projects with the DebugBar.</p>
|
|
<a name="cachecache"></a><h2>CacheCache</h2>
|
|
<p><a href="http://maximebf.github.io/CacheCache/">http://maximebf.github.io/CacheCache/</a></p>
|
|
<p>Displays cache operations using <code>DebugBar\Bridge\CacheCacheCollector</code></p>
|
|
<pre><code>$cache = new CacheCache\Cache(new CacheCache\Backends\Memory());
|
|
$debugbar->addCollector(new DebugBar\Bridge\CacheCacheCollector($cache));</code></pre>
|
|
<p>CacheCache uses <a href="https://github.com/Seldaek/monolog">Monolog</a> for logging,
|
|
thus it is required to collect data.</p>
|
|
<p><code>CacheCacheCollector</code> subclasses <code>MonologCollector</code>, thus it can be
|
|
<a href="base-collectors.html#messages">aggregated in the messages view</a>.</p>
|
|
<a name="doctrine"></a><h2>Doctrine</h2>
|
|
<p><a href="http://doctrine-project.org">http://doctrine-project.org</a></p>
|
|
<p>Displays sql queries into an SQL queries view using <code>DebugBar\Bridge\DoctrineCollector</code>.
|
|
You will need to set a <code>Doctrine\DBAL\Logging\DebugStack</code> logger on your connection.</p>
|
|
<pre><code>$debugStack = new Doctrine\DBAL\Logging\DebugStack();
|
|
$entityManager->getConnection()->getConfiguration()->setSQLLogger($debugStack);
|
|
$debugbar->addCollector(new DebugBar\Bridge\DoctrineCollector($debugStack));</code></pre>
|
|
<p><code>DoctrineCollector</code> also accepts an <code>Doctrine\ORM\EntityManager</code> as argument
|
|
provided the <code>SQLLogger</code> is a ̀DebugStack`.</p>
|
|
<a name="monolog"></a><h2>Monolog</h2>
|
|
<p><a href="https://github.com/Seldaek/monolog">https://github.com/Seldaek/monolog</a></p>
|
|
<p>Integrates Monolog messages into a message view using <code>DebugBar\Bridge\MonologCollector</code>.</p>
|
|
<pre><code>$logger = new Monolog\Logger('mylogger');
|
|
$debugbar->addCollector(new DebugBar\Bridge\MonologCollector($logger));</code></pre>
|
|
<p>Note that multiple logger can be collected:</p>
|
|
<pre><code>$debugbar['monolog']->addLogger($logger);</code></pre>
|
|
<p><code>MonologCollector</code> can be <a href="base-collectors.html#messages">aggregated</a> into the <code>MessagesCollector</code>.</p>
|
|
<a name="propel"></a><h2>Propel</h2>
|
|
<p><a href="http://propelorm.org/">http://propelorm.org/</a></p>
|
|
<p>Displays propel queries into an SQL queries view using <code>DebugBar\Bridge\PropelCollector</code>.
|
|
You will need to activate Propel debug mode.</p>
|
|
<pre><code>// before Propel::init()
|
|
$debugbar->addCollector(new DebugBar\Bridge\PropelCollector());
|
|
|
|
Propel::init('/path/to/config');
|
|
|
|
// after Propel::init()
|
|
// not mandatory if you set config options by yourself
|
|
DebugBar\Bridge\PropelCollector::enablePropelProfiling();</code></pre>
|
|
<p>Queries can be collected on a single connection by providing the <code>PropelPDO</code> object
|
|
to the <code>PropelCollector</code> as first argument.</p>
|
|
<a name="slim"></a><h2>Slim</h2>
|
|
<p><a href="http://slimframework.com">http://slimframework.com</a></p>
|
|
<p>Displays message from the Slim logger into a message view using <code>DebugBar\Bridge\SlimCollector</code>.</p>
|
|
<pre><code>$app = new Slim\Slim();
|
|
$debugbar->addCollector(new DebugBar\Bridge\SlimCollector($app));</code></pre>
|
|
<a name="swift-mailer"></a><h2>Swift Mailer</h2>
|
|
<p><a href="http://swiftmailer.org/">http://swiftmailer.org/</a></p>
|
|
<p>Display log messages and sent mail using <code>DebugBar\Bridge\SwiftMailer\SwiftLogCollector</code> and
|
|
<code>DebugBar\Bridge\SwiftMailer\SwiftMailCollector</code>.</p>
|
|
<pre><code>$mailer = Swift_Mailer::newInstance(Swift_NullTransport::newInstance());
|
|
$debugbar['messages']->aggregate(new DebugBar\Bridge\SwiftMailer\SwiftLogCollector($mailer));
|
|
$debugbar->addCollector(new DebugBar\Bridge\SwiftMailer\SwiftMailCollector($mailer));</code></pre>
|
|
<a name="twig"></a><h2>Twig</h2>
|
|
<p><a href="http://twig.sensiolabs.org/">http://twig.sensiolabs.org/</a></p>
|
|
<p>Collects info about rendered templates using <code>DebugBar\Bridge\Twig\TwigCollector</code>.
|
|
You need to wrap your <code>Twig_Environment</code> object into a <code>DebugBar\Bridge\Twig\TraceableTwigEnvironment</code> object.</p>
|
|
<pre><code>$loader = new Twig_Loader_Filesystem('.');
|
|
$env = new DebugBar\Bridge\Twig\TraceableTwigEnvironment(new Twig_Environment($loader));
|
|
$debugbar->addCollector(new DebugBar\Bridge\Twig\TwigCollector($env));</code></pre>
|
|
<p>You can provide a <code>DebugBar\DataCollector\TimeDataCollector</code> as the second argument of
|
|
<code>TraceableTwigEnvironment</code> so render operation can be measured.</p>
|
|
|
|
<a name="data-formatter"></a><h1>Data Formatter</h1>
|
|
<p>An instance of <code>DebugBar\DataFormatter\DataFormatterInterface</code> is used by collectors to
|
|
format data.</p>
|
|
<p>The default instance is <code>DebugBar\DataFormatter\DataFormatter</code>. This can be modified
|
|
using <code>DebugBar\DataCollector\DataCollector::setDefaultDataFormatter()</code>.</p>
|
|
<p>You can use a custom formater for each collector using <code>DataCollector::setDataFormatter()</code>.</p>
|
|
|
|
<a name="storage"></a><h1>Storage</h1>
|
|
<p>DebugBar supports storing collected data for later analysis.
|
|
You'll need to set a storage handler using <code>setStorage()</code> on your <code>DebugBar</code> instance.</p>
|
|
<pre><code>$debugbar->setStorage(new DebugBar\Storage\FileStorage('/path/to/dir'));</code></pre>
|
|
<p>Each time <code>DebugBar::collect()</code> is called, the data will be persisted.</p>
|
|
<a name="available-storage"></a><h2>Available storage</h2>
|
|
<a name="file"></a><h3>File</h3>
|
|
<p>It will collect data as json files under the specified directory
|
|
(which has to be writable).</p>
|
|
<pre><code>$storage = new DebugBar\Storage\FileStorage($directory);</code></pre>
|
|
<a name="redis"></a><h3>Redis</h3>
|
|
<p>Stores data inside a Redis hash. Uses <a href="http://github.com/nrk/predis">Predis</a>.</p>
|
|
<pre><code>$storage = new DebugBar\Storage\RedisStorage($client);</code></pre>
|
|
<a name="pdo"></a><h3>PDO</h3>
|
|
<p>Stores data inside a database.</p>
|
|
<pre><code>$storage = new DebugBar\Storage\PdoStorage($pdo);</code></pre>
|
|
<p>The table name can be changed using the second argument and sql queries
|
|
can be changed using <code>setSqlQueries()</code>.</p>
|
|
<a name="creating-your-own-storage"></a><h2>Creating your own storage</h2>
|
|
<p>You can easily create your own storage handler by implementing the
|
|
<code>DebugBar\Storage\StorageInterface</code>.</p>
|
|
<a name="request-id-generator"></a><h2>Request ID generator</h2>
|
|
<p>For each request, the debug bar will generate a unique id under which to store the
|
|
collected data. This is perform using a <code>DebugBar\RequestIdGeneratorInterface</code> object.</p>
|
|
<p>If none are defined, the debug bar will automatically use <code>DebugBar\RequestIdGenerator</code>
|
|
which uses the <code>$_SERVER</code> array to generate the id.</p>
|
|
|
|
<a name="open-handler"></a><h1>Open handler</h1>
|
|
<p>The debug bar can open previous sets of collected data which were stored using
|
|
a storage handler (see previous section). To do so, it needs to be provided an
|
|
url to an open handler.</p>
|
|
<p>An open handler must respect a very simple protocol. The default implementation
|
|
is <code>DebugBar\OpenHandler</code>.</p>
|
|
<pre><code>$openHandler = new DebugBar\OpenHandler($debugbar);
|
|
$openHandler->handle();</code></pre>
|
|
<p>Calling <code>handle()</code> will use data from the <code>$_REQUEST</code> array and echo the output.
|
|
The function also supports input from other source if you provide an array as
|
|
first argument. It can also return the data instead of echoing (use false as
|
|
second argument) and not send the content-type header (use false as third argument).</p>
|
|
<p>One you have setup your open handler, tell the <code>JavascriptRenderer</code> its url.</p>
|
|
<pre><code>$renderer->setOpenHandlerUrl('open.php');</code></pre>
|
|
<p>This adds a button in the top right corner of the debug bar which allows you
|
|
to browse and open previous sets of collected data.</p>
|
|
|
|
<a name="http-drivers"></a><h1>HTTP drivers</h1>
|
|
<p>Some features of the debug bar requires sending http headers or
|
|
using the session. Many frameworks implement their own mechanism
|
|
on top of PHP native features.</p>
|
|
<p>To make integration with other frameworks as easy as possible,
|
|
the <code>DebugBar</code> object uses an instance of <code>DebugBar\HttpDriverInterface</code>
|
|
to access those features.</p>
|
|
<p><code>DebugBar\PhpHttpDriver</code>, which uses native PHP mechanisms, is provided
|
|
and will be used if no other driver are specified.</p>
|
|
|
|
<a name="javascript-bar"></a><h1>Javascript Bar</h1>
|
|
<p><strong>This section is here to document the inner workings of the client side debug bar.
|
|
Nothing described below is needed to run the debug bar in a normal way.</strong></p>
|
|
<p>The default client side implementation of the debug bar is made
|
|
entirely in Javascript and is located in the <em>debugbar.js</em> file.</p>
|
|
<p>It adds a bottom-anchored bar which can have tabs and indicators.
|
|
The bar can be in an open or close state. When open, the tab panel is
|
|
visible.
|
|
An indicator is a piece of information displayed in the always-visible
|
|
part of the bar.</p>
|
|
<p>The bar handles multiple datasets by displaying a select box
|
|
which allows you to switch between them.</p>
|
|
<p>The state of the bar (height, visibility, active panel) can be saved
|
|
between requests (enabled in the standard bar).</p>
|
|
<p>Each panel is composed of a widget which is used to display the
|
|
data from a data collector. Some common widgets are provided in
|
|
the <em>widgets.js</em> file.</p>
|
|
<p>The <code>PhpDebugBar</code> namespace is used for all objects and the only
|
|
dependencies are <em>jQuery</em> and <em>FontAwesome</em> (css). <em>FontAwesome</em> is
|
|
optional but is used to add nice icons!</p>
|
|
<p>The main class is <code>PhpDebugBar.DebugBar</code>. It provides the infrastructure
|
|
to manage tabs, indicators and datasets.</p>
|
|
<p>When initialized, the <code>DebugBar</code> class adds itself to the <code><body></code> of the
|
|
page. It is empty by default.</p>
|
|
<a name="tabs-and-indicators"></a><h2>Tabs and indicators</h2>
|
|
<p>Controls (ie. tabs and indicators) are uniquely named. You can check if
|
|
a control exists using <code>isControl(name)</code>.</p>
|
|
<p>Tabs can be added using the <code>createTab(name, widget, title)</code> function.
|
|
The third argument is optional and will be computed from the name if not
|
|
provided.</p>
|
|
<pre><code>var debugbar = new PhpDebugBar.DebugBar();
|
|
debugbar.createTab("messages", new PhpDebugBar.Widgets.MessagesWidget());</code></pre>
|
|
<p>Indicators can be added using <code>createIndicator(name, icon, tooltip, position)</code>.
|
|
Only <code>name</code> is required in this case. <code>icon</code> should be the name of a FontAwesome
|
|
icon. <code>position</code> can either be <em>right</em> (default) or <em>left</em>.</p>
|
|
<pre><code>debugbar.createIndicator("time", "cogs", "Request duration");</code></pre>
|
|
<p>You may have noticed that the data to use inside these controls is not
|
|
specified at the moment. Although it could be specified when initialized, it
|
|
is better to use data mapping to support dynamically changing the data set.</p>
|
|
<a name="data-mapping"></a><h2>Data mapping</h2>
|
|
<p>To enable dynamically changing the data sets, we need to specify which values
|
|
should be feed into which controls. This can be done using <code>setDataMap(map)</code>
|
|
which takes as argument an object where properties are control names. Values
|
|
should be arrays where the first item is the property from the data set and
|
|
the second a default value.</p>
|
|
<pre><code>debugbar.setDataMap({
|
|
"messages": ["messages", []],
|
|
"time": ["time.duration_str", "0ms"]
|
|
});</code></pre>
|
|
<p>You can notice that nested properties can also be accessed using the dot
|
|
notation.</p>
|
|
<p>In this mapping, <code>data["messages"]</code> will be fed to the <em>messages</em> tab
|
|
and <code>data["time"]["duration_str"]</code> will be fed to the <em>time</em> indicator.</p>
|
|
<p>Note: you can append mapping info using <code>addDataMap(map)</code></p>
|
|
<a name="datasets"></a><h2>Datasets</h2>
|
|
<p>Although you shouldn't have to do anything regarding managing datasets,
|
|
it is interesting to know a few functions related to them.</p>
|
|
<p><code>addDataSet(data, id)</code> adds a dataset to the bar. The select box that
|
|
allows to switch between sets is only displayed if more than one are added.
|
|
<code>id</code> is optional and will be auto-generated if not specified.</p>
|
|
<p><code>showDataSet(id)</code> allows you to switch to a specific dataset.</p>
|
|
<a name="widgets"></a><h2>Widgets</h2>
|
|
<p>Widgets should inherit from the <code>PhpDebugBar.Widget</code> class which is used
|
|
as the base of every visual component in the debug bar.</p>
|
|
<p>New widgets can be created using <code>extend()</code>:</p>
|
|
<pre><code>var MyWidget = PhpDebugBar.Widget.extend({
|
|
// class properties
|
|
});</code></pre>
|
|
<p>The Widget class defines a <code>set(attr, value)</code> function which can be used
|
|
to set the value of attributes.</p>
|
|
<p>Using <code>bindAttr(attr, callback)</code>, you can trigger a callback every time
|
|
the value of the attribute is changed. <code>callback</code> can also be a <code>jQuery</code>
|
|
object and in that case it will use the <code>text()</code> function to fill the element.</p>
|
|
<p>Widgets should define a <code>render()</code> function which initializes the widget
|
|
elements.</p>
|
|
<p><code>initialize(options)</code> will always be called after the constructor.</p>
|
|
<pre><code>var MyWidget = PhpDebugBar.Widget.extend({
|
|
|
|
tagName: 'div', // optional as 'div' is the default
|
|
|
|
className: 'mywidget',
|
|
|
|
render: function() {
|
|
this.bindAttr('data', this.$el);
|
|
}
|
|
|
|
});
|
|
|
|
// ----
|
|
|
|
debugbar.createTab("mytab", new MyWidget());
|
|
debugbar.addDataMap({"mytab": ["mydata", ""]});</code></pre>
|
|
<p>Widgets for bundled data collectors are included as well as more generic
|
|
widgets that you can build on top of. They are located in <em>widgets.js</em> in
|
|
the <code>PhpDebugBar.Widgets</code> namespace.</p>
|
|
<p>Generic widgets:</p>
|
|
<ul>
|
|
<li><code>ListWidget</code>: renders an array as a UL list</li>
|
|
<li><code>KVListWidget</code>: renders a hash as a DL list</li>
|
|
<li><code>VariablesListWidget</code>: an extension of <code>KVListWidget</code> to display a list of variables</li>
|
|
<li><code>IFrameWidget</code>: renders an iframe</li>
|
|
</ul>
|
|
<p>Data collectors related widgets:</p>
|
|
<ul>
|
|
<li><code>MessagesWidget</code>: for the <code>MessagesCollector</code></li>
|
|
<li><code>TimelineWidget</code>: for the <code>TimeDataCollector</code></li>
|
|
<li><code>ExceptionWidget</code>: for the <code>ExceptionCollector</code></li>
|
|
<li><code>SQLQueriesWidget</code>: for the <code>PDOCollector</code></li>
|
|
<li><code>TemplatesWidget</code>: for the <code>TwigCollector</code></li>
|
|
</ul>
|
|
<a name="custom-tabs-and-indicators"></a><h2>Custom tabs and indicators</h2>
|
|
<p>Behind the scene, <code>createTab()</code> and <code>createIndicator()</code> use <code>addTab(name, tab)</code> and
|
|
<code>addIndicator(name, indicator)</code>. Tabs are objects of type <code>PhpDebugBar.DebugBar.Tab</code>
|
|
and indicators of type <code>PhpDebugBar.DebugBar.Indicator</code>. These classes subclass
|
|
<code>PhpDebugBar.Widget</code> which makes it easy to create custom tabs or indicators.</p>
|
|
<pre><code>var LinkIndicator = PhpDebugBar.DebugBar.Indicator.extend({
|
|
|
|
tagName: 'a',
|
|
|
|
render: function() {
|
|
LinkIndicator.__super__.render.apply(this);
|
|
this.bindAttr('href', function(href) {
|
|
this.$el.attr('href', href);
|
|
});
|
|
}
|
|
|
|
});
|
|
|
|
// ----
|
|
|
|
debugbar.addIndicator('phpdoc', new LinkIndicator({ href: 'http://doc.php.com', title: 'PHP doc' }));</code></pre>
|
|
<a name="openhandler"></a><h2>OpenHandler</h2>
|
|
<p>An OpenHandler object can be provided using <code>setOpenHandler()</code>. The object is in charge
|
|
of loading datasets. The only requirement is to provide a <code>show()</code> method which takes
|
|
as only parameter a callback which expects an id and data parameter.</p>
|
|
<p>The default implementation is <code>PhpDebugBar.OpenHandler</code> which must be use in conjunction
|
|
with the server side <code>DebugBar\OpenHandler</code> (see previous section).</p>
|
|
<pre><code>debugbar.setOpenHandler(new PhpDebugBar.OpenHandler({ url: "open.php" }));</code></pre>
|
|
|
|
|
|
|
|
|
|
|
|
</div>
|
|
<footer id="footer">
|
|
Powered by <a href="http://github.com/maximebf/beautiful-docs">beautiful-docs</a> -
|
|
<a href="#top">Back to top</a> - <a href="/docs/all.html">Everything on a single page</a>
|
|
- <a href="?print=1">Print current page</a> - <a href="/docs/all.html?print=1">Print all pages</a>
|
|
|
|
</footer>
|
|
</div>
|
|
</body>
|
|
</html>
|