Laravel5.5 LTS 日本語ドキュメント

このリポジトリはPHP Webアプリフレームワークである、LaravelのLTSバージョンである5.5の公式英文ドキュメントを日本語へ翻訳しています。

This project is maintained by okinaka

HTTPレスポンス

レスポンスの生成

文字列と配列

当然ながら全てのルートやコントローラは、ユーザーのブラウザーに対し、何らかのレスポンスを返す必要があります。Laravelはレスポンスを返すために様々な手段を用意しています。一番基本的なレスポンスは、ルートかコントローラから単に文字列を返します。フレームワークが自動的に、文字列を完全なHTTPレスポンスへ変換します。

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

ルートやコントローラから文字列を返す他に、配列も返せます。フレームワークは自動的に、配列をJSONレスポンスへ変換します。

Route::get('/', function () {
    return [1, 2, 3];
});

{tip} Eloquentコレクションも返せることを知っていますか？　自動的にJSONへ変換されます。試してください！

レスポンスオブジェクト

通常、皆さんは単純な文字列や配列をルートアクションから返すだけじゃありませんよね。代わりに、Illuminate\Http\Responseインスタンスかviewsを返したいですよね。

完全なResponseインスタンスを返せば、レスポンスのHTTPステータスコードやヘッダをカスタマイズできます。Responseインスタンスは、Symfony\Component\HttpFoundation\Responseクラスを継承しており、HTTPレスポンスを構築するために様々なメソッドを提供しています。

Route::get('home', function () {
    return response('Hello World', 200)
                  ->header('Content-Type', 'text/plain');
});

ヘッダの付加

レスポンスインスタンスをスラスラと構築できるように、ほとんどのレスポンスメソッドはチェーンとしてつなげられることを覚えておきましょう。たとえば、ユーザーにレスポンスを送り返す前に、headerメソッドでいくつかのヘッダを追加できます。

return response($content)
            ->header('Content-Type', $type)
            ->header('X-Header-One', 'Header Value')
            ->header('X-Header-Two', 'Header Value');

もしくは、withHeadersメソッドで、レスポンスへ追加したいヘッダの配列を指定します。

return response($content)
            ->withHeaders([
                'Content-Type' => $type,
                'X-Header-One' => 'Header Value',
                'X-Header-Two' => 'Header Value',
            ]);

クッキーの付加

レスポンスインスタンスのcookieメソッドで、レスポンスへ簡単にクッキーを付加できます。たとえば、cookieメソッドでクッキーを生成し、レスポンスインスタンスへ、さっと付加してみましょう。

return response($content)
                ->header('Content-Type', $type)
                ->cookie('name', 'value', $minutes);

cookieメソッドは、さらに使用機会が少ない引数をいくつか受け付けます。これらの引数は、全般的にPHPネイティブのsetcookieメソッドに指定する引数と、同じ目的、同じ意味合いを持っています。

->cookie($name, $value, $minutes, $path, $domain, $secure, $httpOnly)

もしくは、アプリケーションから送り出すレスポンスへアタッチするクッキーを「キュー」するために、Cookieファサードが使えます。queueメソッドは、CookieインスタンスかCookieインスタンスを生成するために必要な引数を受け取ります。こうしたクッキーは、ブラウザにレスポンスが送信される前にアタッチされます。

Cookie::queue(Cookie::make('name', 'value', $minutes));

Cookie::queue('name', 'value', $minutes);

クッキーと暗号化

Laravelにより生成されるクッキーは、クライアントにより変更されたり読まれたりされないようにデフォルトで暗号化され、署名されます。アプリケーションで生成する特定のクッキーで暗号化を無効にしたい場合は、app/Http/Middlewareディレクトリ中に存在する、App\Http\Middleware\EncryptCookiesミドルウェアの$exceptプロパティで指定してください。

/**
 * 暗号化しないクッキー名
 *
 * @var array
 */
protected $except = [
    'cookie_name',
];

リダイレクト

リダイレクトのレスポンスはIlluminate\Http\RedirectResponseクラスのインスタンスであり、ユーザーを他のURLへリダイレクトさせるために必要なしっかりとしたヘッダを含んでいます。RedirectResponseインスタンスを生成するには様々な方法があります。一番簡単な方法は、グローバルなredirectヘルパを使う方法です。

Route::get('dashboard', function () {
    return redirect('home/dashboard');
});

例えば送信されたフォーム内容にエラーがある場合など、直前のページヘユーザーをリダイレクトさせたい場合もあります。グローバルなbackヘルパ関数を使ってください。この機能はセッションを利用しているため、back関数を使用するルートはwebミドルウェアグループに属しているか、セッションミドルウェアが適用されることを確認してください。

Route::post('user/profile', function () {
    // レスポンスのバリデーション処理…

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

名前付きルートへのリダイレクト

redirectヘルパを引数無しで呼ぶと、Illuminate\Routing\Redirectorインスタンスが返され、Redirectorインスタンスのメソッドが呼び出せるようになります。たとえば、名前付きルートに対するRedirectResponseを生成したい場合は、routeメソッドが使えます。

return redirect()->route('login');

ルートにパラメーターがある場合は、routeメソッドの第２引数として渡してください。

// profile/{id}のURIへのリダイレクト

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

Eloquentモデルによる、パラメータの埋め込み

Eloquentモデルの”ID”をルートパラメーターとしてリダイレクトする場合は、モデルをそのまま渡してください。IDは自動的にとり出されます。

// profile/{id}のURIへのリダイレクト

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

ルートパラメータに埋め込む値をカスタマイズしたい場合は、EloquentモデルのgetRouteKeyメソッドをオーバーライドします。

/**
 * モデルのルートキー値の取得
 *
 * @return mixed
 */
public function getRouteKey()
{
    return $this->slug;
}

コントローラアクションへのリダイレクト

コントローラアクションに対するリダイレクトを生成することもできます。そのためには、コントローラとアクションの名前をactionメソッドに渡してください。LaravelのRouteServiceProviderにより、ベースのコントローラ名前空間が自動的に設定されるため、コントローラの完全名前空間名を指定する必要がないことを覚えておいてください。

return redirect()->action('HomeController@index');

コントローラルートにパラメーターが必要ならば、actionメソッドの第２引数として渡してください。

return redirect()->action(
    'UserController@profile', ['id' => 1]
);

フラッシュデータを保存するリダイレクト

新しいURLへリダイレクトし、セッションへフラッシュデータを保存するのは、一度にまとめて行われる典型的な作業です。典型的な使い方は、あるアクションが実行成功した後に、実効成功メッセージをフラッシュデータとしてセッションに保存する場合でしょう。これに便利なように、RedirectResponseインスタンスを生成し、メソッドチェーンを一つだけさっと書けば、データをセッションへ保存できるようになっています。

Route::post('user/profile', function () {
    // ユーザープロフィールの更新処理…

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

ユーザーを新しいページヘリダイレクトした後、セッションへ保存したフラッシュデータのメッセージを取り出して、表示します。たとえば、Blade記法を使ってみましょう。

@if (session('status'))
    <div class="alert alert-success">
        
    </div>
@endif

他のレスポンスタイプ

responseヘルパは、他のタイプのレスポンスインスタンスを生成するために便利です。responseヘルパが引数なしで呼び出されると、Illuminate\Contracts\Routing\ResponseFactory契約が返されます。この契約はレスポンスを生成するための、様々なメソッドを提供しています。

Viewレスポンス

レスポンスのステータスやヘッダをコントロールしながらも、レスポンス内容としてビューを返す必要がある場合は、viewメソッドを使用してください。

return response()
            ->view('hello', $data, 200)
            ->header('Content-Type', $type);

もちろん、カスタムHTTPステータスコードやヘッダの指定が不必要であれば、シンプルにグローバルviewヘルパ関数を使用することもできます。

JSONレスポンス

jsonメソッドは自動的にContent-Typeヘッダをapplication/jsonにセットし、同時に指定された配列をjson_encode PHP関数によりJSONへ変換します。

return response()->json([
    'name' => 'Abigail',
    'state' => 'CA'
]);

JSONPレスポンスを生成したい場合は、jsonメソッドとwithCallbackメソッドを組み合わせてください。

return response()
            ->json(['name' => 'Abigail', 'state' => 'CA'])
            ->withCallback($request->input('callback'));

Fileダウンロード

downloadメソッドは指定したパスのファイルをダウンロードようにブラウザに強要するレスポンスを生成するために使用します。downloadメソッドはファイル名を第２引数として受け取り、ユーザーがダウンロードするファイル名になります。第３引数にHTTPヘッダの配列を渡すこともできます。

return response()->download($pathToFile);

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

return response()->download($pathToFile)->deleteFileAfterSend(true);

{note} ファイルダウンロードを管理しているSymfony HttpFoundationクラスは、ASCIIのダウンロードファイル名を指定するよう要求しています。

Fileレスポンス

fileメソッドは、ダウンロードする代わりに、ブラウザへ画像やPDFのようなファイルを表示するために使用します。このメソッドは第1引数にファイルパス、第2引数にヘッダの配列を指定します。

return response()->file($pathToFile);

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

レスポンスマクロ

いろいろなルートやコントローラで、再利用するためのカスタムレスポンスを定義したい場合はResponseファサードのmacroメソッドが使用できます。たとえば、サービスプロバイダのbootメソッドで定義します。

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Illuminate\Support\Facades\Response;

class ResponseMacroServiceProvider extends ServiceProvider
{
    /**
     * アプリケーションのレスポンスマクロ登録
     *
     * @return void
     */
    public function boot()
    {
        Response::macro('caps', function ($value) {
            return Response::make(strtoupper($value));
        });
    }
}

macroメソッドは登録名を第１引数、クロージャを第２引数に取ります。マクロのクロージャはResponseFactoryの実装か、responseヘルパに対し、登録名で呼び出すことで、実行されます。

return response()->caps('foo');