# Extension and action examples

<!-- Maintained by scripts/generate-package-readmes.php -->

Use the action functions with records and Data objects supplied by your application.
They pass each argument to the package operation and return its result.

These adapters show container registration. Use the owning package registry when
a contract requires contributor discovery.

Contract adapters wrap an existing implementation. Call their registration function
from your service provider with that implementation; tagged contracts keep their declared tag.
Resolve the backend by its concrete class before registration so the replacement contract
does not resolve itself. Static contract metadata uses one backend class per adapter.

## Contract `Capell\Newsletter\Contracts\NewsletterAudienceProvider`

<!-- example: contract Capell\Newsletter\Contracts\NewsletterAudienceProvider -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

final class NewsletterAudienceProviderAdapter implements \Capell\Newsletter\Contracts\NewsletterAudienceProvider
{
    public function __construct(private readonly \Capell\Newsletter\Contracts\NewsletterAudienceProvider $backend) {}

    #[\Override]
    public function audiencesForSite(int $siteId): \Illuminate\Support\Collection
    {
        return $this->backend->audiencesForSite($siteId);
    }
}

function registerNewsletterAudienceProviderAdapter(\Capell\Newsletter\Contracts\NewsletterAudienceProvider $backend): void
{
    app()->bind(NewsletterAudienceProviderAdapter::class, static fn (): NewsletterAudienceProviderAdapter => new NewsletterAudienceProviderAdapter($backend));
    app()->bind(\Capell\Newsletter\Contracts\NewsletterAudienceProvider::class, NewsletterAudienceProviderAdapter::class);
}
```

## Contract `Capell\Newsletter\Contracts\NewsletterProviderAdapter`

<!-- example: contract Capell\Newsletter\Contracts\NewsletterProviderAdapter -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

final class NewsletterProviderAdapterAdapter implements \Capell\Newsletter\Contracts\NewsletterProviderAdapter
{
    public function __construct(private readonly \Capell\Newsletter\Contracts\NewsletterProviderAdapter $backend) {}

    #[\Override]
    public function listAudiences(\Capell\Newsletter\Models\ProviderConnection $connection): array
    {
        return $this->backend->listAudiences($connection);
    }

    #[\Override]
    public function normalizeWebhook(\Capell\Newsletter\Models\ProviderConnection $connection, \Illuminate\Http\Request $request): \Illuminate\Support\Collection
    {
        return $this->backend->normalizeWebhook($connection, $request);
    }

    #[\Override]
    public function supportsOAuth(): bool
    {
        return $this->backend->supportsOAuth();
    }

    #[\Override]
    public function supportsProviderOwnedConfirmation(): bool
    {
        return $this->backend->supportsProviderOwnedConfirmation();
    }

    #[\Override]
    public function syncSubscriber(\Capell\Newsletter\Models\ProviderConnection $connection, \Capell\Newsletter\Models\ProviderAudience $audience, \Capell\Newsletter\Data\ProviderSubscriberData $subscriber): \Capell\Newsletter\Data\ProviderSyncResultData
    {
        return $this->backend->syncSubscriber($connection, $audience, $subscriber);
    }

    #[\Override]
    public function verifyWebhook(\Capell\Newsletter\Models\ProviderConnection $connection, \Illuminate\Http\Request $request): bool
    {
        return $this->backend->verifyWebhook($connection, $request);
    }
}

function registerNewsletterProviderAdapterAdapter(\Capell\Newsletter\Contracts\NewsletterProviderAdapter $backend): void
{
    app()->bind(NewsletterProviderAdapterAdapter::class, static fn (): NewsletterProviderAdapterAdapter => new NewsletterProviderAdapterAdapter($backend));
    app()->bind(\Capell\Newsletter\Contracts\NewsletterProviderAdapter::class, NewsletterProviderAdapterAdapter::class);
}
```

## Contract `Capell\Newsletter\Contracts\NewsletterSegmentProvider`

<!-- example: contract Capell\Newsletter\Contracts\NewsletterSegmentProvider -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

final class NewsletterSegmentProviderAdapter implements \Capell\Newsletter\Contracts\NewsletterSegmentProvider
{
    public function __construct(private readonly \Capell\Newsletter\Contracts\NewsletterSegmentProvider $backend) {}

    #[\Override]
    public function querySubscribers(\Capell\Newsletter\Models\Segment $segment): \Illuminate\Database\Eloquent\Builder
    {
        return $this->backend->querySubscribers($segment);
    }
}

function registerNewsletterSegmentProviderAdapter(\Capell\Newsletter\Contracts\NewsletterSegmentProvider $backend): void
{
    app()->bind(NewsletterSegmentProviderAdapter::class, static fn (): NewsletterSegmentProviderAdapter => new NewsletterSegmentProviderAdapter($backend));
    app()->bind(\Capell\Newsletter\Contracts\NewsletterSegmentProvider::class, NewsletterSegmentProviderAdapter::class);
}
```

## Contract `Capell\Newsletter\Contracts\NewsletterSendHandoff`

<!-- example: contract Capell\Newsletter\Contracts\NewsletterSendHandoff -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

final class NewsletterSendHandoffAdapter implements \Capell\Newsletter\Contracts\NewsletterSendHandoff
{
    public function __construct(private readonly \Capell\Newsletter\Contracts\NewsletterSendHandoff $backend) {}

    #[\Override]
    public function handoff(\Capell\Newsletter\Models\NewsletterSend $send, array $payload): void
    {
        $this->backend->handoff($send, $payload);
    }
}

function registerNewsletterSendHandoffAdapter(\Capell\Newsletter\Contracts\NewsletterSendHandoff $backend): void
{
    app()->bind(NewsletterSendHandoffAdapter::class, static fn (): NewsletterSendHandoffAdapter => new NewsletterSendHandoffAdapter($backend));
    app()->bind(\Capell\Newsletter\Contracts\NewsletterSendHandoff::class, NewsletterSendHandoffAdapter::class);
}
```

## Contract `Capell\Newsletter\Contracts\ReconcilesNewsletterProviderSync`

<!-- example: contract Capell\Newsletter\Contracts\ReconcilesNewsletterProviderSync -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

final class ReconcilesNewsletterProviderSyncAdapter implements \Capell\Newsletter\Contracts\ReconcilesNewsletterProviderSync
{
    public function __construct(private readonly \Capell\Newsletter\Contracts\ReconcilesNewsletterProviderSync $backend) {}

    #[\Override]
    public function reconcileSubscriber(\Capell\Newsletter\Models\ProviderConnection $connection, \Capell\Newsletter\Models\ProviderAudience $audience, \Capell\Newsletter\Data\ProviderSubscriberData $subscriber): ?\Capell\Newsletter\Data\ProviderSyncResultData
    {
        return $this->backend->reconcileSubscriber($connection, $audience, $subscriber);
    }
}

function registerReconcilesNewsletterProviderSyncAdapter(\Capell\Newsletter\Contracts\ReconcilesNewsletterProviderSync $backend): void
{
    app()->bind(ReconcilesNewsletterProviderSyncAdapter::class, static fn (): ReconcilesNewsletterProviderSyncAdapter => new ReconcilesNewsletterProviderSyncAdapter($backend));
    app()->bind(\Capell\Newsletter\Contracts\ReconcilesNewsletterProviderSync::class, ReconcilesNewsletterProviderSyncAdapter::class);
}
```

## Action `applyNewsletterTags`

<!-- example: action applyNewsletterTags -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

function runApplyNewsletterTags(\Capell\Newsletter\Models\Subscriber $subscriber, array $tagIds, bool $replace = false): \Capell\Newsletter\Models\Subscriber
{
    return \Capell\Newsletter\Actions\ApplyNewsletterTagsAction::run($subscriber, $tagIds, $replace);
}
```

## Action `buildDueNewsletterSends`

<!-- example: action buildDueNewsletterSends -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

function runBuildDueNewsletterSends(?\Carbon\CarbonInterface $now = null, int $limit = 50): \Illuminate\Support\Collection
{
    return \Capell\Newsletter\Actions\BuildDueNewsletterSendsAction::run($now, $limit);
}
```

## Action `buildListUnsubscribeHeaders`

<!-- example: action buildListUnsubscribeHeaders -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

function runBuildListUnsubscribeHeaders(\Capell\Newsletter\Models\Subscriber $subscriber): array
{
    return \Capell\Newsletter\Actions\BuildListUnsubscribeHeadersAction::run($subscriber);
}
```

## Action `buildNewsletterSendHandoffPayload`

<!-- example: action buildNewsletterSendHandoffPayload -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

function runBuildNewsletterSendHandoffPayload(\Capell\Newsletter\Models\NewsletterSend $send): array
{
    return \Capell\Newsletter\Actions\BuildNewsletterSendHandoffPayloadAction::run($send);
}
```

## Action `confirmSubscriber`

<!-- example: action confirmSubscriber -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

function runConfirmSubscriber(string $token, ?\Capell\Newsletter\Data\ConsentEvidenceData $evidence = null): \Capell\Newsletter\Data\ConfirmSubscriberResultData
{
    return \Capell\Newsletter\Actions\ConfirmSubscriberAction::run($token, $evidence);
}
```

## Action `createPreferenceCenterToken`

<!-- example: action createPreferenceCenterToken -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

function runCreatePreferenceCenterToken(\Capell\Newsletter\Models\Subscriber $subscriber): string
{
    return \Capell\Newsletter\Actions\CreatePreferenceCenterTokenAction::run($subscriber);
}
```

## Action `createUnsubscribeToken`

<!-- example: action createUnsubscribeToken -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

function runCreateUnsubscribeToken(\Capell\Newsletter\Models\Subscriber $subscriber): string
{
    return \Capell\Newsletter\Actions\CreateUnsubscribeTokenAction::run($subscriber);
}
```

## Action `evaluateNewsletterSegment`

<!-- example: action evaluateNewsletterSegment -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

function runEvaluateNewsletterSegment(\Capell\Newsletter\Models\Segment $segment): \Illuminate\Database\Eloquent\Builder
{
    return \Capell\Newsletter\Actions\EvaluateNewsletterSegmentAction::run($segment);
}
```

## Action `exportSubscribers`

<!-- example: action exportSubscribers -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

function runExportSubscribers(int $siteId, ?\Capell\Newsletter\Models\Segment $segment = null): \Illuminate\Support\LazyCollection
{
    return \Capell\Newsletter\Actions\ExportSubscribersAction::run($siteId, $segment);
}
```

## Action `handleProviderWebhook`

<!-- example: action handleProviderWebhook -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

function runHandleProviderWebhook(\Capell\Newsletter\Models\ProviderConnection $connection, \Illuminate\Http\Request $request): \Illuminate\Support\Collection
{
    return \Capell\Newsletter\Actions\HandleProviderWebhookAction::run($connection, $request);
}
```

## Action `importSubscribers`

<!-- example: action importSubscribers -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

function runImportSubscribers(int $siteId, array $rows, string $consentBasis, bool $dryRun = true, array $tagIds = [], ?\Illuminate\Database\Eloquent\Model $actor = null, ?string $filename = null): \Capell\Newsletter\Models\ImportBatch
{
    return \Capell\Newsletter\Actions\ImportSubscribersAction::run($siteId, $rows, $consentBasis, $dryRun, $tagIds, $actor, $filename);
}
```

## Action `parseSubscriberCsvRows`

<!-- example: action parseSubscriberCsvRows -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

function runParseSubscriberCsvRows(string $contents): array
{
    return \Capell\Newsletter\Actions\ParseSubscriberCsvRowsAction::run($contents);
}
```

## Action `queueDueNewsletterSends`

<!-- example: action queueDueNewsletterSends -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

function runQueueDueNewsletterSends(?\Carbon\CarbonInterface $now = null, int $limit = 50): int
{
    return \Capell\Newsletter\Actions\QueueDueNewsletterSendsAction::run($now, $limit);
}
```

## Action `queueProviderSync`

<!-- example: action queueProviderSync -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

function runQueueProviderSync(\Capell\Newsletter\Models\Subscriber $subscriber, string $operation = 'sync_subscriber', bool $dispatchJobs = true): void
{
    \Capell\Newsletter\Actions\QueueProviderSyncAction::run($subscriber, $operation, $dispatchJobs);
}
```

## Action `recordConsentEvent`

<!-- example: action recordConsentEvent -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

function runRecordConsentEvent(\Capell\Newsletter\Models\Subscriber $subscriber, \Capell\Newsletter\Enums\ConsentEventType $eventType, ?\Capell\Newsletter\Data\ConsentEvidenceData $evidence = null, ?\Capell\Newsletter\Enums\SubscriberStatus $status = null, ?\Capell\Newsletter\Models\ProviderConnection $providerConnection = null, array $metadata = []): \Capell\Newsletter\Models\ConsentEvent
{
    return \Capell\Newsletter\Actions\RecordConsentEventAction::run($subscriber, $eventType, $evidence, $status, $providerConnection, $metadata);
}
```

## Action `recoverStalledSubscriberImports`

<!-- example: action recoverStalledSubscriberImports -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

function runRecoverStalledSubscriberImports(?\Carbon\CarbonInterface $now = null, int $limit = 100): int
{
    return \Capell\Newsletter\Actions\RecoverStalledSubscriberImportsAction::run($now, $limit);
}
```

## Action `requestDoubleOptIn`

<!-- example: action requestDoubleOptIn -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

function runRequestDoubleOptIn(\Capell\Newsletter\Models\Subscriber $subscriber, ?\Capell\Newsletter\Data\ConsentEvidenceData $evidence = null): ?\Capell\Newsletter\Models\PublicToken
{
    return \Capell\Newsletter\Actions\RequestDoubleOptInAction::run($subscriber, $evidence);
}
```

## Action `requeueDueProviderSyncAttempts`

<!-- example: action requeueDueProviderSyncAttempts -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

function runRequeueDueProviderSyncAttempts(?int $limit = null, bool $dispatchJobs = true): int
{
    return \Capell\Newsletter\Actions\RequeueDueProviderSyncAttemptsAction::run($limit, $dispatchJobs);
}
```

## Action `resolvePreferenceCenter`

<!-- example: action resolvePreferenceCenter -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

function runResolvePreferenceCenter(string $token): \Capell\Newsletter\Data\PreferenceCenterResolutionData
{
    return \Capell\Newsletter\Actions\ResolvePreferenceCenterAction::run($token);
}
```

## Action `resolveUtmAttribution`

<!-- example: action resolveUtmAttribution -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

function runResolveUtmAttribution(?\Capell\Newsletter\Data\ConsentEvidenceData $evidence = null, array $parameters = []): ?\Capell\Newsletter\Data\UtmAttributionData
{
    return \Capell\Newsletter\Actions\ResolveUtmAttributionAction::run($evidence, $parameters);
}
```

## Action `scheduleNewsletterSend`

<!-- example: action scheduleNewsletterSend -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

function runScheduleNewsletterSend(int $siteId, string $name, string $subject, \Carbon\CarbonInterface|string $scheduledAt, ?int $segmentId = null, ?int $providerAudienceId = null, ?string $preheader = null, ?string $utmSource = null, ?string $utmMedium = null, ?string $utmCampaign = null, ?string $utmTerm = null, ?string $utmContent = null, ?string $utmId = null, array $metadata = []): \Capell\Newsletter\Models\NewsletterSend
{
    return \Capell\Newsletter\Actions\ScheduleNewsletterSendAction::run($siteId, $name, $subject, $scheduledAt, $segmentId, $providerAudienceId, $preheader, $utmSource, $utmMedium, $utmCampaign, $utmTerm, $utmContent, $utmId, $metadata);
}
```

## Action `subscribeFromFormSubmission`

<!-- example: action subscribeFromFormSubmission -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

function runSubscribeFromFormSubmission(object $event): ?\Capell\Newsletter\Models\Subscriber
{
    return \Capell\Newsletter\Actions\SubscribeFromFormSubmissionAction::run($event);
}
```

## Action `subscribeFromPublicRequest`

<!-- example: action subscribeFromPublicRequest -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

function runSubscribeFromPublicRequest(\Capell\Core\Models\Site $site, array $payload, \Illuminate\Http\Request $request): \Capell\Newsletter\Models\Subscriber
{
    return \Capell\Newsletter\Actions\SubscribeFromPublicRequestAction::run($site, $payload, $request);
}
```

## Action `syncNewsletterSubscriberContact`

<!-- example: action syncNewsletterSubscriberContact -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

function runSyncNewsletterSubscriberContact(\Capell\Newsletter\Models\Subscriber $subscriber): ?\Capell\Contacts\Data\ContactSourceSyncResultData
{
    return \Capell\Newsletter\Actions\SyncNewsletterSubscriberContactAction::run($subscriber);
}
```

## Action `syncSubscriberToProvider`

<!-- example: action syncSubscriberToProvider -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

function runSyncSubscriberToProvider(\Capell\Newsletter\Models\SyncAttempt $syncAttempt): \Capell\Newsletter\Models\SyncAttempt
{
    return \Capell\Newsletter\Actions\SyncSubscriberToProviderAction::run($syncAttempt);
}
```

## Action `unsubscribeSubscriber`

<!-- example: action unsubscribeSubscriber -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

function runUnsubscribeSubscriber(string $token, ?\Capell\Newsletter\Data\ConsentEvidenceData $evidence = null): ?\Capell\Newsletter\Models\Subscriber
{
    return \Capell\Newsletter\Actions\UnsubscribeSubscriberAction::run($token, $evidence);
}
```

## Action `updateNewsletterSendStatus`

<!-- example: action updateNewsletterSendStatus -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

function runUpdateNewsletterSendStatus(\Capell\Newsletter\Models\NewsletterSend $send, \Capell\Newsletter\Enums\NewsletterSendStatus $status, ?\Carbon\CarbonInterface $occurredAt = null, array $metadata = []): \Capell\Newsletter\Models\NewsletterSend
{
    return \Capell\Newsletter\Actions\UpdateNewsletterSendStatusAction::run($send, $status, $occurredAt, $metadata);
}
```

## Action `updatePreferenceCenter`

<!-- example: action updatePreferenceCenter -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

function runUpdatePreferenceCenter(string $token, \Capell\Newsletter\Data\PreferenceCenterUpdateData $data): ?\Capell\Newsletter\Data\PreferenceCenterData
{
    return \Capell\Newsletter\Actions\UpdatePreferenceCenterAction::run($token, $data);
}
```

## Action `upsertSubscriber`

<!-- example: action upsertSubscriber -->

```php
<?php
declare(strict_types=1);

namespace App\CapellExamples\Newsletter;

function runUpsertSubscriber(\Capell\Newsletter\Data\SubscriberData $data, ?\Capell\Newsletter\Data\ConsentEvidenceData $evidence = null, \Capell\Newsletter\Enums\ConsentEventType $eventType = \Capell\Newsletter\Enums\ConsentEventType::FormCapture, bool $recordConsentEvent = true): \Capell\Newsletter\Models\Subscriber
{
    return \Capell\Newsletter\Actions\UpsertSubscriberAction::run($data, $evidence, $eventType, $recordConsentEvent);
}
```