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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.log.writers" xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>Writers</title>

    <para>
        A Writer is an object that inherits from <classname>Zend_Log_Writer_Abstract</classname>.
        A Writer's responsibility is to record log data to a storage backend.
    </para>

    <sect2 id="zend.log.writers.stream">
        <title>Writing to Streams</title>

        <para>
            <classname>Zend_Log_Writer_Stream</classname> sends log
            data to a <ulink url="http://www.php.net/stream">PHP stream</ulink>.
        </para>

        <para>
            To write log data to the <acronym>PHP</acronym> output buffer, use the URL
            <filename>php://output</filename>. Alternatively, you can send log data directly to a
            stream like <constant>STDERR</constant> (<filename>php://stderr</filename>).
        </para>

        <programlisting language="php"><![CDATA[
$writer = new Zend_Log_Writer_Stream('php://output');
$logger = new Zend_Log($writer);

$logger->info('Informational message');
]]></programlisting>

        <para>
            To write data to a file, use one of the
            <ulink url="http://www.php.net/manual/en/wrappers.php#wrappers.file">Filesystem
            URLs</ulink>:
        </para>

        <programlisting language="php"><![CDATA[
$writer = new Zend_Log_Writer_Stream('/path/to/logfile');
$logger = new Zend_Log($writer);

$logger->info('Informational message');
]]></programlisting>

        <para>
            By default, the stream opens in the append mode ("a").
            To open it with a different mode, the <classname>Zend_Log_Writer_Stream</classname>
            constructor accepts an optional second parameter for the mode.
        </para>

        <para>
            The constructor of <classname>Zend_Log_Writer_Stream</classname> also accepts an
            existing stream resource:
        </para>

        <programlisting language="php"><![CDATA[
$stream = @fopen('/path/to/logfile', 'a', false);
if (! $stream) {
    throw new Exception('Failed to open stream');
}

$writer = new Zend_Log_Writer_Stream($stream);
$logger = new Zend_Log($writer);

$logger->info('Informational message');
]]></programlisting>

        <para>
            You cannot specify the mode for existing stream resources. Doing so
            causes a <classname>Zend_Log_Exception</classname> to be thrown.
        </para>
    </sect2>

    <sect2 id="zend.log.writers.database">
        <title>Writing to Databases</title>

        <para>
            <classname>Zend_Log_Writer_Db</classname> writes log information to a database table
            using <classname>Zend_Db</classname>. The constructor of
            <classname>Zend_Log_Writer_Db</classname> receives a
            <classname>Zend_Db_Adapter</classname> instance, a table name, and a mapping of database
            columns to event data items:
        </para>

        <programlisting language="php"><![CDATA[
$params = array ('host'     => '127.0.0.1',
                 'username' => 'malory',
                 'password' => '******',
                 'dbname'   => 'camelot');
$db = Zend_Db::factory('PDO_MYSQL', $params);

$columnMapping = array('lvl' => 'priority', 'msg' => 'message');
$writer = new Zend_Log_Writer_Db($db, 'log_table_name', $columnMapping);

$logger = new Zend_Log($writer);

$logger->info('Informational message');
]]></programlisting>

        <para>
            The example above writes a single row of log data to the database table named
            'log_table_name' table. The database column named 'lvl'
            receives the priority number and the column named 'msg' receives the log message.
        </para>
    </sect2>

    <xi:include href="Zend_Log-Writers-Firebug.xml" />
    <xi:include href="Zend_Log-Writers-Mail.xml" />
    <xi:include href="Zend_Log-Writers-Syslog.xml" />
    <xi:include href="Zend_Log-Writers-ZendMonitor.xml" />

    <sect2 id="zend.log.writers.null">
        <title>Stubbing Out the Writer</title>

        <para>
            The <classname>Zend_Log_Writer_Null</classname> is a stub that does not write log data
            to anything. It is useful for disabling logging or stubbing out logging during tests:
        </para>

        <programlisting language="php"><![CDATA[
$writer = new Zend_Log_Writer_Null;
$logger = new Zend_Log($writer);

// goes nowhere
$logger->info('Informational message');
]]></programlisting>
    </sect2>

    <sect2 id="zend.log.writers.mock">
        <title>Testing with the Mock</title>

        <para>
            The <classname>Zend_Log_Writer_Mock</classname> is a very simple writer that records
            the raw data it receives in an array exposed as a public property.
        </para>

        <programlisting language="php"><![CDATA[
$mock = new Zend_Log_Writer_Mock;
$logger = new Zend_Log($mock);

$logger->info('Informational message');

var_dump($mock->events[0]);

// Array
// (
//    [timestamp] => 2007-04-06T07:16:37-07:00
//    [message] => Informational message
//    [priority] => 6
//    [priorityName] => INFO
// )
]]></programlisting>

        <para>
            To clear the events logged by the mock, simply set
            <command>$mock->events = array()</command>.
        </para>
    </sect2>

    <sect2 id="zend.log.writers.compositing">
        <title>Compositing Writers</title>

        <para>
            There is no composite Writer object. However, a Log instance can write
            to any number of Writers. To do this, use the <methodname>addWriter()</methodname>
            method:
        </para>

        <programlisting language="php"><![CDATA[
$writer1 = new Zend_Log_Writer_Stream('/path/to/first/logfile');
$writer2 = new Zend_Log_Writer_Stream('/path/to/second/logfile');

$logger = new Zend_Log();
$logger->addWriter($writer1);
$logger->addWriter($writer2);

// goes to both writers
$logger->info('Informational message');
]]></programlisting>
    </sect2>
</sect1>