# Das Response-Objekt

## Verwendung

Das Response-Objekt ist das logische Gegenstück zum Request-Objekt. Sein Zweck ist es, Inhalte und/oder Header zu vereinigen, um sie in einem Rutsch zu versenden. Zusätzlich übergibt der FrontController alle aufgefangenen Ausnahmen an das Response-Objekt, um dem Entwickler das Verarbeiten von Ausnahmen zu ermöglichen. Diese Funktionalität kann durch Setzen von Zend_Controller_Front::throwExceptions(true) überschrieben werden.

    $front->throwExceptions(true);

Um die Ausgabe der Anwort inklusive der gesetzten Header zu senden, verwendet man sendResponse():

    $response->sendResponse();

Standardmäßig ruft der FrontController sendResponse() auf, wenn er die Anfrage fertig bearbeitet hat; nerweise wird es nie notwendig sein ihn aufzurufen. Wenn man trotzdem die Antwort manipulieren will oder sie beim Testen verwenden will, kann dieses Verhalten durch das Setzen des Flags returnResponse mit Zend_Controller_Front::returnResponse(true) geändert werden:

    $front->returnResponse(true);
    $response = $front->dispatch();

    // ein bisschen mehr verarbeiten, wie z.B. loggen...
    // und dann die Ausgabe senden:
    $response->sendResponse();

Entwickler sollten das Response-Objekt in ihren Aktions-Controllern verwenden. Statt die Ausgabe direkt zu machen und Header zu versenden, sollten diese an das Response-Objekt übergeben werden:

    // Innerhalb einer Controller Aktion:
    // Setze einen Header
    $this->getResponse()
        ->setHeader('Content-Type', 'text/html')
        ->appendBody($content);

Dadurch werden alle Header in einem Rutsch versendet, genau vor der Anzeige des Inhalts.

Wenn die View Integration des Aktions-Controllers verwendet wird, muss der bearbeitete Inhalt des View-Skripts im Response-Objekt nicht gesetzt werden, da die Zend_Controller_Action::render() das standardmäßig macht.

Sollte in der Anwendung eine Ausnahme auftreten, überprüft man den Schalter isException() des Response-Objekts und erhält die Ausnahme durch Verwendung von getException(). Zusätzlich kann man ein eigenes Response-Objekt erstellen, das zu einer Fehlerseite umleitet, die Nachricht der Ausnahme loggt, die Nachricht der Ausnahme schön formatiert ausgibt (für Entwicklungsumgebungen), usw.

Man kann das Response-Objekt im Anschluss an die Methode dispatch() des FrontControllers erhalten oder den FrontController auffordern, das Response-Objekt zurückzugeben statt den Inhalt auszugeben.

    // Erhalten nach dem Dispatch:
    $front->dispatch();
    $response = $front->getResponse();
    if ($response->isException()) {
        // log, mail, etc...
    }

    // Oder den FrontController-Dispatch-Prozess auffordern, es zurück zu geben
    $front->returnResponse(true);
    $response = $front->dispatch();

    // mach irgend was...

    // gib zum Schluß die Antwort aus
    $response->sendResponse();

Standardmäßig werden Ausnahmenachrichten nicht ausgegeben. Dieses Verhalten kann durch den Aufruf von renderException() überschrieben werden oder indem der FrontController aufgefordert wird, die Exceptions durch throwExceptions() auszuwerfen, wie oben gezeigt:

    $response->renderExceptions(true);
    $front->dispatch($request, $response);

    // oder:
    $front->returnResponse(true);
    $response = $front->dispatch();
    $response->renderExceptions();
    $response->sendResponse();

    // oder:
    $front->throwExceptions(true);
    $front->dispatch();

## Header manipulieren

Wie vorher besprochen, ist einer der Aspekte der Aufgaben des Response-Objekts das Sammeln und Abschicken der HTTP-Antwort-Header. Eine Vielzahl von Methoden existieren hierfür:

- canSendHeaders($throw = false) wird verwendet, um zu ermitteln, ob bereits Header gesendet wurden. Ein optionaler Parameter bestimmt, ob eine Ausnahme geworfen werden soll oder nicht, wenn bereits Header gesendet wurden. Das kann durch das Setzen der Eigenschaft headersSentThrowsException zu `FALSE` überschrieben werden.

- setHeader($name, $value, $replace = false) wird verwendet, um einen individuellen Header zu setzen. Standardmäßig ersetzt das keinen bereits existierenden gleichnamigen Header im Objekt; allerdings wird das Setzen von `$replace` zu `TRUE` dies erzwingen.

  Vor dem Setzen des Headers wird mit canSendHeaders() geprüft, ob diese Operation zu diesem Zeitpunkt erlaubt ist und erzwingt, dass eine Ausnahme geworfen wird.

- setRedirect($url, $code = 302) setzt einen HTTP Location Header für eine Umleitung. Wenn ein HTTP Status Code angegeben wurde, wird dieser Status Code verwendet.

  Intern wird setHeader() mit dem `$replace`-Flag aufgerufen um sicherzustellen, dass nur ein solcher Header gesendet wird.

- getHeaders() gibt ein Array aller Header zurück. Jedes Array-Element ist ein Array mit den Schlüsseln 'name' und 'value'.

- clearHeaders() löscht alle registrierten Header.

- setRawHeader() kann verwendet werden um Header zu setzen, die keine Schlüssel-und-Werte-Paare sind, wie einen HTTP Status Header.

- getRawHeaders() gibt jeden registrierten rohen Header zurück.

- clearRawHeaders() löscht jeden registrierten rohen Header.

- clearAllHeaders() löscht beide, reguläre Schlüssel-und-Werte-Header genauso wie rohe Header.

Zusätzlich zu den obigen Methoden, gibt es Zugriffsmethoden für das Setzen und Empfangen der HTTP-Antwort-Codes für die aktuellen Anfrage, setHttpResponseCode() und getHttpResponseCode().

## Benannte Segmente

Das Response-Objekt unterstützt "benannte Segmente". Das erlaubt es den Inhalt des Bodys in verschiedene Segmente zu isolieren und diese Segmente zu reihen, damit die Ausgabe in einer spezifizierten Reihenfolge zurückgegeben wird. Intern wird der Inhalt der Bodys in einem Array gespeichert und die verschiedenen Zugriffsmethoden können verwendet werden, um die Platzierung und Benennung innerhalb des Arrays zu indizieren.

Als Beispiel könnte ein preDispatch() Hook verwendet werden, um dem Response-Objekt einen Header hinzuzufügen, dann den Aktionscontroller einen Inhalt des Bodys hinzufügen zu lassen und einen postDispatch() Hook einen Footer hinzufügen zu lassen:

    // Angenommen diese Plugin Klasse ist im Front Controller registriert
    class MyPlugin extends Zend_Controller_Plugin_Abstract
    {
        public function preDispatch(Zend_Controller_Request_Abstract $request)
        {
            $response = $this->getResponse();
            $view = new Zend_View();
            $view->setBasePath('../views/scripts');

            $response->prepend('header', $view->render('header.phtml'));
        }

        public function postDispatch(Zend_Controller_Request_Abstract $request)
        {
            $response = $this->getResponse();
            $view = new Zend_View();
            $view->setBasePath('../views/scripts');

            $response->append('footer', $view->render('footer.phtml'));
        }
    }

    // Ein Beispiel Aktion Controller
    class MyController extends Zend_Controller_Action
    {
        public function fooAction()
        {
            $this->render();
        }
    }

Im obigen Beispiel wird ein Aufruf zu `/my/foo` den endgültigen Inhalt des Bodys des Antwortobjekts mit der folgenden Struktur verursachen:

    array(
        'header'  => ..., // Header Inhalt
        'default' => ..., // Body Inhalt von MyController::fooAction()
        'footer'  => ...  // Footer Inhalt
    );

Wenn das gerendert wird, wird es in der Reihenfolge gerendert, in der die Elements im Array angeordnet sind.

Eine Vielzahl von Methoden kann verwendet werden, um die benannten Segmente zu manipulieren:

- setBody() und appendBody() erlauben die Übergabe eines zweiten Werts `$name`, der ein benanntes Segment kennzeichnet. In jedem Fall wird bei der Übergabe das spezifizierte benannte Segment überschrieben oder es wird erstellt, wenn es nicht existiert (standardmäßig dem Array hinzugefügt). Wenn kein benanntes Segment an setBody() übergeben wird, setzt es den kompletten Inhalt des Body Arrays zurück. Wenn kein benanntes Segment an appendBody() übergeben wird, wird der Inhalt dem Wert im 'default' benannten Segment hinzugefügt.

- prepend($name, $content) erstellt ein benanntes Segment `$name` und platziert dieses am Beginn des Arrays. Wenn das Segment bereits existiert, wird es vor der Operation entfernt (bzw. überschrieben und ersetzt).

- append($name, $content) erstellt ein benanntes Segment `$name` und platziert es am Ende des Arrays. Wenn das Segment bereits existiert, wird es vor der Operation entfernt (bzw. überschrieben und ersetzt).

- insert($name, $content, $parent = null, $before = false) erstellt ein benanntes Segment `$name`. Wenn ein `$parent`-Segment angegeben wurde, wird das neue Segment entweder vor oder nach diesem Segment im Array platziert (basierend auf dem Wert von `$before`). Wenn das Segment bereits existiert, wird es vor der Operation entfernt (bzw. überschrieben und ersetzt).

- clearBody($name = null) entfernt ein einzelnes benanntes Segment wenn ein `$name` angegeben wurde (andernfalls das komplette Array).

- getBody($spec = false) kann verwendet werden, um ein einzelnes Array Segment zu erhalten, wenn `$spec` der Name des benannten Segments ist. Wenn `$spec` `FALSE` ist, gibt es einen String zurück, der durch Zusammenfügen aller benannten Segmente in ihrer Reihenfolge erstellt wird. Wenn `$spec` `TRUE` ist, gibt er das Array des Body Inhalts zurück.

## Testen auf Ausnahmen im Response-Objekt

Wie vorher beschrieben werden Ausnahmen standardmäßig während des Dispatchens gefangen und im Response-Objekt registriert. Ausnahmen werden in einem Stack registriert, der es erlaubt alle geworfen Ausnahmen zu speichern -- Anwendungsausnahmen, Dispatch-Ausnahmen, Plugin-Ausnahmen, usw. Wenn man auf bestimmte Ausnahmen prüfen oder Ausnahmen loggen will, muß man die Ausnahme-API des Response-Objekts verwenden:

- setException(Exception $e) erlaubt es, eine Ausnahme zu registrieren.

- isException() sagt, ob eine Ausnahme bereits registriert wurde.

- getException() gibt den kompletten Ausnahme-Stack zurück.

- hasExceptionOfType($type) erlaubt es festzustellen, ob eine Ausnahme einer speziellen Klasse im Stack vorhanden ist.

- hasExceptionOfMessage($message) erlaubt es festzustellen, ob eine Ausnahme mit einer speziellen Nachricht im Stack vorhanden ist.

- hasExceptionOfCode($code) erlaubt es festzustellen, ob eine Ausnahme mit einem bestimmten Code im Stack vorhanden ist.

- getExceptionByType($type) erlaubt es, alle Ausnahmen einer speziellen Klasse vom Stack zu erhalten. `FALSE` wird zurückgegeben wenn keine gefunden wurden, und andernfalls ein Array mit Ausnahmen.

- getExceptionByMessage($message) erlaubt es, alle Ausnahmen mit einer speziellen Nachricht vom Stack zu erhalten. `FALSE` wird zurückgegeben, wenn keine gefunden wurden, und andernfalls ein Array mit Ausnahmen.

- getExceptionByCode($code) erlaubt es, alle Ausnahmen mit einem speziellen Code vom Stack zu erhalten. `FALSE` wird zurückgegeben, wenn keine gefunden wurden, und andernfalls ein Array mit Ausnahmen.

- renderExceptions($flag) erlaubt es ein Flag zu setzen, das anzeigt, ob die Ausnahmen ausgegeben werden sollen, wenn die Antwort gesendet wurde oder nicht.

## Erben vom Response-Objekt

Der Zweck des Response-Objekts ist es, Header und Inhalte von den verschiedenen Aktionen und Plugins zu sammeln und diese an den Client zurückzugeben; zweitens sammelt es in der Reihenfolge ihres Auftretens alle Fehler (Ausnahmen) und gibt diese zurück oder versteckt sie vor dem Endbenutzer.

Die Basis-Antwortklasse ist Zend_Controller_Response_Abstract, und jede erbende Klasse, die erstellt wird, sollte von dieser Klasse oder eine ihrer Derivate erben. Die verschiedenen vorhandenen Methoden wurden im vorhergehenden Abschnitt aufgezählt.

Die Gründe eine Subklasse des Response-Objekts zu erstellen beinhalten das Ändern wie eine Ausgabe zurückgegeben wird, basierend auf der Antwortumgebung (z.B., keine Header senden für CLI oder PHP-GTK-Anfragen), zusätzliche Funktionalitäten um eine endgültige Ansicht zurückzugeben, basierend auf Inhalt, der in benannten Segmenten gespeichert wurde, usw.