Events and scheduled work

Aikeedo dispatches domain events whenever something meaningful happens: a user signs up, an order is fulfilled, credits are consumed. Plugins subscribe to those events, and use the cron event for scheduled work. Register listeners in boot() through the event mapper:

src/Plugin.php

<?php

declare(strict_types=1);

namespace Acme\Crm;

use Acme\Crm\Listeners\PushContact;
use Acme\Crm\Listeners\SyncContacts;
use Cron\Domain\Events\CronEvent;
use Easy\EventDispatcher\Mapper\ArrayMapper;
use Override;
use Plugin\Domain\Context;
use Plugin\Domain\PluginInterface;
use User\Domain\Events\UserCreatedEvent;
use User\Domain\Events\UserUpdatedEvent;

class Plugin implements PluginInterface
{
    public function __construct(
        private ArrayMapper $mapper,
    ) {}

    #[Override]
    public function boot(Context $context): void
    {
        $this->mapper->addEventListener(UserCreatedEvent::class, PushContact::class);
        $this->mapper->addEventListener(UserUpdatedEvent::class, PushContact::class);
        $this->mapper->addEventListener(CronEvent::class, SyncContacts::class);
    }
}

Write a listener

A listener is an invokable class. It’s resolved from the container, so it can depend on any service:

src/Listeners/PushContact.php

<?php

declare(strict_types=1);

namespace Acme\Crm\Listeners;

use Acme\Crm\Client;
use Easy\Container\Attributes\Inject;
use Psr\Log\LoggerInterface;
use Throwable;
use User\Domain\Events\AbstractUserEvent;

class PushContact
{
    public function __construct(
        private Client $client,
        private LoggerInterface $logger,

        #[Inject('option.crm.auto_sync')]
        private ?bool $autoSync = false,
    ) {}

    public function __invoke(AbstractUserEvent $event): void
    {
        if (!$this->autoSync) {
            return;
        }

        $user = $event->user;

        try {
            $this->client->upsertContact([
                'email' => (string) $user->getEmail()->value,
                'first_name' => (string) $user->getFirstName()->value,
            ]);
        } catch (Throwable $th) {
            // Never let an integration break the user's request.
            $this->logger->error('CRM sync failed', ['exception' => $th]);
        }
    }
}

Listeners run synchronously inside the request that dispatched the event. Keep them fast, and catch your own exceptions, or a failing third-party API will break signup. Log failures instead of swallowing them silently, and reconcile later from cron.

Priorities

use Easy\EventDispatcher\Priority;

$this->mapper->addEventListener(UserCreatedEvent::class, Welcome::class, Priority::HIGH);

Priority::HIGH (100) runs before Priority::NORMAL (50), which runs before Priority::LOW (0).

Inheritance matters

Listeners match with instanceof, so a listener on a parent class also receives its subclasses.

Event	Extends
`UserUpdatedEvent`	`AbstractUserEvent`
`EmailVerifiedEvent`	`UserUpdatedEvent`
`UserEmailUpdatedEvent`	`UserUpdatedEvent`

Registering the same listener on both UserUpdatedEvent and EmailVerifiedEvent makes it run twice when an email is verified. Subscribe to the most general event you care about, and branch inside the listener with instanceof if you need to tell them apart.

Module	Events	Payload
User	`UserCreatedEvent`, `UserUpdatedEvent`, `UserDeletedEvent`, `EmailVerifiedEvent`, `UserEmailUpdatedEvent`, `UserPasswordUpdatedEvent`, `PasswordRecoveryCreatedEvent`	`$event->user`
Workspace	`WorkspaceCreatedEvent`, `WorkspaceUpdatedEvent`, `WorkspaceDeletedEvent`, `InvitationCreatedEvent`	`$event->workspace`, or the invitation
Billing	`OrderCreatedEvent`, `OrderFulfilledEvent`	`$event->order`
Billing	`SubscriptionCreatedEvent`, `SubscriptionActivatedEvent`, `SubscriptionUsageResetEvent`	`$event->subscription`
Billing	`PlanCreatedEvent`, `PlanUpdatedEvent`, `PlanDeletedEvent`, `CouponCreatedEvent`, `CouponUpdatedEvent`, `CouponDeletedEvent`	The plan or coupon
Billing	`CreditUsageEvent`	`$event->workspace`, `$event->count`
Option	`OptionCreatedEvent`, `OptionUpdatedEvent`, `OptionDeletedEvent`	The option
Preset	`PresetCreatedEvent`, `PresetUpdatedEvent`, `PresetDeletedEvent`	The preset
Category	`CategoryCreatedEvent`, `CategoryUpdatedEvent`, `CategoryDeletedEvent`	The category
Cron	`CronEvent`	none

Class names are under <Module>\Domain\Events\. See the event catalog for the full list, including who listens in core.

Dispatch your own events

use Psr\EventDispatcher\EventDispatcherInterface;

public function __construct(
    private EventDispatcherInterface $dispatcher,
) {}

$this->dispatcher->dispatch(new NoteCreatedEvent($note));

Other plugins can then subscribe to your event, which is how you make your plugin extensible.

Scheduled work

There’s no queue. Recurring work runs when cron.php executes, which dispatches Cron\Domain\Events\CronEvent. Subscribe to it like any other event.

$this->mapper->addEventListener(CronEvent::class, SyncContacts::class);

A cron listener should process a bounded batch and remember where it stopped, because the next tick may be a minute away:

src/Listeners/SyncContacts.php

<?php

declare(strict_types=1);

namespace Acme\Crm\Listeners;

use Acme\Crm\Client;
use Cron\Domain\Events\CronEvent;
use Easy\Container\Attributes\Inject;
use Option\Application\Commands\SaveOptionCommand;
use Shared\Infrastructure\CommandBus\Dispatcher;
use Throwable;
use User\Application\Commands\ListUsersCommand;

class SyncContacts
{
    private const BATCH_SIZE = 50;

    public function __construct(
        private Client $client,
        private Dispatcher $dispatcher,

        #[Inject('option.crm.sync')]
        private ?array $sync = null,
    ) {}

    public function __invoke(CronEvent $event): void
    {
        $state = $this->sync ?? [];

        // Only run while an administrator has started a sync.
        if (($state['status'] ?? null) !== 'processing') {
            return;
        }

        $cmd = new ListUsersCommand();
        $cmd->setLimit(self::BATCH_SIZE);

        if (!empty($state['cursor_id'])) {
            $cmd->setCursor($state['cursor_id'], 'starting_after');
        }

        $synced = (int) ($state['synced'] ?? 0);
        $failed = (int) ($state['failed'] ?? 0);
        $cursor = $state['cursor_id'] ?? null;
        $processed = 0;

        foreach ($this->dispatcher->dispatch($cmd) as $user) {
            $processed++;
            $cursor = (string) $user->getId()->getValue();

            try {
                $this->client->upsertContact([
                    'email' => (string) $user->getEmail()->value,
                ]);

                $synced++;
            } catch (Throwable) {
                $failed++;
            }
        }

        $this->dispatcher->dispatch(new SaveOptionCommand('crm', json_encode([
            'sync' => [
                'status' => $processed === 0 ? 'completed' : 'processing',
                'cursor_id' => $cursor,
                'synced' => $synced,
                'failed' => $failed,
            ],
        ])));
    }
}

Points to copy from this pattern:

Opt in. Do nothing unless an administrator started the job, so an idle installation pays nothing for your plugin.
Batch. Process a fixed number of records per tick.
Persist a cursor. Store the last processed ID in an option, so the next tick continues instead of restarting.
Track counters and a status. processing, paused and completed give the admin page something to show, and stopping is just a status change.
Rate-limit yourself. For a daily job, store a timestamp and return early until it’s due.

Entity changes made in cron listeners are flushed after the event finishes, the same as in a web request.

Testing

Run the cron tick by hand with php cron.php.
Trigger domain events by doing the thing in the UI, such as creating a user.
Watch var/log/app-*.log, and log at the start and end of your listener while developing.

Get Started

Plugins

Extension Guides

Themes

Core Architecture

REST API

Events and scheduled work

Write a listener

Priorities

Inheritance matters

Dispatch your own events

Scheduled work

Testing

​Subscribe to an event

​Write a listener

​Priorities

​Inheritance matters

​Events you can subscribe to

​Dispatch your own events

​Scheduled work

​Testing

​Related

Subscribe to an event

Write a listener

Priorities

Inheritance matters

Events you can subscribe to

Dispatch your own events

Scheduled work

Testing

Related