Версія фреймворка: 8.x

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

Основна маршрутизація

Найпростіші маршрути Laravel приймають URI та aClosure, забезпечуючи дуже простий і виразний метод визначення маршрутів:

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

Файли маршрутів за замовчуванням

Всі маршрути Laravel визначені у файлах ваших маршрутів, які знаходяться вroutesкаталог. Ці файли автоматично завантажуються фреймворком.routes/web.phpфайл визначає маршрути, призначені для вашого веб-інтерфейсу. Цим маршрутам присвоєноwebгрупа проміжного програмного забезпечення, яка надає такі функції, як стан сеансу та захист CSRF. Маршрути вroutes/api.phpє без громадянства і їм присвоєноapiгрупа проміжного програмного забезпечення.

Для більшості програм ви почнете з визначення маршрутів у вашомуroutes/web.phpфайл. Маршрути, визначені вroutes/web.phpможна отримати доступ, ввівши URL-адресу визначеного маршруту у своєму браузері. Наприклад, ви можете отримати доступ до наступного маршруту, перейшовши доhttp://your-app.test/userу вашому браузері:

use App\Http\Controllers\UserController;

Route::get('/user', [UserController::class, 'index']);

Маршрути, визначені вroutes/api.phpфайл вкладений у групу маршрутівRouteServiceProvider. У межах цієї групи/apiПрефікс URI застосовується автоматично, тому вам не потрібно вручну застосовувати його до кожного маршруту у файлі. Ви можете змінити префікс та інші параметри групи маршрутів, змінивши ваш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 () {
    //
});

Захист CSRF

Будь-які 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повертає a302код стану. Ви можете налаштувати код стану, використовуючи необов’язковий третій параметр:

Route::redirect('/here', '/there', 301);

Ви можете використовуватиRoute::permanentRedirectметод повернення a301код стану:

Route::permanentRedirect('/here', '/there');
При використанні параметрів маршруту в маршрутах перенаправлення, Laravel зарезервує такі параметри, і їх не можна використовувати:destinationіstatus.

Переглянути маршрути

Якщо для вашого маршруту потрібно лише повернути Шаблон, ви можете використовуватиRoute::viewметод. Подобаєтьсяredirectметод, цей метод забезпечує простий ярлик, так що вам не потрібно визначати повний маршрут або контролер.viewметод приймає URI як перший аргумент, а ім'я подання як другий аргумент. Крім того, ви можете надати масив даних для передачі у подання як необов’язковий третій аргумент:

Route::view('/welcome', 'welcome');

Route::view('/welcome', 'welcome', ['name' => 'Taylor']);
При використанні параметрів маршруту у перегляді маршрутів 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) {
    //
});

Параметри маршруту завжди укладені в межах{}фігурні дужки і повинні складатися з алфавітних символів і не можуть містити символу-характер. Замість використання-символу, використовуйте підкреслення (_). Параметри маршруту вводяться у зворотні виклики / контролери маршруту на основі їхнього порядку - імена аргументів зворотного виклику / контролера не мають значення.

Необов’язкові параметри

Іноді вам може знадобитися вказати параметр маршруту, але необов’язково вкажіть наявність цього параметра маршруту. Ви можете зробити це, поставивши?позначка після імені параметра. Обов’язково надайте відповідній змінній маршруту значення за замовчуванням:

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');

Глобальні обмеження

Якщо ви хочете, щоб параметр маршруту завжди був обмежений даним регулярним виразом, ви можете використовуватиpatternметод. Ви повинні визначити ці закономірності вbootметод вашогоRouteServiceProvider:

/**
 * Define your route model bindings, pattern filters, etc.
 *
 * @return void
 */
public function boot()
{
    Route::pattern('id', '[0-9]+');
}

Після того, як шаблон визначено, він автоматично застосовується до всіх маршрутів з використанням цього імені параметра:

Route::get('user/{id}', function ($id) {
    // Only executed if {id} is numeric...
});

Зашифровані похилі риски

Компонент маршрутизації Laravel дозволяє всі символи, крім/. Ви повинні явно дозволити/бути частиною вашого заповнювача за допомогоюwhereумовний регулярний вираз:

Route::get('search/{search}', function ($search) {
    return $search;
})->where('search', '.*');
Кодовані скісні риски вперед підтримуються лише в останньому сегменті маршруту.

Іменовані маршрути

Іменовані маршрути дозволяють зручно створювати URL-адреси або перенаправляти для конкретних маршрутів. Ви можете вказати назву маршруту, встановивши ланцюжокnameметоду у визначенні маршруту:

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

Ви також можете вказати назви маршрутів для дій контролера:

Route::get('user/profile', [UserProfileController::class, 'show'])->name('profile');
Назви маршрутів завжди повинні бути унікальними.

Створення URL-адрес для іменованих маршрутів

Після того, як ви присвоїли ім'я даному маршруту, ви можете використовувати його назву під час створення URL-адрес або переспрямувань через глобальнийrouteфункція:

// Generating URLs...
$url = route('profile');

// Generating Redirects...
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
Іноді, можливо, ви захочете вказати значення параметрів URL-адрес за замовчуванням за замовчуванням, наприклад, поточну локаль. Для цього ви можете використовуватиURL::defaultsметод.

Огляд поточного маршруту

Якщо ви хочете визначити, чи поточний запит був перенаправлений на заданий іменований маршрут, ви можете використовуватиnamedметод на екземплярі Route. Наприклад, ви можете перевірити поточну назву маршруту з проміжного програмного забезпечення маршруту:

/**
 * Handle an incoming request.
 *
 * @param  \Illuminate\Http\Request  $request
 * @param  \Closure  $next
 * @return mixed
 */
public function handle($request, Closure $next)
{
    if ($request->route()->named('profile')) {
        //
    }

    return $next($request);
}

Групи маршрутів

Групи маршрутів дозволяють спільно використовувати атрибути маршруту, наприклад Middlware, для великої кількості маршрутів без необхідності визначати ці атрибути для кожного окремого маршруту.

Вкладені групи намагаються розумно "об'єднати" атрибути зі своєю батьківською групою. Проміжне програмне забезпечення таwhereумови об’єднуються, а імена та префікси додаються. Розділювачі простору імен та похилі риски в префіксах URI автоматично додаються, де це доречно.

Проміжне програмне забезпечення

Щоб призначити Middlware для всіх маршрутів у групі, ви можете використовуватиmiddlewareметод перед визначенням групи. Проміжне програмне забезпечення виконується в порядку, вказаному в масиві:

Route::middleware(['first', 'second'])->group(function () {
    Route::get('/', function () {
        // Uses first & second middleware...
    });

    Route::get('user/profile', function () {
        // Uses first & second middleware...
    });
});

Маршрутизація субдоменів

Групи маршрутів також можуть використовуватися для обробки маршрутизації субдоменів. Субдоменам можуть бути призначені параметри маршруту, як і URI маршруту, що дозволяє захопити частину субдомену для використання у вашому маршруті або контролері. Субдомен можна вказати, зателефонувавши доdomainметод перед визначенням групи:

Route::domain('{account}.myapp.com')->group(function () {
    Route::get('user/{id}', function ($account, $id) {
        //
    });
});
Для того, щоб забезпечити доступність ваших маршрутів субдомену, вам слід зареєструвати маршрути субдомену перед реєстрацією маршрутів кореневого домену. Це не дозволить маршрутам кореневого домену перезаписувати маршрути субдоменів, які мають однаковий шлях URI.

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

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

Route::prefix('admin')->group(function () {
    Route::get('users', function () {
        // Matches The "/admin/users" URL
    });
});

Префікси імен маршрутів

nameметод може використовуватися для префікса кожного імені маршруту в групі заданим рядком. Наприклад, вам може знадобитися префікс всіх назв згрупованих маршрутівadmin. Даний рядок має префікс до назви маршруту точно так, як це вказано, тому ми обов’язково надамо кінцевий результат.символ у префіксі:

Route::name('admin.')->group(function () {
    Route::get('users', function () {
        // Route assigned name "admin.users"...
    })->name('users');
});

Прив'язка моделі маршруту

Вводячи ідентифікатор моделі в маршрут або дію контролера, ви часто будете запитувати, щоб отримати модель, яка відповідає цьому ідентифікатору. Прив'язка моделі маршруту Laravel забезпечує зручний спосіб автоматичного введення екземплярів моделі безпосередньо у ваші маршрути. Наприклад, замість того, щоб вводити ідентифікатор користувача, ви можете ввести весьUserекземпляр моделі, який відповідає заданому ідентифікатору.

Неявне прив'язування

Laravel автоматично вирішує красномовні моделі, визначені в маршрутах або діях контролера, імена змінних яких наведених на тип відповідають імені сегмента маршруту. Наприклад:

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

Так як$userзмінна наводиться на тип якApp\Models\UserКрасномовна модель та назва змінної відповідає{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]);
}

Налаштування ключа

Іноді вам може знадобитися вирішити красномовні моделі, використовуючи стовпець, відмінний відid. Для цього ви можете вказати стовпець у визначенні параметрів маршруту:

Route::get('api/posts/{post:slug}', function (App\Models\Post $post) {
    return $post;
});

Спеціальні ключі та сфера дії

Іноді, при неявному прив’язуванні декількох Eloquent моделей в одному визначенні маршруту, можливо, ви захочете застосувати другу модель красномовства таким чином, що вона повинна бути дочірньою до першої красномовної моделі. Наприклад, розглянемо цю ситуацію, яка отримує допис у блозі від slug для певного користувача:

use App\Models\Post;
use App\Models\User;

Route::get('api/users/{user}/posts/{post:slug}', function (User $user, Post $post) {
    return $post;
});

При використанні користувацького неявного прив’язування як вкладеного параметра маршруту, Laravel автоматично застосує запит для отримання вкладеної моделі своїм батьком, використовуючи конвенції, щоб вгадати ім’я зв’язку на батьківському. У цьому випадку передбачається, щоUserмодель має відносини з іменемposts(множина імені параметра маршруту), який можна використовувати для отриманняPostмодель.

Налаштування імені ключа за замовчуванням

Якщо ви хочете, щоб прив'язка моделі використовувала стовпець бази даних за замовчуванням, відмінний відidпри отриманні заданого класу моделі ви можете замінитиgetRouteKeyNameна красномовній моделі:

/**
 * Get the route key for the model.
 *
 * @return string
 */
public function getRouteKeyName()
{
    return 'slug';
}

Явне прив'язування

Щоб зареєструвати явне прив'язування, використовуйте маршрутизаторmodelметод, щоб вказати клас для даного параметра. Ви повинні визначити свої явні прив'язки моделей на початкуbootметод вашогоRouteServiceProviderклас:

/**
 * Define your route model bindings, pattern filters, etc.
 *
 * @return void
 */
public function boot()
{
    Route::model('user', \App\Models\User::class);

    // ...
}

Далі визначте маршрут, який містить{user}параметр:

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

Оскільки ми зв'язали всіх{user}параметрів доApp\Models\Userмодель, aUserекземпляр буде введений у маршрут. Так, наприклад, запит доprofile/1буде вводитиUserз бази даних, що має ідентифікатор1.

Якщо відповідний екземпляр моделі не знайдено в базі даних, відповідь 404 HTTP буде автоматично сформовано.

Налаштування логіки роздільної здатності

Якщо ви хочете використовувати свою власну логіку роздільної здатності, ви можете використовуватиRoute::bindметод.Closureви переходите доbindметод отримає значення сегменту URI і повинен повернути екземпляр класу, який слід ввести в маршрут:

/**
 * Define your route model bindings, pattern filters, etc.
 *
 * @return void
 */
public function boot()
{
    Route::bind('user', function ($value) {
        return App\Models\User::where('name', $value)->firstOrFail();
    });

    // ...
}

Крім того, ви можете замінитиresolveRouteBindingметод на вашій красномовній моделі. Цей метод отримає значення сегменту URI і повинен повернути екземпляр класу, який слід ввести в маршрут:

/**
 * Retrieve the model for a bound value.
 *
 * @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метод буде використаний для вирішення дочірнього прив'язки батьківської моделі:

/**
 * Retrieve the child model for a bound value.
 *
 * @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" через обробник винятків вашої програми. Однак, оскільки ви можете визначитиfallbackмаршрут у межах вашогоroutes/web.phpфайл, все Middlware вwebдо маршруту застосовуватиметься група проміжного програмного забезпечення. Ви можете додавати додаткове Middlware до цього маршруту за потреби:

Route::fallback(function () {
    //
});
Запасний маршрут завжди повинен бути останнім маршрутом, зареєстрованим вашим додатком.

Обмеження ставки

Визначення обмежувачів ставок

Laravel включає потужні та настроювані послуги обмеження швидкості, які ви можете використовувати для обмеження обсягу трафіку для певного маршруту або групи маршрутів. Для початку слід визначити конфігурації обмежувача швидкості, які відповідають потребам вашої програми. Як правило, це можна зробити у вашій програміRouteServiceProvider.

Обмежувачі ставок визначаються за допомогоюRateLimiterфасадніforметод.forметод приймає ім'я обмежувача швидкості та Закриття, яке повертає конфігурацію обмеження, яка повинна застосовуватися до маршрутів, яким призначений цей обмежувач швидкості:

use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Support\Facades\RateLimiter;

RateLimiter::for('global', function (Request $request) {
    return Limit::perMinute(1000);
});

Якщо вхідний запит перевищує вказаний ліміт швидкості, відповідь із кодом стану 429 HTTP автоматично повернеться Laravel. Якщо ви хочете визначити власну відповідь, яку слід повернути з обмеженням швидкості, ви можете скористатися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')),
    ];
});

Прикріплення обмежувачів ставок до маршрутів

Обмежувачі ставок можуть бути прикріплені до маршрутів або груп маршрутів за допомогоюthrottleMiddlware. Проміжне програмне забезпечення дросельної заслінки приймає назву обмежувача швидкості, який ви хочете призначити маршруту:

Route::middleware(['throttle:uploads'])->group(function () {
    Route::post('/audio', function () {
        //
    });

    Route::post('/video', function () {
        //
    });
});

Дротування з Редісом

Як правило,throttleMiddlware відображається наIlluminate\Routing\Middleware\ThrottleRequestsклас. Це відображення визначено у ядрі HTTP вашої програми. Однак, якщо ви використовуєте 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="/foo/bar" method="POST">
    <input type="hidden" name="_method" value="PUT">
    <input type="hidden" name="_token" value="{{ csrf_token() }}">
</form>

Ви можете використовувати@methodДиректива Blade для створення_methodвхід:

<form action="/foo/bar" method="POST">
    @method('PUT')
    @csrf
</form>

Доступ до поточного маршруту

Ви можете використовуватиcurrent,currentRouteName, and currentRouteActionметоди наRouteфасад для доступу до інформації про маршрут, який обробляє вхідний запит:

$route = Route::current();

$name = Route::currentRouteName();

$action = Route::currentRouteAction();

Зверніться до документації API для обохосновний клас фасаду маршрутуіЕкземпляр маршрутупереглянути всі доступні методи.

Спільне використання ресурсів (CORS)

Laravel може автоматично відповідати на запити CORS OPTIONS зі значеннями, які ви налаштовуєте. Усі налаштування CORS можуть бути налаштовані у вашомуcorsфайл конфігурації та запити OPTIONS автоматично оброблятимутьсяHandleCorsMiddlware, яке за замовчуванням включено у ваш глобальний стек проміжного програмного забезпечення.

Щоб отримати додаткову інформацію про CORS та заголовки CORS, зверніться доВеб-документація MDN щодо CORS.