Документация InstantCMS

для администраторов и разработчиков

Инструменты пользователя

Инструменты сайта


dev:controllers:actions

Действия контроллеров

Контроллер представляет из себя класс, наследуемый от системного класса cmsFrontend или cmsBackend для публичной и административной части сайта соответственно.

Здесь и далее мы будем рассматривать все на примере frontend-контроллера. Особенности реализации backend-контроллера будут рассмотрены в отдельной статье.

Класс контроллера

Класс определяется в файле /system/controllers/{имя компонента}/frontend.php.

В простейшем случае класс выглядит так:

class shop extends cmsFrontend { }

где shop - название компонента, совпадающие с названием его папки.

Определение действий

Действие контроллера (экшен) - это дочерний метод класса контроллера, обрабатывающий запросы пользователя через URL.

Например, пользователь открывает страницу site.ru/shop/catalog/view/123. Роутер InstantCMS произведет разбор данного адреса на составные части:

  • shop - компонент, frontend-контроллер которого нужно запустить
  • catalog - экшен контроллера, который нужно вызвать
  • все что далее, в нашем случае view и 123 - параметры, которые нужно передать экшену

Таким образом, чтобы обработать подобный URL мы должны создать файл /system/controllers/shop/frontend.php со следующим содержимым:

class shop extends cmsFrontend {
 
    public function actionCatalog($do, $id){
        dump("Hello, do = {$do}, id = {$id}");
    }
 
}

В результате, после открытия URL site.ru/shop/catalog/view/123 пользователь увидит в браузере текст:

Hello, do = view, id = 123

Разумеется, в реальности экшен не должен совершать вывод на экран с помощью dump() или echo. Вместо этого используются шаблоны, работа с которыми будет рассмотрена в следующих разделах.

Индексное действие

В случаях, когда в URL содержится только название компонента, без указания экшена будет вызван метод actionIndex().

Названия действий

Название метода каждого экшена в контроллере формируется по принципу: action{Name}, где {Name} - полученный из URL идентификатор экшена.

В URL название экшена может состоять из нескольких слов, разделенных знаком подчеркивания (_). В этом случае название метода формируется по принципу: action{ManyWordsName}. Каждая заглавная буква в {ManyWordsName} соответствует знаку подчеркивания в URL.

Примеры преобразования имен:

URL Контроллер Метод контроллера
site.ru/shop shop actionIndex()
site.ru/shop/catalog shop actionCatalog()
site.ru/shop/view_order shop actionViewOrder()
site.ru/shop/add_many_items shop actionAddManyItems()

Действия во внешних файлах

Экшены могут быть определены как внутри класса контроллера (в файле frontend.php), так и в собственных отдельных файлах. В случаях, когда контроллер содержит большое количество объемных экшенов целесообразнее вынести их в отдельные файлы.

Файлы хранятся в папке /system/controllers/{имя компонента}/actions.

Название файла должно совпадать с названием экшена в URL страницы.

Например, рассмотренный выше экшен actionCatalog() для компонента shop может быть вынесен в файл /system/controllers/shop/actions/catalog.php.

Внутри файла должен быть определен класс action{Имя компонента}{Название экшена}, наследуемый от системного класса cmsAction:

class actionShopCatalog extends cmsAction { } 

Внутри класса должен быть определен метод run():

class actionShopCatalog extends cmsAction {
 
    public function run($do, $id){
 
        dump("Hello from file! Do = {$do}, id = {$id}");
 
    }
 
}

Метод run() принимает параметры экшена из URL, аналогично с тем, как это делал сам экшен когда был определен в frontend.php.

Важным моментом в данном случае является то, что внутри метода run() доступны все методы и свойства самого контроллера (класса, определенного в frontend.php) через $this.

Например, frontend.php:

class example extends cmsFrontend {
 
    public $my_name = 'John';
 
    public function sayHello($your_name) {
        dump("Hello, {$your_name}!", false);
    }
 
 
}

actions/hello.php:

class actionExampleHello extends cmsAction {
 
    public function run(){
 
        $this->sayHello('Vasiliy');
 
        dump("My name is {$this->my_name}");
 
    }
 
}

В этом случае обращение по URL site.ru/example/hello выведет:

Hello, Vasiliy!
My name is John

Таким образом, код который должен быть доступен внутри любого экшена (не зависимо от его расположения) можно размещать внутри класса контроллера.

Иногда, по каким-то причинам разработки, необходимо написать экшен, который будет вызываться из других контроллеров или иным способом, но не напрямую через URL. Для того, чтобы защититься от прямых вызовов таких экшенов существует свойство $lock_explicit_call. Установите его в true.

class actionUsersProfile extends cmsAction {
 
    public $lock_explicit_call = true;
 
    public function run(){
 
        // PHP code
 
    }
 
}

Действия before и after

Иногда может потребоваться выполнить одинаковый код в начале или конце каждого экшена (например, провести какую-либо инициализацию или очистку). В этом случае нет необходимости дублировать код в каждом экшене. Вместо этого можно объявить специальные методы before() и after() в теле контроллера.

Пример:

class shop extends cmsFrontend {
 
    public function before($action_name){
 
        // Эта строка обязательна
        parent::before($action_name);
 
        // Код внутри этого метода будет выполнен 
        // ПЕРЕД запуском любого экшена контроллера
        dump("Before: {$action_name}", false);
 
        return true;
 
    }
 
    public function after($action_name){
 
        // Эта строка обязательна
        parent::after($action_name);
 
        // Код внутри этого метода будет выполнен 
        // ПОСЛЕ запуска любого экшена контроллера
        dump("After: {$action_name}");
 
    }
 
    public function actionCatalog($do, $id){
 
        dump("do = {$do}, id = {$id}", false);
 
    }
 
}

Методы before() и after() имеют входящий параметр - название экшена до/после которого они вызываются. Это позволяет разграничить логику для каждого конкретного экшена.

Таким образом, для нашего примера, если пользователь откроет URL site.ru/shop/catalog/view/123 он получит вывод:

Before: catalog
do = view, id = 123
After: catalog

Метод before() должен возвращать true или false. Если он вернет false - вызываемый экшен не будет выполнен, но никаких ошибок при этом также не будет показано. Если внутри before() необходимо выдать 404 ошибку, то необходимо использовать метод ядра:

cmsCore::error404();

Изменение роутинга

Иногда может потребоваться изменить системную логику роутинга экшенов.

Например, мы захотим чтобы адреса профилей пользователей на сайте имели вид: site.ru/users/{id}, где {id} - идентификатор пользователя в базе. В этом случае мы получим множество разных адресов:

  • site.ru/users/1
  • site.ru/users/24
  • site.ru/users/6
  • и так далее

Стандартный роутер при обращении, например, к адресу site.ru/users/24 будет пытаться вызвать метод action24() в контроллере компонента users. Нам же в данном случае нужно, чтобы второй сегмент в URL отвечал не за название экшена, а за параметр какого-либо из них.

Мы можем определить собственный метод для роутинга, внутри контроллера:

class users extends cmsFrontend {
 
    public function routeAction($action_name){
 
        // Если название вызываемого экшена состоит НЕ из одних цифр,
        // то возвращаем исходное название, как ни в чем не бывало
        if (!is_numeric($action_name)){ return $action_name; }
 
        // иначе, понимаем что в $action_name на самом деле id пользователя
        $user_id = $action_name;
 
        // сохраняем полученный ID как первый параметр для того экшена,
        // на который будет перенаправлять работу
        array_unshift($this->current_params, $action_name);
 
        // возвращаем название нужного экшена
        return 'view_profile';
 
    }
 
    public function actionViewProfile($id) {
 
        if (!is_numeric($id)) { cmsCore::error404(); }    
 
        dump("Это профиль пользователя ID = {$id}");    
 
    }    
 
}

Метод routeAction() запускается до вызова указанного в URL экшена (но после before()). В качестве аргумента он принимает название экшена, определенное системным роутером. Далее этот метод может совершать любые нужные проверки. В итоге он должен вернуть название экшена который будет вызван.


Вернуться к оглавлению

dev/controllers/actions.txt · Последние изменения: 02.09.2016 09:57 — fuze