<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 21818 -->
<!-- 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>
                    Ein assoziatives Array an Parametern das verwendet wird wenn der Log Filter
                    instanziert wird. Jede <methodname>factory()</methodname> Methode eines Log
                    Filters führt diese mit den Constructor Argumenten zusammen, wie anbei erwähnt.
                </para>
            </listitem>
        </varlistentry>

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

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

    <para>
        Jeder Writer und jeder Filter hat spezifische Optionen.
    </para>

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

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

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

                    <listitem>
                        <para>
                            Eine Instanz von <classname>Zend_Db_Adapter</classname>.
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>table</term>

                    <listitem>
                        <para>
                            Der Name der Tabelle in der RDBMS welche Log Einträge enthalten soll.
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>columnMap</term>

                    <listitem>
                        <para>
                            Ein assoziatives Array welches die Namen der Spalten der
                            Datenbanktabelle mit den Feldern der Log Events verknüpft.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </sect3>

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

            <para>
                Dieser Log Writer nimmt keine Optionen; alle übergebenen werden ignoriert.
            </para>
        </sect3>

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

            <para>
                <classname>Zend_Log_Writer_Mail</classname> implementiert aktuell (mit 1.10) keine
                Factory, und wirft eine Exception wenn man versucht Ihn über
                <methodname>Zend_Log::factory()</methodname> zu instanzieren.
            </para>
        </sect3>

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

            <para>
                Dieser Log Writer nimmt keine Optionen; alle übergebenen werden ignoriert.
            </para>
        </sect3>

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

            <para>
                Dieser Log Writer nimmt keine Optionen; alle übergebenen werden ignoriert.
            </para>
        </sect3>

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

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

                    <listitem>
                        <para>
                            Ein gültiger Identifikator eines <acronym>PHP</acronym> Streams auf den
                            geloggt werden soll.
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>mode</term>

                    <listitem>
                        <para>
                            Der I/O Modus mit dem geloggt werden soll; Standardwert ist "a" für
                            "append".
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </sect3>

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

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

                    <listitem>
                        <para>
                            Der Name der Anwendung die vom Syslog Writer verwendet wird.
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>facility</term>

                    <listitem>
                        <para>
                            Die Facility die vom Syslog Writer verwendet wird.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </sect3>

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

            <para>
                Dieser Log Writer nimmt keine Optionen; alle übergebenen werden ignoriert.
            </para>
        </sect3>
    </sect2>

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

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

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

                    <listitem>
                        <para>
                            Ein regulärer Ausdruck der passen muss damit eine Nachricht geloggt
                            wird.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </sect3>

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

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

                    <listitem>
                        <para>
                            Das maximale Level der Priorität mit dem Nachrichten geloggt werden.
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>operator</term>

                    <listitem>
                        <para>
                            Der Vergleichsoperator mit dem Vergleiche der Priorität durchgeführt
                            werden; der Standardwert ist "&lt;=".
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </sect3>

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

            <para>
                Dieser Log Filter nimmt keine Optionen; alle übergebenen werden ignoriert.
            </para>
        </sect3>
    </sect2>

    <sect2 id="zend.log.factory.custom">
        <title>Erstellen konfigurierbarer Writer und Filter</title>

        <para>
            Wenn man die Notwendigkeit hat eigene Log Writer und/oder Filter zu schreiben kann man
            diese sehr einfach zu <methodname>Zend_Log::factory()</methodname> kompatibel machen.
        </para>

        <para>
            Dazu muss man mindestens <interfacename>Zend_Log_FactoryInterface</interfacename>
            implementieren, welches eine statische <methodname>factory()</methodname> Methode
            erwartet die ein einzelnes <varname>$config</varname> Argument akzeptiert. Wenn der
            eigene Log Writer <classname>Zend_Log_Writer_Abstract</classname> erweitert, oder der
            eigene Filter <classname>Zend_Log_Filter_Abstract</classname> erweitert, nimmt man das
            bereits kostenlos mit.
        </para>

        <para>
            Dann muss man einfach Verknüpfungen zwischen akzeptierten Konfigurationen und den
            Contructor Argumenten definieren. Als Beispiel:
        </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 erwartet ein Array oder eine Instanz von Zend_Config'
            );
        }

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

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

        <para>
            Alternativ könnte man die richtigen Setter nach der Instanzierung aufrufen, aber noch
            bevor die Instanz zurückgegeben wird:
        </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 erwartet ein Array oder eine Instanz von Zend_Config'
            );
        }

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