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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.log.factory">
    <title>Using the Factory to Create a Log</title>

    <para>
        In addition to direct instantiation, you may also use the static
        <methodname>factory()</methodname> method to instantiate a Log instance, as well as to
        configure attached writers and their filters. Using the factory, you can attach zero or
        more writers. Configuration may be passed as either an array or a
        <classname>Zend_Config</classname> instance. If you want to create an instance of
        a custom class (extending Zend_Log), you can pass a <varname>className</varname>
        option to the <methodname>factory()</methodname> method.
    </para>

    <para>
        As an example:
    </para>

    <programlisting language="php"><![CDATA[
$logger = Zend_Log::factory(array(
    'timestampFormat' => 'Y-m-d',
    array(
        'writerName'   => 'Stream',
        'writerParams' => array(
            'stream'   => '/tmp/zend.log',
        ),
        'formatterName' => 'Simple',
        'formatterParams' => array(
            'format'   => '%timestamp%: %message% -- %info%',
        ),
        'filterName'   => 'Priority',
        'filterParams' => array(
            'priority' => Zend_Log::WARN,
        ),
    ),
    array(
        'writerName'   => 'Firebug',
        'filterName'   => 'Priority',
        'filterParams' => array(
            'priority' => Zend_Log::INFO,
        ),
    ),
));
]]></programlisting>

    <para>
        The above will instantiate a logger with two writers, one for writing to a local file,
        another for sending data to Firebug. Each has an attached priority filter, with different
        maximum priorities.
    </para>

    <para>
        By default, events are logged with the ISO 8601 date format. You can choose your own format
        with the option <emphasis>timestampFormat</emphasis>.
    </para>

    <para>
        Each writer can be defined with the following keys:
    </para>

    <variablelist>
        <varlistentry>
            <term>writerName (required)</term>

            <listitem>
                <para>
                    The "short" name of a log writer; the name of the log writer minus the leading
                    class prefix/namespace. See the "writerNamespace" entry below for more details.
                    Examples: "Mock", "Stream", "Firebug".
                </para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term>writerParams (optional)</term>

            <listitem>
                <para>
                    An associative array of parameters to use when instantiating the log writer.
                    Each log writer's <methodname>factory()</methodname> method will map these to
                    constructor arguments, as noted below.
                </para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term>writerNamespace (optional)</term>

            <listitem>
                <para>
                    The class prefix/namespace to use when constructing the final log writer
                    classname. By default, if this is not provided, "Zend_Log_Writer" is assumed;
                    however, you can pass your own namespace if you are using a custom log writer.
                </para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term>formatterName (optional)</term>

            <listitem>
                <para>
                    The "short" name of a formatter to use with the given log writer; the name of the
                    formatter minus the leading class prefix/namespace. See the "formatterNamespace"
                    entry below for more details. Examples: "Simple", "Xml".
                </para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term>formatterParams (optional)</term>

            <listitem>
                <para>
                    An associative array of parameters to use when instantiating the log formatter.
                    Each log formatter's <methodname>factory()</methodname> method will map these to
                    constructor arguments, as noted below.
                </para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term>formatterNamespace (optional)</term>

            <listitem>
                <para>
                    The class prefix/namespace to use when constructing the final log formatter
                    classname. By default, if this is not provided, "Zend_Log_Formatter" is assumed;
                    however, you can pass your own namespace if you are using a custom log formatter.
                </para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term>filterName (optional)</term>

            <listitem>
                <para>
                    The "short" name of a filter to use with the given log writer; the name of the
                    filter minus the leading class prefix/namespace. See the "filterNamespace" entry
                    below for more details. Examples: "Message", "Priority".
                </para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term>filterParams (optional)</term>

            <listitem>
                <para>
                    An associative array of parameters to use when instantiating the log filter.
                    Each log filter's <methodname>factory()</methodname> method will map these to
                    constructor arguments, as noted below.
                </para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term>filterNamespace (optional)</term>

            <listitem>
                <para>
                    The class prefix/namespace to use when constructing the final log filter
                    classname. By default, if this is not provided, "Zend_Log_Filter" is assumed;
                    however, you can pass your own namespace if you are using a custom log filter.
                </para>
            </listitem>
        </varlistentry>
    </variablelist>

    <para>
        Each writer and each filter has specific options.
    </para>

    <sect2 id="zend.log.factory.writer-options">
        <title>Writer Options</title>

        <sect3 id="zend.log.factory.writer-options.db">
            <title>Zend_Log_Writer_Db Options</title>

            <variablelist>
                <varlistentry>
                    <term>db</term>

                    <listitem>
                        <para>
                            A <classname>Zend_Db_Adapter</classname> instance.
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>table</term>

                    <listitem>
                        <para>
                            The name of the table in the RDBMS that will contain log entries.
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>columnMap</term>

                    <listitem>
                        <para>
                            An associative array mapping database table column names to log event
                            fields.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </sect3>

        <sect3 id="zend.log.factory.writer-options.firebug">
            <title>Zend_Log_Writer_Firebug Options</title>

            <para>
                This log writer takes no options; any provided will be ignored.
            </para>
        </sect3>

        <sect3 id="zend.log.factory.writer-options.mail">
            <title>Zend_Log_Writer_Mail Options</title>

            <table id="zend.log.factory.writer-options.mail.table">
                <title>Zend_Log_Writer_Mail Options</title>

                <tgroup cols="4">
                    <thead>
                        <row>
                            <entry>Option</entry>
                            <entry>Data Type</entry>
                            <entry>Default Value</entry>
                            <entry>Description</entry>
                        </row>
                    </thead>

                    <tbody>
                        <row>
                            <entry><emphasis>mail</emphasis></entry>
                            <entry><type>String</type></entry>
                            <entry><classname>Zend_Mail</classname></entry>

                            <entry>
                                An <classname>Zend_Mail</classname> instance
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis>charset</emphasis></entry>
                            <entry><type>String</type></entry>
                            <entry>iso-8859-1</entry>

                            <entry>
                                Charset of the mail
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis>from</emphasis></entry>
                            <entry><type>String</type> or <type>Array</type></entry>
                            <entry><constant>NULL</constant></entry>

                            <entry>
                                Sender of the mail

                                The parameters for <type>Array</type> type are :
                                <itemizedlist>
                                    <listitem>
                                        <para>
                                            <property>email</property> : address of sender
                                        </para>
                                    </listitem>

                                    <listitem>
                                        <para>
                                            <property>name</property> : name of sender
                                        </para>
                                    </listitem>
                                </itemizedlist>
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis>to</emphasis></entry>
                            <entry><type>String</type> or <type>Array</type></entry>
                            <entry><constant>NULL</constant></entry>

                            <entry>
                                Recipient(s) of the mail
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis>cc</emphasis></entry>
                            <entry><type>String</type> or <type>Array</type></entry>
                            <entry><constant>NULL</constant></entry>

                            <entry>
                                Carbon copy recipient(s) of the mail
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis>bcc</emphasis></entry>
                            <entry><type>String</type> or <type>Array</type></entry>
                            <entry><constant>NULL</constant></entry>

                            <entry>
                                Blind carbon copy recipient(s) of the mail
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis>subject</emphasis></entry>
                            <entry><type>String</type></entry>
                            <entry><constant>NULL</constant></entry>

                            <entry>
                                Subject of the mail
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis>subjectPrependText</emphasis></entry>
                            <entry><type>String</type></entry>
                            <entry><constant>NULL</constant></entry>

                            <entry>
                                A summary of number of errors per priority is appended to the
                                subject of the mail
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis>layout</emphasis></entry>
                            <entry><type>String</type></entry>
                            <entry><constant>NULL</constant></entry>

                            <entry>
                                An <classname>Zend_Layout</classname> instance
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis>layoutOptions</emphasis></entry>
                            <entry><type>Array</type></entry>
                            <entry><constant>NULL</constant></entry>

                            <entry>
                                See the section <xref linkend="zend.layout.options" />
                            </entry>
                        </row>

                        <row>
                            <entry><emphasis>layoutFormatter</emphasis></entry>
                            <entry><type>String</type></entry>
                            <entry><constant>NULL</constant></entry>

                            <entry>
                                An <classname>Zend_Log_Formatter_Interface</classname> instance
                            </entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
        </sect3>

        <sect3 id="zend.log.factory.writer-options.mock">
            <title>Zend_Log_Writer_Mock Options</title>

            <para>
                This log writer takes no options; any provided will be ignored.
            </para>
        </sect3>

        <sect3 id="zend.log.factory.writer-options.null">
            <title>Zend_Log_Writer_Null Options</title>

            <para>
                This log writer takes no options; any provided will be ignored.
            </para>
        </sect3>

        <sect3 id="zend.log.factory.writer-options.stream">
            <title>Zend_Log_Writer_Stream Options</title>

            <variablelist>
                <varlistentry>
                    <term>stream|url</term>

                    <listitem>
                        <para>
                            A valid <acronym>PHP</acronym> stream identifier to which to log.
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>mode</term>

                    <listitem>
                        <para>
                            The I/O mode with which to log; defaults to "a", for "append".
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </sect3>

        <sect3 id="zend.log.factory.writer-options.syslog">
            <title>Zend_Log_Writer_Syslog Options</title>

            <variablelist>
                <varlistentry>
                    <term>application</term>

                    <listitem>
                        <para>
                            Application name used by the syslog writer.
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>facility</term>

                    <listitem>
                        <para>
                            Facility used by the syslog writer.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </sect3>

        <sect3 id="zend.log.factory.writer-options.zendmonitor">
            <title>Zend_Log_Writer_ZendMonitor Options</title>

            <para>
                This log writer takes no options; any provided will be ignored.
            </para>
        </sect3>
    </sect2>

    <sect2 id="zend.log.factory.filter-options">
        <title>Filter Options</title>

        <sect3 id="zend.log.factory.filter-options.message">
            <title>Zend_Log_Filter_Message Options</title>

            <variablelist>
                <varlistentry>
                    <term>regexp</term>

                    <listitem>
                        <para>
                            Regular expression that must be matched in order to log a message.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </sect3>

        <sect3 id="zend.log.factory.filter-options.priority">
            <title>Zend_Log_Filter_Priority Options</title>

            <variablelist>
                <varlistentry>
                    <term>priority</term>

                    <listitem>
                        <para>
                            The maximum priority level by which messages will be logged.
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>operator</term>

                    <listitem>
                        <para>
                            The comparison operator by which to do priority comparisons; defaults to
                            "&lt;=".
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </sect3>

        <sect3 id="zend.log.factory.filter-options.suppress">
            <title>Zend_Log_Filter_Suppress Options</title>

            <para>
                This log filter takes no options; any provided will be ignored.
            </para>
        </sect3>
    </sect2>

    <sect2 id="zend.log.factory.custom">
        <title>Creating Configurable Writers and Filters</title>

        <para>
            If you find yourself needing to write your own log writers and/or filters, you can make
            them compatible with <methodname>Zend_Log::factory()</methodname> very easily.
        </para>

        <para>
            At the minimum, you need to implement
            <interfacename>Zend_Log_FactoryInterface</interfacename>, which expects a static
            <methodname>factory()</methodname> method that accepts a single argument,
            <varname>$config</varname>, which may be either an array or
            <classname>Zend_Config</classname> object. If your log writer extends
            <classname>Zend_Log_Writer_Abstract</classname>, or your log filter extends
            <classname>Zend_Log_Filter_Abstract</classname>, you will pick this up for free.
        </para>

        <para>
            Then, simply define mappings between the accepted configuration and any constructor
            arguments. As an example:
        </para>

        <programlisting language="php"><![CDATA[
class My_Log_Writer_Foo extends Zend_Log_Writer_Abstract
{
    public function __construct($bar, $baz)
    {
        // ...
    }

    public static function factory($config)
    {
        if ($config instanceof Zend_Config) {
            $config = $config->toArray();
        }
        if (!is_array($config)) {
            throw new Exception(
                'factory expects an array or Zend_Config instance'
            );
        }

        $default = array(
            'bar' => null,
            'baz' => null,
        );
        $config = array_merge($default, $config);

        return new self(
            $config['bar'],
            $config['baz']
        );
    }
}
]]></programlisting>

        <para>
            Alternately, you could call appropriate setters after instantiation, but prior to
            returning the instance:
        </para>

        <programlisting language="php"><![CDATA[
class My_Log_Writer_Foo extends Zend_Log_Writer_Abstract
{
    public function __construct($bar = null, $baz = null)
    {
        // ...
    }

    public function setBar($value)
    {
        // ...
    }

    public function setBaz($value)
    {
        // ...
    }

    public static function factory($config)
    {
        if ($config instanceof Zend_Config) {
            $config = $config->toArray();
        }
        if (!is_array($config)) {
            throw new Exception(
                'factory expects an array or Zend_Config instance'
            );
        }

        $writer = new self();
        if (isset($config['bar'])) {
            $writer->setBar($config['bar']);
        }
        if (isset($config['baz'])) {
            $writer->setBaz($config['baz']);
        }
        return $writer;
    }
}
]]></programlisting>
    </sect2>
</sect1>