Маршрутизация

Статистика: Символов — 10 589/9 014 без пробелов (6 962/5 989 без кода):, слов — 974
Разметка: Wiki
{{TOC}}

== Основы ==
В Laravel используются последние возможности PHP 5.3 для создания простой и понятной маршрутизации. Благодаря этому, с одинаковой легкостью можно проектировать, как простые веб-приложения, так и сложные программные интерфейсы. //Маршруты// обычно задаются в **application/routes.php**.

В отличии от других сред программирования для PHP в Laravel //маршрутизация// может делаться двумя способами. **((docs/v3/controllers Контроллеры))** - самый распространённый шаблон проектирования, однако кроме них вы можете встраивать свой код напрямую в //маршруты//. Эта возможность //особенно// полезна, если вы пишите небольшой сайт всего на пару страниц и не хотите создавать пачку ((docs/v3/controllers контроллеров)) с дюжиной методов, либо свалить все методы в один //контроллер// и затем вручную направлять запросы, которые к нему поступают.

В примере ниже **первый параметр** - адрес //маршрута//, который вы регистрируете в маршрутизаторе (**Router**). **Второй параметр** - функция, содержащая логику для этого //маршрута//. //Маршруты// регистрируются **без задания ведущего слеша (%%(t)/%%)** - единственное исключение - //корневой маршрут//, который состоит из одного слеша (%%'/'%%).

.(alert)
//Маршруты// обрабатываются в порядке их регистрации, поэтому "всеядный" ("catch-all") //маршрут// должен быть зарегистрирован после всех остальных (обычно в конце **routes.php**), иначе очередь до них не дойдёт.

**Регистрация маршрута, отвечающего на //GET//-запрос %%(t)/%%:**
%%
  Route::get('/', function () {
    return "Привет, мир!";
  });
%%

**Регистрация маршрута для любого ((ВП:HTTP))-запроса на %%(t)/%% (//GET//, //POST//, //PUT// и //DELETE//):**
%%
  Route::any('/', function () {
    return "Привет, мир!";
  });
%%

**Регистрация для отдельных HTTP-запросов:**
%%
  Route::post('user', function () {
    // обработчик POST-запроса на /user
  });

  Route::put('user/(:num)', function  ($id) {
    // обработчик PUT-запроса на /user/<число>
  });

  Route::delete('user/(:num)', function ($id) {
    // обработчик DELETE-запроса на /user/<число>
  });
%%

**Регистрация одного маршрута для одного адреса, но нескольких HTTP-запросов:**
%%
  Router::register(array('GET', 'POST'), $uri, $callback);
%%

=== ((#wc)) Подстановка (шаблоны) ===
**Задание части ((ВП:URI)) как последовательности цифр:**
%%
  Route::get('user/(:num)', function ($id) {
    // код обработчика - например, по запросу /user/123
  });
%%

**Буквенно-цифровой сегмент:**
%%
  Route::get('post/(:any)', function ($title) {
    // код обработчика - например, по запросу /post/sY34v
  });
%%

.(tl_note)
На самом деле %%(t) (:any)%% допускает также **точки, проценты, дефисы и подчёркивания**: %%(t) . % - _%% - //прим. пер.//

**Задание необязательной части URI:**
%%
  Route::get('page/(:any?)', function ($page = 'index') {
    // сработает для /page ($page устанавливается в 'index') и для /page/chat ($page = 'chat').
  });
%%

.(tl_note)
**Знак вопроса (%%(t)?%%)** может быть добавлен к любому шаблону: %%(t) (:num?)%%, %%(t) (:any?)%%, %%(t) (:all?)%% (**all** допускает любой символ включая %%(t)/%%). - //прим. пер.//

== Событие "404" ==
Если запрос не был обработан ни одним маршрутом возникнет событие "404". Умолчательный обработчик для него задан в **application/routes.php**:
%%
  Event::listen('404', function () {
    return Response::error('404');
  });
%%

Вы можете изменить его в соответствии с требованиями вашего приложения.

.(further_reading)
Связанные темы:
  * ((docs/v3/events))

== Фильтры ==
**Фильтры маршрутов** могут выполняться //до// ("предварительные фильтры") или //после// ("постфильтры") того, как обработчик определённого запроса был вызван. Фильтры обычно задаются в **application/routes.php**.

**Предварительный фильтр может вернуть значение** - в этом случае оно используется как ответ клиенту и обработчик маршрута не вызывается - это весьма удобно для проверок пользовательских прав и подобных вещей.

**Пост-фильтр принимает объект %%Response%%**, возвращённый выполненным ||маршрутом|| или //предварительным фильтром//.

**Регистрация фильтра:**
%%
  Route::filter('filter', function () {
    return Redirect::to('home');
  });
%%

**Добавление фильтра к маршруту:**
%%
  Route::get('blocked', array('before' => 'filter', function () {
    return View::make('blocked');
  }));
%%

**Добавление постфильтра:**
%%
  Route::get('download', array('after' => 'log', function () {
    // код маршрута.
  }));
%%

**Добавление нескольких фильтров одному маршруту:**
%%
  Route::get('create', array('before' => 'auth|csrf', function () {
    // код маршрута после выполнения фильтров "auth" и "csrf".
  }));
%%

**Передача параметров для фильтров:**
%%
  Route::get('panel', array('before' => 'role:admin', function () {
    // код маршрута; фильтр "role" получит параметр "admin".
  }));
%%

=== Фильтрация по шаблону ===
Иногда вам может понадобиться вызвать фильтр для всех запросов, подходящих под определённую маску. Например, фильтр **auth** может быть применён ко всем запросам, начинающимся на %%(t)admin%%. Вот как это делается:
%%
  Route::filter('pattern: admin/*', 'auth');
%%

=== Глобальные фильтры ===
В Laravel есть два **глобальных фильтра**, вызываемых до и после выполнения любого //маршрута//. Вы можете найти их в **application/routes.php**. Из них удобно запускать какие-то общие ((docs/v3/bundles пакеты)) или задавать настройки.

== Группы маршрутов ==
**Группы маршрутов** позволяют вам задавать общие свойства для нескольких //маршрутов//, что делает код упорядоченным и удобным для чтения.

%%
  Route::group(array('before' => 'auth'), function() {
    Route::get('panel', function () {
      // маршрут "panel" с добавленным предварительным фильтром "auth".
    });

    Route::get('dashboard', function () {
      // маршрут "dashboard" - также с фильтром "auth".
    });
  });
%%

== Именованные маршруты ==
Генерация URL или переадресаций с использованием ((ВП:URI)) самого //маршрута// может вызвать проблемы, если последний поменяет свой адрес. Это может быть решено присвоением маршруту //имени// и использованием его вместо настоящего адреса - если он поменяется все созданные ссылки автоматически укажут на новое расположение и дополнительных изменений не потребуется.

**Регистрация именованного маршрута:**
%%
  Route::get('/', array('as' => 'home', function () {
    return "Привет, мир!";
  }));
%%

**Создание адреса для именованного маршрута:**
%%
  $url = URL::to_route('home');
%%

**Переадресация на именованный маршрут:**
%%
  return Redirect::to_route('home');
%%

Как только вы присвоили маршруту //имя// вы можете легко проверить, **соответствует ли ему текущий запрос**:
%%
  if (Request::route()->is('home')) {
    // маршрут "home" обрабатывает текущий запрос.
  }
%%

== ((#https)) HTTPS-маршруты ==
Регистрируя маршрут вы можете задать ему атрибут **https** - в этом случае при генерации URL или переадресации будет использован безопасный протокол ((ВП:HTTPS)).

**Регистрация HTTPS-маршрута:**
%%
  Route::get('login', array('https' => true, function () {
    return View::make('login');
  }));
%%

**Регистрация с помощью метода %%secure()%%:**
%%
  Route::secure('GET', 'login', function () {
    return View::make('login');
  });
%%

== ((#пакеты)) Маршруты пакетов ==
**((docs/v3/bundles Пакеты))** - система модулей Laravel. //Пакеты// могут быть легко настроены для обработки запросов в вашем приложении. Больше информации дано в ((docs/v3/bundles соответствующей статье)), а пока просто знайте, что //маршруты// не только могут быть использованы для создания доступа к функциональности //пакета//, но они также могут регистрироваться самими пакетами.

Откроем файл **application/bundles.php**.

**Регистрация пакета для обработки определённого пути:**
%%
  return array(
    'admin' => array('handles' => 'admin'),
  );
%%

Как вы видите, в массиве мы указали опцию **handles** - это позволяет Laravel вызывать //пакет// **admin** при любом запросе, начинающимся на %%(t)admin/%%.

Теперь вы можете регистрировать маршруты для своего //пакета// - создайте файл **routes.php** в его папке и добавьте туда следующее...

**Регистрация обработчика для запроса в корень пакета:**
%%
  Route::get('(:bundle)', function () {
    return 'Вы открыли страницу пакета admin.';
  });
%%

Изучим этот пример. Что означает **(:bundle)**? Эта строка будет заменена на то самое значение опции **handles**, которое мы указали выше, регистрируя наш //пакет//. Это делает наш код "сухим" (см. "[[ВП:DRY]]") и подзволяет пользователям нашего //пакета// изменять его коренной адрес без последствий для зарегистрированных им //маршрутов//. Удобно, не так ли?

**Регистрация маршрута для пакета:**
%%
  Route::get('(:bundle)/panel', function () {
    return "Запрос admin/panel был успешно обработан.";
  });
%%

== Маршрутизация контроллеров ==
Использование **((docs/v3/controllers контроллеров))** - ещё один из способов управление логикой приложения. Если вы ещё с ними не знакомы прочитайте ((docs/v3/controllers эту статью в документации)) и возвращайтесь к этому разделу.

Важно отметить, что все //маршруты// в Laravel должны быть //явно зарегистрированы// - в том числе принадлежащие //контроллерам//. Это значит, что их методы, которые не были явно зарегистрированы **не будут доступны**. Однако существует возможность сделать это автоматически для всех методов одного или нескольких //контроллеров// - обычно это делается в **application/routes.php**,

Скорее всего вы просто хотите зарегистрировать все имеющиеся в вашем приложении //контроллеры// - в папке **controllers**. Вы можете сделать это одной простой строчкой:
%%
  Route::controller(Controller::detect());
%%

Метод %%Controller::detect%% просто возвращает массив всех контроллеров, определённых в вашем проекте.

Если вы хотите автоматически зарегистрировать все //((docs/v3/controllers контроллеры))// в определённом //((docs/v3/bundles пакете))//, то просто передайте ему имя //пакета//. Это имя не задано, сканируется папка проекта (**application/controllers**).

**Регистрация котроллеров пакета "admin":**
%%
  Route::controller(Controller::detect('admin'));
%%

**Регистрация котроллера "home":**
%%
  Route::controller('home');
%%

**Регистрация нескольких контроллеров:**
%%
  Route::controller(array('dashboard.panel', 'admin'));
%%

Как только контроллер зарегистрирован вы можете вызывать его методы, используя следующий URL:
%%(t)
  http://localhost/controller/method/arguments
%%

Это адресное соглашение похоже на применяемое в **CodeIgniter** и других распространённых фреймворках, где **первый сегмент** - имя //контроллера//, **второй** - метод, а **остальные** передаются в него в качестве параметров. Если метод не указан, используется **index**.

**Регистрация маршрута, указывающего на ((docs/v3/controllers#действи+я))е ((docs/v3/controllers контроллера)):**
%%
  Route::get('welcome', 'home@index');
%%

**Регистрация маршрута для ((docs/v3/controllers#действи+я))е и с ((#фильтры постфильтром)) "log":**
%%
  Route::get('welcome', array('after' => 'log', 'uses' => 'home@index'));
%%

== Командная строка ==
Вы можете тестировать свои //маршруты// используя интерфейс командной строки Laravel - "((docs/v3/artisan/tasks Artisan))" - для этого просто укажите тип HTTP-запроса и URL. Ответ будет выведен в консоль используя функцию ((php:var-dump var_dump)).

**Вызов маршрута, используя "Artisan":**
%%(sh)
  php artisan route:call get api/user/1
%%