Event System

PteroCA provides a comprehensive event-driven architecture with 266 events across 26 categories, allowing plugins to hook into virtually every system operation.

Overview

Events in PteroCA follow consistent patterns:

• Pre-Events - Before an operation (can be vetoed/stopped)

• Post-Events - After an operation (for side effects)

• Mutable Events - Allow modifying data in transit

• CLI Events - Background process events

All domain events extend AbstractDomainEvent with automatic UUID generation, timestamps, and schema versioning.

Event Patterns

Pre-Event Pattern (Validation/Veto)

Pre-events allow plugins to validate or block operations:

use App\Core\Event\User\Registration\UserRegistrationRequestedEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class SecuritySubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            UserRegistrationRequestedEvent::class => 'onRegistrationRequested',
        ];
    }

    public function onRegistrationRequested(UserRegistrationRequestedEvent $event): void
    {
        // Block suspicious registrations
        if ($this->isBlacklisted($event->getEmail())) {
            $event->stopPropagation();
            $event->setRejected(true, 'Email domain is blacklisted');
        }
    }
}

Post-Event Pattern (Side Effects)

Post-events are for logging, notifications, and integrations:

use App\Core\Event\User\UserRegisteredEvent;

class WelcomeEmailSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            UserRegisteredEvent::class => 'onUserRegistered',
        ];
    }

    public function onUserRegistered(UserRegisteredEvent $event): void
    {
        $user = $event->getUser();

        // Send welcome email
        $this->mailer->sendWelcomeEmail($user);

        // Initialize plugin data
        $this->pluginDataService->initializeForUser($user);
    }
}

Mutable Events

Some events allow modifying data in transit:

use App\Core\Event\Balance\BalanceAboutToBeAddedEvent;

class BonusSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            BalanceAboutToBeAddedEvent::class => 'onBalanceAboutToBeAdded',
        ];
    }

    public function onBalanceAboutToBeAdded(BalanceAboutToBeAddedEvent $event): void
    {
        // Add 10% bonus on first payment
        if ($this->isFirstPayment($event->getUserId())) {
            $bonus = $event->getAmount() * 0.10;
            $event->setAmount($event->getAmount() + $bonus);
        }
    }
}

---

Event Categories

1. User Events (18 events)

Events related to user lifecycle, authentication, and account management.

Registration Flow (10 events)

Event	Type	Description
UserRegistrationRequestedEvent	Pre (Stoppable)	Before registration starts
UserRegistrationValidatedEvent	Pre	After validation passes
UserAboutToBeCreatedEvent	Pre-Persist (Stoppable)	Before database insert
UserCreatedEvent	Post-Persist	After database insert (in transaction)
UserRegisteredEvent	Post-Commit	Registration completed
UserEmailVerificationRequestedEvent	Post	Verification email sent
UserEmailVerifiedEvent	Post-Commit	Email verified
UserRegistrationFailedEvent	Error	Registration failed
EmailVerificationResendRequestedEvent	Pre	Resend verification requested
EmailVerificationResentEvent	Post-Commit	Verification email resent

Example:

use App\Core\Event\User\Registration\UserRegisteredEvent;

public function onUserRegistered(UserRegisteredEvent $event): void
{
    $userId = $event->getUserId();
    $email = $event->getEmail();
    $context = $event->getContext(); // IP, user agent, locale

    // Initialize plugin-specific user data
    $this->initializeUserData($userId);
}

Authentication Flow (7 events)

Event	Type	Description
UserLoginRequestedEvent	Pre	Login page accessed
UserLoginAttemptedEvent	Pre	Login form submitted
UserLoginValidatedEvent	Pre	After credentials validated
UserAuthenticationSuccessfulEvent	Post	Authentication succeeded
UserLoggedInEvent	Post-Commit	Session created
UserAuthenticationFailedEvent	Error	Authentication failed
UserLogoutRequestedEvent	Pre	Logout requested
UserLoggedOutEvent	Post-Commit	User logged out

Example:

use App\Core\Event\User\UserLoggedInEvent;

public function onUserLogin(UserLoggedInEvent $event): void
{
    $user = $event->getUser();
    $request = $event->getRequest();

    // Log login activity
    $this->activityLogger->log($user, $request->getClientIp());
}

Account Events (3 events)

Event	Type	Description
UserAccountUpdateRequestedEvent	Pre	Account update requested
UserAccountUpdatedEvent	Post	Account updated
PterodactylAccountSyncedEvent	Post	Synced with Pterodactyl

---

2. Server Events (87 events)

Comprehensive server lifecycle and management events.

Server Purchase & Renewal (19 events)

Event	Type	Description
ServerPurchaseValidatedEvent	Pre	Voucher/price validated
ServerAboutToBeCreatedEvent	Pre (Stoppable)	Before server creation
ServerCreatedOnPterodactylEvent	Post	Created on Pterodactyl
ServerEntityCreatedEvent	Post-Persist	Database record created
ServerProductCreatedEvent	Post	ServerProduct snapshot created
ServerBalanceChargedEvent	Post-Commit	Balance deducted
ServerPurchaseCompletedEvent	Post-Commit	Purchase completed
ServerRenewalValidatedEvent	Pre	Renewal validated
ServerAboutToBeRenewedEvent	Pre (Stoppable)	Before renewal
ServerExpirationExtendedEvent	Post	Expiration date changed
ServerUnsuspendedEvent	Post	Server unsuspended
ServerRenewalBalanceChargedEvent	Post-Commit	Renewal charged
ServerRenewalCompletedEvent	Post-Commit	Renewal completed

Example:

use App\Core\Event\Server\ServerPurchaseCompletedEvent;

public function onServerPurchase(ServerPurchaseCompletedEvent $event): void
{
    $serverId = $event->getServerId();
    $userId = $event->getUserId();
    $finalPrice = $event->getFinalPrice();

    // Send server setup guide
    $this->notificationService->sendServerSetupGuide($userId, $serverId);

    // Track analytics
    $this->analytics->trackPurchase($userId, $finalPrice);
}

Server Management (6 events)

Event	Type	Description
ServersListAccessedEvent	Post	Server list accessed
ServersListDataLoadedEvent	Post	Server list data loaded
ServerDetailsRequestedEvent	Pre	Server details requested
ServerDetailsLoadedEvent	Post	Server details loaded
ServerManagementPageAccessedEvent	Post	Management page accessed
ServerManagementDataLoadedEvent	Post	Management data loaded

Server Backups (10 events)

Event	Type	Description
ServerBackupCreationRequestedEvent	Pre	Backup creation requested
ServerBackupCreatedEvent	Post	Backup created
ServerBackupCreationFailedEvent	Error	Backup creation failed
ServerBackupDeletionRequestedEvent	Pre	Backup deletion requested
ServerBackupDeletedEvent	Post	Backup deleted
ServerBackupDownloadRequestedEvent	Pre	Backup download requested
ServerBackupDownloadInitiatedEvent	Post	Download started
ServerBackupRestoreRequestedEvent	Pre	Restore requested
ServerBackupRestoreInitiatedEvent	Post	Restore started
ServerBackupRestoredEvent	Post	Backup restored

Server Databases (7 events)

Event	Type	Description
ServerDatabaseCreationRequestedEvent	Pre	Database creation requested
ServerDatabaseCreatedEvent	Post	Database created
ServerDatabaseCreationFailedEvent	Error	Database creation failed
ServerDatabaseDeletionRequestedEvent	Pre	Database deletion requested
ServerDatabaseDeletedEvent	Post	Database deleted
ServerDatabasePasswordRotationRequestedEvent	Pre	Password rotation requested
ServerDatabasePasswordRotatedEvent	Post	Password rotated

Server Network/Allocations (12 events)

Event	Type	Description
ServerAllocationCreationRequestedEvent	Pre	Allocation creation requested
ServerAllocationCreatedEvent	Post	Allocation created
ServerAllocationCreationFailedEvent	Error	Creation failed
ServerAllocationDeletionRequestedEvent	Pre	Deletion requested
ServerAllocationDeletedEvent	Post	Allocation deleted
ServerAllocationDeletionFailedEvent	Error	Deletion failed
ServerAllocationEditRequestedEvent	Pre	Edit requested
ServerAllocationEditedEvent	Post	Allocation edited
ServerAllocationEditFailedEvent	Error	Edit failed
ServerAllocationPrimaryChangeRequestedEvent	Pre	Primary change requested
ServerAllocationPrimaryChangedEvent	Post	Primary changed
ServerAllocationPrimaryChangeFailedEvent	Error	Change failed

Server Configuration (11 events)

Event	Type	Description
ServerDetailsUpdateRequestedEvent	Pre	Details update requested
ServerDetailsUpdatedEvent	Post	Details updated
ServerAutoRenewalToggleRequestedEvent	Pre	Auto-renewal toggle requested
ServerAutoRenewalToggledEvent	Post	Auto-renewal toggled
ServerReinstallRequestedEvent	Pre	Reinstall requested
ServerReinstallInitiatedEvent	Post	Reinstall started
ServerReinstalledEvent	Post	Reinstall completed
ServerStartupOptionUpdateRequestedEvent	Pre	Startup option update
ServerStartupOptionUpdatedEvent	Post	Startup option updated
ServerStartupVariableUpdateRequestedEvent	Pre	Variable update
ServerStartupVariableUpdatedEvent	Post	Variable updated

Server Schedules (15 events)

Event	Type	Description
ServerScheduleCreationRequestedEvent	Pre	Schedule creation requested
ServerScheduleCreatedEvent	Post	Schedule created
ServerScheduleCreationFailedEvent	Error	Creation failed
ServerScheduleUpdateRequestedEvent	Pre	Update requested
ServerScheduleUpdatedEvent	Post	Schedule updated
ServerScheduleUpdateFailedEvent	Error	Update failed
ServerScheduleDeletionRequestedEvent	Pre	Deletion requested
ServerScheduleDeletedEvent	Post	Schedule deleted
ServerScheduleDeletionFailedEvent	Error	Deletion failed
ServerScheduleTaskCreationRequestedEvent	Pre	Task creation requested
ServerScheduleTaskCreatedEvent	Post	Task created
ServerScheduleTaskUpdateRequestedEvent	Pre	Task update requested
ServerScheduleTaskUpdatedEvent	Post	Task updated
ServerScheduleTaskDeletionRequestedEvent	Pre	Task deletion requested
ServerScheduleTaskDeletedEvent	Post	Task deleted

Server Subusers (7 events)

Event	Type	Description
ServerSubuserCreationRequestedEvent	Pre	Subuser creation requested
ServerSubuserCreatedEvent	Post	Subuser created
ServerSubuserCreationFailedEvent	Error	Creation failed
ServerSubuserDeletionRequestedEvent	Pre	Deletion requested
ServerSubuserDeletedEvent	Post	Subuser deleted
ServerSubuserPermissionsUpdateRequestedEvent	Pre	Permissions update
ServerSubuserPermissionsUpdatedEvent	Post	Permissions updated

Server Tabs (1 event)

Event	Type	Description
ServerTabsCollectedEvent	Post (Mutable)	Collect custom server tabs

Example:

use App\Core\Event\ServerTabsCollectedEvent;
use Plugins\MyPlugin\Tab\MyCustomTab;

public function onServerTabs(ServerTabsCollectedEvent $event): void
{
    $tabs = $event->getTabs();
    $tabs[] = $this->myCustomTab;
    $event->setTabs($tabs);
}

Server Miscellaneous (7 events)

Event	Type	Description
ServerEulaAcceptanceRequestedEvent	Pre	EULA acceptance requested
ServerEulaAcceptedEvent	Post	EULA accepted
ServerEulaAcceptanceFailedEvent	Error	EULA acceptance failed
ServerWebsocketTokenRequestedEvent	Pre	WebSocket token requested
ServerWebsocketTokenGeneratedEvent	Post	WebSocket token generated

---

3. Payment & Balance Events (16 events)

Balance Recharge (7 events)

Event	Type	Description
BalanceRechargePageAccessedEvent	Post	Recharge page accessed
BalanceRechargeFormDataLoadedEvent	Post	Form data loaded
BalancePaymentValidatedEvent	Pre	Payment validated
BalanceAboutToBeAddedEvent	Pre (Stoppable, Mutable)	Before balance added
BalanceAddedEvent	Post-Commit	Balance added
BalancePaymentCallbackAccessedEvent	Post	Payment callback received
PaymentFinalizedEvent	Post-Commit	Payment finalized

Example - Add Bonus:

use App\Core\Event\Balance\BalanceAboutToBeAddedEvent;

public function onBalanceAboutToBeAdded(BalanceAboutToBeAddedEvent $event): void
{
    // Add 10% bonus for first-time recharge
    if ($this->isFirstRecharge($event->getUserId())) {
        $currentAmount = $event->getAmount();
        $bonusAmount = $currentAmount * 0.10;
        $event->setAmount($currentAmount + $bonusAmount);

        $this->logger->info('Added first-time bonus', [
            'userId' => $event->getUserId(),
            'bonus' => $bonusAmount,
        ]);
    }
}

Payment Gateways (4 events)

Event	Type	Description
PaymentGatewaysCollectedEvent	Post (Mutable)	Collect available gateways
PaymentContinueRequestedEvent	Pre	Payment continuation
PaymentContinuedEvent	Post	Payment continued
PaymentContinueFailedEvent	Error	Continue failed

Cart (9 events)

Event	Type	Description
CartTopUpPageAccessedEvent	Post	Top-up page accessed
CartTopUpDataLoadedEvent	Post	Top-up data loaded
CartPaymentRedirectEvent	Post	Redirecting to payment
CartConfigurePageAccessedEvent	Post	Configure page accessed
CartConfigureDataLoadedEvent	Post	Configure data loaded
CartBuyRequestedEvent	Post	Purchase requested
CartRenewPageAccessedEvent	Post	Renew page accessed
CartRenewDataLoadedEvent	Post	Renew data loaded
CartRenewBuyRequestedEvent	Post	Renewal requested

---

4. Store Events (6 events)

Event	Type	Description
StoreAccessedEvent	Post	Store page accessed
StoreDataLoadedEvent	Post	Store data loaded
StoreCategoryAccessedEvent	Post	Category page accessed
StoreCategoryDataLoadedEvent	Post	Category data loaded
StoreProductViewedEvent	Post	Product page viewed
StoreProductDataLoadedEvent	Post	Product data loaded

Example - Track Product Views:

use App\Core\Event\Store\StoreProductViewedEvent;

public function onProductViewed(StoreProductViewedEvent $event): void
{
    $productId = $event->getProductId();
    $userId = $event->getUserId(); // Can be null for guests

    // Track product view for analytics
    $this->analytics->trackProductView($productId, $userId);
}

---

5. Plugin Events (14 events)

Event	Type	Description
PluginDiscoveredEvent	Post	Plugin discovered during scan
PluginRegisteredEvent	Post	Plugin registered in database
PluginEnablementRequestedEvent	Pre	Plugin enable requested
PluginEnabledEvent	Post	Plugin enabled
PluginDisablementRequestedEvent	Pre	Plugin disable requested
PluginDisabledEvent	Post	Plugin disabled
PluginUpdatedEvent	Post	Plugin updated
PluginFaultedEvent	Error	Plugin faulted
PluginIndexPageAccessedEvent	Post	Plugin list accessed
PluginIndexDataLoadedEvent	Post	Plugin list loaded
PluginDetailsPageAccessedEvent	Post	Plugin details accessed
PluginDetailsDataLoadedEvent	Post	Plugin details loaded
PluginEnablementFailedEvent	Error	Enable failed
PluginDisablementFailedEvent	Error	Disable failed

---

6. Form & View Events (4 events)

Form Events (2 events)

Event	Type	Description
FormBuildEvent	Post (Mutable)	Building form, add fields
FormSubmitEvent	Pre (Stoppable, Mutable)	After submit, before processing

Example - Add Custom Field:

use App\Core\Event\Form\FormBuildEvent;
use Symfony\Component\Form\Extension\Core\Type\CheckboxType;

public function onFormBuild(FormBuildEvent $event): void
{
    if ($event->getFormType() === 'registration') {
        $event->getForm()->add('newsletter', CheckboxType::class, [
            'label' => 'Subscribe to newsletter',
            'required' => false,
            'mapped' => false,
        ]);
    }
}

Example - Validate Form Data:

use App\Core\Event\Form\FormSubmitEvent;

public function onFormSubmit(FormSubmitEvent $event): void
{
    if ($event->getFormType() === 'registration') {
        $data = $event->getFormData();

        // Custom validation
        if ($this->isDomainBlacklisted($data['email'])) {
            $event->stopPropagation();
            $event->setRejected(true, 'Email domain not allowed');
        }
    }
}

View Events (1 event)

Event	Type	Description
ViewDataEvent	Post (Mutable)	Before rendering template

Example - Add Dashboard Widget:

use App\Core\Event\ViewDataEvent;

public function onViewData(ViewDataEvent $event): void
{
    if ($event->getViewName() === 'dashboard') {
        $viewData = $event->getViewData();
        $viewData['custom_widget'] = $this->widgetService->getWidgetData();
        $event->setViewData($viewData);
    }
}

---

7. Menu & Navigation Events (2 events)

Event	Type	Description
MenuItemsCollectedEvent	Post (Mutable)	Collect menu items
SettingsMenuCollectedEvent	Post (Mutable)	Settings submenu collected

Example - Add Menu Item:

use App\Core\Event\Menu\MenuItemsCollectedEvent;
use EasyCorp\Bundle\EasyAdminBundle\Config\MenuItem;

public function onMenuItemsCollected(MenuItemsCollectedEvent $event): void
{
    $event->addMenuItem('main',
        MenuItem::linkToRoute('My Plugin', 'fa fa-puzzle-piece', 'plugin_my_plugin_index')
            ->setPermission('access_my_plugin')
    );
}

---

8. Email Events (2 events)

Event	Type	Description
EmailBeforeSendEvent	Post (Mutable)	Before sending email
EmailAfterSendEvent	Post	After email sent

Example - Modify Email:

use App\Core\Event\EmailBeforeSendEvent;

public function onEmailBeforeSend(EmailBeforeSendEvent $event): void
{
    $email = $event->getEmail();

    // Add custom footer
    $body = $email->getHtmlBody();
    $body .= '<p>Powered by MyPlugin</p>';
    $email->html($body);

    // Add BCC for archiving
    $email->bcc('[email protected]');
}

---

9. CRUD/Admin Panel Events (11 events)

Configuration Events (5 events)

Event	Type	Description
CrudConfiguredEvent	Post	CRUD configuration done
CrudActionsConfiguredEvent	Post	Actions configured
CrudFieldsConfiguredEvent	Post (Mutable)	Fields configured
CrudFiltersConfiguredEvent	Post	Filters configured
CrudIndexQueryBuiltEvent	Post (Mutable)	Query built for index

Operation Events (6 events)

Event	Type	Description
CrudEntityPersistingEvent	Pre (Stoppable)	Before CREATE
CrudEntityPersistedEvent	Post	After CREATE
CrudEntityUpdatingEvent	Pre (Stoppable)	Before UPDATE
CrudEntityUpdatedEvent	Post	After UPDATE
CrudEntityDeletingEvent	Pre (Stoppable)	Before DELETE
CrudEntityDeletedEvent	Post	After DELETE

Example - Audit CRUD Operations:

use App\Core\Event\Crud\CrudEntityPersistedEvent;
use App\Core\Event\Crud\CrudEntityUpdatedEvent;
use App\Core\Event\Crud\CrudEntityDeletedEvent;

public static function getSubscribedEvents(): array
{
    return [
        CrudEntityPersistedEvent::class => 'onEntityPersisted',
        CrudEntityUpdatedEvent::class => 'onEntityUpdated',
        CrudEntityDeletedEvent::class => 'onEntityDeleted',
    ];
}

public function onEntityPersisted(CrudEntityPersistedEvent $event): void
{
    $this->auditLogger->logCreate(
        $event->getEntityFqcn(),
        $event->getEntityInstance()->getId(),
        $event->getUser()
    );
}

---

10. Password Recovery Events (8 events)

Event	Type	Description
PasswordResetRequestedEvent	Pre	Reset requested
PasswordResetTokenGeneratedEvent	Post	Token created
PasswordResetEmailSentEvent	Post-Commit	Email sent
PasswordResetValidatedEvent	Pre	Token validated
PasswordAboutToBeChangedEvent	Pre (Stoppable)	Before change
PasswordChangedEvent	Post-Commit	Password changed
PasswordResetCompletedEvent	Post-Commit	Process completed
PasswordResetFailedEvent	Error	Process failed

---

11. SSO Events (4 events)

Event	Type	Description
SSORedirectRequestedEvent	Pre	SSO redirect requested
SSOTokenGeneratedEvent	Post	JWT token created
SSORedirectInitiatedEvent	Post-Commit	Redirect initiated
SSOFailedEvent	Error	SSO failed

---

12. Voucher Events (9 events)

Event	Type	Description
VoucherCreationRequestedEvent	Pre	Creation requested
VoucherCreatedEvent	Post	Voucher created
VoucherUpdateRequestedEvent	Pre	Update requested
VoucherUpdatedEvent	Post	Voucher updated
VoucherDeletionRequestedEvent	Pre	Deletion requested
VoucherDeletedEvent	Post	Voucher deleted
VoucherRedemptionRequestedEvent	Pre	Redemption requested
VoucherRedeemedEvent	Post	Voucher redeemed
VoucherRedemptionFailedEvent	Error	Redemption failed

---

13. Dashboard Events (2 events)

Event	Type	Description
DashboardAccessedEvent	Post	Dashboard accessed
DashboardDataLoadedEvent	Post	Dashboard data loaded

---

14. Admin Overview Events (2 events)

Event	Type	Description
AdminOverviewAccessedEvent	Post	Admin overview accessed
AdminOverviewDataLoadedEvent	Post	Admin data loaded

---

15. Product Events (2 events)

Event	Type	Description
ProductCopyRequestedEvent	Pre	Product copy requested
ProductCopiedEvent	Post	Product copied

---

16. Page Events (2 events)

Event	Type	Description
PageAccessedEvent	Post	Static page accessed
PageDataLoadedEvent	Post	Page data loaded

---

17. Security Events (1 event)

Event	Type	Description
PermissionsRegisteredEvent	Post (Mutable)	Permissions registration

Example - Register Custom Permissions:

use App\Core\Event\Security\PermissionsRegisteredEvent;

public function onPermissionsRegistered(PermissionsRegisteredEvent $event): void
{
    $registry = $event->getPermissionRegistry();

    $registry->registerPermission('my_plugin', [
        'access_my_plugin' => 'Access My Plugin',
        'manage_my_plugin' => 'Manage My Plugin',
    ]);
}

---

18. Widget Events (1 event)

Event	Type	Description
WidgetsCollectedEvent	Post (Mutable)	Dashboard widgets collected

---

19. Theme Events (20 events)

Events related to theme management, installation, and configuration.

Theme Upload (4 events)

Event	Type	Description
ThemeUploadPageAccessedEvent	Post	Theme upload page accessed
ThemeUploadRequestedEvent	Pre	Theme upload requested
ThemeUploadedEvent	Post	Theme uploaded successfully
ThemeUploadFailedEvent	Error	Theme upload failed

Theme Copy (3 events)

Event	Type	Description
ThemeCopyRequestedEvent	Pre	Theme copy requested
ThemeCopiedEvent	Post	Theme copied successfully
ThemeCopyFailedEvent	Error	Theme copy failed

Theme Export (3 events)

Event	Type	Description
ThemeExportRequestedEvent	Pre	Theme export requested
ThemeExportedEvent	Post	Theme exported successfully
ThemeExportFailedEvent	Error	Theme export failed

Theme Delete (3 events)

Event	Type	Description
ThemeDeletingEvent	Pre	Theme deletion requested (stoppable)
ThemeDeletedEvent	Post	Theme deleted successfully
ThemeDeletionFailedEvent	Error	Theme deletion failed

Theme Default Change (3 events)

Event	Type	Description
ThemeDefaultChangeRequestedEvent	Pre	Default theme change requested
ThemeDefaultChangedEvent	Post	Default theme changed
ThemeDefaultChangeFailedEvent	Error	Default theme change failed

Theme Page Access (4 events)

Event	Type	Description
ThemeIndexPageAccessedEvent	Post	Theme list page accessed
ThemeIndexDataLoadedEvent	Post	Theme list data loaded
ThemeDetailsPageAccessedEvent	Post	Theme details page accessed
ThemeDetailsDataLoadedEvent	Post	Theme details data loaded

Example - Track Theme Changes:

use App\Core\Event\Theme\ThemeDefaultChangedEvent;

public function onThemeDefaultChanged(ThemeDefaultChangedEvent $event): void
{
    $themeName = $event->getThemeName();
    $context = $event->getContext(); // panel, landing, or email
    $userId = $event->getUserId();

    // Log theme change for auditing
    $this->auditLogger->log('theme_changed', [
        'theme' => $themeName,
        'context' => $context,
        'changed_by' => $userId,
    ]);

    // Clear theme cache
    $this->cacheService->clearThemeCache();
}

---

20. Landing Page Events (4 events)

Events for the public landing page and store.

Event	Type	Description
LandingPageAccessedEvent	Post	Landing page or store page accessed
LandingPageDataLoadedEvent	Post	Featured categories/products loaded
NavigationButtonsCollectedEvent	Mutable	Navigation buttons collection (allows adding custom buttons)
WidgetsCollectedEvent	Post	Widgets collected for landing page context

Example - Add Custom Navigation Button:

use App\Core\Event\Landing\NavigationButtonsCollectedEvent;

public function onNavigationButtons(NavigationButtonsCollectedEvent $event): void
{
    $event->addButton([
        'label' => 'Documentation',
        'url' => 'https://docs.example.com',
        'icon' => 'fa-book',
    ]);
}

---

21. CLI Events (23 events)

Events dispatched during background CLI commands.

Suspend Unpaid Servers (6 events)

Event	Type	Description
SuspendUnpaidServersProcessStartedEvent	Pre	Process started
ServerSuspendedForNonPaymentEvent	Post	Server suspended
ServerSuspensionFailedEvent	Error	Suspension failed
ServerAutoRenewedEvent	Post	Server auto-renewed
SuspendUnpaidServersProcessCompletedEvent	Post	Process completed
SuspendUnpaidServersProcessFailedEvent	Error	Process failed

Delete Inactive Servers (6 events)

Event	Type	Description
DeleteInactiveServersProcessStartedEvent	Pre	Process started
InactiveServerDeletionRequestedEvent	Pre	Deletion requested
InactiveServerDeletedEvent	Post	Server deleted
InactiveServerDeletionFailedEvent	Error	Deletion failed
DeleteInactiveServersProcessCompletedEvent	Post	Process completed
DeleteInactiveServersProcessFailedEvent	Error	Process failed

Sync Servers (7 events)

Event	Type	Description
ServersSyncProcessStartedEvent	Pre	Sync started
OrphanedServerFoundEvent	Post	Orphaned server found
OrphanedServerSkippedEvent	Post	Server skipped
OrphanedServerDeletedEvent	Post	Orphaned server deleted
OrphanedServerDeletionFailedEvent	Error	Deletion failed
ServersSyncProcessCompletedEvent	Post	Sync completed
ServersSyncProcessFailedEvent	Error	Sync failed

User Management CLI (6 events)

Event	Type	Description
UserCreationProcessStartedEvent	Pre	CLI user creation started
UserCreationProcessCompletedEvent	Post	CLI user created
UserCreationProcessFailedEvent	Error	Creation failed
PasswordChangeProcessStartedEvent	Pre	Password change started
PasswordChangeProcessCompletedEvent	Post	Password changed
PasswordChangeProcessFailedEvent	Error	Change failed

---

Event Context

All events include contextual information:

$context = $event->getContext();
// [
//     'ip' => '192.168.1.100',
//     'userAgent' => 'Mozilla/5.0...',
//     'locale' => 'en_US',
//     'source' => 'web',  // or 'api', 'cli'
//     'referralCode' => null,
//     'consents' => ['marketing' => false]
// ]

Service Registration

CRITICAL: Do NOT tag event subscribers with kernel.event_subscriber!

services:
    # CORRECT - No kernel.event_subscriber tag
    Plugins\MyPlugin\EventSubscriber\MenuEventSubscriber:
        public: true

    # WRONG - Would load even when plugin disabled
    # Plugins\MyPlugin\EventSubscriber\MenuEventSubscriber:
    #     tags: ['kernel.event_subscriber']

The plugin registry discovers event subscribers automatically when the plugin is enabled.

Event Priority

Control execution order when multiple listeners exist:

public static function getSubscribedEvents(): array
{
    return [
        UserLoggedInEvent::class => ['onUserLogin', 10],  // Higher = runs first
    ];
}

Stopping Event Propagation

Prevent other listeners from executing:

public function onUserLogin(UserLoggedInEvent $event): void
{
    // Handle event
    $this->handleLogin($event->getUser());

    // Stop other listeners
    $event->stopPropagation();
}

Best Practices

1. Keep listeners fast - They block request processing

2. Handle errors gracefully - Don't let exceptions propagate

3. Use dependency injection - Inject services you need

4. Log important actions - For debugging and auditing

5. Don't abuse events - Use for cross-cutting concerns only

6. Check event data - Validate before using

7. Use Pre-events for validation - Block operations when needed

8. Use Post-events for side effects - Logging, notifications, integrations

9. Be cautious with mutable events - Document what you modify

10. Test event listeners - Ensure they don't break core functionality

Common Use Cases

1. Welcome Bonus

use App\Core\Event\Balance\BalanceAboutToBeAddedEvent;

public function onBalanceAdding(BalanceAboutToBeAddedEvent $event): void
{
    if ($this->isFirstPayment($event->getUserId())) {
        $event->setAmount($event->getAmount() * 1.10); // 10% bonus
    }
}

2. Fraud Detection

use App\Core\Event\User\Registration\UserRegistrationRequestedEvent;

public function onRegistration(UserRegistrationRequestedEvent $event): void
{
    if ($this->fraudDetector->isSuspicious($event->getEmail(), $event->getContext())) {
        $event->stopPropagation();
        $event->setRejected(true, 'Registration blocked by fraud detection');
    }
}

3. External CRM Sync

use App\Core\Event\User\UserRegisteredEvent;
use App\Core\Event\Server\ServerPurchaseCompletedEvent;

public function onUserRegistered(UserRegisteredEvent $event): void
{
    $this->crmClient->createContact($event->getUserId(), $event->getEmail());
}

public function onServerPurchase(ServerPurchaseCompletedEvent $event): void
{
    $this->crmClient->addPurchase($event->getUserId(), $event->getFinalPrice());
}

4. Custom Analytics

use App\Core\Event\Store\StoreProductViewedEvent;
use App\Core\Event\Server\ServerPurchaseCompletedEvent;

public function onProductView(StoreProductViewedEvent $event): void
{
    $this->analytics->trackEvent('product_viewed', [
        'product_id' => $event->getProductId(),
        'user_id' => $event->getUserId(),
    ]);
}

public function onPurchase(ServerPurchaseCompletedEvent $event): void
{
    $this->analytics->trackEvent('purchase_completed', [
        'server_id' => $event->getServerId(),
        'amount' => $event->getFinalPrice(),
    ]);
}

5. Notification System

use App\Core\Event\Server\ServerCreatedEvent;
use App\Core\Event\Server\ServerExpirationExtendedEvent;

public function onServerCreated(ServerCreatedEvent $event): void
{
    $this->notifier->send($event->getUserId(), 'server_created', [
        'server_id' => $event->getServerId(),
    ]);
}

public function onServerRenewal(ServerExpirationExtendedEvent $event): void
{
    $this->notifier->send($event->getUserId(), 'server_renewed', [
        'server_id' => $event->getServerId(),
        'expires_at' => $event->getNewExpiresAt(),
    ]);
}

Related Guides

• UI Components - Register widgets and tabs via events

• Controllers & Routes - Handle user actions

• Dependencies - Service registration

• Best Practices - Plugin development guidelines