Skip to end of metadata
Go to start of metadata

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

Zend Framework: Zend_Log_Writer_Firebug Component Proposal

Proposed Component Name Zend_Log_Writer_Firebug
Developer Notes http://framework.zend.com/wiki/display/ZFDEV/Zend_Log_Writer_Firebug
Proposers Christoph Dorn
Zend Liaison Matthew Weier O'Phinney
Revision 1.0 - 15 June 2008: Initial Draft.
1.1 - 27 June 2008: Revisions based on comments.
1.2 - 16 July 2008: Major revision based on feedback from Wil and Matthew (wiki revision: 37)

Table of Contents

1. Overview

Status
This component is now in the standard incubator with complete documentation and tests.

Zend_Log_Writer_Firebug is used to inject logging messages into the Firebug Console from PHP. The component is a plugin for the Wildfire project. The goal of the Wildfire project is to develop standardized communication channels and a dynamic and scriptable remote plugin architecture. At this time the primary focus is to provide a system to allow PHP code to inject logging messages into the Firebug Console.

For the purpose of logging to Firebug a communication protocol has been developed that uses HTTP request and response headers to send data between the server and client components. It is great for logging intelligence data generated during script execution to the client browser without interfering with the page content. Debugging AJAX requests that require clean JSON and XML responses is possible with this approach.

Why Wildfire

Javascript is becoming a major force in client browsers and applications not only for enhancing web pages but also the browser and applications themselves. The Firefox browser is a great example of an application that can be extended by Javascript-based extensions. Up until now extensions installed on the client were fixed in their functionality and ability to interact with the loaded web age. That is about to change.

Wildfire will provide a standard for allowing server-side code to dynamically extend and enhance client extensions in a streamlined and secure fashion. Users will not need to install custom extensions for specific sites, but rather simply authorize a specific site to load dynamic extensions into the browser. The dynamically loaded extensions will reside in a sandbox with the same security policies as any other web page. In addition, the Wildfire client extension will provide an API to interact with the browser itself. This API is also extensible by plugins which are installed as any other browser extension.

The Wildfire concept has been proven by the FirePHP project. The Wildfire communication protocols and plugin system will be developed over time based on user demand.

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

  • This component will not be automatically initialized by default
  • This component will send logging information to Firebug only if the developer requests it
  • This component will not send any logging information in the response headers if the FirePHP extension is not installed on the client
  • This component will provide a Zend_Log_Writer implementation
  • This component will provide a facility to log Exceptions
  • This component will provide a Zend_Controller_Plugin_Abstract implementation to flush debug data on request end but before page content is sent
  • This component will not prevent cyclical exception handling should exceptions occur in the component. This must be handled by the developer.
  • This component will make use of Zend_Json_Encoder to encode debug data
  • This component will allow for mapping of all existing and custom Zend_Log priority levels to Firebug logging styles
  • This component will not save any data using Zend_Cache or the filesystem.

4. Dependencies on Other Framework Components

  • Zend_Loader
  • Zend_Log_Writer_Abstract
  • Zend_Controller_Request_Abstract
  • Zend_Controller_Response_Abstract
  • Zend_Controller_Plugin_Abstract
  • Zend_Json_Encoder

5. Theory of Operation

Overview

The idea is that the Zend_Log_Writer_Firebug component will provide the first transport to send debug information to a client in a non-destructive way. In this case the Firebug Console (via FirePHP).

Zend_Log_Writer_Firebug as it is implemented now provides a great way to aid in debugging Zend Framework applications on an ad-hock basis. This use-case will be expanded to a more comprehensive debugging framework that hooks into all Zend Framework components.

Future

The future debugging/intelligence/insight system, possibly implemented by an enhanced Log Writer should collect data at all critical points within all components and provide facilities to enable and disable debug information on a component basis. The collected debug information may be persisted to files, logged or otherwise recorded as well as sent to the client via Zend_Log_Writer_Firebug.

A future version of Zend_Wildfire (the Firefox extension as well as the Zend components) will provide a debug toolbar to be displayed in the browser similar to the symfony debug toolbar. To achieve this we must first collect the mentioned debug information on a component basis.

All functionality beyond the current implementation should be part of new proposals that if applicable require certain additions to the Zend_Wildfire components.

6. Milestones / Tasks

  • Milestone 1: [DONE] Reference implementation
  • Milestone 2: [DONE] Reference implementation refined
  • Milestone 3: [DONE] Working prototype checked into the incubator
  • Milestone 4: [DONE] Unit tests exist, work, and are checked into SVN.
  • Milestone 5: [DONE] Initial documentation exists.

7. Class Index

  • Zend_Log_Writer_Firebug
  • Zend_Wildfire_Exception
  • Zend_Wildfire_Plugin_FirePhp
  • Zend_Wildfire_Plugin_Interface
  • Zend_Wildfire_Channel_Interface
  • Zend_Wildfire_Channel_HttpHeaders
  • Zend_Wildfire_Protocol_JsonStream

8. Use Cases

Typical use of the Zend_Log_Writer_Firebug component will be in conjunction with Zend_Controller_Front. In these use-cases initialize the component in your bootstrap file and use the logging calls in your models, views and controllers.

You can also use Zend_Log_Writer_Firebug without Zend_Controller_Front.

9. Class Skeletons

]]></ac:plain-text-body></ac:macro>

]]></ac:plain-text-body></ac:macro>

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Jun 16, 2008

    <p>Zend_Debug::trace() would be a better method name than fire(). See ActionScript, .NET, etc.</p>

    <p><a class="external-link" href="http://www.adobe.com/support/flash/action_scripts/actionscript_dictionary/actionscript_dictionary808.html">http://www.adobe.com/support/flash/action_scripts/actionscript_dictionary/actionscript_dictionary808.html</a>
    <a class="external-link" href="http://msdn.microsoft.com/en-us/library/bb310977.aspx">http://msdn.microsoft.com/en-us/library/bb310977.aspx</a></p>

    <blockquote><p>The Zend_Log_Writer_FirePhp and Zend_Db_Profiler_FirePhp classes have been dispersed in the Zend namespace to place them within their parent packages. If this is not desirable we can rename them to Zend_Debug_FirePhp_Log_Writer and Zend_Debug_FirePhp_Db_Profiler respectively.</p></blockquote>

    <p>I think Zend_Debug_FirePhp_LogWriter and Zend_Debug_FirePhp_DbProfiler would be the best options, to keep everything together. There's only one class for each, so no need to make "Log" or "Db" its own namespace. (See the variety of components that have DbTable classes.)</p>

    <p>I'd like to see as part of this proposal a simple plugin mechanism using Zend_Loader_PluginLoader. Something like Zend_Debug::setDebugger('FirePhp'); (along with an add() method) that implements Zend_Debug_Interface.</p>

    1. Jun 16, 2008

      <p>Zend_Debug::trace() would work for me. Just need to make sure users are aware that it does not necessarily generate a backtrace but rather only logs what you supply to the method.</p>

      <p>Zend_Debug_FirePhp_LogWriter and Zend_Debug_FirePhp_DbProfiler is fine with me.</p>

      <p>I like the idea of a plugin system for Zend_Debug. Question is if it should cover both the ::dump() and ::trace() methods? If both, then it may be nice for people to be able to specify which debugger/target to use for each method. This would allow for ::dump() to go to page content while ::trace() goes to FirePhp or if a lot of ::dump() calls are already present in the application one could simply route these to FirePhp without having to rename ::dump() to ::trace().</p>

      <p>With add() you mean Zend_Debug::addDebugger() to be able to add multiple targets? If not, I am not quite sure what you mean.</p>

      <p>Instead of ::setDebugger('FirePhp') would ::setTarget('FirePhp','trace') be more appropriate?</p>

  2. Jun 24, 2008

    <p>I agree that trace() would be a better method name. It does have the connotation of backtrace, which is a familiar idiom with debug tools; documentation could make it clear to developers not to expect a full backtrace. </p>

    <p>Additionally, we're typically recommending that components be self-contained, even if they interact with other components, so I'd recommend renaming the log writer and db profiler to fit under the Zend_Debug_FirePhp namespace (which it sounds like you are already planning to do).</p>

    <p>Regarding the plugin interface Matthew Ratzloff refers to, this would be at the Zend_Debug level, not in the FirePhp subcomponent – I think he's suggesting the idea of having multiple debug strategies in place in a single request. However, I think your idea of a plugin architecture within FirePhp also makes sense, as it allows users to determine what exactly they wish to profile with FirePHP – as well as to create profilers for their own components that plug in to it.</p>

    1. Jun 25, 2008

      <p>The plugin architecture was intended for Zend_Debug. It could be as simple as calling Zend_Debug::addMethod('trace','FirePhp') to add a static "trace()" method to Zend_Debug which directs the data to FirePhp. We could also simply add a ::trace() method to Zend_Debug and always direct it to FirePhp for now.</p>

      <p>I think it is important to have a method to direct data to FirePHP in Zend_Debug to make usage easier. Also the FirPhp component is more of a transport and should not be used directly. Zend_Debug is suited better for that. If this is not desirable I guess we could just use Zend_Debug_FirePhp::trace() for now.</p>

      <p>Could you let me know about your preference so I can finalize the code.</p>

      1. Jun 26, 2008

        <p>Well, adding dynamic static methods is not possible without PHP 5.3 at this time, so it would make most sense to add a single method to Zend_Debug, and attach observers/plugins to Zend_Debug that it would then dispatch to. (Man, I can't wait for __callStatic() and LSB!). </p>

        <p>Otherwise, this sounds fine!</p>

  3. Jul 01, 2008

    fc

    <p>It's great to see Zend_Debug finally moving forward. I never understood why people said that you only need xDebug to debug your applications. It's like saying you only need PHPUnit to test them.</p>

    <p>Great stuff Chris <ac:emoticon ac:name="smile" /></p>

    1. Jul 01, 2008

      <p>It's interesting that you say this. I have heard that lots of times as well. I think it all depends on your use. If you are working on straight-forward business logic within a framework and have a good understanding of PHP and your data structures interactive debugging is a complete overkill and only slows you down. xDebug is great for complex algorithms, profiling and fining bugs, but during development I hardly ever use it.</p>

      <p>The addition to Zend_Debug is a first step. The next will be a developer bar and then tight integration will all parts of Zend Framework. There are lots of exciting things to look forward to.</p>

  4. Jul 24, 2008

    <p>Given the development of an entire protocol component as part of this, <code>Zend_Wildfire</code>, I think the Firebug integration should happen separately, as part of <code>Zend_Log_Writer_Firebug</code>. This is where other log writers exist – for example, there is no "Zend_Db_LogWriter" class. It's also where users would look first – I can't think of anyone who would think to check under the <code>Zend_Wildfire</code> namespace for this functionality. A similar situation would be the <code>Zend_Http</code> component (a protocol) and the <code>Zend_Controller_Request_Http</code> class (a class that uses the protocol).</p>

    1. Jul 24, 2008

      <p>I can move Zend_Wildfire_FirebugLogWriter to Zend_Log_Writer_Firebug no problem. I like it better too.</p>

      <p>~matthew: Should I go ahead and make this change?</p>

      1. Jul 24, 2008

        <p>As I understand it, Wildfire is intended to be a protocol that anyone can implement – Firebug (through FirePHP) just happens to be a consumer of this protocol. So wouldn't a more appropriate name be <code>Zend_Log_Writer_Wildfire</code>, or are there some Firebug-specific parts to this?</p>

        1. Jul 24, 2008

          <p>It is specific to Firebug as the writer needs to know what Firebug supports and how to communicate with it. Wildfire is just the underlying protocol without any knowledge of the data it is communicating.</p>

          <p>Zend_Log_Writer_Firebug is the best name I think.</p>

      2. Jul 25, 2008

        <p>This makes sense for now, as the other component-specific log writers are in the Zend_Log tree.</p>

        <p>However, we have been moving towards self-contained components lately (see Zend_Dojo, Zend_Layout, and Zend_Tool for examples). We may revisit this for ZF 2.0. Short answer: go ahead with renaming to Zend_Log_Writer_Firebug.</p>

        1. Jul 29, 2008

          <p>The writer has been renamed to Zend_Log_Writer_Firebug.</p>

          <p>I have also implemented a Zend_Db_Profiler_Firebug component for which I can write tests and documentation should there be interest to include this right away as well.</p>

  5. Aug 05, 2008

    <ac:macro ac:name="note"><ac:parameter ac:name="title">Zend Comment</ac:parameter><ac:rich-text-body>
    <p>This proposal is accepted as-is for immediate development and inclusion in 1.6.0</p></ac:rich-text-body></ac:macro>