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