# Action Controllers

## Wprowadzenie

`Zend_Controller_Action` jest klasą abstrakcyjną, której możesz użyć do implementacji kontrolerów akcji, których wraz z kontrolerem frontowym użyjesz do budowania aplikacji opartej na wzorcu Model-View-Controller (MVC).

Aby użyć klasy `Zend_Controller_Action`, powinieneś ją rozszerzyć w swoich klasach kontrolerów akcji (lub rozszerzyć ją aby utworzyć swoją własną bazową klasę dla kontrolerów akcji). Najbardziej podstawową operacją jest rozszerzenie tej klasy oraz utworzenie metod akcji, które odpowiadają różnym akcjom jakie ma obsługiwać kontroler na twojej stronie. Obsługa routingu i uruchamiania w Zend_Controller automatycznie przeszuka wszystkie metody twojej klasy, których nazwa zakończona jest wyrazem 'Action', aby znaleźć odpowiednią akcję kontrolera.

Na przykład, załóżmy, że twoja klasa jest zdefiniowana w ten sposób:

    class FooController extends Zend_Controller_Action
    {
        public function barAction()
        {
            // zrób coś
        }

        public function bazAction()
        {
            // zrób coś
        }
    }

Powyższa klasa `FooController` (kontroler `foo`) definiuje dwie akcje, `bar` oraz `baz`.

Można tu osiągnąć dużo więcej, na przykład: utworzyć własne akcje inicjalizacyjne, utworzyć domyślne akcje do wywołania gdy nie ma określonej akcji (lub określona jest nieprawidłowa), użyć metod pre- oraz post-dispatch oraz użyć wielu różnych metod pomocników. Ten rozdział jest rozeznaniem w funkcjonalnościach kontrolera akcji.

### Domyślne zachowanie

Domyślnie kontroler frontowy włącza klasę pomocniczą akcji ViewRenderer. Ta klasa zajmuje się przekazywaniem widoku do kontrolera, a także automatycznym renderowaniem widoków. Możesz to wyłączyć w swoim kontrolerze akcji używając jednej z poniższych metod:

    class FooController extends Zend_Controller_Action
    {
        public function init()
        {
            // Lokalnie, tylko dla tego kontrolera; affects all actions, as loaded in init:
            $this->_helper->viewRenderer->setNoRender(true);

            // Globalnie:
            $this->_helper->removeHelper('viewRenderer');

            // Także globalnie, but would need to be in conjunction with the local
            // version in order to propagate for this controller:
            Zend_Controller_Front::getInstance()->setParam('noViewRenderer', true);
        }
    }

`initView()`, `getViewScript()`, `render()`, and `renderScript()` each proxy to the `ViewRenderer` unless the helper is not in the helper broker or the `noViewRenderer` flag has been set.

Możesz także w prosty sposób wyłączyć renderowanie dla konkretnego widoku ustawiając flagę `noRender` w klasie `ViewRenderer`:

    class FooController extends Zend_Controller_Action
    {
        public function barAction()
        {
            // wyłączamy automatyczne renderowanie tylko dla tej akcji:
            $this->_helper->viewRenderer->setNoRender();
        }
    }

Możesz chcieć wyłączyć klasę `ViewRenderer` jeśli nie potrzebujesz obiektu widoku lub jeśli nie chcesz renderować skryptów widoku. (na przykład jeśli używasz kontrolera akcji aby obsługiwać żądania do webserwisu takie jak SOAP, XML-RPC czy REST). W większości przypadków nie będziesz potrzebować wyłączać globalnie renderowania klasy `ViewRenderer`, wystarczy selektywne wyłączenie wewnątrz pojedynczego kontrolera lub akcji.

## Inicjalizacja obiektu

O ile zawsze możesz nadpisać konstruktor kontrolera akcji, nie zalecamy tego. Zend_Controller_Action::__construct() przeprowadza kilka ważnych zadań, takich jak zarejestrowanie obiektów żądania i odpowiedzi, oraz przekazanie argumentów wywołania przez kontroler frontowy. Jeśli musisz nadpisać konstruktor, upewnij się że wywołasz metodę `parent::__construct($request, $response, $invokeArgs)`.

Bardziej odpowiednim sposobem skonfigurowania instancji jest użycie metody `init()`, która jest wywoływana jako ostatnie zadanie konstruktora `__construct()`. Na przykład jeśli chcesz połączyć się z bazą danych:

    class FooController extends Zend_Controller_Action
    {
        public function init()
        {
            $this->db = Zend_Db::factory('Pdo_Mysql', array(
                'host'     => 'myhost',
                'username' => 'user',
                'password' => 'XXXXXXX',
                'dbname'   => 'website'
            ));
        }
    }

## Metody Pre-Dispatch oraz Post-Dispatch

Klasa `Zend_Controller_Action` definiuje dwie metody, `preDispatch()` oraz `postDispatch()`, które mogą być wywołane przed i po wywołaniu akcji. Mogą one być użyteczne w wielu sytuacjach: weryfikowanie autentykacji oraz kontroli dostępu ACL odnośnie uruchamianej akcji, (przez wywołanie metody `_forward()` w metodzie `preDispatch()`, dzięki czemu akcja może być pominięta), lub na przykład umieszczenie wygenerowanej zawartości w głównym szablonie (`postDispatch()`).

## Metody dostępowe

W obiekcie zarejestrowanych jest wiele obiektów oraz zmiennych i wszystkie mają metody dostępowe..

- Obiekt żądania: metoda `getRequest()` może być użyta do odebrania obiektu żądania używanego do wywoływania akcji.

- Obiekt odpowiedzi: metoda `getResponse()` może być użyta do odebrania obiektu odpowiedzi przechowującego finalną odpowiedź. Niektóre typowe wywołania mogą wyglądać tak:

      $this->getResponse()->setHeader('Content-Type', 'text/xml');
      $this->getResponse()->appendBody($content);

- Argumenty wywołania: kontroler frontowy może przekazać parametry do routera, obiektu uruchamiającego oraz do kontrolera akcji. Aby je odebrać użyj metody `getInvokeArg($key)`; alternatywnie pobierz całą listę używając metody `getInvokeArgs()`.

- Parametry żądania: Obiekt żądania przechowuje parametry żądania takie jak dowolne parametry z tablic _GET lub _POST oraz parametry użytkownika zdefiniowane w ścieżce adresu URL. Aby je odebrać, użyj metody `_getParam($key)` lub `_getAllParams()`. Możesz także ustawić parametry żądania używając metody `_setParam()`; jest to użyteczne gdy przenosimy do innych akcji.

  Aby sprawdzić czy parametr istnieje czy nie (co jest użyteczne przy wywołaniach logicznych), użyj `_hasParam($key)`.

  Metoda `_getParam()` może pobierać opcjonalny drugi argument zawierający domyślną wartość, ktora zostanie użyta, jeśli parametr nie został zdefiniowany lub jeśli jest pusty. Użycie drugiego parametru powoduje, że wywołanie metody `_hasParam()` przed odebraniem parametru nie jest konieczne:

      // Użyj domyślnej wartości 1 jeśli parametr id jest pusty
      $id = $this->_getParam('id', 1);

      // Zamiast:
      if ($this->_hasParam('id') {
          $id = $this->_getParam('id');
      } else {
          $id = 1;
      }

## Integracja z widokiem

`Zend_Controller_Action` provides a rudimentary and flexible mechanism for view integration.

Odpowiadają za to dwie metody, `initView()` oraz `render()`;

the former method lazy-loads the `$view` public property, and the latter renders a view based on the current requested action, using the directory hierarchy to determine the script path.

### Inicjowanie obiektu widoku

Metoda `initView()` inicjuje obiekt widoku. Metoda `render()` wywołuje `initView()` w celu odebrania obiektu widoku, ale może on być zainicjowany w dowolnym momencie; domyślnie przypisuje ona do właściwości `$view` obiekt klasy `Zend_View`, ale może być użyta dowolna klasa implementująca interfejs `Zend_View_Interface`. Jeśli obiekt `$view` jest już zainicjowany, metoda po prostu zwróci ten obiekt.

Domyślna implementacja zakłada taką strukturę katalogów:

    applicationOrModule/
        controllers/
            IndexController.php
        views/
            scripts/
                index/
                    index.phtml
            helpers/
            filters/

Innymi słowy, założone jest, że skrypty widoków znajdują się w podkatalogu `views/scripts/`, a podkatalog `views` zawiera poboczne funkcjonalności (klasy pomocnicze, filtry). Gdy określana jest nazwa skryptu oraz ścieżka, katalog `views/scripts/` jest używany jako katalog bazowy. Zawiera on katalogi o nazwach pochodzących od kontrolerów, co zapewnia hierarchię skryptów widoków.

### Renderowanie widoków

Metoda `render()` ma taką sygnaturę:

    string render(string $action = null, string $name = null, bool $noController = false);

`render()` renderuje skrypt widoku. Jeśli nie przekazano argumentów, zakładane jest, że ścieżka skryptu to `[kontroler]/[akcja].phtml` (gdzie `.phtml` jest wartością właściwości `$viewSuffix`). Przekazanie wartości parametru `$action` spowoduje zrenderowanie tego szablonu z podkatalogu `[kontroler]`. Aby zrezygnować z użycia podkatalogu `[kontroler]`, przekaż logiczną wartość true dla `$noController`. Na koniec szablony są renderowane i przekazywane do obiektu odpowiedzi; jeśli chcesz zrenderować do konkretnego nazwanego segmentu w obiekcie odpowiedzi, przekaż wartość dla parametru `$name`.

Z tego względu, że nazwy kontrolera i akcji mogą zawierać takie rozgraniczające znaki jak '_', '.', oraz '-', metoda render() zamienia je wszystkie na '-' gdy określa nazwę skryptu. Wewnętrznie, do przeprowadzenia tej operacji używane są znaki rozgraniczające słowa oraz ścieżki z obiektu uruchamiającego. Dlatego żądanie do `/foo.bar/baz-bat` zrenderuje skrypt `foo-bar/baz-bat.phtml`. Jeśli nazwa metody akcji jest w postaci camelCasing, zapamiętaj, że spowoduje to rozdzieleniem słów za pomocą znaku '-' podczas określania nazwy pliku skryptu widoku.

Kilka przykładów:

    class MyController extends Zend_Controller_Action
    {
        public function fooAction()
        {
            // Renderuje my/foo.phtml
            $this->render();

            // Renderuje my/bar.phtml
            $this->render('bar');

            // Renderuje baz.phtml
            $this->render('baz', null, true);

            // Renderuje my/login.phtml w segmencie 'form' obiektu odpowiedzi
            $this->render('login', 'form');

            // Renderuje site.phtml w segmencie 'page' obiektu odpowiedzi;
            // nie używa podkatalogu 'my/'
            $this->render('site', 'page', true);
        }

        public function bazBatAction()
        {
            // Renderuje my/baz-bat.phtml
            $this->render();
        }
    }

## Metody narzędziowe

Oprócz metod dostępowych i metod integracji z widokiem, klasa `Zend_Controller_Action` posiada kilka metod narzędziowych używanych do przeprowadzania ważnych zadań wewnątrz twoich metod akcji (lub wewnątrz metod pre-/post-dispatch).

- `_forward($action, $controller = null, $module = null, array $params = null)`: wykonuje inną akcję. Jeśli zostanie wywołana w metodzie `preDispatch()`, obecnie zażądana akcja zostanie pominięta, na rzecz nowej akcji. W przeciwnym wypadku, po wykonaniu obecnej akcji, będzie wywołana akcja zażądana w metodzie _forward().

- `_redirect($url, array $options = array())`: przekierowuje do innej lokacji. Ta metoda przyjmuje w parametrze URL oraz opcjonalny zestaw opcji. Domyślnie przeprowadzane jest przekierowanie HTTP 302.

  Zestaw opcji może zawierać jeden lub więcej z poniższych kluczy:

  - exit: określa czy skrypt ma zakończyć działanie od razu po przekierowaniu. Jeśli tak, to skrypt zamknie wszystkie otwarte sesje i przeprowadzi przekierowanie.

    Możesz ustawić tę opcję globalnie wewnątrz kontrolera używając metody dostępowej `setRedirectExit()`.

  - prependBase: określa czy bazowy adres URL zarejestrowany w obiekcie żądania ma być dołączony do adresu URL przekierowania.

    Możesz ustawić tę opcję globalnie wewnątrz kontrolera używając metody dostępowej `setRedirectPrependBase()`.

  - code: kod HTTP do użycia podczas przekierowania. Domyślnie użyty jest kod HTTP 302; może być użyty dowolny kod pomiędzy 301 a 306.

    Możesz ustawić tę opcję globalnie wewnątrz kontrolera używając metody dostępowej `setRedirectCode()`.

## Rozszerzanie klasy kontrolera akcji

By design, `Zend_Controller_Action` must be subclassed in order to create an action controller. At the minimum, you will need to define action methods that the controller may call.

Besides creating useful functionality for your web applications, you may also find that you're repeating much of the same setup or utility methods in your various controllers; if so, creating a common base controller class that extends `Zend_Controller_Action` could solve such redundancy.

### Jak obsługiwać nieistniejące akcje

Jeśli zażądamy nieistniejącej akcji kontrolera, wywołana zostanie metoda `Zend_Controller_Action::__call()`. Metoda `__call()` jest oczywiście magiczną metodą PHP służącą do przeładowania metod.

Domyślnie, ta metoda wyrzuca wyjątek `Zend_Controller_Action_Exception` oznaczający, że zażądana metoda nie została znaleziona w kontrolerze. Jeśli nazwa zażądanej metody zakończona jest słowem 'Action', zakładane jest, że zażądana została akcja i że ona nie istnieje; taki błąd powoduje wyrzucenie wyjątku z kodem 404. Próby wywołania wszystkich innych metod powodują wyrzucenie wyjątku z kodem 500. Pozwala to na rozróżnienie błędu nie znalezionej strony od innych błędów aplikacji.

Na przykład, jeśli chcesz wyświetlić informacje o błędzie, możesz zrobić to w taki sposób:

    class MyController extends Zend_Controller_Action
    {
        public function __call($method, $args)
        {
            if ('Action' == substr($method, -6)) {
                // Jeśli metoda akcji nie została znaleziona, renderuje szablon informujący o błędzie
                return $this->render('error');
            }

            // wszystkie inne metody wyrzucają wyjątek
            throw new Exception('Invalid method "' . $method . '" called', 500);
        }
    }

Inną możliwością jest przeniesienie do domyślnego kontrolera:

    class MyController extends Zend_Controller_Action
    {
        public function indexAction()
        {
            $this->render();
        }

        public function __call($method, $args)
        {
            if ('Action' == substr($method, -6)) {
                // Jeśli metoda akcji nie została znaleziona, przenieś do akcji index
                return $this->_forward('index');
            }

            // wszystkie inne metody wyrzucają wyjątek
            throw new Exception('Invalid method "' . $method . '" called', 500);
        }
    }

Besides overriding `__call()`, each of the initialization, utility, accessor, view, and dispatch hook methods mentioned previously in this chapter may be overridden in order to customize your controllers. As an example, if you are storing your view object in a registry, you may want to modify your `initView()` method with code resembling the following:

    abstract class My_Base_Controller extends Zend_Controller_Action
    {
        public function initView()
        {
            if (null === $this->view) {
                if (Zend_Registry::isRegistered('view')) {
                    $this->view = Zend_Registry::get('view');
                } else {
                    $this->view = new Zend_View();
                    $this->view->setBasePath(dirname(__FILE__) . '/../views');
                }
            }

            return $this->view;
        }
    }

Hopefully, from the information in this chapter, you can see the flexibility of this particular component and how you can shape it to your application's or site's needs.