HTTP 回應

建立回應
重新導向
其他回應類型
回應巨集

建立回應

字串和陣列

所有路由和控制器都應該回傳一個回應，以便傳送回使用者的瀏覽器。Laravel 提供了幾種不同的方式來回傳回應。最基本的回應是從路由或控制器回傳字串。框架會自動將字串轉換成完整的 HTTP 回應。

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

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

除了從您的路由和控制器回傳字串之外，您也可以回傳陣列。框架會自動將陣列轉換成 JSON 回應。

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

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

您知道您也可以從您的路由或控制器回傳 Eloquent 集合嗎？它們會自動轉換為 JSON。試試看！

回應物件

通常，您不會只是從您的路由動作中回傳簡單的字串或陣列。相反地，您將會回傳完整的 Illuminate\Http\Response 實例或視圖。

回傳完整的 Response 實例可讓您自訂回應的 HTTP 狀態碼和標頭。Response 實例繼承自 Symfony\Component\HttpFoundation\Response 類別，該類別提供了多種用於建構 HTTP 回應的方法。

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

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

Eloquent 模型和集合

您也可以直接從您的路由和控制器回傳 Eloquent ORM 模型和集合。當您這樣做時，Laravel 會自動將模型和集合轉換為 JSON 回應，同時尊重模型的隱藏屬性。

1use App\Models\User;
2 
3Route::get('/user/{user}', function (User $user) {
4    return $user;
5});

use App\Models\User;

Route::get('/user/{user}', function (User $user) {
    return $user;
});

將標頭附加到回應

請記住，大多數回應方法都是可鏈式的，允許流暢地建構回應實例。例如，您可以使用 header 方法將一系列標頭新增到回應，然後再將其傳送回使用者。

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

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

或者，您可以使用 withHeaders 方法來指定要新增到回應的標頭陣列。

1return response($content)
2    ->withHeaders([
3        'Content-Type' => $type,
4        'X-Header-One' => 'Header Value',
5        'X-Header-Two' => 'Header Value',
6    ]);

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

快取控制中介層

Laravel 包含一個 cache.headers 中介層，可用於快速設定一組路由的 Cache-Control 標頭。指令應使用對應的 cache-control 指令的「snake case」等效形式提供，並應以分號分隔。如果在指令列表中指定了 etag，則回應內容的 MD5 雜湊將自動設定為 ETag 識別符。

1Route::middleware('cache.headers:public;max_age=2628000;etag')->group(function () {
2    Route::get('/privacy', function () {
3        // ...
4    });
5 
6    Route::get('/terms', function () {
7        // ...
8    });
9});

Route::middleware('cache.headers:public;max_age=2628000;etag')->group(function () {
    Route::get('/privacy', function () {
        // ...
    });

    Route::get('/terms', function () {
        // ...
    });
});

將 Cookie 附加到回應

您可以使用 cookie 方法將 cookie 附加到外發的 Illuminate\Http\Response 實例。您應該將 cookie 的名稱、值和 cookie 應被視為有效的分鐘數傳遞給此方法。

1return response('Hello World')->cookie(
2    'name', 'value', $minutes
3);

return response('Hello World')->cookie(
    'name', 'value', $minutes
);

cookie 方法也接受一些較少使用的參數。通常，這些參數的目的和含義與 PHP 原生 setcookie 方法的參數相同。

1return response('Hello World')->cookie(
2    'name', 'value', $minutes, $path, $domain, $secure, $httpOnly
3);

return response('Hello World')->cookie(
    'name', 'value', $minutes, $path, $domain, $secure, $httpOnly
);

如果您想確保 cookie 與外發回應一起傳送，但您還沒有該回應的實例，您可以使用 Cookie facade 來「佇列」cookie，以便在傳送回應時附加到回應。queue 方法接受建立 cookie 實例所需的參數。這些 cookie 將在傳送回應之前附加到外發回應。

1use Illuminate\Support\Facades\Cookie;
2 
3Cookie::queue('name', 'value', $minutes);

use Illuminate\Support\Facades\Cookie;

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

如果您想產生一個 Symfony\Component\HttpFoundation\Cookie 實例，可以在稍後附加到回應實例，您可以使用全域 cookie 輔助函式。除非將此 cookie 附加到回應實例，否則它不會傳送回客戶端。

1$cookie = cookie('name', 'value', $minutes);
2 
3return response('Hello World')->cookie($cookie);

$cookie = cookie('name', 'value', $minutes);

return response('Hello World')->cookie($cookie);

提前過期 Cookie

您可以透過外發回應的 withoutCookie 方法使其過期來移除 cookie。

1return response('Hello World')->withoutCookie('name');

return response('Hello World')->withoutCookie('name');

如果您還沒有外發回應的實例，您可以使用 Cookie facade 的 expire 方法使 cookie 過期。

1Cookie::expire('name');

Cookie::expire('name');

Cookie 和加密

預設情況下，由於 Illuminate\Cookie\Middleware\EncryptCookies 中介層，Laravel 產生的所有 cookie 都會被加密和簽署，因此它們無法被客戶端修改或讀取。如果您想為應用程式產生的一部分 cookie 停用加密，您可以使用應用程式的 bootstrap/app.php 檔案中的 encryptCookies 方法。

1->withMiddleware(function (Middleware $middleware) {
2    $middleware->encryptCookies(except: [
3        'cookie_name',
4    ]);
5})

->withMiddleware(function (Middleware $middleware) {
    $middleware->encryptCookies(except: [
        'cookie_name',
    ]);
})

重新導向

重新導向回應是 Illuminate\Http\RedirectResponse 類別的實例，並包含將使用者重新導向到另一個 URL 所需的正確標頭。有幾種方法可以產生 RedirectResponse 實例。最簡單的方法是使用全域 redirect 輔助函式。

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

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

有時您可能希望將使用者重新導向到他們先前的位置，例如當提交的表單無效時。您可以使用全域 back 輔助函式來執行此操作。由於此功能使用 session，請確保呼叫 back 函式的路由正在使用 web 中介層群組。

1Route::post('/user/profile', function () {
2    // Validate the request...
3 
4    return back()->withInput();
5});

Route::post('/user/profile', function () {
    // Validate the request...

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

重新導向到具名路由

當您在沒有參數的情況下呼叫 redirect 輔助函式時，會回傳 Illuminate\Routing\Redirector 的實例，讓您可以在 Redirector 實例上呼叫任何方法。例如，要產生到具名路由的 RedirectResponse，您可以使用 route 方法。

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

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

如果您的路由有參數，您可以將它們作為第二個參數傳遞給 route 方法。

1// For a route with the following URI: /profile/{id}
2 
3return redirect()->route('profile', ['id' => 1]);

// For a route with the following URI: /profile/{id}

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

透過 Eloquent 模型填充參數

如果您要重新導向到具有從 Eloquent 模型填充的「ID」參數的路由，您可以傳遞模型本身。ID 將會自動提取。

1// For a route with the following URI: /profile/{id}
2 
3return redirect()->route('profile', [$user]);

// For a route with the following URI: /profile/{id}

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

如果您想自訂放置在路由參數中的值，您可以在路由參數定義 (/profile/{id:slug}) 中指定欄位，或者您可以覆寫 Eloquent 模型上的 getRouteKey 方法。

1/**
2 * Get the value of the model's route key.
3 */
4public function getRouteKey(): mixed
5{
6    return $this->slug;
7}

/**
 * Get the value of the model's route key.
 */
public function getRouteKey(): mixed
{
    return $this->slug;
}

重新導向到控制器動作

您也可以產生重新導向到控制器動作。為此，請將控制器和動作名稱傳遞給 action 方法。

1use App\Http\Controllers\UserController;
2 
3return redirect()->action([UserController::class, 'index']);

use App\Http\Controllers\UserController;

return redirect()->action([UserController::class, 'index']);

如果您的控制器路由需要參數，您可以將它們作為第二個參數傳遞給 action 方法。

1return redirect()->action(
2    [UserController::class, 'profile'], ['id' => 1]
3);

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

重新導向到外部網域

有時您可能需要重新導向到應用程式外部的網域。您可以透過呼叫 away 方法來執行此操作，該方法會建立 RedirectResponse，而無需任何額外的 URL 編碼、驗證或驗證。

1return redirect()->away('https://www.google.com');

return redirect()->away('https://www.google.com');

使用快閃 Session 資料重新導向

重新導向到新的 URL 和快閃資料到 session 通常是同時完成的。通常，這是在使用 session 快閃成功訊息成功執行動作後完成的。為了方便起見，您可以建立 RedirectResponse 實例，並在單一的流暢方法鏈中將資料快閃到 session。

1Route::post('/user/profile', function () {
2    // ...
3 
4    return redirect('/dashboard')->with('status', 'Profile updated!');
5});

Route::post('/user/profile', function () {
    // ...

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

在使用者被重新導向後，您可以從 session 顯示快閃訊息。例如，使用 Blade 語法。

1@if (session('status'))
2    <div class="alert alert-success">
3        {{ session('status') }}
4    </div>
5@endif

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

使用輸入重新導向

您可以使用 RedirectResponse 實例提供的 withInput 方法，在將使用者重新導向到新位置之前，將當前請求的輸入資料快閃到 session。如果使用者遇到驗證錯誤，通常會這樣做。一旦輸入被快閃到 session，您就可以在下一個請求期間輕鬆地檢索它以重新填充表單。

1return back()->withInput();

return back()->withInput();

其他回應類型

response 輔助函式可用於產生其他類型的回應實例。當在沒有參數的情況下呼叫 response 輔助函式時，會回傳 Illuminate\Contracts\Routing\ResponseFactory 合約的實作。此合約提供了幾種用於產生回應的有用方法。

視圖回應

如果您需要控制回應的狀態和標頭，但也需要回傳視圖作為回應的內容，您應該使用 view 方法。

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

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

當然，如果您不需要傳遞自訂 HTTP 狀態碼或自訂標頭，您可以使用全域 view 輔助函式。

JSON 回應

json 方法會自動將 Content-Type 標頭設定為 application/json，以及使用 json_encode PHP 函式將給定的陣列轉換為 JSON。

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

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

如果您想建立 JSONP 回應，您可以將 json 方法與 withCallback 方法結合使用。

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

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

檔案下載

download 方法可用於產生一個回應，強制使用者的瀏覽器下載給定路徑的檔案。download 方法接受檔案名稱作為該方法的第二個參數，這將決定下載檔案的使用者看到的檔案名稱。最後，您可以將 HTTP 標頭陣列作為該方法的第三個參數傳遞。

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

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

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

管理檔案下載的 Symfony HttpFoundation 要求下載的檔案具有 ASCII 檔案名稱。

檔案回應

file 方法可用於直接在使用者的瀏覽器中顯示檔案（例如圖片或 PDF），而不是啟動下載。此方法接受檔案的絕對路徑作為其第一個參數，以及標頭陣列作為其第二個參數。

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

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

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

串流回應

透過在資料產生時將其串流傳輸到客戶端，您可以顯著減少記憶體使用量並提高效能，尤其對於非常大的回應而言。串流回應允許客戶端在伺服器完成傳送資料之前開始處理資料。

 1function streamedContent(): Generator {
 2    yield 'Hello, ';
 3    yield 'World!';
 4}
 5 
 6Route::get('/stream', function () {
 7    return response()->stream(function (): void {
 8        foreach (streamedContent() as $chunk) {
 9            echo $chunk;
10            ob_flush();
11            flush();
12            sleep(2); // Simulate delay between chunks...
13        }
14    }, 200, ['X-Accel-Buffering' => 'no']);
15});

function streamedContent(): Generator {
    yield 'Hello, ';
    yield 'World!';
}

Route::get('/stream', function () {
    return response()->stream(function (): void {
        foreach (streamedContent() as $chunk) {
            echo $chunk;
            ob_flush();
            flush();
            sleep(2); // Simulate delay between chunks...
        }
    }, 200, ['X-Accel-Buffering' => 'no']);
});

在內部，Laravel 使用 PHP 的輸出緩衝功能。正如您在上面的範例中所看到的，您應該使用 ob_flush 和 flush 函式將緩衝的內容推送到客戶端。

串流 JSON 回應

如果您需要以增量方式串流 JSON 資料，您可以使用 streamJson 方法。此方法對於需要逐步傳送到瀏覽器的大型資料集特別有用，格式可以輕鬆地被 JavaScript 解析。

1use App\Models\User;
2 
3Route::get('/users.json', function () {
4    return response()->streamJson([
5        'users' => User::cursor(),
6    ]);
7});

use App\Models\User;

Route::get('/users.json', function () {
    return response()->streamJson([
        'users' => User::cursor(),
    ]);
});

串流下載

有時您可能希望將給定操作的字串回應轉換為可下載的回應，而無需將操作的內容寫入磁碟。您可以在這種情況下使用 streamDownload 方法。此方法接受回呼函式、檔案名稱和可選的標頭陣列作為其參數。

1use App\Services\GitHub;
2 
3return response()->streamDownload(function () {
4    echo GitHub::api('repo')
5        ->contents()
6        ->readme('laravel', 'laravel')['contents'];
7}, 'laravel-readme.md');

use App\Services\GitHub;

return response()->streamDownload(function () {
    echo GitHub::api('repo')
        ->contents()
        ->readme('laravel', 'laravel')['contents'];
}, 'laravel-readme.md');

回應巨集

如果您想定義一個自訂回應，您可以在各種路由和控制器中重複使用，您可以使用 Response facade 上的 macro 方法。通常，您應該從應用程式的服務提供者之一的 boot 方法中呼叫此方法，例如 App\Providers\AppServiceProvider 服務提供者。

 1<?php
 2 
 3namespace App\Providers;
 4 
 5use Illuminate\Support\Facades\Response;
 6use Illuminate\Support\ServiceProvider;
 7 
 8class AppServiceProvider extends ServiceProvider
 9{
10    /**
11     * Bootstrap any application services.
12     */
13    public function boot(): void
14    {
15        Response::macro('caps', function (string $value) {
16            return Response::make(strtoupper($value));
17        });
18    }
19}

<?php

namespace App\Providers;

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

class AppServiceProvider extends ServiceProvider
{
    /**
     * Bootstrap any application services.
     */
    public function boot(): void
    {
        Response::macro('caps', function (string $value) {
            return Response::make(strtoupper($value));
        });
    }
}

macro 函式接受名稱作為其第一個參數，並接受閉包作為其第二個參數。當從 ResponseFactory 實作或 response 輔助函式呼叫巨集名稱時，將會執行巨集的閉包。

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

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

序言

開始使用

架構概念

基礎

深入探討

安全性

資料庫

Eloquent ORM

測試

套件

HTTP 回應

建立回應

字串和陣列

回應物件

Eloquent 模型和集合

將標頭附加到回應

快取控制中介層

將 Cookie 附加到回應

提前過期 Cookie

Cookie 和加密

重新導向

重新導向到具名路由

透過 Eloquent 模型填充參數

重新導向到控制器動作

重新導向到外部網域

使用快閃 Session 資料重新導向

使用輸入重新導向

其他回應類型

視圖回應

JSON 回應

檔案下載

檔案回應

串流回應

串流 JSON 回應

串流下載

回應巨集

產品

套件

資源