> ## 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 核心类广泛使用，以统一调试体验。

目的很简单：像 `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-CN')
        ->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() 辅助函数 / Tappable" icon="hand-point-up" href="/zh/advanced/tap">
    了解「插入副作用同时返回值」的模式。
  </Card>

  <Card title="Conditionable trait" icon="git-branch" href="/zh/advanced/conditionable">
    了解在链式处理中按条件分支的设计方法。
  </Card>

  <Card title="Macroable trait" icon="puzzle-piece" href="/zh/advanced/macroable">
    了解如何扩展既有类，添加自定义方法。
  </Card>
</Columns>


## Related topics

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