mirror of
https://github.com/maximebf/php-debugbar.git
synced 2025-07-28 04:00:43 +02:00
654 lines
25 KiB
HTML
654 lines
25 KiB
HTML
<!DOCTYPE html>
|
||
<html>
|
||
<head>
|
||
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
||
<title>PHP Debug Bar</title>
|
||
<link type="text/css" rel="stylesheet" href="http://fonts.googleapis.com/css?family=Droid+Sans&subset=latin">
|
||
<link type="text/css" rel="stylesheet" href="/php-debugbar/docs/css/reset.css">
|
||
<link type="text/css" rel="stylesheet" href="/php-debugbar/docs/css/docs.css">
|
||
<link type="text/css" rel="stylesheet" href="/php-debugbar/docs/css/print.css" media="print">
|
||
<link type="text/css" rel="stylesheet" href="http://yandex.st/highlightjs/6.1/styles/sunburst.min.css">
|
||
|
||
<link type="text/css" rel="stylesheet" href="style.css">
|
||
|
||
<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.4.3/jquery.min.js"></script>
|
||
<script type="text/javascript" src="http://yandex.st/highlightjs/6.1/highlight.min.js"></script>
|
||
|
||
<script type="text/javascript" src="/php-debugbar/docs/js/viewer.js"></script>
|
||
</head>
|
||
<body>
|
||
<div id="page">
|
||
<a name="top" />
|
||
|
||
<header id="header">
|
||
<h1><a href="/php-debugbar/docs/">PHP Debug Bar</a></h1>
|
||
</header>
|
||
|
||
<div id='content'><a name="php-debug-bar"></a><h1>PHP Debug Bar</h1>
|
||
<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 with no other dependencies</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>
|
||
</ul>
|
||
<a name="installation"></a><h2>Installation</h2>
|
||
<p>The easiest way to install DebugBar is using <a href="https://github.com/composer/composer">Composer</a>
|
||
with the following requirement:
|
||
|
||
</p>
|
||
<pre><code>{
|
||
"require": {
|
||
"maximebf/debugbar": ">=1.0.0"
|
||
}
|
||
}</code></pre>
|
||
<p>Alternatively, you can <a href="https://github.com/maximebf/php-debugbar/zipball/master">download the archive</a>
|
||
and add the src/ folder to PHP's include path:
|
||
|
||
</p>
|
||
<pre><code>set_include_path('/path/to/src' . PATH_SEPARATOR . get_include_path());</code></pre>
|
||
<p>DebugBar does not provide an autoloader but follows the <a href="https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md">PSR-0 convention</a>.<br>You can use the following snippet to autoload ConsoleKit classes:
|
||
|
||
</p>
|
||
<pre><code>spl_autoload_register(function($className) {
|
||
if (substr($className, 0, 8) === 'DebugBar') {
|
||
$filename = str_replace('\\', DIRECTORY_SEPARATOR, trim($className, '\\')) . '.php';
|
||
require_once $filename;
|
||
}
|
||
});</code></pre>
|
||
<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 projets in no time.
|
||
The easiest way is using the <code>render()</code> functions
|
||
|
||
</p>
|
||
<pre><code><?php
|
||
use DebugBar\StandardDebugBar;
|
||
use DebugBar\JavascriptRenderer;
|
||
|
||
$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>$debugbar["messages"]->addMessage("hello world!");</code></pre>
|
||
<p><code>StandardDebugBar</code> activates all bundled 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://maximebf.github.io/php-debugbar">docs</a>.
|
||
</p>
|
||
|
||
<a name="php-debug-bar"></a><h1>PHP Debug Bar</h1>
|
||
<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 with no other dependencies</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>
|
||
</ul>
|
||
<a name="installation"></a><h2>Installation</h2>
|
||
<p>The easiest way to install DebugBar is using <a href="https://github.com/composer/composer">Composer</a>
|
||
with the following requirement:
|
||
|
||
</p>
|
||
<pre><code>{
|
||
"require": {
|
||
"maximebf/debugbar": ">=1.0.0"
|
||
}
|
||
}</code></pre>
|
||
<p>Alternatively, you can <a href="https://github.com/maximebf/php-debugbar/zipball/master">download the archive</a>
|
||
and add the src/ folder to PHP's include path:
|
||
|
||
</p>
|
||
<pre><code>set_include_path('/path/to/src' . PATH_SEPARATOR . get_include_path());</code></pre>
|
||
<p>DebugBar does not provide an autoloader but follows the <a href="https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md">PSR-0 convention</a>.<br>You can use the following snippet to autoload ConsoleKit classes:
|
||
|
||
</p>
|
||
<pre><code>spl_autoload_register(function($className) {
|
||
if (substr($className, 0, 8) === 'DebugBar') {
|
||
$filename = str_replace('\\', DIRECTORY_SEPARATOR, trim($className, '\\')) . '.php';
|
||
require_once $filename;
|
||
}
|
||
});</code></pre>
|
||
<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 projets in no time.
|
||
The easiest way is using the <code>render()</code> functions
|
||
|
||
</p>
|
||
<pre><code><?php
|
||
use DebugBar\StandardDebugBar;
|
||
use DebugBar\JavascriptRenderer;
|
||
|
||
$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>$debugbar["messages"]->addMessage("hello world!");</code></pre>
|
||
<p><code>StandardDebugBar</code> activates all bundled 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://maximebf.github.io/php-debugbar">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>
|
||
<a name="base-collectors"></a><h2>Base collectors</h2>
|
||
<p>Provided by the <code>DebugBar\DataCollector</code> namespace.
|
||
|
||
</p>
|
||
<a name="messages"></a><h3>Messages</h3>
|
||
<p>Provides a way to log messages (compotible 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 MessagesCollector());
|
||
$debugbar['message']->info('hello world');</code></pre>
|
||
<a name="timedata"></a><h3>TimeData</h3>
|
||
<p>Provides a way to log total execution time as well as taking "measures" (ie. measure the exution time of a particular operation).
|
||
|
||
</p>
|
||
<pre><code>$debugbar->addCollector(new 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><h3>Exceptions</h3>
|
||
<p>Display exceptions
|
||
|
||
</p>
|
||
<pre><code>$debugbar->addCollector(new ExceptionsCollector());
|
||
|
||
try {
|
||
throw new Exception('foobar');
|
||
} catch (Exception $e) {
|
||
$debugbar['exceptions']->addException($e);
|
||
}</code></pre>
|
||
<a name="pdo"></a><h3>PDO</h3>
|
||
<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 PDO\TraceablePDO(new PDO('sqlite::memory:'));
|
||
$debugbar->addCollector(new PDO\PDOCollector($pdo));</code></pre>
|
||
<a name="others"></a><h3>Others</h3>
|
||
<p>Misc collectors which you can just register:
|
||
|
||
</p>
|
||
<ul>
|
||
<li><code>MemoryCollector</code> (<em>memory</em>)</li>
|
||
<li><code>PhpInfoCollector</code> (<em>php</em>)</li>
|
||
<li><code>RequestDataCollector</code> (<em>request</em>)</li>
|
||
</ul>
|
||
|
||
<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 three 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>
|
||
</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 projets.
|
||
|
||
</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>Note that you can only use the debug bar assets and manage the dependencies by yourself
|
||
using <code>$renderer->setIncludeVendors(false)</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 initilization 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 initilization.
|
||
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>
|
||
</ul>
|
||
<p>At least <em>icon</em> or <em>widget</em> are needed. If <em>widget</em> is specified, a tab will be created, otherwise
|
||
an indicator.
|
||
|
||
</p>
|
||
<pre><code>$renderer->addControl('messages', array(
|
||
"widget" => "PhpDebugBar.Widgets.MessagesWidget",
|
||
"map" => "messages",
|
||
"default" => "[]"
|
||
));</code></pre>
|
||
|
||
<a name="javascript-bar"></a><h1>Javascript Bar</h1>
|
||
<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, visibilty, 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>, <em>jquery-drag</em> and <em>FontAwesome</em> (css).
|
||
|
||
</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 by <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 swtich 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>A widget is a javascript object which must contain at least an <code>element</code>
|
||
property. <code>element</code>'s value will be appended to the tab panel.
|
||
|
||
</p>
|
||
<p>Widgets should provide a <code>setData()</code> function so they can be used with
|
||
the data mapper.
|
||
|
||
</p>
|
||
<pre><code>var MyWidget = function() {
|
||
this.element = $('<div class="mywidget" />');
|
||
};
|
||
|
||
MyWidget.prototype.setData = function(text) {
|
||
this.element.text(text);
|
||
};
|
||
|
||
// ----
|
||
|
||
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>
|
||
</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 projets with the DebugBar.
|
||
|
||
</p>
|
||
<a name="monolog"></a><h2>Monolog</h2>
|
||
<p>Integrates Monolog messages into the messages view.
|
||
|
||
</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>
|
||
<a name="propel"></a><h2>Propel</h2>
|
||
<p>Logs propel queries into an SQL queries view. 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="twig"></a><h2>Twig</h2>
|
||
<p>Collects info about rendered templates. 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\TwigDataCollector($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>
|
||
|
||
</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="/php-debugbar/docs/all.html">Everything on a single page</a>
|
||
- <a href="?print=1">Print current page</a> - <a href="/php-debugbar/docs/all.html?print=1">Print all pages</a>
|
||
|
||
</footer>
|
||
</div>
|
||
</body>
|
||
</html>
|