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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.log.writers" xmlns:xi="http://www.w3.org/2001/XInclude">
   4     <title>Writers</title>
   5
   6     <para>
   7         A Writer is an object that inherits from <classname>Zend_Log_Writer_Abstract</classname>.
   8         A Writer's responsibility is to record log data to a storage backend.
   9     </para>
  10
  11     <sect2 id="zend.log.writers.stream">
  12         <title>Writing to Streams</title>
  13
  14         <para>
  15             <classname>Zend_Log_Writer_Stream</classname> sends log
  16             data to a <ulink url="http://www.php.net/stream">PHP stream</ulink>.
  17         </para>
  18
  19         <para>
  20             To write log data to the <acronym>PHP</acronym> output buffer, use the URL
  21             <code>php://output</code>. Alternatively, you can send log data directly to a stream
  22             like <constant>STDERR</constant> (<code>php://stderr</code>).
  23         </para>
  24
  25         <programlisting language="php"><![CDATA[
  26 $writer = new Zend_Log_Writer_Stream('php://output');
  27 $logger = new Zend_Log($writer);
  28
  29 $logger->info('Informational message');
  30 ]]></programlisting>
  31
  32         <para>
  33             To write data to a file, use one of the
  34             <ulink url="http://www.php.net/manual/en/wrappers.php#wrappers.file">Filesystem
  35             URLs</ulink>:
  36         </para>
  37
  38         <programlisting language="php"><![CDATA[
  39 $writer = new Zend_Log_Writer_Stream('/path/to/logfile');
  40 $logger = new Zend_Log($writer);
  41
  42 $logger->info('Informational message');
  43 ]]></programlisting>
  44
  45         <para>
  46             By default, the stream opens in the append mode (<code>"a"</code>).
  47             To open it with a different mode, the <classname>Zend_Log_Writer_Stream</classname>
  48             constructor accepts an optional second parameter for the mode.
  49         </para>
  50
  51         <para>
  52             The constructor of <classname>Zend_Log_Writer_Stream</classname> also accepts an
  53             existing stream resource:
  54         </para>
  55
  56         <programlisting language="php"><![CDATA[
  57 $stream = @fopen('/path/to/logfile', 'a', false);
  58 if (! $stream) {
  59     throw new Exception('Failed to open stream');
  60 }
  61
  62 $writer = new Zend_Log_Writer_Stream($stream);
  63 $logger = new Zend_Log($writer);
  64
  65 $logger->info('Informational message');
  66 ]]></programlisting>
  67
  68         <para>
  69             You cannot specify the mode for existing stream resources. Doing so
  70             causes a <classname>Zend_Log_Exception</classname> to be thrown.
  71         </para>
  72     </sect2>
  73
  74     <sect2 id="zend.log.writers.database">
  75         <title>Writing to Databases</title>
  76
  77         <para>
  78             <classname>Zend_Log_Writer_Db</classname> writes log information to a database table
  79             using <classname>Zend_Db</classname>. The constructor of
  80             <classname>Zend_Log_Writer_Db</classname> receives a
  81             <classname>Zend_Db_Adapter</classname> instance, a table name, and a mapping of database
  82             columns to event data items:
  83         </para>
  84
  85         <programlisting language="php"><![CDATA[
  86 $params = array ('host'     => '127.0.0.1',
  87                  'username' => 'malory',
  88                  'password' => '******',
  89                  'dbname'   => 'camelot');
  90 $db = Zend_Db::factory('PDO_MYSQL', $params);
  91
  92 $columnMapping = array('lvl' => 'priority', 'msg' => 'message');
  93 $writer = new Zend_Log_Writer_Db($db, 'log_table_name', $columnMapping);
  94
  95 $logger = new Zend_Log($writer);
  96
  97 $logger->info('Informational message');
  98 ]]></programlisting>
  99
 100         <para>
 101             The example above writes a single row of log data to the database table named
 102             <code>log_table_name</code> table. The database column named <code>lvl</code>
 103             receives the priority number and the column named <code>msg</code> receives the
 104             log message.
 105         </para>
 106     </sect2>
 107
 108     <xi:include href="Zend_Log-Writers-Firebug.xml" />
 109     <xi:include href="Zend_Log-Writers-Mail.xml" />
 110     <xi:include href="Zend_Log-Writers-Syslog.xml" />
 111     <xi:include href="Zend_Log-Writers-ZendMonitor.xml" />
 112
 113     <sect2 id="zend.log.writers.null">
 114         <title>Stubbing Out the Writer</title>
 115
 116         <para>
 117             The <classname>Zend_Log_Writer_Null</classname> is a stub that does not write log data
 118             to anything. It is useful for disabling logging or stubbing out logging during tests:
 119         </para>
 120
 121         <programlisting language="php"><![CDATA[
 122 $writer = new Zend_Log_Writer_Null;
 123 $logger = new Zend_Log($writer);
 124
 125 // goes nowhere
 126 $logger->info('Informational message');
 127 ]]></programlisting>
 128     </sect2>
 129
 130     <sect2 id="zend.log.writers.mock">
 131         <title>Testing with the Mock</title>
 132
 133         <para>
 134             The <classname>Zend_Log_Writer_Mock</classname> is a very simple writer that records
 135             the raw data it receives in an array exposed as a public property.
 136         </para>
 137
 138         <programlisting language="php"><![CDATA[
 139 $mock = new Zend_Log_Writer_Mock;
 140 $logger = new Zend_Log($mock);
 141
 142 $logger->info('Informational message');
 143
 144 var_dump($mock->events[0]);
 145
 146 // Array
 147 // (
 148 //    [timestamp] => 2007-04-06T07:16:37-07:00
 149 //    [message] => Informational message
 150 //    [priority] => 6
 151 //    [priorityName] => INFO
 152 // )
 153 ]]></programlisting>
 154
 155         <para>
 156             To clear the events logged by the mock, simply set <code>$mock->events = array()</code>.
 157         </para>
 158     </sect2>
 159
 160     <sect2 id="zend.log.writers.compositing">
 161         <title>Compositing Writers</title>
 162
 163         <para>
 164             There is no composite Writer object. However, a Log instance can write
 165             to any number of Writers. To do this, use the <methodname>addWriter()</methodname>
 166             method:
 167         </para>
 168
 169         <programlisting language="php"><![CDATA[
 170 $writer1 = new Zend_Log_Writer_Stream('/path/to/first/logfile');
 171 $writer2 = new Zend_Log_Writer_Stream('/path/to/second/logfile');
 172
 173 $logger = new Zend_Log();
 174 $logger->addWriter($writer1);
 175 $logger->addWriter($writer2);
 176
 177 // goes to both writers
 178 $logger->info('Informational message');
 179 ]]></programlisting>
 180     </sect2>
 181 </sect1>