# 永続的な遅延

`delay()`ビルダーメソッドを使うと、ワークフローのステップ間で一定時間停止できます。遅延ステップは永続化されます。遅延はデータベースに保存されるため、ワーカーの再起動、デプロイ、サーバーの再起動後も保持されます。

## `->delay()`メソッド

ワークフローのチェーン内の任意の場所に遅延ステップを追加します:

```php
use Queuety\Queuety;

Queuety::workflow( 'drip_campaign' )
    ->then( SendWelcomeEmailHandler::class )
    ->delay( days: 1 )
    ->then( SendFollowUpEmailHandler::class )
    ->delay( days: 3 )
    ->then( SendFinalEmailHandler::class )
    ->dispatch( [ 'user_id' => 42 ] );
```

ワークフローは次のように進みます:

1. `SendWelcomeEmailHandler`を実行
2. 1日待機
3. `SendFollowUpEmailHandler`を実行
4. 3日待機
5. `SendFinalEmailHandler`を実行

## 時間のパラメーター

`delay()`メソッドでは、名前付きの時間パラメーターを任意に組み合わせて指定できます:

| パラメーター | 型 | 説明 |
|---|---|---|
| `$seconds` | `int` | 待機する秒数 |
| `$minutes` | `int` | 待機する分数 |
| `$hours` | `int` | 待機する時間数 |
| `$days` | `int` | 待機する日数 |

すべての値は合算されます。次の指定は同じ意味です:

```php
->delay( seconds: 3600 )
->delay( minutes: 60 )
->delay( hours: 1 )
```

組み合わせて指定することもできます:

```php
->delay( hours: 1, minutes: 30 ) // 90 minutes total
```

## 遅延ステップの仕組み

ワークフローが遅延ステップに到達すると、Queuetyは`__queuety_delay`内部ジョブをディスパッチし、その`available_at`列には現在時刻に遅延時間を加えた時刻を設定します。遅延が経過するまで、ジョブはデータベースに置かれ、どのワーカーにも取得されません。

つまり、次のようになります：

- **ポーリング不要。** ワーカーが遅延を繰り返し確認することはありません。指定時刻になると、ジョブが利用可能になります。
- **メモリ使用なし。** 待機中に実行中の処理はありません。遅延はデータベースの行としてのみ存在します。
- **再起動後も保持。** ワーカーが再起動しても、遅延ジョブは正しい`available_at`タイムスタンプとともにキューに残ります。

遅延後に遅延ジョブが取得されると、ワークフローは自動的に次のステップへ進みます。

## 例: 通知を遅らせる

ユーザーが登録してから1時間後にリマインダーを送信します。ただし、オンボーディングが完了していない場合に限ります:

```php
Queuety::workflow( 'onboarding_reminder' )
    ->then( CreateAccountHandler::class )
    ->delay( hours: 1 )
    ->then( CheckOnboardingHandler::class )
    ->then( SendReminderHandler::class )
    ->dispatch( [ 'email' => 'user@example.com' ] );
```

`CheckOnboardingHandler`ステップで状態を確認し、[条件分岐](https://queuety.inline0.dev/ja/docs/workflows/conditional)を使ってオンボーディングがすでに完了している場合はリマインダーをスキップできます。

## 例: バックオフを伴う再試行

再試行に相当するステップの間に意図的な遅延を挿入します:

```php
Queuety::workflow( 'poll_external_api' )
    ->then( CheckStatusHandler::class, 'check' )
    ->delay( minutes: 5 )
    ->then( CheckStatusHandler::class, 'recheck' )
    ->delay( minutes: 15 )
    ->then( CheckStatusHandler::class, 'final_check' )
    ->then( ProcessResultHandler::class )
    ->dispatch( [ 'external_id' => 'abc-123' ] );
```

## 複数の遅延

ワークフローには任意の数の遅延ステップを含められます。各遅延は独立しており、ワークフローの状態では連番の名前（`delay_0`、`delay_1`など）で追跡されます。

```php
Queuety::workflow( 'multi_step_drip' )
    ->then( StepA::class )
    ->delay( hours: 2 )
    ->then( StepB::class )
    ->delay( days: 1 )
    ->then( StepC::class )
    ->delay( minutes: 30 )
    ->then( StepD::class )
    ->dispatch( $payload );
```