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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 15103 -->
<!-- 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 Kontrollern 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 die durch fehlende Kontroller oder Aktionsmethoden auftreten</para>
        </listitem>

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

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

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

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

        <listitem>
            <para>
                <code>setErrorHandlerController()</code> setzt den Kontroller der verwendet werden soll.
            </para>
        </listitem>

        <listitem>
            <para>
                <code>setErrorHandlerAction()</code> setzt die Kontroller Aktion die verwendet werden soll.
            </para>
        </listitem>

        <listitem>
            <para>
                <code>setErrorHandler()</code> 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
        <code>setErrorHandler()</code> weitergeleitet wird.
    </para>

    <para>
        <classname>Zend_Controller_Plugin_ErrorHandler</classname> benötigt einen <code>postDispatch()</code> 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ärend der Abarbeitung des Error Handlers auftritt, teilt das Plugin dem Front Kontroller
        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 <code>ErrorHandler</code> Plugin nicht nur Anwendungsfehler erfasst, sondern auch Fehler in der
            Kontroller Kette die durch fehlende Kontroller Klassen und/oder Aktions Methoden auftreten, kann es
            als 404 Handler verwendet werden. Hierfür muß der eigene Fehler Kontroller den Typ der Ausnahme prüfen.
        </para>

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

        <programlisting role="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 <code>$errors->type</code>
            erhalten. Es wird eines der folgenden sein:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <classname>Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_CONTROLLER</classname>,
                    zeigt das der Kontroller nicht gefunden wurde.
                </para>
            </listitem>

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

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

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

        <programlisting role="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_CONTROLLER:
            case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ACTION:
                // 404 Fehler -- Kontroller 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
            <code>exception</code> Eigenschaft des <code>error_handler</code> Objektes genommen wird:
        </para>

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


        switch ($errors->type) {
            case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_CONTROLLER:
            case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ACTION:
                // 404 Fehler -- Kontroller 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
            <code>render()</code> macht, ist es möglich das das Antwort Objekt bereits Inhalt in sich gespeichert
            hat. Das kann dazu führen das eine Mixtur vin 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 role="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 role="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 role="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 role="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 Kontroller</title>

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

        <programlisting role="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_CONTROLLER:
            case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ACTION:
                // 404 Fehler -- Kontroller 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>
<!--
vim:se ts=4 sw=4 et:
-->