repo_zf1/documentation/manual/de/module_specs/Zend_Controller-Plugins-ErrorHandler.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect3 id="zend.controller.plugins.standard.errorhandler">
    <title>Zend_Controller_Plugin_ErrorHandler</title>

    <para>
        <classname>Zend_Controller_Plugin_ErrorHandler</classname> bietet ein Plugin für die
        Handhabung von Ausnahmen die von der Anwendung geworfen werden, inklusive denen die aus
        fehlenden Controllern oder Aktionen resultieren; das ist eine Alternative zu den Methoden
        die in der <link linkend="zend.controller.exceptions">Sektion MVC Ausnahmen</link>
        aufgeführt sind.
    </para>

    <para>
        Die primären Ziele dieses Plugins sind:
    </para>

    <itemizedlist>
        <listitem>
            <para>Abfangen von Ausnahmen welche auftreten wenn keine passende Route existiert</para>
        </listitem>

        <listitem>
            <para>
                Abfangen von Ausnahmen die durch fehlende Controller oder Aktionsmethoden auftreten
            </para>
        </listitem>

        <listitem>
            <para>Abfangen von Ausnahmen die innerhalb von Controllern aufrufen</para>
        </listitem>
    </itemizedlist>

    <para>
        Mit anderen Worten ist das <emphasis>ErrorHandler</emphasis> Plugin kreiert worden um
        <acronym>HTTP</acronym> 404 Fehler zu behandeln (fehlende Seite) und 500 Fehler (interner
        Fehler). Es ist nicht dazu gedacht Ausnahmen zu fangen die in anderen Plugins verursacht
        werden.
    </para>

    <para>
        Standardmäßig leitet <classname>Zend_Controller_Plugin_ErrorHandler</classname> auf
        <methodname>ErrorController::errorAction()</methodname> im Standardmodul weiter. Es kann
        ein alternativer Wert für dieses gesetzt werden durch Verwendung der diversen
        Zugriffsmethoden die zu dem Plugin existieren:
    </para>

    <itemizedlist>
        <listitem>
            <para>
                <methodname>setErrorHandlerModule()</methodname> setzt das Controller Modul das
                verwendet werden soll.
            </para>
        </listitem>

        <listitem>
            <para>
                <methodname>setErrorHandlerController()</methodname> setzt den Controller der
                verwendet werden soll.
            </para>
        </listitem>

        <listitem>
            <para>
                <methodname>setErrorHandlerAction()</methodname> setzt die Controller Aktion die
                verwendet werden soll.
            </para>
        </listitem>

        <listitem>
            <para>
                <methodname>setErrorHandler()</methodname> nimmt ein assoziatives Array, welches
                einen der Schlüssel 'module', 'controller', oder 'action' enthalten kann und mit
                denen es die gewünschten Werte setzt.
            </para>
        </listitem>
    </itemizedlist>

    <para>
        Zusätzlich kann ein optionales assoziatives Array an den Konstruktor übergeben werden,
        welches dann an den <methodname>setErrorHandler()</methodname> weitergeleitet wird.
    </para>

    <para>
        <classname>Zend_Controller_Plugin_ErrorHandler</classname> benötigt einen
        <methodname>postDispatch()</methodname> Hook und prüft auf Ausnahmen die im <link
            linkend="zend.controller.response">Antwort Objekt</link> registriert sind. Wenn welche
        gefunden werden, versucht es zur registrieren Fehler Handler Aktion weiterzuleiten.
    </para>

    <para>
        Wenn eine Ausnahme während der Abarbeitung des Error Handlers auftritt, teilt das Plugin dem
        Front Controller mit das eine Ausnahme geworfen werden muß, und die letzte registrierte
        Ausnahme im Antwort Objekt wird nocheinmal geworfen.
    </para>

    <sect4 id="zend.controller.plugins.standard.errorhandler.fourohfour">
        <title>Den Fehler Handler als 404 Handler verwenden</title>

        <para>
            Da das <emphasis>ErrorHandler</emphasis> Plugin nicht nur Anwendungsfehler erfasst,
            sondern auch Fehler in der Controller Kette die durch fehlende Controller Klassen
            und/oder Aktions Methoden auftreten, kann es als 404 Handler verwendet werden. Hierfür
            muß der eigene Fehler Controller den Typ der Ausnahme prüfen.
        </para>

        <para>
            Aufgefangene Ausnahmen werden in einem in der Anfrage registrierten Objekt geloggt. Um
            dieses zu empfangen kann
            <methodname>Zend_Controller_Action::_getParam('error_handler')</methodname> verwendet
            werden:
        </para>

        <programlisting language="php"><![CDATA[class ErrorController extends Zend_Controller_Action
{
    public function errorAction()
    {
        $errors = $this->_getParam('error_handler');
    }
}
]]></programlisting>

        <para>
            Sobald das Fehler Objekt vorhanden ist, kann man es über den Typ mit
            <command>$errors->type;</command> erhalten. Es wird eines der folgenden sein:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <constant>Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ROUTE</constant>,
                    zeigt das keine passende Route existiert.
                </para>
            </listitem>

            <listitem>
                <para>
                    <constant>Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_CONTROLLER</constant>,
                    zeigt das der Controller nicht gefunden wurde.
                </para>
            </listitem>

            <listitem>
                <para>
                    <constant>Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ACTION</constant>,
                    zeigt das die angefragte Aktion nicht gefunden wurde.
                </para>
            </listitem>

            <listitem>
                <para>
                    <constant>Zend_Controller_Plugin_ErrorHandler::EXCEPTION_OTHER</constant>,
                    zeigt andere Ausnahmen.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Man kann auf jeden der ersten drei Typen testen, und wenn dem so ist, eine 404 Seite
            anzeigen:
        </para>

        <programlisting language="php"><![CDATA[
class ErrorController extends Zend_Controller_Action
{
    public function errorAction()
    {
        $errors = $this->_getParam('error_handler');

        switch ($errors->type) {
            case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ROUTE:
            case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_CONTROLLER:
            case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ACTION:
                // 404 Fehler -- Controller oder Aktion nicht gefunden
                $this->getResponse()
                     ->setRawHeader('HTTP/1.1 404 Not Found');

                // ... Ausgabe für die Anzeige erzeugen...
                break;
            default:
                // Anwendungsfehler; Fehler Seite anzeigen, aber den
                // Status Code nicht ändern
                break;
        }
    }
}
]]></programlisting>

        <para>
            Letztendlich kann die Anwendung die den Fehler Handler verursacht hat, empfangen werden
            indem die <property>exception</property> Eigenschaft des
            <emphasis>error_handler</emphasis> Objektes genommen wird:
        </para>

        <programlisting language="php"><![CDATA[
public function errorAction()
{
        $errors = $this->_getParam('error_handler');

        switch ($errors->type) {
            case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ROUTE:
            case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_CONTROLLER:
            case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ACTION:
                // 404 Fehler -- Controller oder Aktion nicht gefunden
                $this->getResponse()
                     ->setRawHeader('HTTP/1.1 404 Not Found');

                // ... Ausgabe für die Anzeige erzeugen...
                break;
            default:
                // Anwendungsfehler; Fehler Seite anzeigen, aber den
                // Status Code nicht ändern

                // ...

                // Ausnahme loggen:
                $exception = $errors->exception;
                $log = new Zend_Log(
                    new Zend_Log_Writer_Stream(
                        '/tmp/applicationException.log'
                    )
                );
                $log->debug($exception->getMessage() . "\n" .
                            $exception->getTraceAsString());
                break;
        }
}
]]></programlisting>
    </sect4>

    <sect4 id="zend.controller.plugins.standard.errorhandler.buffer">
        <title>Zuvor gerenderte Ausgaben erhalten</title>

        <para>
            Wenn mehrfache Aktionen in einer Anfrage behandelt werden, oder wenn die Aktion mehrere
            Aufrufe zu <methodname>render()</methodname> macht, ist es möglich dass das Antwort
            Objekt bereits Inhalt in sich gespeichert hat. Das kann dazu führen das eine Mixtur von
            erwartetem Inhalt und Fehler Inhalt gerendert wird.
        </para>

        <para>
            Wenn Fehler innerhalb solcher Seiten gerendert werden, ist keine Änderung notwendig.
            Wenn solche Inhalte nicht gerendert werden sollen, muß der Antwort Body vor dem rendern
            jeglicher Views gelöscht werden:
        </para>

        <programlisting language="php"><![CDATA[
$this->getResponse()->clearBody();
]]></programlisting>
    </sect4>

    <sect4 id="zend.controller.plugins.standard.errorhandler.examples">
        <title>Beispiele für die Verwendung des Plugins</title>

        <example id="zend.controller.plugins.standard.errorhandler.examples.example-1">
            <title>Standardverwendung</title>

            <programlisting language="php"><![CDATA[
$front = Zend_Controller_Front::getInstance();
$front->registerPlugin(new Zend_Controller_Plugin_ErrorHandler());
]]></programlisting>
        </example>

        <example id="zend.controller.plugins.standard.errorhandler.examples.example-2">
            <title>Einen anderen Fehler Handler setzen</title>

            <programlisting language="php"><![CDATA[
$front = Zend_Controller_Front::getInstance();
$front->registerPlugin(new Zend_Controller_Plugin_ErrorHandler(array(
    'module'     => 'mystuff',
    'controller' => 'static',
    'action'     => 'error'
)));
]]></programlisting>
        </example>

        <example id="zend.controller.plugins.standard.errorhandler.examples.example-3">
            <title>Zugriffsmethoden verwenden</title>

            <programlisting language="php"><![CDATA[
$plugin = new Zend_Controller_Plugin_ErrorHandler();
$plugin->setErrorHandlerModule('mystuff')
       ->setErrorHandlerController('static')
       ->setErrorHandlerAction('error');

$front = Zend_Controller_Front::getInstance();
$front->registerPlugin($plugin);
]]></programlisting>
        </example>
    </sect4>

    <sect4 id="zend.controller.plugins.standard.errorhandler.controllerexamples">
        <title>Beispiel für den Fehler Controller</title>

        <para>
            Um das Fehler Handler Plugin zu verwenden, benötigt man einen Fehler Controller.
            Nachfolgend ist ein einfaches Beispiel.
        </para>

        <programlisting language="php"><![CDATA[
class ErrorController extends Zend_Controller_Action
{
    public function errorAction()
    {
        $errors = $this->_getParam('error_handler');

        switch ($errors->type) {
            case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ROUTE:
            case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_CONTROLLER:
            case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ACTION:
                // 404 Fehler -- Controller oder Aktion nicht gefunden
                $this->getResponse()->setRawHeader('HTTP/1.1 404 Not Found');

                $content =<<<EOH
<h1>Error!</h1>
<p>Die angefragte Seite konnte nicht gefunden werden.</p>
EOH;
                break;
            default:
                // Anwendungsfehler
                $content =<<<EOH
<h1>Fehler!</h1>
<p>Ein unerwarteter Fehler trat auf.
Bitte versuchen Sie es etwas später nocheinmal.</p>
EOH;
                break;
        }

        // Vorherige Inhalte löschen
        $this->getResponse()->clearBody();

        $this->view->content = $content;
    }
}
]]></programlisting>
    </sect4>
</sect3>