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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 19550 -->
<!-- Reviewed: no -->
<sect1 id="zend.log.factory">
    <title>Die Factory verwenden um ein Log zu erstellen</title>

    <para>
        Zusätzlich zur direkten Instanzierung kann man auch die statische
        <methodname>factory()</methodname> Methode verwenden um eine Log Instanz zu initiieren,
        und auch um angehängte Writer und deren Filter zu konfigurieren. Bei Verwendung der
        Factory kann man keine oder mehrere Writer anhängen. Die Konfiguration kann entweder als
        Array oder Instanz von <classname>Zend_Config</classname> übergeben werden.
    </para>

    <para>
        Als Beispiel:
    </para>

    <programlisting language="php"><![CDATA[
$logger = Zend_Log::factory(array(
    array(
        'writerName'   => 'Stream',
        'writerParams' => array(
            'stream'   => '/tmp/zend.log',
        ),
        'filterName'   => 'Priority',
        'filterParams' => array(
            'priority' => Zend_Log::WARN,
        ),
    ),
    array(
        'writerName'   => 'Firebug',
        'filterName'   => 'Priority',
        'filterParams' => array(
            'priority' => Zend_Log::INFO,
        ),
    ),
));
]]></programlisting>

    <para>
        Das obige instanziert einen Logger mit zwei Writern, einen für das schreiben einer lokalen
        Daten, und einen anderen für das Senden der Daten zu Firebug. Jeder hat einen angehängten
        Filter für Prioritäten, mit unterschiedlichen maximalen Prioritäten.
    </para>

    <para>
        Jeder Writer kann mit den folgenden Schlüsseln definiert werden:
    </para>

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

            <listitem>
                <para>
                    Der "kurze" Name eines Log Writers; der Name des Log Writers ohne den führenden
                    Klassenpräfix/Namespace. Siehe auch den "writerNamespace" Eintrag weiter unten
                    für weitere Details. Beispiele: "Mock", "Stream", "Firebug".
                </para>
            </listitem>
        </varlistentry>

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

            <listitem>
                <para>
                    Ein assoziatives Array von Parametern das verwendet wird wenn der Log Writer
                    instanziert wird. Jede <methodname>factory()</methodname> Methode eines Log
                    Writers führt diese mit den Argumenten des Contructors zusammen, wie anbei
                    erwähnt.
                </para>
            </listitem>
        </varlistentry>

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

            <listitem>
                <para>
                    Der Klassenpräfix/Namespace der verwendet wird wenn der endgültige Klassenname
                    des Log Writers erstellt wird. Wird er nicht angegeben, dann wird standardmäßig
                    "Zend_Log_Writer" angenommen; trotzdem kann man einen eigenen Namespace
                    übergeben, wenn man einen eigenen Log Writer verwendet.
                </para>
            </listitem>
        </varlistentry>

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

            <listitem>
                <para>
                    Der "kurze" Name des Filters der mit dem angegebenen Log Writer verwendet werden
                    soll; der Name des Filters ohne den führenden Klassenpräfix/Namespace. Siehe
                    auch den "filterNamespace" Eintrag weiter unter für weitere Details. Beispiele:
                    "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>

            <para>
                <classname>Zend_Log_Writer_Mail</classname> currently (as of 1.10) does not
                implement a factory, and will raise an exception if you attempt to instantiate it
                via <methodname>Zend_Log::factory()</methodname>.
            </para>
        </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 PHP 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_Writer_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>