Skip to content

HTTP 回應

建立回應

字串與陣列

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

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

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

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

📌 備註

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

回應物件

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

回傳完整的 Response 實例允許您自訂回應的 HTTP 狀態碼與標頭。Response 實例繼承自 Symfony\Component\HttpFoundation\Response 類別,該類別提供了多種建構 HTTP 回應的方法:

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

Eloquent 模型與集合

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

php
use App\Models\User;

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

附加標頭至回應

請記住,大多數的回應方法都是可以鏈結的,這使得建構回應實例的過程更加流暢。例如,您可以使用 header 方法在將回應傳送回使用者之前,為回應加入一系列的標頭:

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

或者,您可以使用 withHeaders 方法來指定要加入到回應中的標頭陣列:

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

您可以使用 withoutHeader 方法從傳出的回應中移除特定的標頭:

php
return response($content)->withoutHeader('X-Debug');

return response($content)->withoutHeader(['X-Debug', 'X-Powered-By']);

快取控制中介層

Laravel 包含一個 cache.headers 中介層,可用於快速為一組路由設定 Cache-Control 標頭。指示語 (Directives) 應使用與其對應的快取控制指示語之「蛇形命名法 (snake case)」格式,並以分號分隔。如果在指示語清單中指定了 etag,回應內容的 MD5 雜湊值將會自動被設定為 ETag 識別碼:

php
Route::middleware('cache.headers:public;max_age=30;s_maxage=300;stale_while_revalidate=600;etag')->group(function () {
    Route::get('/privacy', function () {
        // ...
    });

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

您可以使用 cookie 方法將 Cookie 附加到傳出的 Illuminate\Http\Response 實例。您應該將名稱、值以及 Cookie 的有效分鐘數傳遞給此方法:

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

cookie 方法還接受一些較少使用的參數。通常,這些參數的目的與意義與 PHP 原生的 setcookie 方法所使用的參數相同:

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

如果您希望確保 Cookie 隨傳出的回應一起傳送,但您尚未擁有該回應的實例,您可以使用 Cookie Facade 將 Cookie 「排入佇列 (queue)」,以便在回應傳送時附加。queue 方法接受建立 Cookie 實例所需的參數。這些 Cookie 將在傳送到瀏覽器之前被附加到傳出的回應中:

php
use Illuminate\Support\Facades\Cookie;

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

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

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

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

您可以透過傳出回應的 withoutCookie 方法讓 Cookie 過期,進而移除它:

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

如果您尚未擁有傳出回應的實例,可以使用 Cookie Facade 的 expire 方法讓 Cookie 過期:

php
Cookie::expire('name');

預設情況下,得益於 Illuminate\Cookie\Middleware\EncryptCookies 中介層,Laravel 產生的所有 Cookie 都經過加密與簽署,因此客戶端無法修改或讀取它們。如果您想針對應用程式產生的部分 Cookie 停用加密,可以在應用程式的 bootstrap/app.php 檔案中使用 encryptCookies 方法:

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

📌 備註

一般來說,永遠不應該停用 Cookie 加密,因為這會使您的 Cookie 暴露於潛在的客戶端資料外洩與竄改風險中。

重新導向

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

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

有時您可能希望將使用者重新導向到他們之前的位置,例如當提交的表單無效時。您可以使用全域 back 輔助函式來做到這一點。由於此功能利用了 session,請確保呼叫 back 函式的路由使用了 web 中介層群組:

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

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

重新導向至具名路由

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

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

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

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

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

透過 Eloquent 模型填入參數

如果您正在重新導向到一個具有「ID」參數的路由,而該參數是從 Eloquent 模型填入的,則您可以直接傳遞模型本身。ID 將會被自動擷取:

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

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

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

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

重新導向至控制器動作

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

php
use App\Http\Controllers\UserController;

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

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

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

重新導向至外部網域

有時您可能需要重新導向到應用程式之外的網域。您可以透過呼叫 away 方法來做到這一點,該方法會建立一個 RedirectResponse,而不進行任何額外的 URL 編碼、驗證或驗證:

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

重新導向並攜帶 Session 閃存資料

重新導向到新的 URL 並將 資料閃存 (Flash) 到 Session 通常是同時進行的。這通常在成功執行某個動作後,將成功訊息閃存到 Session 時進行。為了方便起見,您可以建立一個 RedirectResponse 實例並在單個流暢的方法鏈中將資料閃存到 Session:

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

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

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

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

重新導向並攜帶輸入資料

您可以使用 RedirectResponse 實例提供的 withInput 方法,在將使用者重新導向到新位置之前,將當前請求的輸入資料閃存到 Session。這通常在使用者遇到驗證錯誤時使用。一旦輸入資料被閃存到 Session,您就可以在下一個請求中輕鬆地 取得它 以重新填充表單:

php
return back()->withInput();

其他回應類型

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

視圖回應

如果您需要控制回應的狀態和標頭,但也需要回傳 視圖 (View) 作為回應內容,則應使用 view 方法:

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

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

JSON 回應

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

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

如果您想建立一個 JSONP 回應,可以將 json 方法與 withCallback 方法結合使用:

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

檔案下載

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

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

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

⚠️ 警告

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

檔案回應

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

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

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

串流回應

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

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

為了方便起見,如果您提供給 stream 方法的閉包回傳了一個 Generator,Laravel 將自動在產生器回傳的字串之間排空 (Flush) 輸出緩衝區,並停用 Nginx 的輸出緩衝:

php
Route::post('/chat', function () {
    return response()->stream(function (): Generator {
        $stream = OpenAI::client()->chat()->createStreamed(...);

        foreach ($stream as $response) {
            yield $response->choices[0];
        }
    });
});

取用串流回應

您可以使用 Laravel 的 stream npm 套件來取用串流回應,該套件提供了方便的 API 用於與 Laravel 回應和事件串流進行互動。首先,請安裝 @laravel/stream-react@laravel/stream-vue 套件:

shell
npm install @laravel/stream-react
shell
npm install @laravel/stream-vue

接著,可以使用 useStream 來取用事件串流。提供串流 URL 後,當您的 Laravel 應用程式傳回內容時,該 Hook 會自動將 data 更新為串接後的回應:

tsx
import { useStream } from "@laravel/stream-react";

function App() {
    const { data, isFetching, isStreaming, send } = useStream("chat");

    const sendMessage = () => {
        send({
            message: `Current timestamp: ${Date.now()}`,
        });
    };

    return (
        <div>
            <div>{data}</div>
            {isFetching && <div>Connecting...</div>}
            {isStreaming && <div>Generating...</div>}
            <button onClick={sendMessage}>Send Message</button>
        </div>
    );
}
vue
<script setup lang="ts">
import { useStream } from "@laravel/stream-vue";

const { data, isFetching, isStreaming, send } = useStream("chat");

const sendMessage = () => {
    send({
        message: `Current timestamp: ${Date.now()}`,
    });
};
</script>

<template>
    <div>
        <div>{{ data }}</div>
        <div v-if="isFetching">Connecting...</div>
        <div v-if="isStreaming">Generating...</div>
        <button @click="sendMessage">Send Message</button>
    </div>
</template>

透過 send 將資料傳回串流時,系統會在傳送新資料前取消與該串流的現有連線。所有請求都以 JSON POST 請求發送。

⚠️ 警告

由於 useStream Hook 會向您的應用程式發送 POST 請求,因此需要有效的 CSRF 權杖。最簡單的提供方式是透過應用程式佈局的 head 區塊中的 meta 標籤包含它

提供給 useStream 的第二個參數是一個選項物件,您可以用它來定義串流取用行為。該物件的預設值如下所示:

tsx
import { useStream } from "@laravel/stream-react";

function App() {
    const { data } = useStream("chat", {
        id: undefined,
        initialInput: undefined,
        headers: undefined,
        csrfToken: undefined,
        onResponse: (response: Response) => void,
        onData: (data: string) => void,
        onCancel: () => void,
        onFinish: () => void,
        onError: (error: Error) => void,
    });

    return <div>{data}</div>;
}
vue
<script setup lang="ts">
import { useStream } from "@laravel/stream-vue";

const { data } = useStream("chat", {
    id: undefined,
    initialInput: undefined,
    headers: undefined,
    csrfToken: undefined,
    onResponse: (response: Response) => void,
    onData: (data: string) => void,
    onCancel: () => void,
    onFinish: () => void,
    onError: (error: Error) => void,
});
</script>

<template>
    <div>{{ data }}</div>
</template>

onResponse 在串流收到成功的初始回應後觸發,且原始的 Response 會被傳遞給回呼函式。onData 在接收到每個分塊 (Chunk) 時被呼叫,目前的分塊會被傳遞給回呼函式。onFinish 在串流完成以及在擷取 / 讀取週期中發生錯誤時被呼叫。

預設情況下,初始化時不會對串流發送請求。您可以使用 initialInput 選項傳送初始負載給串流:

tsx
import { useStream } from "@laravel/stream-react";

function App() {
    const { data } = useStream("chat", {
        initialInput: {
            message: "Introduce yourself.",
        },
    });

    return <div>{data}</div>;
}
vue
<script setup lang="ts">
import { useStream } from "@laravel/stream-vue";

const { data } = useStream("chat", {
    initialInput: {
        message: "Introduce yourself.",
    },
});
</script>

<template>
    <div>{{ data }}</div>
</template>

若要手動取消串流,您可以使用 Hook 回傳的 cancel 方法:

tsx
import { useStream } from "@laravel/stream-react";

function App() {
    const { data, cancel } = useStream("chat");

    return (
        <div>
            <div>{data}</div>
            <button onClick={cancel}>Cancel</button>
        </div>
    );
}
vue
<script setup lang="ts">
import { useStream } from "@laravel/stream-vue";

const { data, cancel } = useStream("chat");
</script>

<template>
    <div>
        <div>{{ data }}</div>
        <button @click="cancel">Cancel</button>
    </div>
</template>

每次使用 useStream Hook 時,都會產生一個隨機的 id 來識別串流。這會隨每個請求一起在 X-STREAM-ID 標頭中傳回伺服器。當從多個組件取用同一個串流時,您可以透過提供自己的 id 來讀取或寫入該串流:

tsx
// App.tsx
import { useStream } from "@laravel/stream-react";

function App() {
    const { data, id } = useStream("chat");

    return (
        <div>
            <div>{data}</div>
            <StreamStatus id={id} />
        </div>
    );
}

// StreamStatus.tsx
import { useStream } from "@laravel/stream-react";

function StreamStatus({ id }) {
    const { isFetching, isStreaming } = useStream("chat", { id });

    return (
        <div>
            {isFetching && <div>Connecting...</div>}
            {isStreaming && <div>Generating...</div>}
        </div>
    );
}
vue
<!-- App.vue -->
<script setup lang="ts">
import { useStream } from "@laravel/stream-vue";
import StreamStatus from "./StreamStatus.vue";

const { data, id } = useStream("chat");
</script>

<template>
    <div>
        <div>{{ data }}</div>
        <StreamStatus :id="id" />
    </div>
</template>

<!-- StreamStatus.vue -->
<script setup lang="ts">
import { useStream } from "@laravel/stream-vue";

const props = defineProps<{
    id: string;
}>();

const { isFetching, isStreaming } = useStream("chat", { id: props.id });
</script>

<template>
    <div>
        <div v-if="isFetching">Connecting...</div>
        <div v-if="isStreaming">Generating...</div>
    </div>
</template>

串流 JSON 回應

若您需要以漸進方式串流 JSON 資料,可以使用 streamJson 方法。此方法對於需要以 JavaScript 易於解析的格式,將大型資料集逐步傳送到瀏覽器的場景特別有用:

php
use App\Models\User;

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

useJsonStream hook 與 useStream hook 完全相同,唯一的區別在於它會在串流完成後嘗試將資料解析為 JSON:

tsx
import { useJsonStream } from "@laravel/stream-react";

type User = {
    id: number;
    name: string;
    email: string;
};

function App() {
    const { data, send } = useJsonStream<{ users: User[] }>("users");

    const loadUsers = () => {
        send({
            query: "taylor",
        });
    };

    return (
        <div>
            <ul>
                {data?.users.map((user) => (
                    <li>
                        {user.id}: {user.name}
                    </li>
                ))}
            </ul>
            <button onClick={loadUsers}>Load Users</button>
        </div>
    );
}
vue
<script setup lang="ts">
import { useJsonStream } from "@laravel/stream-vue";

type User = {
    id: number;
    name: string;
    email: string;
};

const { data, send } = useJsonStream<{ users: User[] }>("users");

const loadUsers = () => {
    send({
        query: "taylor",
    });
};
</script>

<template>
    <div>
        <ul>
            <li v-for="user in data?.users" :key="user.id">
                {{ user.id }}: {{ user.name }}
            </li>
        </ul>
        <button @click="loadUsers">Load Users</button>
    </div>
</template>

事件串流 (SSE)

eventStream 方法可用於回傳使用 text/event-stream 內容類型的伺服器傳送事件 (SSE) 串流回應。eventStream 方法接受一個閉包,該閉包應在回應可用時將其 yield 到串流中:

php
Route::get('/chat', function () {
    return response()->eventStream(function () {
        $stream = OpenAI::client()->chat()->createStreamed(...);

        foreach ($stream as $response) {
            yield $response->choices[0];
        }
    });
});

如果您想自定義事件名稱,可以 yield 一個 StreamedEvent 類別的實例:

php
use Illuminate\Http\StreamedEvent;

yield new StreamedEvent(
    event: 'update',
    data: $response->choices[0],
);

取用事件串流

可以使用 Laravel 的 stream npm 套件來取用事件串流,該套件提供了與 Laravel 事件串流互動的便利 API。首先,請安裝 @laravel/stream-react@laravel/stream-vue 套件:

shell
npm install @laravel/stream-react
shell
npm install @laravel/stream-vue

接著,可以使用 useEventStream 來取用事件串流。提供串流 URL 後,當訊息從您的 Laravel 應用程式回傳時,此 hook 會自動使用串接後的回應來更新 message

jsx
import { useEventStream } from "@laravel/stream-react";

function App() {
  const { message } = useEventStream("/chat");

  return <div>{message}</div>;
}
vue
<script setup lang="ts">
import { useEventStream } from "@laravel/stream-vue";

const { message } = useEventStream("/chat");
</script>

<template>
  <div>{{ message }}</div>
</template>

傳給 useEventStream 的第二個參數是一個選項物件,您可以用它來自定義串流取用行為。該物件的預設值如下所示:

jsx
import { useEventStream } from "@laravel/stream-react";

function App() {
  const { message } = useEventStream("/stream", {
    eventName: "update",
    onMessage: (message) => {
      //
    },
    onError: (error) => {
      //
    },
    onComplete: () => {
      //
    },
    endSignal: "</stream>",
    glue: " ",
  });

  return <div>{message}</div>;
}
vue
<script setup lang="ts">
import { useEventStream } from "@laravel/stream-vue";

const { message } = useEventStream("/chat", {
  eventName: "update",
  onMessage: (message) => {
    // ...
  },
  onError: (error) => {
    // ...
  },
  onComplete: () => {
    // ...
  },
  endSignal: "</stream>",
  glue: " ",
});
</script>

事件串流也可以由您的應用程式前端透過 EventSource 物件手動取用。當串流完成時,eventStream 方法會自動發送 </stream> 更新至事件串流:

js
const source = new EventSource('/chat');

source.addEventListener('update', (event) => {
    if (event.data === '</stream>') {
        source.close();

        return;
    }

    console.log(event.data);
});

若要自定義發送到事件串流的最後一個事件,您可以將 StreamedEvent 實例提供給 eventStream 方法的 endStreamWith 參數:

php
return response()->eventStream(function () {
    // ...
}, endStreamWith: new StreamedEvent(event: 'update', data: '</stream>'));

串流下載

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

php
use App\Services\GitHub;

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

回應巨集

如果您想要定義一個可以在多種路由與控制器中重複使用的自定義回應,您可以使用 Response Facade 上的 macro 方法。通常,您應該在應用程式的其中一個服務提供者(例如 App\Providers\AppServiceProvider)的 boot 方法中呼叫此方法:

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

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