documentation/manual/en/module_specs/Zend_Log-Overview.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.log.overview">
   4     <title>Overview</title>
   5
   6     <para>
   7         <classname>Zend_Log</classname> is a component for general purpose logging.
   8         It supports multiple log backends, formatting messages sent to the log,
   9         and filtering messages from being logged. These functions are divided
  10         into the following objects:
  11
  12         <itemizedlist>
  13             <listitem>
  14                 <para>
  15                     A Log (instance of <classname>Zend_Log</classname>) is the object that your
  16                     application uses the most. You can have as many Log objects as you
  17                     like; they do not interact. A Log object must contain at
  18                     least one Writer, and can optionally contain one or more Filters.
  19                 </para>
  20             </listitem>
  21
  22             <listitem>
  23                 <para>
  24                     A Writer (inherits from <classname>Zend_Log_Writer_Abstract</classname>) is
  25                     responsible for saving data to storage.
  26                 </para>
  27             </listitem>
  28
  29             <listitem>
  30                 <para>
  31                     A Filter (implements <classname>Zend_Log_Filter_Interface</classname>)
  32                     blocks log data from being saved. A filter may be applied to an
  33                     individual Writer, or to a Log where it is applied before all
  34                     Writers. In either case, filters may be chained.
  35                 </para>
  36             </listitem>
  37
  38             <listitem>
  39                 <para>
  40                     A Formatter (implements <classname>Zend_Log_Formatter_Interface</classname>)
  41                     can format the log data before it is written by a Writer. Each
  42                     Writer has exactly one Formatter.
  43                 </para>
  44             </listitem>
  45         </itemizedlist>
  46     </para>
  47
  48     <sect2 id="zend.log.overview.creating-a-logger">
  49         <title>Creating a Log</title>
  50
  51         <para>
  52             To get started logging, instantiate a Writer and then pass it to a Log instance:
  53         </para>
  54
  55         <programlisting language="php"><![CDATA[
  56 $logger = new Zend_Log();
  57 $writer = new Zend_Log_Writer_Stream('php://output');
  58
  59 $logger->addWriter($writer);
  60 ]]></programlisting>
  61
  62         <para>
  63             It is important to note that the Log must
  64             have at least one Writer. You can add any number of Writers using the
  65             Log's <methodname>addWriter()</methodname> method.
  66         </para>
  67
  68         <para>
  69             Alternatively, you can pass a Writer directly to constructor of Log as
  70             a shortcut:
  71         </para>
  72
  73         <programlisting language="php"><![CDATA[
  74 $writer = new Zend_Log_Writer_Stream('php://output');
  75 $logger = new Zend_Log($writer);
  76 ]]></programlisting>
  77
  78         <para>
  79             The Log is now ready to use.
  80         </para>
  81     </sect2>
  82
  83     <sect2 id="zend.log.overview.logging-messages">
  84         <title>Logging Messages</title>
  85
  86         <para>
  87             To log a message, call the <methodname>log()</methodname> method of a Log instance
  88             and pass it the message with a corresponding priority:
  89         </para>
  90
  91         <programlisting language="php"><![CDATA[
  92 $logger->log('Informational message', Zend_Log::INFO);
  93 ]]></programlisting>
  94
  95         <para>
  96             The first parameter of the <methodname>log()</methodname> method is a string
  97             <code>message</code> and the second parameter is an integer <code>priority</code>. The
  98             priority must be one of the priorities recognized by the Log instance. This is explained
  99             in the next section.
 100         </para>
 101
 102         <para>
 103             A shortcut is also available. Instead of calling the <methodname>log()</methodname>
 104             method, you can call a method by the same name as the priority:
 105         </para>
 106
 107         <programlisting language="php"><![CDATA[
 108 $logger->log('Informational message', Zend_Log::INFO);
 109 $logger->info('Informational message');
 110
 111 $logger->log('Emergency message', Zend_Log::EMERG);
 112 $logger->emerg('Emergency message');
 113 ]]></programlisting>
 114     </sect2>
 115
 116     <sect2 id="zend.log.overview.destroying-a-logger">
 117         <title>Destroying a Log</title>
 118
 119         <para>
 120             If the Log object is no longer needed, set the variable containing it to
 121             <constant>NULL</constant> to destroy it. This will automatically call the
 122             <methodname>shutdown()</methodname> instance method of each attached Writer before
 123             the Log object is destroyed:
 124         </para>
 125
 126         <programlisting language="php"><![CDATA[
 127 $logger = null;
 128 ]]></programlisting>
 129
 130         <para>
 131             Explicitly destroying the log in this way is optional and is performed
 132             automatically at <acronym>PHP</acronym> shutdown.
 133         </para>
 134     </sect2>
 135
 136     <sect2 id="zend.log.overview.builtin-priorities">
 137         <title>Using Built-in Priorities</title>
 138
 139         <para>
 140             The <classname>Zend_Log</classname> class defines the following priorities:
 141         </para>
 142
 143         <programlisting language="php"><![CDATA[
 144 EMERG   = 0;  // Emergency: system is unusable
 145 ALERT   = 1;  // Alert: action must be taken immediately
 146 CRIT    = 2;  // Critical: critical conditions
 147 ERR     = 3;  // Error: error conditions
 148 WARN    = 4;  // Warning: warning conditions
 149 NOTICE  = 5;  // Notice: normal but significant condition
 150 INFO    = 6;  // Informational: informational messages
 151 DEBUG   = 7;  // Debug: debug messages
 152 ]]></programlisting>
 153
 154         <para>
 155             These priorities are always available, and a convenience method of the same name
 156             is available for each one.
 157         </para>
 158
 159         <para>
 160             The priorities are not arbitrary. They come from the BSD <code>syslog</code> protocol,
 161             which is described in <ulink url="http://tools.ietf.org/html/rfc3164">RFC-3164</ulink>.
 162             The names and corresponding priority numbers are also
 163             compatible with another <acronym>PHP</acronym> logging system,
 164             <ulink url="http://pear.php.net/package/log">PEAR Log</ulink>,
 165             which perhaps promotes interoperability between it and <classname>Zend_Log</classname>.
 166         </para>
 167
 168         <para>
 169             Priority numbers descend in order of importance. <constant>EMERG</constant> (0)
 170             is the most important priority. <constant>DEBUG</constant> (7) is the least
 171             important priority of the built-in priorities. You may define priorities
 172             of lower importance than <constant>DEBUG</constant>. When
 173             selecting the priority for your log message, be aware of this priority
 174             hierarchy and choose appropriately.
 175         </para>
 176     </sect2>
 177
 178     <sect2 id="zend.log.overview.user-defined-priorities">
 179         <title>Adding User-defined Priorities</title>
 180
 181         <para>
 182             User-defined priorities can be added at runtime using the Log's
 183             <methodname>addPriority()</methodname> method:
 184         </para>
 185
 186         <programlisting language="php"><![CDATA[
 187 $logger->addPriority('FOO', 8);
 188 ]]></programlisting>
 189
 190         <para>
 191             The snippet above creates a new priority, <constant>FOO</constant>, whose
 192             value is <code>8</code>. The new priority is then available for logging:
 193         </para>
 194
 195         <programlisting language="php"><![CDATA[
 196 $logger->log('Foo message', 8);
 197 $logger->foo('Foo Message');
 198 ]]></programlisting>
 199
 200         <para>
 201             New priorities cannot overwrite existing ones.
 202         </para>
 203     </sect2>
 204
 205     <sect2 id="zend.log.overview.understanding-fields">
 206         <title>Understanding Log Events</title>
 207
 208         <para>
 209             When you call the <methodname>log()</methodname> method or one of its shortcuts, a
 210             log event is created. This is simply an associative array with data
 211             describing the event that is passed to the writers. The following keys
 212             are always created in this array: <code>timestamp</code>,
 213             <code>message</code>, <code>priority</code>, and
 214             <code>priorityName</code>.
 215         </para>
 216
 217         <para>
 218             The creation of the <code>event</code> array is completely transparent.
 219             However, knowledge of the <code>event</code> array is required for adding an
 220             item that does not exist in the default set above.
 221         </para>
 222
 223         <para>
 224             To add a new item to every future event, call the
 225             <methodname>setEventItem()</methodname> method giving a key and a value:
 226         </para>
 227
 228         <programlisting language="php"><![CDATA[
 229 $logger->setEventItem('pid', getmypid());
 230 ]]></programlisting>
 231
 232         <para>
 233             The example above sets a new item named <code>pid</code> and populates
 234             it with the PID of the current process. Once a new item has been
 235             set, it is available automatically to all writers along with all of the
 236             other data event data during logging. An item can be overwritten at any
 237             time by calling the <methodname>setEventItem()</methodname> method again.
 238         </para>
 239
 240         <para>
 241             Setting a new event item with <methodname>setEventItem()</methodname> causes the
 242             new item to be sent to all writers of the logger. However, this does
 243             not guarantee that the writers actually record the item. This is
 244             because the writers won't know what to do with it unless a formatter
 245             object is informed of the new item. Please see the section on Formatters
 246             to learn more.
 247         </para>
 248     </sect2>
 249
 250     <sect2 id="zend.log.overview.as-errorHandler">
 251         <title>Log PHP Errors</title>
 252
 253         <para>
 254             <classname>Zend_Log</classname> can also be used to log <acronym>PHP</acronym> errors.
 255             Calling <methodname>registerErrorHandler()</methodname> will add
 256             <classname>Zend_Log</classname> before the current error handler, and will pass the
 257             error along as well.
 258         </para>
 259
 260         <table id="zend.log.overview.as-errorHandler.properties.table-1">
 261             <title>
 262                 Zend_Log events from PHP errors have the additional fields matching
 263                 <methodname>handler  ( int $errno  , string $errstr  [, string $errfile  [, int
 264                     $errline  [, array $errcontext  ]]] )</methodname> from <ulink
 265                     url="http://us3.php.net/manual/en/function.set-error-handler.php">set_error_handler</ulink>
 266             </title>
 267
 268             <tgroup cols="3">
 269                 <thead>
 270                     <row>
 271                         <entry>Name</entry>
 272                         <entry>Error Handler Paramater</entry>
 273                         <entry>Description</entry>
 274                     </row>
 275                 </thead>
 276
 277                 <tbody>
 278                     <row>
 279                         <entry>message</entry>
 280                         <entry>errstr</entry>
 281                         <entry>Contains the error message, as a string.</entry>
 282                     </row>
 283
 284                     <row>
 285                         <entry>errno</entry>
 286                         <entry>errno</entry>
 287                         <entry>Contains the level of the error raised, as an integer.</entry>
 288                     </row>
 289
 290                     <row>
 291                         <entry>file</entry>
 292                         <entry>errfile</entry>
 293
 294                         <entry>
 295                             Contains the filename that the error was raised in, as a string.
 296                         </entry>
 297                     </row>
 298
 299                     <row>
 300                         <entry>line</entry>
 301                         <entry>errline</entry>
 302
 303                         <entry>
 304                             Contains the line number the error was raised at, as an integer.
 305                         </entry>
 306                     </row>
 307
 308                     <row>
 309                         <entry>context</entry>
 310                         <entry>errcontext</entry>
 311
 312                         <entry>
 313                             (optional) An array that points to the active symbol table at the point
 314                             the error occurred. In other words, errcontext  will contain an array of
 315                             every variable that existed in the scope the error was triggered in.
 316                             User error handler must not modify error context.
 317                         </entry>
 318                     </row>
 319
 320                 </tbody>
 321             </tgroup>
 322         </table>
 323     </sect2>
 324 </sect1>