Proposal for "Log_FirePHP"

» Metadata » Status
» Description
Important:

This proposal is not supposed to be a new package but a driver for existing PEAR::Log package

Introduction

What is FirePHP ?

If you don't know it, FirePHP enables you to log to your Firebug Console using a simple PHP method call.

You can know much more on visit official web site at http://www.firephp.org.
Don't forget to visit also the FirePHP headquarters at http://www.firephp.org/HQ to see other frameworks integration (such Zend, Symfony, ...)

What makes FirePHP different from other debugging methods ?

All data is sent via a set of X-FirePHP-Data response headers. This means that the debugging data will not interfere with the content on your page.
Avoid echo, var_dump, print_r, that you could use/add and forget to remove once your debugging step is over !


PEAR::Log integration

Following FirePHP users coding style

fb( mixed $Object )
fb( mixed $Object, 'Label' )
fb( mixed $Object, FirePHP::* )
fb( mixed $Object, 'Label', FirePHP::* )

and to match standard PEAR::Log function

log($message, $priority = null)

the $message parameter should be an array with 3 key-values: "message", "label" and "type".
  1. "message" key-value is mandatory for FB info, warn, error, dump and table
  2. "label" key-value is only mandatory for FB trace
  3. "type" key-value is optional : default is PEAR_LOG_FIREPHP_LOG


There are some PHP constants ( PEAR_LOG_FIREPHP_* ) to match the FirePHP $Type behavior:

For example:
PEAR_LOG_FIREPHP_LOG stand for FirePHP::LOG,
PEAR_LOG_FIREPHP_EXCEPTION stand for FirePHP::EXCEPTION, and so on ...


So to code something equivalent to :

fb( mixed $Object , string $Label )
fb( mixed $Object , string $Type )
fb( mixed $Object , string $Label , string $Type )


You should write :

<?php
require 'Log.php';

$logger = &Log::singleton('firephp', '', 'ident');

$logger->log(array('message' => $Object));
$logger->log(array('message' => $Object, 'label' => $Label), $priority);
$logger->log(array('message' => $Object, 'label' => $Label, 'type' => $Type), $priority);
$logger->log(array('message' => $Object, 'type' => $Type), $priority);
?>


TIP : when you use the convenience method, there is no need to give the "type" key-value. Each convenience method add it if missing.

THANKS TO Michal Smolinski to suggest also the simple signature
$logger->log($Object); // when $Object is a string

SEE : firephp_composite.html (example script) source code line 20

Convenience functions logging (emerg, alert, crit, err, warning, notice, info, debug) are also supported (since 2008-11-01) .

Configure options "timeFormat" and "lineFormat" are applied on "Label" if specified, then (if missing) it will be on "message" (only if object is a string)

Examples script "firephp_basic.php" (highlighted and source code provided below) will produce such results:
  1. screenshot 1
  2. screenshot 2
  3. screenshot 3


Examples script "firephp_composite.php" (highlighted and source code provided below) will produce such results:
  1. screenshot 4


Quick Start

  1. install Firebug extension from https://addons.mozilla.org/en-US/firefox/addon/1843
  2. install FirePHP extension from https://addons.mozilla.org/en-US/firefox/addon/6149
  3. install FirePHP Core Library from PEAR channel
  4. copy the new FirePHP PEAR::Log driver in a directory of your include_path


pear channel-discover pear.firephp.org
pear install firephp/FirePHPCore

Credits

I gave my agreement to Christoph Dorn (author of FirePHP), to become a co-author to this proposal :
Read the thread at http://n2.nabble.com/Dependency-too-high-on-PEAR-package-for-PHP-core-Library-td1319760ef842658.html

Changelog

2008-10-11 : First draft version, only support FirePHP 0.1.2 features
2008-11-01 : Second draft version support FirePHP 0.2 features (options, error/exception/assert handlers, group messages)
2008-11-08 : New API following recommandation of Jon Parise
2008-11-11 : "object" key-value is replaced by "message" key-value to run better with other handlers especially with composite
» Dependencies » Links
  • PHP 5.2.0+
  • Log 1.11+
  • FireFox 3
  • Firebug 1.2.1
  • FirePHP 0.1.2 (since first draft 2008-10-11)
  • FirePHP 0.2.1 (since second draft 2008-11-01)
» Timeline » Changelog
  • First Draft: 2008-10-11
  • Proposal: 2008-11-11
  • Call for Votes: 2008-12-11

  • Laurent Laville
    [2008-11-12 13:49 UTC]

    Fix typo error in first name of a contributor (sorry Michal)

  • Laurent Laville
    [2008-11-15 15:14 UTC]

    improved visibility of error/assertion messages catched by internal handler.

    function assertionHandler, line 497 : add "type" key-value
    function errorHandler, lines 417, 422, 427, 431, and 437: add "type" key-value

    ZIP archive and driver highlighted source-code were updated (see links provided)

  • Laurent Laville
    [2008-11-15 15:22 UTC]

    forgot to tell that this version also :

    Add support for non-scalar array('message' => ...) values.
    ==> see line 182

    On idea of Jon Parise for main Log package
    See related commit file
    Header: /repository/pear/Log/Log.php,v 1.73 2008/11/12 02:15:47 jon Exp

  • Laurent Laville
    [2008-12-03 22:18 UTC]

    No more changes on this proposal officially opened on 2008-11-11

    I will call for votes on first month anniversary => 2008-12-11

    You have still one full week if you want to give your feedback