HTTP-отклики

Статистика: Символов — 15 320/13 043 без пробелов (7 664/6 599 без кода):, слов — 1 066
Разметка: Wiki
{{TOC}}

{{DOCVER 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51, 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15, 5.1=cdc24ba7426c5b11eb4d050706bd78c3ea4913cc 19.06.2016 20:08:01, 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11}}

== Создание откликов ==
**Строки и массивы**

Все маршруты и контроллеры должны возвращать отклик для отправки обратно в браузер. Laravel предоставляет несколько разных способов для возврата откликов. Самый основной отклик - простой возврат строки из маршрута или контроллера. Фреймворк автоматически конвертирует строку в полный HTTP-отклик:
%%
Route::get('/', function () {
  return 'Hello World';
});
%%

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51)
Помимо строк из маршрутов и контроллеров можно также возвращать массивы. Фреймворк автоматически конвертирует массив в JSON-отклик:
~%%
Route::get('/', function () {
  return [1, 2, 3];
});
~%%

.(alert)
Вы знали, что вы можете также возвращать ((//docs/v5/eloquent-collections коллекции Eloquent)) из маршрутов и контроллеров? Они будут автоматически сконвертированы в JSON. Попробуйте!

**Объекты откликов**

Чаще всего вы будете возвращать из действий маршрутов не просто строки или массивы. Вместо этого вы будете возвращать полные экземпляры %%(t)Illuminate\Http\Response%% или ((/docs/v5/views представления)).

Возврат полного экземпляра %%(t)Response%% позволяет вам изменять HTTP-код состояния и заголовки откликов. Экземпляр %%(t)Response%% наследует класс %%(t)Symfony\Component\HttpFoundation\Response%%, который предоставляет множество методов для создания HTTP-откликов:
~%%
Route::get('home', function () {
  return response('Hello World', 200)
                ->header('Content-Type', 'text/plain');
});
~%%
%%

%%(DOCNEW 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15, 5.1=cdc24ba7426c5b11eb4d050706bd78c3ea4913cc 19.06.2016 20:08:01, 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11)
**Объекты откликов**

Но для большинства маршрутов и //действий// контроллера вы будете возвращать полный объект %%(t)Illuminate\Http\Response%% или ((/docs/v5/views представление)). Возвращая полный экземпляр %%(t)Response%%, вы можете изменить код HTTP-статуса и заголовок отклика. Объект %%(t)Response%% наследует от класса %%(t)Symfony\Component\HttpFoundation\Response%%, предоставляя множество методов для построения HTTP-откликов:
~%%
use Illuminate\Http\Response;

Route::get('home', function () {
  return (new Response($content, $status))
                ->header('Content-Type', $value);
});
~%%

Для удобства вы можете использовать вспомогательную функцию %%response()%%:
~%%
Route::get('home', function () {
  return response($content, $status)
                ->header('Content-Type', $value);
});
~%%

.(alert)
Полный список доступных методов класса %%(t)Response%% можно найти в ((http://laravel.com/api/master/Illuminate/Http/Response.html документации по его API)) и в ((http://api.symfony.com/3.0/Symfony/Component/HttpFoundation/Response.html документации по API Symfony)).
%%

**Добавление заголовков в отклики**

Имейте ввиду, что большинство методов %%(t)Response%% сцепляемы, что делает создание откликов более гибким. Например, вы можете использовать метод %%header()%% для добавления нескольких заголовков в отклик перед его отправкой пользователю:
%%
return response($content)
          ->header('Content-Type', $type)
          ->header('X-Header-One', 'Header Value')
          ->header('X-Header-Two', 'Header Value');
%%

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51, 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15)
Или, вы можете использовать метод %%withHeaders()%% для добавления массива заголовков в отклик:
~%%
return response($content)
          ->withHeaders([
            'Content-Type' => $type,
            'X-Header-One' => 'Header Value',
            'X-Header-Two' => 'Header Value',
          ]);
~%%
%%

%%(DOCNEW 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11)
**Отправка шаблона в отклик**

Если вам нужен доступ к методам класса %%Response%%, но вы хотите возвращать шаблон в качестве содержимого отклика, то вы можете использовать метод %%view()%% для удобства:
~%%
return response()->view('hello')->header('Content-Type', $type);
~%%
%%

**Добавление cookie в отклики**
%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51, 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15)
Использование метода %%cookie()%% на экземплярах отклика позволяет вам легко добавить cookie в отклик. Например, вы можете использовать метод %%cookie()%% для создания cookie и гибкого добавления его в экземпляр отклика:
~%%
return response($content)
                ->header('Content-Type', $type)
                ->cookie('name', 'value', $minutes);
~%%

Метод %%cookie()%% также принимает ещё несколько аргументов, используемых реже. В целом эти аргументы имеют такое же назначение и значение, как аргументы, передаваемые в PHP-метод ((https://secure.php.net/manual/en/function.setcookie.php setcookie)):
~%%
->cookie($name, $value, $minutes, $path, $domain, $secure, $httpOnly)
~%%
%%

%%(DOCNEW 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15)
Или, вы можете использовать метод %%queue()%% ((//docs/v5/facades фасада)) %%(t)Cookie%% для создания cookie, который будет автоматически добавлен в исходящий отклик:
~%%
<?php

namespace App\Http\Controllers;

use Cookie;
use App\Http\Controllers\Controller;
class DashboardController extends Controller
{
  /**
   * Показать панель управления приложения.
   *
   * @return Response
   */
  public function index()
  {
    Cookie::queue('saw_dashboard', true, 15);

    return view('dashboard');
  }
}
~%%

В этом примере cookie %%(t)saw_dashboard%% будет автоматически добавлен в исходящий отклик, без необходимости вручную прикреплять cookie к конкретному экземпляру отклика.
%%

%%(DOCNEW 5.1=cdc24ba7426c5b11eb4d050706bd78c3ea4913cc 19.06.2016 20:08:01, 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11)
Использование вспомогательного метода %%withCookie()%% на экземпляре отклика позволяет вам легко добавить cookie в отклик. Например, вы можете использовать метод %%withCookie()%% для создания cookie и добавления его в экземпляр отклика:
~%%
return response($content)->header('Content-Type', $type)
               ->withCookie('name', 'value');
~%%

Метод %%withCookie()%% принимает дополнительные необязательные аргументы для настройки свойств cookie:
~%%
->withCookie($name, $value, $minutes, $path, $domain, $secure, $httpOnly)
~%%
%%

**Cookies и шифрование**

По умолчанию все генерируемые cookie в Laravel шифруются и подписываются, поэтому они не могут быть прочитаны или изменены клиентом. Если вы хотите отключить шифрование для определённого набора cookie в вашем приложении, вы можете использовать свойство %%$except%% посредника %%(t)App\Http\Middleware\EncryptCookies%%, который находится в каталоге %%(t)app/Http/Middleware%%:
%%
/**
 * Названия тех cookie, которые не надо шифровать.
 *
 * @var array
 */
protected $except = [
  'cookie_name',
];
%%

== Переадресация ==
Отклики для переадресации - это объекты класса %%(t)Illuminate\Http\RedirectResponse%%, и они содержат надлежащие заголовки, необходимые для переадресации пользователя на другой URL. Есть несколько способов создания объекта %%(t)RedirectResponse%%. Простейший из них - использовать глобальный вспомогательный метод %%redirect()%%:
%%
Route::get('dashboard', function () {
  return redirect('home/dashboard');
});
%%

Если вы захотите переадресовать пользователя на предыдущую страницу (например, после отправки формы с некорректными данными), используйте глобальный метод %%back()%%. Поскольку для этого используются ((//docs/v5/session сессии)), маршрут, вызывающий метод %%back()%%, должен использовать группу посредников %%(t)web%% или должен применять всех посредников сессий:
%%
Route::post('user/profile', function () {
  // Проверка запроса...

  return back()->withInput();
});
%%

=== Переадресация на именованный маршрут ===
Когда вы вызываете функцию %%redirect()%% без параметров, возвращается экземпляр %%(t)Illuminate\Routing\Redirector%%, позволяя вам вызывать любой метод объекта %%(t)Redirector%%. Например, для создания %%(t)RedirectResponse%% на именованный маршрут вы можете использовать метод %%route()%%:
%%
return redirect()->route('login');
%%

Если у вашего маршрута есть параметры, вы можете передать их в качестве второго аргумента в метод %%route()%%:
%%
// Для маршрута с таким URI: profile/{id}

return redirect()->route('profile', ['id' => 1]);
%%

**Заполнение параметров через модели Eloquent**

Если вы переадресовываете на маршрут с параметром "ID", который был взят из модели Eloquent, то вы можете просто передать саму модель. ID будет извлечён автоматически:
%%
// Для маршрута с таким URI: profile/{id}

return redirect()->route('profile', [$user]);
%%

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51)
Для изменения значения, помещённого в параметр маршрута, переопределите метод %%getRouteKey()%% в вашей модели Eloquent:
~%%
/**
 * Получить значение ключа маршрута модели.
 *
 * @return mixed
 */
public function getRouteKey()
{
  return $this->slug;
}
~%%
%%

%%(DOCNEW 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11)
**Переадресация на именованный маршрут с именованными параметрами**
~%%
// Для маршрута с таким URI: profile/{user}

return redirect()->route('profile', ['user' => 1]);
~%%
%%

=== Переадресация на действие ((docs/v5/controllers контроллера)) ===
Также вы можете создать отклик-переадресацию на ((/docs/v5/controllers действие контроллера)). Для этого передайте контроллер и название действия в метод %%action()%%. 

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51, 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15, 5.1=f60f8b3697b3ffe381df4ddb7e2875ffce940643 1.04.2016 17:39:10)
Не забудьте, что вам не надо указывать полное пространство имён для контроллера, так как %%(t)RouteServiceProvider%% в Laravel автоматически задаёт пространство имён базового контроллера:
~%%
return redirect()->action('HomeController@index');
~%%
%%

%%(DOCNEW 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11)
~%%
return redirect()->action('App\Http\Controllers\HomeController@index');
~%%

.(alert)
Вам не надо указывать полное пространство имён для контроллера, если вы зарегистрировали пространство имён корневого контроллера с помощью %%URL::setRootControllerNamespace%%.
%%

Если маршрут вашего контроллера требует параметров, вы можете передать их вторым аргументом метода %%action()%%:
%%
return redirect()->action(
  'UserController@profile', ['id' => 1]
);
%%

%%(DOCNEW 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11)
**Переадресация на действие ((docs/v5/controllers контроллера)) с именованными параметрами**
~%%
return redirect()->action('App\Http\Controllers\UserController@profile', ['user' => 1]);
~%%
%%

=== Переадресация с одноразовыми переменными сессии ===
Переадресация на новый URL и ((/docs/v5/session передача данных в сессию)) обычно происходят в одно время. Обычно это делается после успешного выполнения действия, когда вы передаёте сообщение об этом в сессию. Для удобства вы можете создать экземпляр %%(t)RedirectResponse%% и передать данные в сессию в одной гибкой связке методов:
%%
Route::post('user/profile', function () {
  // Обновление профиля пользователя...

  return redirect('dashboard')->with('status', 'Profile updated!');
});
%%

Когда пользователь переадресован, вы можете вывести одноразовое сообщение из ((/docs/v5/session сессии)). Например, с помощью ((/docs/v5/blade синтаксиса Blade)):
%%
@if (session('status'))
  <div class="alert alert-success">
    {{ session('status') }}
  </div>
@endif
%%

== Другие типы откликов ==
Метод %%response()%% можно использовать для создания экземпляров откликов других типов. Когда %%response()%% вызывается без аргументов, возвращается реализация ((/docs/v5/contracts контракта)) %%(t)Illuminate\Contracts\Routing\ResponseFactory%%. Этот контракт предоставляет несколько полезных методов для создания откликов.

=== Отклики представления ===
Если вам необходим контроль над статусом и заголовком отклика, но при этом необходимо возвращать ((/docs/v5/views представление)) в качестве содержимого отклика, используйте метод %%view()%%:
%%
return response()
            ->view('hello', $data, 200)
            ->header('Content-Type', $type);
%%

Конечно, если вам не надо передавать свой код HTTP-статуса и свои заголовки, вы можете просто использовать глобальную функцию %%view()%%.

=== JSON-отклики ===
Метод %%json()%% автоматически задаст заголовок %%(t)Content-Type%% для %%(t)application/json%%, а также конвертирует данный массив в JSON при помощи PHP-функции %%json_encode()%%:
%%
return response()->json([
  'name' => 'Abigail',
  'state' => 'CA'
]);
%%

Если вы хотите создать ((ВП:JSONP))-отклик, используйте метод %%json()%% совместно с методом %%setCallback()%%:
%%
return response()
            ->json(['name' => 'Abigail', 'state' => 'CA'])
            ->withCallback($request->input('callback'));
%%

=== Отклик загрузки файла ===
Метод %%download()%% используется для создания отклика, получив который, браузер пользователя скачивает файл по указанному пути. Метод %%download()%% принимает вторым аргументом имя файла, именно это имя увидит пользователь при скачивании файла. И наконец, вы можете передать массив HTTP-заголовков третьим аргументом метода:
%%
return response()->download($pathToFile);

return response()->download($pathToFile, $name, $headers);
%%

.(alert)
Класс Symfony %%(t)HttpFoundation%%, который управляет загрузкой файлов, требует, чтобы загружаемый файл имел ASCII-имя.

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51, 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15)
=== Отклики файлы ===
Метод %%file()%% служит для вывода файла (такого как изображение или PDF) прямо в браузере пользователя, вместо запуска его скачивания. Этот метод принимает первым аргументом путь к файлу, а вторым аргументом - массив заголовков:
~%%
return response()->file($pathToFile);

return response()->file($pathToFile, $headers);
~%%
%%

== Макрос отклика ==
Если вы хотите определить собственный отклик, который вы смогли бы использовать повторно в различных маршрутах и контроллерах, то можете использовать метод %%macro()%% на фасаде %%(t)Response%%. Например, из метода %%boot()%% ((/docs/v5/providers сервис-провайдера)):
%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51, 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15)
~%%
<?php

namespace App\Providers;

use Illuminate\Support\Facades\Response;
//для версии 5.2 и ранее:
//use Response;
use Illuminate\Support\ServiceProvider;

class ResponseMacroServiceProvider extends ServiceProvider
{
  /**
   * Регистрация макроса отклика приложения.
   *
   * @return void
   */
  public function boot()
  {
    Response::macro('caps', function ($value) {
      return Response::make(strtoupper($value));
    });
  }
}
~%%
%%

%%(DOCNEW 5.1=cdc24ba7426c5b11eb4d050706bd78c3ea4913cc 19.06.2016 20:08:01, 5.0=5d10040a981deee82c0fde0e8e5d2ffc49eaaecb 8.02.2016 18:09:11)
~%%
<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Illuminate\Contracts\Routing\ResponseFactory;

class ResponseMacroServiceProvider extends ServiceProvider
{
  /**
   * Выполнение загрузки сервисов после регистрации.
   *
   * @param  ResponseFactory  $factory
   * @return void
   */
  public function boot(ResponseFactory $factory)
  {
    $factory->macro('caps', function ($value) use ($factory) {
      return $factory->make(strtoupper($value));
    });
  }
}
~%%
%%

Функция %%macro()%% принимает имя в качестве первого аргумента и замыкание в качестве второго. Замыкание макроса будет выполнено при вызове имени макроса из реализации %%(t)ResponseFactory%%: или из метода %%response()%%:
%%
return response()->caps('foo');
%%