# Workflow annuleren

Workflows kunnen programmatisch of via CLI worden geannuleerd. Wanneer een workflow wordt geannuleerd, stelt Queuety de status in op `cancelled`, begraaft alle wachtende of verwerkende taken en voert een optionele opruimhandler uit.

## Een opruimhandler registreren

Gebruik `on_cancel()` in de workflowbuilder om een klasse te registreren die wordt uitgevoerd wanneer de workflow wordt geannuleerd. De handlerklasse moet een methode `handle( array $state ): void` implementeren.

```php
use Queuety\Queuety;

Queuety::workflow( 'import_data' )
    ->then( FetchDataHandler::class )
    ->then( TransformDataHandler::class )
    ->then( LoadDataHandler::class )
    ->on_cancel( ImportCleanupHandler::class )
    ->dispatch( [ 'source_url' => $url ] );
```

De opruimhandler ontvangt de openbare workflowstatus (alle sleutels die niet beginnen met `_`):

```php
class ImportCleanupHandler {

    public function handle( array $state ): void {
        // Clean up any partial imports.
        if ( isset( $state['temp_table'] ) ) {
            global $wpdb;
            $wpdb->query( "DROP TABLE IF EXISTS {$state['temp_table']}" );
        }

        // Notify the user.
        wp_mail(
            $state['notify_email'] ?? '',
            'Import cancelled',
            'Your data import was cancelled.'
        );
    }
}
```

## Annuleren via PHP

Roep `Queuety::cancel_workflow()` aan met de workflow-ID:

```php
Queuety::cancel_workflow( $workflow_id );
```

Deze methode:

1. Vergrendelt de workflowrij
2. Stelt de workflowstatus in op `cancelled`
3. Begraaft alle wachtende en verwerkende taken voor de workflow met het bericht "Workflow cancelled"
4. Registreert een gebeurtenis `workflow_cancelled` en voert een commit uit
5. Voert compensaties voor voltooide stappen in omgekeerde volgorde uit (als die zijn geregistreerd via `compensate_with()`)
6. Voert de `on_cancel`-opruimhandler uit (als die is geregistreerd)

Er wordt een `RuntimeException` gegooid als de workflow al `completed` of `cancelled` is.

## Annuleren via CLI

```bash
wp queuety workflow cancel <id>
```

| Optie | Beschrijving |
|---|---|
| `<id>` | Workflow-ID om te annuleren (vereist) |

```bash
wp queuety workflow cancel 42
```

## Wat gebeurt er bij annulering

Wanneer een workflow wordt geannuleerd:

- **Status** verandert in `cancelled`
- **Stapcompensaties** worden in omgekeerde volgorde van voltooiing uitgevoerd als je ze hebt toegevoegd met `compensate_with()`
- **Opruimhandler** wordt uitgevoerd nadat de workflowrij is gemarkeerd als `cancelled`
- **Wachtende taken** voor de workflow worden onmiddellijk begraven
- **Verwerkende taken** voor de workflow worden begraven; wanneer de actieve handler klaar is, wordt de uitvoer ervan verworpen en gaat de workflow niet verder
- **Voltooide taken** van eerdere stappen blijven ongewijzigd
- **Een logboekvermelding** met gebeurtenis `workflow_cancelled` wordt vastgelegd

## Geannuleerd versus mislukt

| Aspect | Mislukt | Geannuleerd |
|---|---|---|
| Aanleiding | Een stap verbruikt alle pogingen | Expliciete aanroep van `cancel_workflow()` |
| Status | `failed` | `cancelled` |
| Opnieuw proberen | Ja, via `retry_workflow()`, tenzij de workflow al is gecompenseerd | Nee |
| Opruimhandler | Wordt niet aangeroepen | Wordt aangeroepen als deze is geregistreerd via `on_cancel()` |
| Logboekgebeurtenis | `workflow_failed` | `workflow_cancelled` |

## Voorbeeld: annuleren met bevestiging

Een veelgebruikt patroon is de workflowstatus controleren voordat je annuleert:

```php
$status = Queuety::workflow_status( $workflow_id );

if ( null === $status ) {
    throw new \RuntimeException( 'Workflow not found.' );
}

if ( 'running' === $status->status->value || 'paused' === $status->status->value ) {
    Queuety::cancel_workflow( $workflow_id );
}
```