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

Основы

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

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

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

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

Регистрация маршрута, отвечающего на GET-запрос /:

Route::get('/', function () {
  return "Привет, мир!";
});

Регистрация маршрута для любого HTTP-запроса на / (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);

Подстановка (шаблоны)

Задание части URI как последовательности цифр:

Route::get('user/(:num)', function ($id) {
  // код обработчика - например, по запросу /user/123
});

Буквенно-цифровой сегмент:

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

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

Задание необязательной части URI:

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

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

Событие «404»

Если запрос не был обработан ни одним маршрутом возникнет событие «404». Умолчательный обработчик для него задан в application/routes.php:

Event::listen('404', function () {
  return Response::error('404');
});

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

Связанные темы:

• События

Фильтры

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

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

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

Регистрация фильтра:

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 может быть применён ко всем запросам, начинающимся на admin. Вот как это делается:

Route::filter('pattern: admin/*', 'auth');

Глобальные фильтры

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

Группы маршрутов

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

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 — в этом случае при генерации URL или переадресации будет использован безопасный протокол HTTPS.

Регистрация HTTPS-маршрута:

Route::get('login', array('https' => true, function () {
  return View::make('login');
}));

Регистрация с помощью метода PHPsecure():

Route::secure('GET', 'login', function () {
  return View::make('login');
});

Маршруты пакетов

Пакеты — система модулей Laravel. Пакеты могут быть легко настроены для обработки запросов в вашем приложении. Больше информации дано в соответствующей статье, а пока просто знайте, что маршруты не только могут быть использованы для создания доступа к функциональности пакета, но они также могут регистрироваться самими пакетами.

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

Регистрация пакета для обработки определённого пути:

return array(
  'admin' => array('handles' => 'admin'),
);

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

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

Регистрация обработчика для запроса в корень пакета:

Route::get('(:bundle)', function () {
  return 'Вы открыли страницу пакета admin.';
});

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

Регистрация маршрута для пакета:

Route::get('(:bundle)/panel', function () {
  return "Запрос admin/panel был успешно обработан.";
});

Маршрутизация контроллеров

Использование контроллеров — ещё один из способов управление логикой приложения. Если вы ещё с ними не знакомы прочитайте эту статью в документации и возвращайтесь к этому разделу.

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

Скорее всего вы просто хотите зарегистрировать все имеющиеся в вашем приложении контроллеры — в папке controllers. Вы можете сделать это одной простой строчкой:

Route::controller(Controller::detect());

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

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

Регистрация котроллеров пакета «admin»:

Route::controller(Controller::detect('admin'));

Регистрация котроллера «home»:

Route::controller('home');

Регистрация нескольких контроллеров:

Route::controller(array('dashboard.panel', 'admin'));

Как только контроллер зарегистрирован вы можете вызывать его методы, используя следующий URL:

http://localhost/controller/method/arguments

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

Регистрация маршрута, указывающего на действие контроллера:

Route::get('welcome', 'home@index');

Регистрация маршрута для действие и с постфильтром «log»:

Route::get('welcome', array('after' => 'log', 'uses' => 'home@index'));

Командная строка

Вы можете тестировать свои маршруты используя интерфейс командной строки Laravel — «Artisan» — для этого просто укажите тип HTTP-запроса и URL. Ответ будет выведен в консоль используя функцию var_dump.

Вызов маршрута, используя «Artisan»:

shphp artisan route:call get api/user/1