The Insight API is not supported by the FirePHP Firefox Extension.
The new Insight API takes an object oriented approach and provides many more features than the traditional FirePHP API. See
Overview for a comparison:
define('INSIGHT_CONFIG_PATH', '...');
require_once('FirePHP/Init.php');
$inspector = FirePHP::to('page');
$console = $inspector->console();
$console->log('Hello World');
Many methods in the Insight API may be chained and work by successively cloning and augmenting a message object which is finally
sent off. In the example above FirePHP::to() creates a message object targeting the page context. The context is further
refined to point to a console. One or more messages can now be sent to this same context.
While some of the method names in the new Insight API are called the same as in the FirePHP API they take different arguments.
Activation & Authorization
The Insight API must be activated and authorized to record and send data to the client. It is activated by default and may be deactivated from the
client. Authorization occurs on a per-hostname basis. See Authorizing for more information.
If Insight is deactivated from the client the FirePHP API will also be deactivated but only if including
FirePHP using the /FirePHP/*.php files.
Contexts: FirePHP::to('<target>')
To record/log any data a context must be initialized by specifying a target:
page - Obtain a message context that will send messages to the page target. These messages will show up in the
Firebug or DeveloperCompanion consoles.
$inspector = FirePHP::to('page');
$console = $inspector->console();
$console->log('Hello World');
See Insight/Console API below for how to send different kinds of messages to this target.
request - Obtain a message context that will send messages to the request target. These messages will show up in the Companion Window
after an *inspect* has been triggered.
$inspector = FirePHP::to('request');
$console = $inspector->console('<Tab Label>');
$console->log('Hello World');
The <Tab Label> is optional and defaults to Console.
See Insight/Console API below for how to send different kinds of messages to this target.
package - Obtain a message context that will record information about the application package. This info is used in the
Companion Window when displaying information about a request.
See Package API below for how to use this target.
controller - Obtain a message context that is used to control the client.
See Insight/Control API below for how to use this target.
Plugins: FirePHP::plugin('<name>')
Get a plugin by specifying a name. Supported plugins are:
Insight/Console API
The Insight/Console API is used to send messages to a given target.
$console = FirePHP::to('<target>')->console('<Tab Label>');
The <Tab Label> is optional and defaults to Console.
The <target> defines where the messages will show up. See FirePHP::to('<target>') above.
Variable Truncation
Large variables are truncated when traversing (nested arrays and object members) by preventing the transmission of data, beyond certain limits,
to the client.
By default variables are truncated according to the encoder options. To avoid truncating variables use:
$console = $console->nolimit();
Calling nolimit(false) will reset the option and cause variables to be truncated again.
String Trimming
Large strings are trimmed when displayed in the client console.
By default pure string variables are trimmed to 500 characters and string values as part of arrays or objects to 50 characters. To prevent string
trimming use:
$console = $console->notrim();
Calling notrim(false) will reset the option and cause strings to be trimmed again.
Message Expansion
By default logged messages are contracted when displayed in the console. To expand any message use:
$console = $console->expand();
Use this to log expanded tables, groups, traces and general log messages.
Showing the Console
By default logged messages are tracked by the client but not shown to the user unless they already have the console open. To force the console to
show use:
$console->show();
If logging to the Firebug Console you must have Firebug open and the Firebug Console and Net panels enabled.
Options
Individual encoder (and other) options can be set as needed:
$console = $console->option('<Name>', <Value>); // or
$console = $console->options(array(
'<Name>' => <Value>
));
Calling option() or options() without a value argument will return the current value.
Possible options are as follows (default values are shown):
encoder.depthNoLimit : false
encoder.lengthNoLimit : false
encoder.maxDepth : 5
encoder.maxStringLength : 5000
encoder.maxArrayDepth : 3
encoder.maxArrayLength : 25
encoder.maxObjectDepth : 3
encoder.maxObjectLength : 25
encoder.trace.offsetAdjustment : 0 // affects file/line logic
encoder.trace.maxLength : -1 // no maximum
encoder.exception.traceMaxLength : -1 // no maximum
string.trim.enabled : <undefined> // force/prevent string trimming in UI
string.trim.length : 50 // string trim length
string.trim.newlines : true // force/prevent string newline expansion
file : <automatic> // sets file for message
line : <automatic> // sets line for message
Encoder option defaults may be set by configuration. See Advanced Configuration.
Class Member Filters
Manually setting a class member filter:
$filter = array(
'classes' => array(
'<ClassName>' => array('<MemberName>')
)
);
$console->filter($filter)-> [Console API]
Annotation-based class member filter:
class <Name> {
/**
* @insight filter=on
*/
public $var;
}
Logging Variables
$console->log($Variable);
Message Priorities
$console->log($Variable);
$console->info($Variable);
$console->warn($Variable);
$console->error($Variable);
Message Labels
$console->label('<Label>')-> [Console API]
Tables
$header = array('Column 1 Heading', 'Column 2 Heading');
$table = array(
array('Row 1 Column 1 Value', 'Row 1 Column 2 Value'),
array($Variable_r2c1, $Variable_r2c2)
);
$console->table('<Title>', $table);
$console->table('<Title>', $table, $header);
Stack Traces
$console->trace('<Label>');
Groups
Logging to a group by name:
$console->group('<Name>', '<Title>')-> [Console API]
Directing multiple messages to a group context:
$group = $console->group('<Name>', '<Title>')->open();
$console-> [Console API]
$group->close();
Specifying a <Name> is optional.
If the <Title> argument is not provided the first message logged to the group becomes the title.
When opening groups they must be closed in the same order!
You can log to the same group in different parts of an application without keeping track of the $group variable as long as the group name is the
same. The group will appear in the group hierarchy (if multiple nested groups) depending on where a group is first logged.
Conditional Logging
Conditional logging is currently only supported by DeveloperCompanion when logging to the request target and inspecting via the
Companion Window!
By default all logged messages are sent to the client. To conditionally send specific messages, only if requested by client, one or multiple messages
may be wrapped in an on() handler.
Conditional logging by name:
$console->on('<Name>')-> [Console API]
Directing multiple messages to a conditional context:
$on = $console->on('<Name>')->open();
$console-> [Console API]
$on->close();
When opening contexts they must be closed in the same order!
Declared conditions may be used for flow control:
if($console->on('<Name>')->is(true)) {
// conditionally execute
}
It is imperative that this feature is only used for debugging and development related purposes. It will only ever evaluate to TRUE if
an authorized client is detected and the condition is enabled on the client.
Insight/Package API
The Insight/Package API is used to record information about the application package.
$package = FirePHP::to('package');
Quick Links
To add links for a package that will be displayed as buttons in the Companion Window use:
$package->addQuickLink('Link 1', 'http://www.firephp.org/');
// or
$package->addQuickLink('Link 2', array(
'target' => 'window', // tab (default), window or hidden
'url' => 'http://www.firephp.org/'
));
Links added this way will augment links already added via the package.json config file. See here for more info.
Insight/Control API
The Insight/Control API is used to control the client in the context of the request.
$controller = FirePHP::to('controller');
Triggers
Schedule an inspect event for the current request which will be executed by the client once the entire response is received by the browser.
This will cause the client to focus on the data sent while the request executed.
$controller->triggerInspect();
This is equivalent to $console->show();
There are several ways to inspect a given request.
Insight/FirePHP API
The Insight/FirePHP API provides utility functions to make development and monitoring easier.
$firephp = FirePHP::plugin('firephp');
Convenience Logging for Ad-hock Debugging
Fumbling with $console objects can become tedious if you just want to quickly log a variable during development. A p() shortcut function can be made
available to easily print variables to a console.
// Log p() messages to the Firebug Console
$firephp->declareP();
// Log p() messages to a request console called Ad-hock
$firephp->declareP('Ad-hock', true);
// Log p() messages to the provided $console
$console = FirePHP::to('request')->console('Debug');
$firephp->declareP($console, true);
The second argument to declareP() specifies whether an inspect for the request should be triggered. This will automatically open
the Companion Window and load the request data as soon as the p() function is used.
Once declared, to print variables simply use:
p($variable); // or
p($variable, 'Label');
The p() calls should not stay in your code and are intended for use during development only!
Information
Log the current FirePHP version to a FirePHP console.
$firephp->logVersion(); // or
$firephp->logVersion($console);
Recording Environment
Send information about the PHP environment to an Environment console.
$firephp->recordEnvironment(); // or
$firephp->recordEnvironment($console);
Constants
Insight Constants
define('INSIGHT_CONFIG_PATH', <string>);
define('INSIGHT_IPS', <string>);
define('INSIGHT_AUTHKEYS', <string>);
define('INSIGHT_PATHS', <string>);
define('INSIGHT_SERVER_PATH', <string>);
See Install for more information.
FirePHP Constants
define('FIREPHP_ACTIVATED', <boolean>);
May be set to FALSE prior to including FirePHP to force-deactivate FirePHP. This will cause all logging
calls to be ignored on the server and no data will be sent to the client as if FirePHP was never installed on the server.
If the constant is not set prior to including FirePHP it will be automatically set to TRUE (if client detected, FALSE otherwise) when FirePHP
loads and can be used in application code to enable logging and debugging facilities as needed if applicable.
if(FIREPHP_ACTIVATED) ...
If set to TRUE prior to including FirePHP, FirePHP will be force-activated even if no authorized client is detected.
If no authorized client is detected, data will be collected but not exposed. This is useful when using a payload listener to write the data to disk
(or alternate storage) for later access. See Advanced Features below for more information.
Advanced Features
Payload Listener
A payload listener may be registered that will fire at the end of the request. The listener will be provided with all the data collected during the request.
This is useful in cases where the data should be written to disk or alternate storage for later debugging purposes.
Typically data will only be collected if an authorized client is detected. To force-activate data collection use the FIREPHP_ACTIVATED constant.
See Constants.
define('FIREPHP_ACTIVATED', true);
require_once('FirePHP/Init.php');
class PayloadListener {
public function onPayload($request, $payload) {
echo($payload);
}
}
Insight_Helper::getInstance()->registerListener('payload', new PayloadListener());
To send the collected payload to a client (at a later point in time) see Send Raw Payload below.
Send Raw Payload
Previously collected payload data (see Payload Listener above) may be relayed to a client as follows:
require_once('FirePHP/Init.php');
Insight_Helper::getInstance()->relayPayload($payload)
