HTTP 回應

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

建立回應

字串和陣列

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

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

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

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

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

回應物件

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

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

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

Eloquent 模型和集合

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

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

在回應中附加標頭

請記住，大多數回應方法都是可鏈式的，允許流暢地建構回應實例。例如，您可以使用 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',
            ]);

快取控制中介層

Laravel 包含一個 cache.headers 中介層，可用於快速為一組路由設定 Cache-Control 標頭。指令應使用對應的快取控制指令的「蛇形命名法」等效方式提供，並且應以分號分隔。如果在指令清單中指定了 etag，則回應內容的 MD5 雜湊值會自動設定為 ETag 識別碼。

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 應被視為有效的分鐘數傳遞給此方法。

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

cookie 方法也接受一些較少使用的其他引數。一般來說，這些引數具有與傳遞給 PHP 原生 setcookie 方法的引數相同的目的和意義。

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

如果您想要確保 Cookie 與外寄的回應一起傳送，但您尚未擁有該回應的實例，您可以使用 Cookie facade 來「佇列」Cookie，以便在傳送回應時附加到回應。queue 方法接受建立 Cookie 實例所需的引數。這些 Cookie 將在傳送至瀏覽器之前附加到外寄的回應。

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

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

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

提前過期 Cookie

您可以透過外寄回應的 withoutCookie 方法將 Cookie 過期來移除它。

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

如果您尚未擁有外寄回應的實例，您可以使用 Cookie facade 的 expire 方法來讓 Cookie 過期。

Cookie::expire('name');

Cookie 和加密

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

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

重定向

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

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

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

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

重定向到具名路由

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

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

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

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

透過 Eloquent 模型填入參數

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

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

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

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

重定向到控制器動作

您也可以產生指向控制器動作的重定向。若要執行此操作，請將控制器和動作名稱傳遞給 action 方法。

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

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

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

重定向到外部網域

有時您可能需要重定向到應用程式以外的網域。您可以呼叫 away 方法來執行此操作，該方法會建立一個沒有任何其他 URL 編碼、驗證或驗證的 RedirectResponse。

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

重定向並帶有快閃 Session 資料

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

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

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

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

重定向並帶有輸入

您可以使用 RedirectResponse 實例提供的 withInput 方法，在將使用者重定向到新的位置之前，將目前請求的輸入資料快閃到 session。如果使用者遇到驗證錯誤，通常會這樣做。將輸入快閃到 session 後，您可以在下一個請求中輕鬆地擷取它以重新填入表單。

return back()->withInput();

其他回應類型

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

視圖回應

如果您需要控制 response 的狀態和標頭，同時也需要返回一個視圖作為 response 的內容，您應該使用 view 方法。

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

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

JSON 回應

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

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

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

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

檔案下載

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

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

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

檔案回應

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

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

串流回應

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

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 Response

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

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

串流下載

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

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

回應巨集

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

<?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 輔助函式呼叫巨集名稱時，將會執行巨集的閉包。

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