Klasa \core\Router jest wykorzystana przez framework Amelia do stworzenia obiektu rutera - jednego z najważniejszych mechanizmów środowiska, który jest tworzony automatycznie. Jest on dostępny poprzez App::getRouter().

Obiekt routera pozwala zdefiniować routing oraz inicjuje wykonanie akcji za pomocą swojej metody go(). Musi być ona zawsze wykonana po zdefiniowaniu routingu we front controlerze. Inaczej nie wykona się żadna akcja.

Klasa \core\Router wykorzystuje wewnętrznie obiekty klasy \core\Route, reprezentujące ścieżki. Są to trywialne obiekty przechowujące informacje na temat danej ścieżki. Ponadto użytkownik ich nie wykorzystuje bezpośrednio, zatem ta klasa nie będzie opisana w dokumentacji.

Podstawowe użycie klasy routera na cele routingu można zobaczyć w tutorialu >>.

Metody klasy \core\Router dostępne dla użytkownika

public function addRoute($action, $controller, $roles = null)

Metoda pozwalająca dodać ścieżkę routingu w uproszczony sposób. $action określa nazwę akcji, $controller to nazwa klasy kontrolera w domyślnej lokalizacji, a opcjonalny parametr $roles zawiera jedną lub więcej nazw ról (więcej w postaci tabeli PHP). Metoda kontrolera w tej wersji jest domyślna i ma postać "action_".$action (przedrostek "action_" i nazwa akcji).

Gdy rola lub role nie zostaną podane to akcja traktowana jest jako publiczna (każdy może ją wywołać).

Przykład: App::getRouter()->addRoute("main", "MainController", ["admin", "user"]); doda ścieżkę do routingu, która dla akcji "main" wywoła metodę action_main() w kontrolerze klasy MainController.

public function addRouteEx($action, $namespace, $controller, $method, $roles = null)

Podobnie do addRoute() metoda dodaje ścieżkę do routingu, jednak pozwala dodatkowo podać przestrzeń nazw kontrolera (niestandardowe umieszczenie) oraz metodę akcji (niekoniecznie nazwaną z przedroskiem "action_"). Reszta parametrów ma takie samo znaczenie.

public function forwardTo($action_name)

Metoda przekazuje sterowanie do wybranej akcji, co oznacza, że ciąg działania skryptów nie zostaje przerwany, tylko ponownie, dla podanej nowej akcji, wywołana zostanie metoda go() kontrolera.

Wykorzystywana w kontrolerach gdy z jakiegoś powodu (np. w wyniku błędu lub wygenerowania innego widoku) konieczne jest wykonanie innej akcji.

Przykład: App::getRouter()->forwardTo("main"); przekieruje (wykona) akcję "main"

public function getAction(), setAction($action)

Pobierz, ustaw akcję. Pobrać akcję można w celach informacyjnych - np w kontrolerze wykonując jakieś działania. Ustawianie akcji jest wykorzystywane wewnętrznie przez system. Raczej nie powinno być przydane dla użytkownika. W celu przekierowania używaj forwardTo() lub redirectTo().

public function getDefaultRoute(), setDefaultRoute($action_name)

Pobierz, ustaw domyślną ścieżkę. Ustawianie domyślnej ścieżki jest potrzebne praktycznie zawsze. Wywoła się ona wtedy gdy podana w URL akcja nie istnieje lub jest nieznana.

Ustalanie domyślnej ścieżki odbywa się przy definiowaniu routingu. Przykład: App:getRouter()->setDefaultRoute("main") ustali ścieżkę dla akcji "main" jako domyślną

Pobieranie może być przydatne raczej tylko w celach informacyjnych.

public function getLoginRoute(), setLoginRoute($action_name)

Pobierz, ustaw ścieżkę dla obsługi braku uprawnień (z reguły jest to akcja logowania do systemu). Ustawienie pozwala zdefiniować ścieżkę, która zostanie domyślnie wywołana (sterowanie przekierowane na nią) gdy zostanie wywołana pewna akcja niepubliczna (ze zdefiniowanymi rolami), a użytkownik zdalny nie będzie takowej roli posiadał.

Przykład: App::getRouter()->setLoginRoute("noPermission") przygotuje routing do przejścia na akcję "noPermission", gdy ktoś nie będzie posiadał wymaganych uprawnień (roli).

Pobieranie może być przydatne raczej tylko w celach informacyjnych.

public function go()

Metoda uruchamiająca mechanizm routingu. W zdefiniowanych ścieżkach wybierana jest ta dopasowana do aktualnej akcji (ustawionej automatycznie lub jawnie za pomocą setAction()) i wywoływana jest skonfigurowana metoda ustalonego w ścieżce kontrolera. Gdy akcja nie jest zdefiniowana w routingu to wykonywana jest akcja domyślna. Jeśli i ta nie jest określona to rzucany jest wyjątek \Exception ze stosownym komunikatem.

Jeśli zdefiniowany w uruchamianej akcji kontroler jest niedostępny (brak pliku, zła nazwa pliku, zła nazwa klasy lub przestrzeni nazw) to zostanie rzucony wyjątek systemowy ze stosownym komunikatem.

Gdy kontroler istnieje, ale router nie znajdzie w nim zdefiniowanej metody akcji, to również zostanie rzucony wyjątek \Exception ze stosownym komunikatem.

Mechanizm uwzględnia również weryfikację uprawnień i automatyczne przekierowanie na akcję ustalaną przez setLoginRoute() w razie braku uprawnień.

public function redirectTo($action_name, $header = null)

Podobnie do forwardTo(), jednak metoda przekierowuje, czyli odsyła do przeglądarki odpowiedź z nagłówkiem "Location: <url_do_wybranej_akcji>" (typowy redirect).

Domyślne użycie tej metody zakłada nagłówek "Location", jednak można go zmienić podając inny (parametr $header). Można to wykorzystać do przekierowania w aplikacjach AJAXowych.

Metoda wykorzystywana jest w kontrolerach gdy z jakiegoś powodu (np. w wyniku błędu lub wygenerowania innego widoku) konieczne jest przekierowanie przeglądarki do innej akcji. Tak aby URL w przeglądarce odpowiadał pożądanej wartości.

Przykład: App::getRouter()->redirectTo("main"); przekieruje przeglądarkę do akcji "main".

Metody klasy \core\Router na wewnętrzne potrzeby Amelii

__construct(&$config)

Konstruktor przyjmujący obiekt konfiguracji systemu.

private function control($namespace, $controller, $method, $roles = null)

Prywatna funkcja na wewnętrzne potrzeby Routera, pozwalająca wywołać metodę kontrolera z uwzględnieniem kontroli ról.