HTTP 回應 (HTTP Response)

建立 Response (Creating Responses)

字串與陣列 (Strings Arrays)

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

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

除了從路由和 Controller 回傳字串之外,你還可以回傳陣列。框架會自動將陣列轉換為 JSON Response:

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

[!NOTE] 你知道你也可以從路由或 Controller 回傳 Eloquent 集合嗎?它們會自動轉換為 JSON。試試看!

Response 物件 (Response Objects)

通常,你不會只是從路由動作回傳簡單的字串或陣列。相反,你將回傳完整的 Illuminate\Http\Response 實例或 view。

回傳完整的 Response 實例允許你自訂 Response 的 HTTP 狀態碼和標頭。Response 實例繼承自 Symfony\Component\HttpFoundation\Response 類別,它提供了各種建立 HTTP Response 的方法:

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

Eloquent 模型與集合 (Eloquent Models And Collections)

你也可以直接從路由和 Controller 回傳 Eloquent ORM 模型和集合。當你這樣做時,Laravel 會自動將模型和集合轉換為 JSON Response,同時遵守模型的隱藏屬性:

use App\Models\User;

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

將標頭附加到 Response (Attaching Headers To Responses)

請記住,大多數 Response 方法都是可鏈結的,允許流暢地建構 Response 實例。例如,你可以使用 header 方法在將 Response 發送回使用者之前向 Response 新增一系列標頭:

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

或者,你可以使用 withHeaders 方法指定要新增到 Response 的標頭陣列:

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

Cache Control Middleware

Laravel 包含一個 cache.headers Middleware,可用於快速設定一組路由的 Cache-Control 標頭。指令應使用對應的 cache-control 指令的「蛇形命名法」等效項提供,並應以分號分隔。如果在指令列表中指定了 etag,Response 內容的 MD5 雜湊將自動設定為 ETag 識別碼:

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

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

將 Cookie 附加到 Response (Attaching Cookies To Responses)

你可以使用 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 與傳出的 Response 一起發送,但你還沒有該 Response 的實例,你可以使用 Cookie Facade 將 Cookie 「排隊」以在發送 Response 時附加到 Response。queue 方法接受建立 Cookie 實例所需的參數。這些 Cookie 會在發送到瀏覽器之前附加到傳出的 Response:

use Illuminate\Support\Facades\Cookie;

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

產生 Cookie 實例 (Generating Cookie Instances)

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

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

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

提前過期 Cookie (Expiring Cookies Early)

你可以透過傳出 Response 的 withoutCookie 方法使其過期來移除 Cookie:

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

如果你還沒有傳出 Response 的實例,你可以使用 Cookie Facade 的 expire 方法使 Cookie 過期:

Cookie::expire('name');

Cookie 與加密 (Cookies And Encryption)

預設情況下,由於 Illuminate\Cookie\Middleware\EncryptCookies Middleware,Laravel 產生的所有 Cookie 都經過加密和簽名,因此客戶端無法修改或讀取它們。如果你想為應用程式產生的 Cookie 子集停用加密,你可以在應用程式的 bootstrap/app.php 檔案中使用 encryptCookies 方法:

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

重新導向 (Redirects)

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

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

有時你可能希望將使用者重新導向到其先前的位置,例如當提交的表單無效時。你可以使用全域 back 輔助函式來實現。由於此功能使用 Session,請確保呼叫 back 函式的路由使用 web Middleware 群組:

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

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

重新導向到命名路由 (Redirecting Named Routes)

當你在沒有參數的情況下呼叫 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 模型填充參數 (Populating Parameters Via Eloquent Models)

如果你要重新導向到具有從 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;
}

重新導向到 Controller 動作 (Redirecting Controller Actions)

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

use App\Http\Controllers\UserController;

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

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

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

重新導向到外部網域 (Redirecting External Domains)

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

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

使用快閃的 Session 資料重新導向 (Redirecting With Flashed Session Data)

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

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

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

使用者重新導向後,你可以從 Session 顯示快閃的訊息。例如,使用 Blade 語法:

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

使用輸入重新導向 (Redirecting With Input)

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

return back()->withInput();

其他 Response 類型 (Other Response Types)

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

View Response

如果你需要控制 Response 的狀態和標頭,但還需要回傳 view 作為 Response 的內容,你應該使用 view 方法:

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

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

JSON Response

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

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

如果你想建立 JSONP Response,你可以將 json 方法與 withCallback 方法結合使用:

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

檔案下載 (File Downloads)

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

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

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

[!WARNING] 管理檔案下載的 Symfony HttpFoundation 要求正在下載的檔案具有 ASCII 檔案名稱。

檔案 Response (File Responses)

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

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

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

串流 Response (Streamed Responses)

透過在產生資料時將其串流到客戶端,你可以顯著減少記憶體使用並提高效能,尤其是對於非常大的 Response。串流 Response 允許客戶端在伺服器完成發送之前開始處理資料:

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 會自動在產生器回傳的字串之間刷新輸出緩衝區,並停用 Nginx 輸出緩衝:

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

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

使用串流 Response (Consuming Streamed Responses)

串流 Response 可以使用 Laravel 的 stream npm 套件使用,它提供了一個方便的 API 來與 Laravel Response 和事件串流互動。要開始使用,請安裝 @laravel/stream-react 或 @laravel/stream-vue 套件:

npm install @laravel/stream-react

npm install @laravel/stream-vue

然後,useStream 可用於使用事件串流。提供你的串流 URL 後,hook 會在從你的 Laravel 應用程式回傳內容時自動使用串聯的 Response 更新 data:

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>
  );
}

<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 請求發送。

[!WARNING] 由於 useStream hook 向你的應用程式發出 POST 請求,因此需要有效的 CSRF token。提供 CSRF token 的最簡單方法是透過應用程式佈局的 head 中的 meta 標籤包含它。

給予 useStream 的第二個參數是一個選項物件,你可以使用它來自訂串流使用行為。此物件的預設值如下所示:

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>;
}

<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 在接收到每個區塊時呼叫 - 當前區塊傳遞給回呼。onFinish 在串流完成時以及在 fetch / read 週期期間拋出錯誤時呼叫。

預設情況下,初始化時不會向串流發出請求。你可以使用 initialInput 選項將初始負載傳遞給串流:

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

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

  return <div>{"{data}"}</div>;
}

<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 方法:

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

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

  return (
    <div>
      <div>{"{data}"}</div>
      <button onClick={"{cancel}"}>Cancel</button>
    </div>
  );
}

<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 來讀取和寫入串流:

// 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>
  );
}

<!-- 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 Response (Streamed Json Responses)

如果你需要逐步串流 JSON 資料,你可以使用 streamJson 方法。此方法對於需要逐步發送到瀏覽器的大型資料集特別有用,其格式可以由 JavaScript 輕鬆解析:

use App\Models\User;

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

useJsonStream hook 與 useStream hook 相同,只是它會在串流完成後嘗試將資料解析為 JSON:

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>
  );
}

<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) 串流 Response。eventStream 方法接受一個閉包,該閉包應在回應可用時產生 Response 到串流:

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

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

如果你想自訂事件的名稱,你可以產生 StreamedEvent 類別的實例:

use Illuminate\Http\StreamedEvent;

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

使用事件串流 (Consuming Event Streams)

事件串流可以使用 Laravel 的 stream npm 套件使用,它提供了一個方便的 API 來與 Laravel 事件串流互動。要開始使用,請安裝 @laravel/stream-react 或 @laravel/stream-vue 套件:

npm install @laravel/stream-react

npm install @laravel/stream-vue

然後,useEventStream 可用於使用事件串流。提供你的串流 URL 後,hook 會在從你的 Laravel 應用程式回傳訊息時自動使用串聯的 Response 更新 message:

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

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

  return <div>{"{message}"}</div>;
}

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

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

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

給予 useEventStream 的第二個參數是一個選項物件,你可以使用它來自訂串流使用行為。此物件的預設值如下所示:

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>;
}

<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> 更新:

const source = new EventSource("/chat");

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

    return;
  }

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

要自訂發送到事件串流的最終事件,你可以將 StreamedEvent 實例提供給 eventStream 方法的 endStreamWith 參數:

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

串流下載 (Streamed Downloads)

有時你可能希望將給定操作的字串 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 Macros)

如果你想定義可以在各種路由和 Controller 中重複使用的自訂 Response,你可以使用 Response Facade 上的 macro 方法。通常,你應該從應用程式的Service Provider 之一的 boot 方法呼叫此方法,例如 App\Providers\AppServiceProvider Service Provider:

<?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');