- Основы маршрутизации
- Параметры маршрута
- Именованные маршруты
- Группы маршрутов
- Привязка модели к маршруту
- Резервные маршруты
- Ограничение частоты запросов
- Подмена методов формы
- Доступ к текущему маршруту
- Совместное использование ресурсов между источниками (CORS)
- Кеширование маршрутов
Простейшие маршруты Laravel принимают URI и замыкание, обеспечивая нетрудоемкий и выразительный метод определения маршрутов и поведения без сложных конфигурационных файлов маршрутизации:
use Illuminate\Support\Facades\Route;
Route::get('/greeting', function () {
return 'Hello World';
});
Все маршруты Laravel должны быть определены в ваших файлах маршрутов, находящиеся в каталоге routes. Эти файлы автоматически загружаются вашим поставщиком App\Providers\RouteServiceProvider приложения. Файл routes/web.php определяет маршруты для вашего веб-интерфейса. Этим маршрутам назначается группа посредников web, которая обеспечивает такие функции, как состояние сессии и защита от CSRF. Маршруты в routes/api.php не сохраняют состояния и им назначается группа посредников api.
Для большинства приложений вы начнете с определения маршрутов в файле routes/web.php. К маршрутам, определенным в routes/web.php, можно получить доступ, введя URL-адрес определенного маршрута в вашем браузере. Например, вы можете получить доступ к следующему маршруту, перейдя по адресу http://example.com/user в своем браузере:
use App\Http\Controllers\UserController;
Route::get('/user', [UserController::class, 'index']);
Маршруты, определенные в файле routes/api.php, вложены в группу маршрутов в RouteServiceProvider. Внутри этой группы автоматически применяется префикс URI /api, поэтому вам не нужно вручную добавлять его к каждому маршруту в файле маршрутов. Вы можете изменить префикс и другие параметры группы маршрутов, изменив свой класс RouteServiceProvider.
Маршрутизатор позволяет регистрировать маршруты, отвечающие на любой HTTP-метод:
Route::get($uri, $callback);
Route::post($uri, $callback);
Route::put($uri, $callback);
Route::patch($uri, $callback);
Route::delete($uri, $callback);
Route::options($uri, $callback);
Иногда вам может потребоваться зарегистрировать маршрут, отвечающий на несколько HTTP-методов. Вы можете сделать это с помощью метода match. Или вы даже можете зарегистрировать маршрут, отвечающий на все HTTP-методы, используя метод any:
Route::match(['get', 'post'], '/', function () {
//
});
Route::any('/', function () {
//
});
Вы можете объявить любые зависимости, необходимые для вашего маршрута, в сигнатуре замыкания вашего маршрута. Объявленные зависимости будут автоматически извлечены и внедрены в замыкание с помощью контейнера служб Laravel. Например, вы можете объявить класс Illuminate\Http\Request, чтобы текущий HTTP-запрос автоматически был внедрен в замыкание вашего маршрута:
use Illuminate\Http\Request;
Route::get('/users', function (Request $request) {
// ...
});
Помните, что любые HTML-формы, указывающие на маршруты POST, PUT, PATCH или DELETE, которые определены в файле маршрутов web, должны включать поле токена CSRF. В противном случае запрос будет отклонен. Вы можете прочитать больше о защите от CSRF в документации CSRF:
<form method="POST" action="/profile">
@csrf
...
</form>
Если вы определяете маршрут, который перенаправляет на другой URI, то вы можете использовать метод Route::redirect. Этот метод имеет лаконичную запись, так что вам не нужно определять полный маршрут или контроллер для выполнения простого перенаправления:
Route::redirect('/here', '/there');
По умолчанию Route::redirect возвращает код состояния 302. Вы можете переопределить код состояния, используя необязательный третий параметр:
Route::redirect('/here', '/there', 301);
Или вы можете использовать метод Route::permanentRedirect для возврата кода состояния 301:
Route::permanentRedirect('/here', '/there');
{note} При использовании параметров маршрута в маршрутах перенаправления, следующие параметры зарезервированы Laravel и не могут быть использованы:
destinationиstatus.
Если ваш маршрут должен возвращать только HTML-шаблон, то вы можете использовать метод Route::view. Как и метод redirect, этот метод имеет лаконичную запись, так что вам не нужно полностью определять маршрут или контроллер. Метод view принимает URI в качестве первого аргумента и имя шаблона в качестве второго аргумента. Кроме того, вы можете указать массив данных для передачи в шаблон в качестве необязательного третьего аргумента:
Route::view('/welcome', 'welcome');
Route::view('/welcome', 'welcome', ['name' => 'Taylor']);
{note} При использовании параметров маршрута в маршрутах представлений, следующие параметры зарезервированы Laravel и не могут быть использованы:
view,data,statusиheaders.
Иногда вам нужно будет отследить сегменты URI в вашем маршруте. Например, вам может потребоваться отследить идентификатор пользователя из URL-адреса. Вы можете сделать это, указав параметры маршрута:
Route::get('/user/{id}', function ($id) {
return 'User '.$id;
});
Вы можете определить столько параметров маршрута, сколько потребуется для вашего маршрута:
Route::get('/posts/{post}/comments/{comment}', function ($postId, $commentId) {
//
});
Параметры маршрута всегда заключаются в фигурные скобки {} и должны состоять из буквенных символов. Подчеркивание (_) также допускается в именах параметров маршрута. Параметры маршрута будут внедрены в замыкания маршрута / контроллеры в зависимости от их порядка, т.е. имена аргументов замыкания маршрута / контроллера не имеют значения.
Если у вашего маршрута есть зависимости, которые вы хотите, чтобы контейнер служб Laravel автоматически внедрял в замыкание вашего маршрута, то вы должны указать необходимые параметры маршрута после указания этих зависимостей:
use Illuminate\Http\Request;
Route::get('/user/{id}', function (Request $request, $id) {
return 'User '.$id;
});
Иногда может потребоваться указать параметр маршрута, который не всегда может присутствовать в URI. Вы можете сделать это, поставив знак ? после имени параметра. Не забудьте присвоить соответствующей переменной маршрута значение по умолчанию:
Route::get('/user/{name?}', function ($name = null) {
return $name;
});
Route::get('/user/{name?}', function ($name = 'John') {
return $name;
});
Вы можете ограничить формат параметров вашего маршрута, используя метод where экземпляра маршрута. Метод where принимает имя параметра и регулярное выражение, определяющее, как параметр должен быть ограничен:
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]+']);
Для некоторых часто используемых шаблонов регулярных выражений есть соответствующие вспомогательные методы, позволяющие быстро добавлять их к вашим маршрутам:
Route::get('/user/{id}/{name}', function ($id, $name) {
//
})->whereNumber('id')->whereAlpha('name');
Route::get('/user/{name}', function ($name) {
//
})->whereAlphaNumeric('name');
Route::get('/user/{id}', function ($id) {
//
})->whereUuid('id');
Если входящий запрос не соответствует ограничениям шаблона маршрута, то будет возвращен 404 HTTP-ответ.
Если вы хотите, чтобы параметр маршрута всегда ограничивался конкретным регулярным выражением, то вы можете использовать метод pattern. Вы должны определить эти шаблоны в методе boot вашего класса App\Providers\RouteServiceProvider:
/**
* Определить связывание модели и маршрута, шаблоны ограничений регулярных выражений и т.д.
*
* @return void
*/
public function boot()
{
Route::pattern('id', '[0-9]+');
}
Как только шаблон определен, он автоматически применяется ко всем маршрутам, использующим это имя параметра:
Route::get('/user/{id}', function ($id) {
// Выполнится, только если параметр `{id}` имеет числовое значение ...
});
Компонент маршрутизации Laravel позволяет всем символам, кроме /, присутствовать в значениях параметров маршрута. Вы должны явно разрешить / быть частью вашего заполнителя, используя регулярное выражение условия where:
Route::get('/search/{search}', function ($search) {
return $search;
})->where('search', '.*');
{note} Закодированные обратные слеши поддерживаются только в рамках последнего сегмента маршрута.
Именованные маршруты позволяют легко создавать URL-адреса или перенаправления для определенных маршрутов. Вы можете указать имя для маршрута, связав метод name с определением маршрута:
Route::get('/user/profile', function () {
//
})->name('profile');
Вы также можете указать имена маршрутов для действий контроллера:
Route::get(
'/user/profile',
[UserProfileController::class, 'show']
)->name('profile');
{note} Имена маршрутов всегда должны быть уникальными.
После того, как вы присвоили имя указанному маршруту, вы можете использовать имя маршрута при генерации URL-адресов или перенаправлений с помощью вспомогательных глобальных функций route и redirect Laravel:
// Создание URL-адреса ...
$url = route('profile');
// Создание перенаправления ...
return redirect()->route('profile');
Если именованный маршрут определяет параметры, то вы можете передать параметры в качестве второго аргумента функции route. Указанные параметры будут автоматически вставлены в сгенерированный URL в соответствующие места:
Route::get('/user/{id}/profile', function ($id) {
//
})->name('profile');
$url = route('profile', ['id' => 1]);
Если вы передадите дополнительные параметры в массиве, то эти пары ключ / значение будут автоматически добавлены в строку запроса сгенерированного URL-адреса:
Route::get('/user/{id}/profile', function ($id) {
//
})->name('profile');
$url = route('profile', ['id' => 1, 'photos' => 'yes']);
// /user/1/profile?photos=yes
{tip} Иногда вам может потребоваться для всего запроса указать значение по умолчанию для параметров URL, например, текущий язык. Для этого вы можете использовать метод
URL::defaults.
Если вы хотите определить, был ли текущий запрос направлен на конкретный именованный маршрут, то вы можете использовать метод named экземпляра Route. Например, вы можете проверить имя текущего маршрута из посредника маршрута:
/**
* Обработка входящего запроса.
*
* @param \Illuminate\Http\Request $request
* @param \Closure $next
* @return mixed
*/
public function handle($request, Closure $next)
{
if ($request->route()->named('profile')) {
//
}
return $next($request);
}
Группы маршрутов позволяют совместно использовать атрибуты маршрута (например, посредники) для большого количества маршрутов без необходимости определять эти атрибуты для каждого маршрута отдельно.
Вложенные группы пытаются разумно «объединить» атрибуты со своей родительской группой. Посредник и условия where объединяются, а имена и префиксы добавляются. Разделители пространства имен и слеши в префиксах URI автоматически добавляются там, где это необходимо.
Чтобы назначить посредника всем маршрутам в группе, вы можете использовать метод middleware перед определением группы. Посредники будут выполняться в том порядке, в котором они перечислены в массиве:
Route::middleware(['first', 'second'])->group(function () {
Route::get('/', function () {
// Использует посредники `first` и `second` ...
});
Route::get('/user/profile', function () {
// Использует посредники `first` и `second` ...
});
});
Группы маршрутов также могут использоваться для управления маршрутизацией поддоменов. Поддоменам могут быть назначены параметры маршрута так же, как и URI маршрута, что позволяет вам отследить часть поддомена для использования в вашем маршруте или контроллере. Поддомен можно указать, вызвав метод domain перед определением группы:
Route::domain('{account}.example.com')->group(function () {
Route::get('user/{id}', function ($account, $id) {
//
});
});
{note} Чтобы обеспечить доступность маршрутов поддоменов, вы должны зарегистрировать маршруты поддоменов перед регистрацией маршрутов корневого домена. Это предотвратит перезапись маршрутами корневого домена маршрутов поддоменов, имеющих одинаковый путь URI.
Метод prefix используется для подстановки префикса каждому маршруту в группе указанным URI. Например, вы можете захотеть подставить перед всеми URI маршрутов в группе префикс admin:
Route::prefix('admin')->group(function () {
Route::get('/users', function () {
// Соответствует URL-адресу `/admin/users` ...
});
});
Метод name используется для подстановки префикса к каждому имени маршрута в группе указанной строкой. Например, вы можете захотеть подставить перед всеми именами сгруппированных маршрутов префикс admin. Данная строка создаст префикс имени маршрута точно в том виде, в котором он указан, поэтому мы обязательно укажем завершающий символ . в префиксе:
Route::name('admin.')->group(function () {
Route::get('/users', function () {
// Маршруту присвоено имя `admin.users` ...
})->name('users');
});
При внедрении идентификатора модели в маршрут или действие контроллера вы часто будете запрашивать базу данных, чтобы получить модель с соответствующим идентификатором. Привязка модели к маршруту Laravel обеспечивает удобный способ автоматического внедрения экземпляров модели непосредственно в ваши маршруты. Например, вместо того, чтобы внедрять идентификатор пользователя, вы можете внедрить весь экземпляр модели User с соответствующим идентификатором.
Laravel автоматически извлечет модели Eloquent, определенные в маршрутах или действиях контроллера, чьи имена переменных объявленного типа соответствуют имени сегмента маршрута. Например:
use App\Models\User;
Route::get('/users/{user}', function (User $user) {
return $user->email;
});
Так как переменная $user типизирована как модель App\Models\User Eloquent и имя переменной соответствует сегменту {user} URI, то Laravel автоматически внедрит экземпляр модели с идентификатором, совпадающим со значением URI из запроса. Если соответствующий экземпляр модели не найден в базе данных, то автоматически будет сгенерирован 404 HTTP-ответ.
Конечно, неявная привязка также возможна при использовании методов контроллера. Опять же, обратите внимание, что сегмент {user} URI соответствует переменной $user в контроллере, которая типизирована как App\Models\User:
use App\Http\Controllers\UserController;
use App\Models\User;
// Определение маршрута ...
Route::get('/users/{user}', [UserController::class, 'show']);
// Определение метода контроллера ...
public function show(User $user)
{
return view('user.profile', ['user' => $user]);
}
По желанию можно извлекать модели Eloquent, используя столбец, отличный от id. Для этого вы можете указать столбец в определении параметра маршрута:
use App\Models\Post;
Route::get('/posts/{post:slug}', function (Post $post) {
return $post;
});
Если вы хотите, чтобы при извлечении класса связанной модели всегда использовался столбец базы данных, отличный от id, то вы можете переопределить метод getRouteKeyName модели Eloquent:
/**
* Получить ключ маршрута для модели.
*
* @return string
*/
public function getRouteKeyName()
{
return 'slug';
}
При неявном связывании нескольких моделей Eloquent в одном определении маршрута вы можете захотеть ограничить вторую модель Eloquent так, чтобы она была дочерней по отношению к предыдущей модели Eloquent. Например, рассмотрим это определение маршрута, которое извлекает пост в блоге по slug для конкретного пользователя:
use App\Models\Post;
use App\Models\User;
Route::get('/users/{user}/posts/{post:slug}', function (User $user, Post $post) {
return $post;
});
При использовании неявной привязки с измененным ключом в качестве параметра вложенного маршрута, Laravel автоматически задает ограничение запроса для получения вложенной модели своим родителем, используя соглашения, чтобы угадать имя отношения родительской модели. В этом случае предполагается, что модель User имеет отношение с именем posts (форма множественного числа имени параметра маршрута), которое можно использовать для получения модели Post.
Обычно, если не найдена неявно связанная модель, то генерируется 404 HTTP-ответ. Однако вы можете изменить это поведение, вызвав метод missing при определении вашего маршрута. Метод missing принимает замыкание, которое будет вызываться, если неявно связанная модель не может быть найдена:
use App\Http\Controllers\LocationsController;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Redirect;
Route::get('/locations/{location:slug}', [LocationsController::class, 'show'])
->name('locations.view')
->missing(function (Request $request) {
return Redirect::route('locations.index');
});
Вам не обязательно использовать неявные привязки модели на основе соглашений Laravel, чтобы использовать привязку модели. Вы также можете явно определить, как параметры маршрута должны быть сопоставлены моделям. Чтобы зарегистрировать явную привязку, используйте метод маршрутизатора model, чтобы указать класс для переданного параметра. Вы должны определить ваши явные привязки модели в начале метода boot вашего класса RouteServiceProvider:
use App\Models\User;
use Illuminate\Support\Facades\Route;
/**
* Определить связывание модели и маршрута, шаблоны ограничений регулярных выражений и т.д.
*
* @return void
*/
public function boot()
{
Route::model('user', User::class);
// ...
}
Затем определите маршрут, содержащий параметр {user}:
use App\Models\User;
Route::get('/users/{user}', function (User $user) {
//
});
Поскольку мы связали все параметры {user} с моделью App\Models\User, экземпляр этого класса будет внедрен в маршрут. Так, например, при запросе users/1 будет внедрен экземпляр User из базы данных с идентификатором 1.
Если соответствующий экземпляр модели не найден в базе данных, то автоматически будет сгенерирован 404 HTTP-ответ.
Если вы хотите определить свою собственную логику связывания модели, то вы можете использовать метод Route::bind. Замыкание, которое вы передаете методу bind, получит значение сегмента URI и должно вернуть экземпляр класса, который должен быть внедрен в маршрут. Опять же, эти изменения должны выполняться в методе boot поставщика RouteServiceProvider вашего приложения:
use App\Models\User;
use Illuminate\Support\Facades\Route;
/**
* Определить связывание модели и маршрута, шаблоны ограничений регулярных выражений и т.д.
*
* @return void
*/
public function boot()
{
Route::bind('user', function ($value) {
return User::where('name', $value)->firstOrFail();
});
// ...
}
В качестве альтернативы вы можете переопределить метод resolveRouteBinding вашей модели Eloquent. Этот метод получит значение сегмента URI и должен вернуть экземпляр класса, который должен быть внедрен в маршрут:
/**
* Получить модель для привязанного к маршруту значения параметра.
*
* @param mixed $value
* @param string|null $field
* @return \Illuminate\Database\Eloquent\Model|null
*/
public function resolveRouteBinding($value, $field = null)
{
return $this->where('name', $value)->firstOrFail();
}
Если в маршруте используется ограничения неявной привязки модели, то для получения связанной дочерней модели будет использоваться метод resolveChildRouteBinding родительской модели:
/**
* Получить дочернюю модель для привязанного к маршруту значения параметра.
*
* @param string $childType
* @param mixed $value
* @param string|null $field
* @return \Illuminate\Database\Eloquent\Model|null
*/
public function resolveChildRouteBinding($childType, $value, $field)
{
return parent::resolveChildRouteBinding($childType, $value, $field);
}
Используя метод Route::fallback, вы можете определить маршрут, который будет выполняться, когда ни один другой маршрут не соответствует входящему запросу. Как правило, необработанные запросы автоматически отображают страницу 404 через обработчик исключений вашего приложения. Однако, поскольку вы обычно определяете резервный маршрут в своем файле routes/web.php, то все посредники группы web будет применены к этому маршруту. При необходимости вы можете добавить дополнительный посредник для этого маршрута:
Route::fallback(function () {
//
});
{note} Резервный маршрут всегда должен быть последним зарегистрированным маршрутом в вашем приложении.
Laravel содержит мощные и настраиваемые службы ограничения частоты запросов, которые вы можете использовать для ограничения объема трафика для конкретного маршрута или группы маршрутов. Для начала вы должны определить конфигурации ограничителя, которые соответствуют потребностям вашего приложения. Как правило, это должно выполняться в методе configureRateLimiting класса App\Providers\RouteServiceProvider вашего приложения.
Ограничители определяются с помощью метода for фасада RateLimiter. Метод for принимает имя ограничителя и замыкание, которое возвращает конфигурацию ограничений, применяемых к назначенным маршрутам. Конфигурация ограничений – это экземпляры класса Illuminate\Cache\RateLimiting\Limit. Этот класс содержит полезные методы «построения», чтобы вы могли быстро определить свой «лимит». Имя ограничителя может быть любой строкой по вашему желанию:
use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Support\Facades\RateLimiter;
/**
* Настроить ограничители частоты запросов для приложения.
*
* @return void
*/
protected function configureRateLimiting()
{
RateLimiter::for('global', function (Request $request) {
return Limit::perMinute(1000);
});
}
Если входящий запрос превышает указанный лимит, то Laravel автоматически вернет ответ с 429 кодом состояния HTTP. Если вы хотите определить свой собственный ответ, который должен возвращаться, то вы можете использовать метод response:
RateLimiter::for('global', function (Request $request) {
return Limit::perMinute(1000)->response(function () {
return response('Custom response...', 429);
});
});
Поскольку замыкание получает экземпляр входящего HTTP-запроса, то вы можете динамически создать ограничение на основе входящего запроса или статуса аутентификации пользователя:
RateLimiter::for('uploads', function (Request $request) {
return $request->user()->vipCustomer()
? Limit::none()
: Limit::perMinute(100);
});
Иногда может потребоваться сегментация ограничений по некоторым произвольным значениям. Например, вы можете разрешить пользователям получать доступ к указанному маршруту 100 раз в минуту на каждый IP-адрес. Для этого можно использовать метод by при построении лимита:
RateLimiter::for('uploads', function (Request $request) {
return $request->user()->vipCustomer()
? Limit::none()
: Limit::perMinute(100)->by($request->ip());
});
При необходимости вы можете вернуть массив ограничений при указании конфигурации ограничителя. Каждое ограничение будет оцениваться для маршрута в зависимости от порядка, в котором они размещены в массиве:
RateLimiter::for('login', function (Request $request) {
return [
Limit::perMinute(500),
Limit::perMinute(3)->by($request->input('email')),
];
});
Ограничители могут быть закреплены за маршрутами или группами маршрутов с помощью посредника throttle. Посредник throttle принимает имя ограничителя, которое вы хотите назначить маршруту:
Route::middleware(['throttle:uploads'])->group(function () {
Route::post('/audio', function () {
//
});
Route::post('/video', function () {
//
});
});
Как правило, посредник throttle сопоставлен классу Illuminate\Routing\Middleware\ThrottleRequests. Это сопоставление определено в App\Http\Kernel вашего приложения. Если вы используете Redis в качестве драйвера кеша вашего приложения, то вы можете изменить это сопоставление, чтобы использовать класс Illuminate\Routing\Middleware\ThrottleRequestsWithRedis. Этот класс более эффективен при управлении ограничениями запросов с помощью Redis:
'throttle' => \Illuminate\Routing\Middleware\ThrottleRequestsWithRedis::class,
HTML-формы не поддерживают действия PUT, PATCH или DELETE. Таким образом, при определении маршрутов PUT, PATCH или DELETE, которые вызываются из HTML-формы, вам нужно будет добавить в форму скрытое поле _method. Значение, отправленное с полем _method, будет использоваться как метод HTTP-запроса:
<form action="/example" method="POST">
<input type="hidden" name="_method" value="PUT">
<input type="hidden" name="_token" value="{{ csrf_token() }}">
</form>
Для удобства вы можете использовать директиву @method шаблонизатора Blade для создания поля ввода _method:
<form action="/example" method="POST">
@method('PUT')
@csrf
</form>
Вы можете использовать методы current, currentRouteName и currentRouteAction фасада Route для доступа к информации о маршруте, обрабатывающем входящий запрос:
use Illuminate\Support\Facades\Route;
$route = Route::current(); // Illuminate\Routing\Route
$name = Route::currentRouteName(); // string
$action = Route::currentRouteAction(); // string
Вы можете обратиться к документации API базового класса фасада Route и экземпляра Route, чтобы просмотреть все методы, доступные в классах маршрутизатора и маршрута.
Laravel может автоматически отвечать на HTTP-запросы CORS OPTIONS значениями, которые вы сконфигурируете. Все параметры CORS могут быть настроены в конфигурационном файле config/cors.php вашего приложения. Запросы OPTIONS будут автоматически обрабатываться посредником HandleCors, который по умолчанию входит в ваш глобальный стек посредников. Ваш глобальный стек посредников находится в HTTP-ядре вашего приложения (App\Http\Kernel).
{tip} Для получения дополнительной информации о CORS и заголовках CORS обратитесь к веб-документации MDN по CORS.
При развертывании вашего приложения на рабочем веб-сервере, вы должны воспользоваться кешем маршрутов Laravel. Использование кеша маршрутов резко сократит время, необходимое для регистрации всех маршрутов вашего приложения. Чтобы сгенерировать кеш маршрута, выполните команду route:cache Artisan:
php artisan route:cache
После выполнения этой команды ваш файл кеша маршрутов будет загружаться при каждом запросе. Помните, что если вы добавляете какие-либо новые маршруты, то вам нужно будет сгенерировать новый кеш маршрутов. По этой причине вы должны запускать команду route:cache только во время развертывания вашего проекта.
Вы можете использовать команду route:clear для очистки кеша маршрута:
php artisan route:clear