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

Простейшая маршрутизация

В Laravel простейшие маршруты принимают URI (путь) и функцию-замыкание, предоставляя очень простой и выразительный метод определения маршрутов:

Route::get('foo', function () {
  return 'Hello World';
});

Файлы маршрутов по умолчанию

Route::get($uri, $callback);
Route::post($uri, $callback);
Route::put($uri, $callback);
Route::patch($uri, $callback);
Route::delete($uri, $callback);
Route::options($uri, $callback);

Route::match(['get', 'post'], '/', function () {
  //
});

Route::any('foo', function () {
  //
});

Route::get('/', function () {
  return 'Hello World';
});

Route::post('foo/bar', function () {
  return 'Hello World';
});

Route::put('foo/bar', function () {
  //
});

Route::delete('foo/bar', function () {
  //
});

Route::match(['get', 'post'], '/', function () {
  return 'Hello World';
});

Route::any('foo', function () {
  return 'Hello World';
});

$url = url('foo');

<form method="POST" action="/profile">
  {{ csrf_field() }}
  ...
</form>

Параметры маршрутов

Обязательные параметры

Разумеется, иногда вам может понадобиться захватить сегменты URI в вашем маршруте. Например, если вам необходимо захватить ID пользователя из URL. Это можно сделать, определив параметры маршрута:

Route::get('user/{id}', function ($id) {
  return 'User '.$id;
});

Вы можете определить сколько угодно параметров:

Route::get('posts/{post}/comments/{comment}', function ($postId, $commentId) {
  //
});

Параметры маршрута всегда заключаются в фигурные скобки и должны состоять из буквенных символов. Параметры маршрута не могут содержать символ -. Используйте вместо него подчёркивание _.

Необязательные параметры маршрута

Иногда необходимо указать параметр маршрута, но при этом сделать его наличие необязательным. Это можно сделать, поместив знак вопроса ? после названия параметра. Не забудьте задать значение по умолчанию для соответствующей переменной маршрута:

Route::get('user/{name?}', function ($name = null) {
  return $name;
});

Route::get('user/{name?}', function ($name = 'John') {
  return $name;
});

Ограничения регулярными выражениями

Вы можете ограничить формат параметров вашего маршрута с помощью метода PHPwhere() на экземпляре маршрута. Метод PHPwhere() принимает название параметра и регулярное выражение, определяющее ограничения для параметра:

Route::get('user/{name}', function ($name) {
  //
})->where('name', '[A-Za-z]+');

Route::get('user/{id}', function ($id) {
  //
})->where('id', '[0-9]+');

Route::get('user/{id}/{name}', function ($id, $name) {
  //
})->where(['id' => '[0-9]+', 'name' => '[a-z]+']);

Глобальные ограничения

Если вы хотите, чтобы параметр был всегда ограничен заданным регулярным выражением, то можете использовать метод PHPpattern(). Вам следует определить эти шаблоны в методе PHPboot() вашего RouteServiceProvider:

/**
 * Определение привязок вашей модели, шаблонов фильтрации и т.д.
 *
 * @return void
 */
public function boot()
{
  Route::pattern('id', '[0-9]+');

  parent::boot();
}

/**
 * Определение привязок вашей модели, шаблонов фильтрации и т.д.
 *
 * @param  \Illuminate\Routing\Router  $router
 * @return void
 */
public function boot(Router $router)
{
  $router->pattern('id', '[0-9]+');

  parent::boot($router);
}

Когда шаблон определён, он автоматически применяется ко всем маршрутам, использующим этот параметр:

Route::get('user/{id}', function ($id) {
  // Выполняется только если {id} числовой.
});

if ($route->input('id') == 1)
{
  //
}

use Illuminate\Http\Request;

Route::get('user/{id}', function(Request $request, $id)
{
  if ($request->route('id'))
  {
    //
  }
});

Именованные маршруты

Именованные маршруты позволяют удобно генерировать URL-адреса и делать переадресацию на конкретный маршрут.

Route::get('user/profile', function () {
  //
})->name('profile');

Route::get('user/profile', ['as' => 'profile', function () {
  //
}]);

Также можно указать имена маршрутов для действий контроллера:

Route::get('user/profile', 'UserController@showProfile')->name('profile');

Route::get('user/profile', [
  'as' => 'profile', 'uses' => 'UserController@showProfile'
]);

Route::get('user/profile', 'UserController@showProfile')->name('profile');

Route::group(['as' => 'admin::'], function () {
  Route::get('dashboard', ['as' => 'dashboard', function () {
    // Маршрут назван "admin::dashboard"
  }]);
});

$name = Route::currentRouteName();

Генерирование URL адресов для именованных маршрутов

Когда вы назначили имя маршруту, вы можете использовать это имя для генерирования URL адресов и переадресаций глобальным методом PHProute():

// Генерирование URL...
$url = route('profile');

// Генерирование переадресаций...
return redirect()->route('profile');

Если у именованного маршрута есть параметры, вы можете передать их вторым аргументом метода PHProute(). Эти параметры будут автоматически вставлены в соответствующие места URL:

Route::get('user/{id}/profile', function ($id) {
  //
})->name('profile');

$url = route('profile', ['id' => 1]);

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

Группы маршрутов позволяют использовать общие атрибуты маршрутов, такие как посредники и пространства имён, для большого числа маршрутов без необходимости определять эти атрибуты для каждого отдельного маршрута. Общие атрибуты указываются в виде массива первым аргументом метода PHPRoute::group().

Посредники

Посредники применяются ко всем маршрутам в группе путём указания списка этих посредников с параметром middleware в массиве групповых атрибутов. Посредники выполняются в порядке перечисления в этом массиве:

Route::group(['middleware' => 'auth'], function () {
  Route::get('/', function ()    {
    // Использует посредника Auth
  });

  Route::get('user/profile', function () {
    // Использует посредника Auth
  });
});

Пространства имён

Другой типичный пример использования групп маршрутов — назначение одного пространства имён PHP для группы контроллеров, используя параметр namespace в массиве группы:

Route::group(['namespace' => 'Admin'], function() {
  // Контроллеры в пространстве имён "App\Http\Controllers\Admin"

//для версии 5.2 и ранее:
  Route::group(['namespace' => 'User'], function() {
    // Контроллеры в пространстве имён "App\Http\Controllers\Admin\User"
  });
});

Помните, по умолчанию RouteServiceProvider включает ваши файлы маршрутов в группу пространства имён, позволяя вам регистрировать маршруты контроллера без указания полного префикса пространства имён App\Http\Controllers. Поэтому нам надо указать лишь ту часть пространства имён, которая следует за базовым пространством имён App\Http\Controllers.

Доменная маршрутизация

Группы маршрутов можно использовать для обработки маршрутизации поддоменов. Поддоменам можно назначать параметры маршрутов также как URI маршрутов, поэтому вы можете захватить часть поддомена и использовать в своём маршруте или контроллере. Поддомен можно указать с помощью ключа domain в массиве атрибутов группы:

Route::group(['domain' => '{account}.myapp.com'], function () {
  Route::get('user/{id}', function ($account, $id) {
    //
  });
});

Префиксы маршрута

Атрибут группы prefix можно использовать для указания URI-префикса каждого маршрута в группе. Например, если вы хотите добавить admin ко всем URI маршрутов в группе:

Route::group(['prefix' => 'admin'], function () {
  Route::get('users', function ()    {
    // Соответствует URL "/admin/users"
  });
});

Route::group(['prefix' => 'accounts/{account_id}'], function () {
  Route::get('detail', function ($accountId)    {
    // Соответствует URL "accounts/{account_id}/detail"
  });
});

Route::group([
  'prefix' => 'accounts/{account_id}',
  'where' => ['account_id' => '[0-9]+'],
], function() {

  // Здесь определение маршрутов
});

CSRF-защита

Данный раздел актуален для версии 5.2 и ранее. В версии 5.3 он был перенесён в отдельную статью о CSRF.

Введение

В Laravel легко защитить ваше приложение от CSRF-атаки межсайтовой подделки запросов. Межсайтовая подделка запроса — тип вредоносных атак, при котором неавторизованные команды выполняются от имени авторизованного пользователя.

Laravel автоматически генерирует CSRF-"токен" для каждой активной сессии пользователя в приложении. Этот токен используется для проверки того, что запрос в приложение отправляет именно авторизованный пользователь.

Каждый раз определяя HTML-форму в своём приложении, вы должны включать в неё скрытое поле CSRF-токена, чтобы посредник CSRF-защиты смог проверить запрос. Чтобы сгенерировать скрытое поле ввода _token, содержащее CSRF-токен, используйте вспомогательную функцию PHPcsrf_field():

// Vanilla PHP
<?php echo csrf_field(); ?>

// Blade Template Syntax
{{ csrf_field() }}

Функция PHPcsrf_field() генерирует такой HTML:

xml<input type="hidden" name="_token" value="<?php echo csrf_token(); ?>">

Вам не нужно вручную проверять CSRF-токен в запросах типа POST, PUT или DELETE. посредник VerifyCsrfToken, который входит в группу посредников web, будет автоматически проверять совпадение токена входящего запроса с токеном, хранящимся в сессии.

Исключение URI из CSRF-защиты

Иногда бывает необходимо исключить набор URI из CSRF-защиты. Например, при использовании Stripe для обработки платежей и их системы веб-хуков вам необходимо исключить ваш маршрут обработчика веб-хуков из CSRF-защиты Laravel.

Вы можете исключить URI, определив их маршруты вне группы посредников web, которая включена в файл по умолчанию routes.php, или добавив эти URI в свойство PHP$except посредника VerifyCsrfToken:

<?php

namespace App\Http\Middleware;

use Illuminate\Foundation\Http\Middleware\VerifyCsrfToken as BaseVerifier;

class VerifyCsrfToken extends BaseVerifier
{
  /**
   * URI, которые надо исключить из проверки CSRF.
   *
   * @var array
   */
  protected $except = [
    'stripe/*',
  ];
}

X-CSRF-TOKEN

Кроме поиска CSRF-ключа в параметрах «POST», посредник VerifyCsrfToken также проверит наличие заголовка запроса X-CSRF-TOKEN. Например, вы можете хранить ключ в теге «meta»:

<meta name="csrf-token" content="{{ csrf_token() }}">

Когда вы создали тег meta, вы можете добавлять токен в заголовки всех запросов с помощью библиотеки, такой как jQuery. Так обеспечивается простая и удобная CSRF-защита для ваших приложений на основе AJAX:

$.ajaxSetup({
      headers: {
        'X-CSRF-TOKEN': $('meta[name="csrf-token"]').attr('content')
      }
});

X-XSRF-TOKEN

Laravel также хранит CSRF-ключ в cookie XSRF-TOKEN. Вы можете использовать значение из cookie, чтобы задать заголовок запроса X-XSRF-TOKEN. Некоторые фреймворки JavaScript, такие как Angular, делают это автоматически. Вряд ли вам придётся использовать это значение вручную.

Разница между X-CSRF-TOKEN и X-XSRF-TOKEN в том, что первый использует простое текстовое значение, а второй — шифрованное значение, т.к. cookie в Laravel всегда шифруются. Если для передачи значения ключа вы используете функцию PHPcsrf_token(), то вам вероятно нужно использовать заголовок X-CSRF-TOKEN.

Привязка модели

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

Route::get('api/users/{user}', function (App\User $user) {
  return $user->email;
});

/**
 * Получить ключ маршрута для модели.
 *
 * @return string
 */
public function getRouteKeyName()
{
  return 'slug';
}

Явная привязка

Для регистрации явной привязки используйте метод маршрута PHPmodel() для указания класса для данного параметра. Вам надо определить явные привязки вашей модели в методе PHPboot() класса RouteServiceProvider:

public function boot()
{
  parent::boot();

  Route::model('user', App\User::class);
}

public function boot(Router $router)
{
  parent::boot($router);

  $router->model('user', 'App\User');
}

Затем определите маршрут, содержащий параметр PHP{user}:

Route::get('profile/{user}', function (App\User $user) {
  //
});

Route::get('profile/{user}', function(App\User $user)
{
  //
});

Из-за того, что мы ранее привязали все параметры PHP{user} к модели App\User, её экземпляр будет внедрён в маршрут. Таким образом, к примеру, запрос profile/1 внедрит объект User, полученный из БД, который соответствует ID 1.

Если совпадающий экземпляр модели не найден в базе данных, будет автоматически сгенерирован HTTP-отклик 404.

Изменение логики принятия решения

public function boot()
{
  parent::boot();

  Route::bind('user', function ($value) {
    return App\User::where('name', $value)->first();
  });
}

$router->bind('user', function ($value) {
  return App\User::where('name', $value)->first();
});

$router->model('user', 'App\User', function() {
  throw new NotFoundHttpException;
});

Route::model('user', 'User', function()
{
  throw new NotFoundHttpException;
});

Route::bind('user', function($value)
{
  return User::where('name', $value)->first();
});

Подмена методов

HTML-формы не поддерживают действия PUT, PATCH и DELETE. Поэтому при определении маршрутов PUT, PATCH и DELETE, вызываемых из HTML-формы, вам надо добавить в неё скрытое поле _method. Переданное в этом поле значение будет использовано как метод HTTP-запроса:

xml<form action="/foo/bar" method="POST">
  <input type="hidden" name="_method" value="PUT">
  <input type="hidden" name="_token" value="{{ csrf_token() }}">
</form>

<?php echo method_field('PUT'); ?>

Используйте вспомогательный метод PHPmethod_field(), чтобы сгенерировать скрытое поле для _method:

{{ method_field('PUT') }}

Получение текущего маршрута

$route = Route::current();

$name = Route::currentRouteName();

$action = Route::currentRouteAction();

$route = Route::current();

$name = $route->getName();

$actionName = $route->getActionName();

$name = Route::currentRouteName();
$action = Route::currentRouteAction();

Чтобы изучить все доступные методы, обратитесь к документации по API класса, лежащего в основе фасада Route, и экземпляра Route.

abort(404);