> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Dumpable trait

> 解說如何以 Illuminate\Support\Traits\Dumpable 為任意類別新增 dump() / dd()，在不中斷鏈的情況下進行除錯。

## 什麼是 Dumpable trait

`Illuminate\Support\Traits\Dumpable` 是一個為任意類別加入 `dump()` 與 `dd()` 的小巧 trait。於 Laravel 10 引入，Collection、Eloquent Builder、Request 等 Laravel Core 中都廣泛使用它，用於統一除錯體驗。

目的很簡單。以類似 `var_dump` 的方式檢查物件，並在必要時當場中止處理。

```mermaid theme={null}
flowchart TD
    A["於物件呼叫 dump()/dd()"] --> B{"呼叫的是哪一個?"}
    B -- "dump()" --> C["輸出 $this 與額外引數"]
    C --> D["繼續處理"]
    B -- "dd()" --> E["輸出 $this 與額外引數"]
    E --> F["中止處理"]
```

## 確認實作

實作非常簡單，只是呼叫 `dump($this, ...$args)` 與 `dd($this, ...$args)`。

```php theme={null}
trait Dumpable
{
    public function dump(...$args): static
    {
        dump($this, ...$args);
        return $this;
    }

    public function dd(...$args): never
    {
        dd($this, ...$args);
    }
}
```

<Info>
  Laravel 13 的實作位於 `src/Illuminate/Support/Traits/Dumpable.php`。實際的簽章以 PHPDoc `@return $this` 與 `@return never` 表達。
</Info>

## 於自訂類別使用

只要加上 `use Dumpable;`，便可作為實例方法使用 `dump()` / `dd()`。

```php theme={null}
use Illuminate\Support\Traits\Dumpable;

class UserData
{
    use Dumpable;
    
    public function __construct(
        public readonly string $name,
        public readonly string $email,
    ) {}
}

$user = new UserData('Taro', 'taro@example.com');

$user->dump(); // dump 後繼續
$user->dd();   // dump 後結束
```

## 於鏈中間插入除錯

`dump()` 會回傳 `static`（實作上為 `$this`），因此可安全地插入方法鏈之中。

```php theme={null}
$result = collect([1, 2, 3])
    ->map(fn ($n) => $n * 2)
    ->dump()  // 於此確認內容
    ->filter(fn ($n) => $n > 2)
    ->values();
```

若替換為 `dd()`，處理會在該處停止，適合在沉重的後續處理前確認狀態。

## 套件開發的活用

若在自訂的 Value Object、DTO、Builder 中加入 `Dumpable`，使用者無需額外工具便可確認狀態。

<Steps>
  <Step title="加入 Value Object / DTO">
    ```php theme={null}
    use Illuminate\Support\Traits\Dumpable;

    final class InvoiceData
    {
        use Dumpable;

        public function __construct(
            public readonly string $number,
            public readonly int $total,
        ) {}
    }
    ```
  </Step>

  <Step title="於 Fluent Builder 中間進行確認">
    ```php theme={null}
    $payload = (new PackageRequestBuilder)
        ->forUser($userId)
        ->withLocale('zh-TW')
        ->dump('before send')
        ->toArray();
    ```
  </Step>
</Steps>

## 傳入額外引數

`Dumpable` 內部會呼叫 `dump($this, ...$args)` / `dd($this, ...$args)`，因此可將情境資訊一併輸出。

```php theme={null}
$user->dump('除錯點 A');
// $this 與 '除錯點 A' 會一起輸出
```

於多處使用 `dump()` 時特別有用，可立刻辨別是在哪個地點輸出的。

## 相關 trait

<Columns cols={3}>
  <Card title="tap() helper / Tappable" icon="hand-point-up" href="/zh-TW/advanced/tap">
    學習在插入副作用同時回傳值的模式。
  </Card>

  <Card title="Conditionable trait" icon="git-branch" href="/zh-TW/advanced/conditionable">
    學習有條件地分支鏈式處理的設計。
  </Card>

  <Card title="Macroable trait" icon="puzzle-piece" href="/zh-TW/advanced/macroable">
    學習擴充既有類別以加入自訂方法的方法。
  </Card>
</Columns>


## Related topics

- [Support Contracts（Arrayable / Jsonable / Htmlable / Responsable）](/zh-TW/advanced/support-contracts.md)
- [SessionEvent](/zh-TW/packages/laravel-copilot-sdk/session-event.md)
- [Conditionable trait](/zh-TW/advanced/conditionable.md)
- [Macroable trait](/zh-TW/advanced/macroable.md)
- [Eloquent Bootable Traits](/zh-TW/advanced/eloquent-bootable-traits.md)