HTTP Request

什麼是 Request 物件

Illuminate\Http\Request 是以物件導向處理應用程式所收到的 HTTP 請求的類別。可存取請求中所有資訊，如表單資料、query string、檔案、header 等。

於控制器注入 Request

在控制器方法上以 Illuminate\Http\Request type-hint，Laravel 的 service container 會自動注入 request 實例。

<?php

namespace App\Http\Controllers;

use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;

class UserController extends Controller
{
    public function store(Request $request): RedirectResponse
    {
        $name = $request->input('name');

        // 儲存使用者的處理...

        return redirect('/users');
    }
}

在路由 closure 中也可以同樣 type-hint。

use Illuminate\Http\Request;

Route::get('/', function (Request $request) {
    // ...
});

與路由參數同時使用

當控制器方法也接受路由參數時，將路由參數寫在 Request 之後：

use App\Http\Controllers\UserController;

Route::put('/user/{id}', [UserController::class, 'update']);

public function update(Request $request, string $id): RedirectResponse
{
    // 用 $request 存取請求資料，用 $id 存取路由參數

    return redirect('/users');
}

取得請求資料

取得所有輸入資料

all 方法將所有輸入資料以陣列形式取得。無論來自 HTML 表單或 XHR 請求都可使用。

$input = $request->all();

取得特定欄位

input 方法不論 HTTP 方法為何，都會從整個請求 payload（含 query string）取得值。

$name = $request->input('name');

第 2 個引數可指定值不存在時的預設值：

$name = $request->input('name', 'Sally');

陣列輸入以 dot notation 存取。

$name = $request->input('products.0.name');

$names = $request->input('products.*.name');

取得 query string

query 方法只會從 query string（URL 中 ? 之後的部分）取得值。

$name = $request->query('name');

$name = $request->query('name', 'Helen');

// 以陣列取得所有 query string
$query = $request->query();

input 對象是請求 body 與 query string 兩者，query 只針對 query string。若要區分表單 POST 資料與 URL 參數，請使用 query。

型別化取得

除 input 外，也提供指定型別取得輸入值的方法。

// 以字串取得（Stringable 實例）
$name = $request->string('name')->trim();

// 以整數取得
$perPage = $request->integer('per_page');

// 以布林值取得（"1"、"true"、"on"、"yes" → true）
$archived = $request->boolean('archived');

// 以陣列取得
$versions = $request->array('versions');

// 以 Carbon 實例取得日期
$birthday = $request->date('birthday');

動態屬性

也可以將欄位名稱作為屬性直接存取。

$name = $request->name;

動態屬性會先從請求 payload 找值，若找不到再搜尋路由參數。

取得輸入資料的一部分

only 與 except 可取得輸入資料的子集。

$input = $request->only(['username', 'password']);

$input = $request->except(['credit_card']);

輸入的存在確認

以 has 方法確認值是否包含在請求中。

if ($request->has('name')) {
    // ...
}

// 確認是否全部包含多個 key
if ($request->has(['name', 'email'])) {
    // ...
}

要排除空字串以確認值是否存在，使用 filled。

if ($request->filled('name')) {
    // ...
}

當值不存在或為空字串時，使用 isNotFilled。

if ($request->isNotFilled('name')) {
    // ...
}

請求路徑與方法確認

取得與確認路徑

// 取得路徑（例如："foo/bar"）
$uri = $request->path();

// 確認是否符合樣式（可用萬用字元 *）
if ($request->is('admin/*')) {
    // ...
}

// 確認是否符合具名路由
if ($request->routeIs('admin.*')) {
    // ...
}

取得 URL

// 不含 query string 的 URL
$url = $request->url();

// 含 query string 的 URL
$urlWithQueryString = $request->fullUrl();

確認 HTTP 方法

以 isMethod 確認 HTTP 方法。

$method = $request->method();

if ($request->isMethod('post')) {
    // 只處理 POST 請求
}

檔案上傳

取得已上傳的檔案

以 file 方法取得上傳的檔案。回傳 Illuminate\Http\UploadedFile 實例。

$file = $request->file('photo');

// 也可用動態屬性取得
$file = $request->photo;

要確認檔案是否存在，使用 hasFile。

if ($request->hasFile('photo')) {
    // ...
}

儲存檔案

以 store 方法將檔案儲存到 storage。檔名會自動產生。

// 儲存到預設 disk 的 "images" 目錄
$path = $request->photo->store('images');

// 儲存到 S3
$path = $request->photo->store('images', 's3');

要指定檔名時使用 storeAs。

$path = $request->photo->storeAs('images', 'filename.jpg');

接受檔案上傳時，務必驗證檔案類型與大小。建議透過驗證安全地處理。

範例：接收表單資料

以下是在控制器接收使用者註冊表單資料的範例。

<?php

namespace App\Http\Controllers;

use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;

class RegisterController extends Controller
{
    public function store(Request $request): RedirectResponse
    {
        // 取得表單資料
        $name = $request->input('name');
        $email = $request->input('email');
        $password = $request->input('password');

        // 只取所需資料
        $data = $request->only(['name', 'email', 'password']);

        // 建立使用者的處理...

        return redirect('/dashboard');
    }
}

定義對應的路由：

use App\Http\Controllers\RegisterController;

Route::post('/register', [RegisterController::class, 'store']);

後續步驟

Middleware

複習用來過濾請求的 middleware 的使用方式。

開始使用

基礎

請求處理

資料庫

認證

輔助工具與外部通訊

測試與部署

AI 開發輔助

什麼是 Request 物件

於控制器注入 Request

與路由參數同時使用

取得請求資料

取得所有輸入資料

取得特定欄位

取得 query string

型別化取得

動態屬性

取得輸入資料的一部分

輸入的存在確認

請求路徑與方法確認

取得與確認路徑

取得 URL

確認 HTTP 方法

檔案上傳

取得已上傳的檔案

儲存檔案

範例：接收表單資料

後續步驟

Middleware

​什麼是 Request 物件

​於控制器注入 Request

​與路由參數同時使用

​取得請求資料

​取得所有輸入資料

​取得特定欄位

​取得 query string

​型別化取得

​動態屬性

​取得輸入資料的一部分

​輸入的存在確認

​請求路徑與方法確認

​取得與確認路徑

​取得 URL

​確認 HTTP 方法

​檔案上傳

​取得已上傳的檔案

​儲存檔案

​範例：接收表單資料

​後續步驟

Middleware

什麼是 Request 物件

於控制器注入 Request

與路由參數同時使用

取得請求資料

取得所有輸入資料

取得特定欄位

取得 query string

型別化取得

動態屬性

取得輸入資料的一部分

輸入的存在確認

請求路徑與方法確認

取得與確認路徑

取得 URL

確認 HTTP 方法

檔案上傳

取得已上傳的檔案

儲存檔案

範例：接收表單資料

後續步驟