Middleware

Введение

Посредники (англ. middleware) предоставляют удобный механизм для фильтрации HTTP-запросов вашего приложения. Например, в Laravel есть посредник для проверки аутентификации пользователя. Если пользователь не аутентифицирован, посредник перенаправит его на экран входа в систему. Если же пользователь аутентифицирован, посредник позволит запросу пройти далее в приложение.

Конечно, посредники нужны не только для авторизации. CORS-посредник может пригодиться для добавления особых заголовков ко всем ответам в вашем приложении. А посредник логов может зарегистрировать все входящие запросы.

В Laravel есть несколько стандартных посредников, включая посредники для аутентификации и CSRF-защиты. Все они расположены в каталоге app/Http/Middleware.

Создание посредника

Чтобы создать посредника, используйте команду Artisan shmake:middleware:

shphp artisan make:middleware CheckAge

Эта команда поместит новый класс CheckAge в ваш каталог app/Http/Middleware. В этом посреднике мы будем пропускать только те запросы, в которых age будет больше 200, а во всех остальных случаях будем перенаправлять пользователей на «home» URI.

<?php

namespace App\Http\Middleware;

use Closure;

class CheckAge
{
  /**
   * Обработка входящего запроса.
   *
   * @param  \Illuminate\Http\Request  $request
   * @param  \Closure  $next
   * @return mixed
   */
  public function handle($request, Closure $next)
  {
    if ($request->age <= 200) {
      return redirect('home');
    }

    return $next($request);
  }

}

Как видите, если переданный age меньше или равен 200, то посредник вернёт клиенту переадресацию, иначе, запрос будет передан далее в приложение. Чтобы передать запрос дальше в приложение (позволяя посреднику «передать» его), просто вызовите замыкание PHP$next с параметром PHP$request.

Проще всего представить посредника как набор «уровней», которые должен пройти HTTP-запрос, прежде чем он дойдёт до вашего приложения. Каждый уровень может проверить запрос и даже вовсе отклонить его.

Выполнение посредника «до» или «после» запроса

Момент, в который сработает посредник — до или после запроса, зависит от него самого. Например, этот посредник выполнит некоторую задачу прежде, чем запрос будет обработан приложением:

<?php

namespace App\Http\Middleware;

use Closure;

class BeforeMiddleware
{
  public function handle($request, Closure $next)
  {
    // Выполнение действия

    return $next($request);
  }
}

А этот посредник выполнит задачу после того, как запрос будет обработан приложением:

<?php

namespace App\Http\Middleware;

use Closure;

class AfterMiddleware
{
  public function handle($request, Closure $next)
  {
    $response = $next($request);

    // Выполнение действия

    return $response;
  }
}

Регистрация посредника

Глобальный посредник

Если вы хотите, чтобы посредник запускался для каждого HTTP-запроса в вашем приложении, добавьте этот посредник в свойство PHP$middleware класса app/Http/Kernel.php.

Назначение посредника для маршрутов

Если вы хотите назначить посредника для конкретных маршрутов, то сначала вам надо добавить ключ посредника в класс app/Http/Kernel.php. По умолчанию свойство PHP$routeMiddleware этого класса содержит записи посредников Laravel. Чтобы добавить ваш собственный посредник, просто добавьте его к этому списку и присвойте ему ключ на свой выбор. Например:

// в классе App\Http\Kernel...

protected $routeMiddleware = [
  'auth.basic' => \Illuminate\Auth\Middleware\AuthenticateWithBasicAuth::class,
  'guest' => \App\Http\Middleware\RedirectIfAuthenticated::class,
  //для версии 5.2 и выше:
  'throttle' => \Illuminate\Routing\Middleware\ThrottleRequests::class,
  //для версии 5.3 и выше:
  'auth' => \Illuminate\Auth\Middleware\Authenticate::class,
  'bindings' => \Illuminate\Routing\Middleware\SubstituteBindings::class,
  'can' => \Illuminate\Auth\Middleware\Authorize::class,
  //для версии 5.2 и ранее:
  'auth' => \App\Http\Middleware\Authenticate::class,
];

Route::get('admin/profile', function () {
  //
})->middleware('auth');

Route::get('/', function () {
  //
})->middleware('first', 'second');

Route::get('admin/profile', ['middleware' => 'auth', function () {
  //
}]);

Route::get('/', ['middleware' => ['first', 'second'], function () {
  //
}]);

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

При назначении посредника вы можете указать полное имя класса:

use App\Http\Middleware\CheckAge;

Route::get('admin/profile', function () {
  //
})->middleware(CheckAge::class);

/**
 * Группы посредников маршрутов приложения.
 *
 * @var array
 */
protected $middlewareGroups = [
  'web' => [
    \App\Http\Middleware\EncryptCookies::class,
    \Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
    \Illuminate\Session\Middleware\StartSession::class,
    \Illuminate\View\Middleware\ShareErrorsFromSession::class,
    \App\Http\Middleware\VerifyCsrfToken::class,
    \Illuminate\Routing\Middleware\SubstituteBindings::class,
  ],

  'api' => [
    'throttle:60,1',
    'auth:api',
  ],
];

Route::get('/', function () {
  //
})->middleware('web');

Route::group(['middleware' => ['web']], function () {
  //
});

Параметры посредника

В посредник можно передавать дополнительные параметры. Например, если в вашем приложении необходима проверка того, есть ли у аутентифицированного пользователя определённая «роль» для выполнения данного действия, вы можете создать посредника CheckRole, который принимает название роли в качестве дополнительного аргумента.

Дополнительные параметры посредника будут передаваться в посредник после аргумента PHP$next:

<?php

namespace App\Http\Middleware;

use Closure;

class CheckRole
{
  /**
   * Обработка входящего запроса.
   *
   * @param  \Illuminate\Http\Request  $request
   * @param  \Closure  $next
   * @param  string  $role
   * @return mixed
   */
  public function handle($request, Closure $next, $role)
  {
    if (! $request->user()->hasRole($role)) {
      // Redirect...
    }

    return $next($request);
  }

}

Параметры посредника можно указать при определении маршрута, отделив название посредника от параметров двоеточием :. Сами параметры разделяются запятыми:

Route::put('post/{id}', function ($id) {
  //
})->middleware('role:editor');

Route::put('post/{id}', ['middleware' => 'role:editor', function ($id) {
  //
}]);

Посредник terminable

Иногда посредник должен выполнить некоторые действия уже после отправки HTTP-отклика браузеру. Например, посредник «session», поставляемый с Laravel, записывает данные сессии в хранилище после отправки ответа в браузер. Если вы определите метод PHPterminate() в посреднике, то он будет автоматически вызываться после отправки отклика в браузер:

<?php

namespace Illuminate\Session\Middleware;

use Closure;

class StartSession
{
  public function handle($request, Closure $next)
  {
    return $next($request);
  }

  public function terminate($request, $response)
  {
    // Сохранение данных сессии...
  }

}

Метод PHPterminate() получает и запрос, и ответ. Определив посредника как «terminable», вы должны добавить его в список глобальных посредников в вашем HTTP-ядре.

При вызове метода PHPterminate() в посреднике, Laravel получит свежий экземпляр посредника из сервис-контейнера. Если вы хотите использовать тот же самый экземпляр посредника при вызовах методов PHPhandle() и PHPterminate(), зарегистрируйте посредника в контейнере при помощи метода PHPsingleton().