這是如何使用 Laravel Data:

1. 安裝Laravel封包

首先，使用 Composer 安裝 spatie/laravel-data 套件。該軟體包有助於創建 DTO 並有效管理資料。

composer require spatie/laravel-data

2. 建立資料傳輸物件（DTO）

安裝套件後，我們可以建立一個DTO類別來處理資料傳輸。假設我們有一個 User 實體，我們想要建立一個 DTO 來傳輸使用者資料。

執行以下 Artisan 指令來產生新的 DTO 類別：

php artisan make:data UserData

這將在 App/Data 目錄中建立一個 UserData 類別。

3. 定義DTO中的屬性與型別

現在，讓我們編輯 UserData 類別來定義您期望的 DTO 屬性和資料類型。

namespace App\Data;

use Spatie\LaravelData\Data;

class UserData extends Data
{
    public function __construct(
        public string $name,
        public string $email,
        public string $address,
        public ?string $phone = null  // Optional phone field
    ) {}
}

解釋：

• __construct 方法會自動將傳入值指派給 DTO 屬性。
• ?string $phone = null 表示phone 屬性是可選的。

4. 在控制器中使用DTO

現在 UserData DTO 已創建，我們可以在控制器內使用它來處理傳入資料、轉換資料並在應用程式的各層之間傳遞資料。

namespace App\Http\Controllers;

use App\Data\UserData;
use App\Models\User;
use Illuminate\Http\Request;

class UserController extends Controller
{
    public function store(Request $request)
    {
        // Validate the incoming request data
        $validatedData = $request->validate([
            'name' => 'required|string',
            'email' => 'required|email',
            'address' => 'required|string',
            'phone' => 'nullable|string',
        ]);

        // Create a UserData DTO
        $userData = UserData::from($validatedData);

        // You can now access $userData->name, $userData->email, etc.
        User::create([
            'name' => $userData->name,
            'email' => $userData->email,
            'address' => $userData->address,
            'phone' => $userData->phone,
        ]);

        return response()->json(['message' => 'User created successfully']);
    }
}

解釋：

• UserData::from() 方法會自動將經過驗證的請求資料對應到 DTO 物件中。
• DTO 物件現在可用於在控制器和模型（或應用程式的其他層）之間傳輸資料。

5. 使用DTO轉換資料

您也可以在回傳回應時使用 DTO 來轉換資料。我們來修改UserController中的show方法，透過DTO傳回用戶資料。

public function show(User $user)
{
    // Convert the User model to UserData DTO
    $userData = new UserData(
        name: $user->name,
        email: $user->email,
        address: $user->address,
        phone: $user->phone
    );

    return response()->json($userData);
}

解釋：

• 在這裡，我們透過將 User 模型的屬性傳遞到 DTO 建構函數來手動建立 UserData DTO。
• 此DTO可直接作為JSON回應返回，確保結構化資料格式。

6. DTO 與集合

如果您正在處理資料集合，例如獲取使用者列表，DTO 套件也提供了一種簡單的方法來處理集合。

public function index()
{
    $users = User::all();

    // Convert the collection of User models to a collection of UserData DTOs
    $userCollection = UserData::collection($users);

    return response()->json($userCollection);
}

解釋：

• UserData::collection($users) 方法將每個 User 模型對應到 UserData DTO，將整個集合轉換為 DTO 清單。

7. 自訂資料轉換

spatie/laravel-data 套件允許自訂轉換，例如重新命名屬性或新增計算欄位。

class UserData extends Data
{
    public function __construct(
        public string $name,
        public string $email,
        public string $address,
        public ?string $phone = null
    ) {}

    // Add a custom method to compute a full contact string
    public function fullContact(): string
    {
        return "{$this->name} ({$this->email})";
    }
}

現在，您可以在使用此 DTO 時使用 fullContact() 來取得自訂格式的字串。

8. 資料驗證和 DTO

您可以使用 Laravel Data 的規則功能直接在 DTO 中新增驗證規則。

namespace App\Data;

use Spatie\LaravelData\Attributes\Validation\Email;
use Spatie\LaravelData\Attributes\Validation\Required;
use Spatie\LaravelData\Data;

class UserData extends Data
{
    public function __construct(
        #[Required] public string $name,
        #[Email] public string $email,
        public string $address,
        public ?string $phone = null
    ) {}
}

解釋：

• 借助 #[Required] 和 #[Email] 等驗證屬性，您可以直接在 DTO 層級強制執行驗證，從而進一步簡化流程。

結論

在本實作教學中，我們探討如何使用 Laravel Data 建立和使用資料傳輸物件 (DTO)。使用 DTO 模式，您可以乾淨地管理和轉換數據，確保應用程式各層之間的關注點分離，同時使程式碼更易於維護。 spatie/laravel-data 套件簡化了 DTO 管理，為開發人員和大型應用程式提供易於使用的功能。