Event Reference

Complete reference of events available in PteroCA for plugin development.

Overview

PteroCA uses an event-driven architecture based on Symfony's EventDispatcher component. The system contains 277+ events covering all major operations, allowing plugins to react to system changes, extend functionality, and integrate deeply with core features.

Event-Driven Architecture

Benefits:

• Loose coupling - Plugins don't depend on core code directly

• Extensibility - Multiple plugins can respond to same event

• Maintainability - Clean separation of concerns

• Flexibility - Add functionality without modifying core

How it works:

1. Core system dispatches events when significant actions occur

2. Event subscribers (listeners) registered by plugins receive events

3. Subscribers can read event data and take actions

4. Multiple subscribers can respond to the same event

Event Categories

PteroCA events are organized into logical categories:

Category	Events	Purpose
User Events	~20	User registration, login, profile changes
Server Events	~45	Server lifecycle, configuration, management
Payment Events	~12	Payment processing, transactions, refunds
Product Events	~10	Product management, pricing changes
Order Events	~8	Order placement, processing, completion
Plugin Events	~15	Plugin lifecycle, activation, configuration
Theme Events	~15	Theme management, activation, settings
Admin Events	~12	Administrative actions, settings changes
CRUD Events	~140	Entity create, update, delete operations

Using Events in Plugins

Event Subscriber

Create an event subscriber class:

<?php
namespace Plugins\MyPlugin\EventSubscriber;

use App\Core\Event\User\UserRegisteredEvent;
use App\Core\Event\Server\ServerCreatedEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

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

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

        // Your plugin logic here
        $this->logger->info('New user registered', [
            'user_id' => $user->getId(),
            'email' => $user->getEmail(),
        ]);
    }

    public function onServerCreated(ServerCreatedEvent $event): void
    {
        $server = $event->getServer();

        // Your plugin logic here
        $this->notificationService->send(
            $server->getUser(),
            'Your server is ready!'
        );
    }
}

Registering Subscriber

In services.yaml:

services:
    Plugins\MyPlugin\EventSubscriber\MyEventSubscriber:
        tags: ['kernel.event_subscriber']

Event Priority

Control execution order with priority (higher = earlier):

public static function getSubscribedEvents(): array
{
    return [
        UserRegisteredEvent::class => ['onUserRegistered', 10],
        ServerCreatedEvent::class => ['onServerCreated', -10],
    ];
}

Priority guidelines:

• 10 to 100 - High priority (run early)

• 0 - Normal priority (default)

• -10 to -100 - Low priority (run late)

Core Event Categories

User Events

Events related to user accounts and authentication.

Event	When Fired	Properties
UserRegisteredEvent	New user registration	$user
UserUpdatedEvent	User profile updated	$user, $previousData
UserDeletedEvent	User account deleted	$userId, $user
UserEmailVerifiedEvent	Email address verified	$user
UserPasswordChangedEvent	Password changed	$user
UserBalanceChangedEvent	Wallet balance changed	$user, $oldBalance, $newBalance, $transaction
UserLoginEvent	User logged in	$user, $request
UserLogoutEvent	User logged out	$user
User2FAEnabledEvent	Two-factor auth enabled	$user
User2FADisabledEvent	Two-factor auth disabled	$user

Example: Welcome email on registration

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

    $this->emailService->send(
        to: $user->getEmail(),
        template: 'welcome',
        data: ['username' => $user->getUsername()]
    );
}

Server Events

Events for server lifecycle and management.

Event	When Fired	Properties
ServerCreatedEvent	New server created	$server, $user
ServerUpdatedEvent	Server configuration changed	$server, $previousData
ServerDeletedEvent	Server deleted	$serverId, $server
ServerSuspendedEvent	Server suspended	$server, $reason
ServerUnsuspendedEvent	Server unsuspended	$server
ServerRenewedEvent	Server renewed	$server, $period, $payment
ServerExpiredEvent	Server expired	$server
ServerInstallingEvent	Server installation started	$server
ServerInstalledEvent	Server installation completed	$server
ServerInstallFailedEvent	Server installation failed	$server, $error
ServerTransferredEvent	Server ownership transferred	$server, $fromUser, $toUser
ServerEggChangedEvent	Server egg changed	$server, $oldEgg, $newEgg

Example: Notify user when server expires

public function onServerExpired(ServerExpiredEvent $event): void
{
    $server = $event->getServer();

    $this->notificationService->send(
        user: $server->getUser(),
        title: 'Server Expired',
        message: "Your server '{$server->getName()}' has expired."
    );
}

Payment Events

Events for payment processing and transactions.

Event	When Fired	Properties
PaymentCreatedEvent	Payment session created	$payment
PaymentCompletedEvent	Payment successfully processed	$payment, $user
PaymentFailedEvent	Payment failed	$payment, $reason
PaymentCancelledEvent	Payment cancelled by user	$payment
PaymentRefundedEvent	Payment refunded	$payment, $refund
BalanceAddedEvent	Balance manually added	$user, $amount, $admin
BalanceDeductedEvent	Balance manually deducted	$user, $amount, $admin
VoucherRedeemedEvent	Voucher code used	$voucher, $user

Example: Track successful payments

public function onPaymentCompleted(PaymentCompletedEvent $event): void
{
    $payment = $event->getPayment();

    $this->analyticsService->track('payment_completed', [
        'amount' => $payment->getAmount(),
        'currency' => $payment->getCurrency(),
        'provider' => $payment->getProvider(),
    ]);
}

Product Events

Events related to product management.

Event	When Fired	Properties
ProductCreatedEvent	New product created	$product
ProductUpdatedEvent	Product modified	$product, $previousData
ProductDeletedEvent	Product deleted	$productId, $product
ProductActivatedEvent	Product made active	$product
ProductDeactivatedEvent	Product made inactive	$product
ProductPriceChangedEvent	Product pricing updated	$product, $oldPrice, $newPrice
CategoryCreatedEvent	Category created	$category
CategoryUpdatedEvent	Category modified	$category, $previousData
CategoryDeletedEvent	Category deleted	$categoryId, $category

Example: Sync products to external system

public function onProductUpdated(ProductUpdatedEvent $event): void
{
    $product = $event->getProduct();

    $this->externalApiClient->updateProduct(
        id: $product->getId(),
        data: [
            'name' => $product->getName(),
            'price' => $product->getPrice(),
            'active' => $product->isActive(),
        ]
    );
}

Order Events

Events for order processing.

Event	When Fired	Properties
OrderCreatedEvent	New order placed	$order, $user
OrderUpdatedEvent	Order modified	$order, $previousData
OrderCompletedEvent	Order fulfilled	$order
OrderCancelledEvent	Order cancelled	$order, $reason
OrderPaidEvent	Order payment received	$order, $payment

Example: Send order confirmation

public function onOrderCompleted(OrderCompletedEvent $event): void
{
    $order = $event->getOrder();

    $this->emailService->send(
        to: $order->getUser()->getEmail(),
        template: 'order_completed',
        data: [
            'order' => $order,
            'items' => $order->getItems(),
        ]
    );
}

Plugin Events

Events for plugin lifecycle management.

Event	When Fired	Properties
PluginInstalledEvent	Plugin installed	$plugin
PluginUninstalledEvent	Plugin uninstalled	$pluginIdentifier
PluginEnabledEvent	Plugin activated	$plugin
PluginDisabledEvent	Plugin deactivated	$plugin
PluginUpdatedEvent	Plugin updated to new version	$plugin, $oldVersion, $newVersion
PluginConfiguredEvent	Plugin settings changed	$plugin, $settings

Example: Initialize plugin data on enable

public function onPluginEnabled(PluginEnabledEvent $event): void
{
    $plugin = $event->getPlugin();

    if ($plugin->getIdentifier() === 'my-plugin') {
        $this->dataInitializer->createDefaultData();
    }
}

Theme Events

Events for theme management.

Event	When Fired	Properties
ThemeInstalledEvent	Theme installed	$theme
ThemeUninstalledEvent	Theme uninstalled	$themeIdentifier
ThemeActivatedEvent	Theme set as active	$theme
ThemeDeactivatedEvent	Theme deactivated	$theme
ThemeUpdatedEvent	Theme updated	$theme, $oldVersion, $newVersion
ThemeConfiguredEvent	Theme settings changed	$theme, $settings

Admin Events

Events for administrative actions.

Event	When Fired	Properties
SettingsChangedEvent	System settings updated	$key, $oldValue, $newValue, $admin
AdminActionEvent	Administrative action performed	$action, $admin, $target, $data
UserPromotedEvent	User given admin privileges	$user, $admin
UserDemotedEvent	User admin privileges revoked	$user, $admin

Example: Log admin actions

public function onAdminAction(AdminActionEvent $event): void
{
    $this->auditLogger->log([
        'admin' => $event->getAdmin()->getEmail(),
        'action' => $event->getAction(),
        'target' => $event->getTarget(),
        'timestamp' => new \DateTime(),
    ]);
}

CRUD Events

EasyAdmin generates events for all entity operations.

Event Pattern

For each entity, events follow this pattern:

App\Core\Event\Crud\{Entity}PrePersistEvent
App\Core\Event\Crud\{Entity}PostPersistEvent
App\Core\Event\Crud\{Entity}PreUpdateEvent
App\Core\Event\Crud\{Entity}PostUpdateEvent
App\Core\Event\Crud\{Entity}PreRemoveEvent
App\Core\Event\Crud\{Entity}PostRemoveEvent

Common CRUD Entities

Entity	Create	Update	Delete
User	UserPrePersistEvent	UserPreUpdateEvent	UserPreRemoveEvent
Server	ServerPrePersistEvent	ServerPreUpdateEvent	ServerPreRemoveEvent
Product	ProductPrePersistEvent	ProductPreUpdateEvent	ProductPreRemoveEvent
Payment	PaymentPrePersistEvent	PaymentPreUpdateEvent	PaymentPreRemoveEvent
Order	OrderPrePersistEvent	OrderPreUpdateEvent	OrderPreRemoveEvent

Pre vs Post Events

Pre Events (before database operation):

• Validate data

• Modify entity before save

• Cancel operation (throw exception)

• Set default values

Post Events (after database operation):

• Trigger side effects

• Send notifications

• Update external systems

• Log changes

Example: Validate before server creation

public function onServerPrePersist(ServerPrePersistEvent $event): void
{
    $server = $event->getServer();

    // Validate server name
    if (strlen($server->getName()) < 3) {
        throw new \InvalidArgumentException('Server name too short');
    }

    // Set default values
    if (!$server->getDescription()) {
        $server->setDescription('No description provided');
    }
}

Example: Notify after server update

public function onServerPostUpdate(ServerPostUpdateEvent $event): void
{
    $server = $event->getServer();

    // Notify user of changes
    $this->notificationService->send(
        $server->getUser(),
        'Server Updated',
        "Your server '{$server->getName()}' has been modified."
    );
}

Advanced Event Patterns

Stopping Event Propagation

Prevent other listeners from processing an event:

public function onServerCreated(ServerCreatedEvent $event): void
{
    // Handle event
    $this->processServer($event->getServer());

    // Stop propagation
    $event->stopPropagation();
}

Conditional Event Handling

public function onPaymentCompleted(PaymentCompletedEvent $event): void
{
    $payment = $event->getPayment();

    // Only process large payments
    if ($payment->getAmount() < 100) {
        return;
    }

    $this->fraudDetectionService->reviewPayment($payment);
}

Async Event Processing

For long-running tasks, use message queue:

public function onServerCreated(ServerCreatedEvent $event): void
{
    // Queue heavy task instead of blocking
    $this->messageBus->dispatch(
        new SendWelcomeEmailMessage(
            serverId: $event->getServer()->getId()
        )
    );
}

Event Data Access

public function onUserBalanceChanged(UserBalanceChangedEvent $event): void
{
    $user = $event->getUser();
    $oldBalance = $event->getOldBalance();
    $newBalance = $event->getNewBalance();
    $transaction = $event->getTransaction();

    $change = $newBalance - $oldBalance;

    $this->logger->info('Balance changed', [
        'user_id' => $user->getId(),
        'change' => $change,
        'transaction_type' => $transaction->getType(),
    ]);
}

Creating Custom Events

Plugins can define and dispatch custom events.

Define Event Class

<?php
namespace Plugins\MyPlugin\Event;

use Symfony\Contracts\EventDispatcher\Event;

class CustomActionEvent extends Event
{
    public function __construct(
        private readonly string $actionName,
        private readonly array $data,
        private readonly \DateTime $timestamp,
    ) {}

    public function getActionName(): string
    {
        return $this->actionName;
    }

    public function getData(): array
    {
        return $this->data;
    }

    public function getTimestamp(): \DateTime
    {
        return $this->timestamp;
    }
}

Dispatch Custom Event

use Symfony\Component\EventDispatcher\EventDispatcherInterface;
use Plugins\MyPlugin\Event\CustomActionEvent;

class MyService
{
    public function __construct(
        private readonly EventDispatcherInterface $eventDispatcher,
    ) {}

    public function performAction(string $name, array $data): void
    {
        // Do action logic
        // ...

        // Dispatch event
        $this->eventDispatcher->dispatch(
            new CustomActionEvent(
                actionName: $name,
                data: $data,
                timestamp: new \DateTime()
            )
        );
    }
}

Subscribe to Custom Event

public static function getSubscribedEvents(): array
{
    return [
        CustomActionEvent::class => 'onCustomAction',
    ];
}

public function onCustomAction(CustomActionEvent $event): void
{
    $this->logger->info('Custom action triggered', [
        'action' => $event->getActionName(),
        'data' => $event->getData(),
    ]);
}

Best Practices

Error Handling

Always handle errors in event subscribers:

public function onUserRegistered(UserRegisteredEvent $event): void
{
    try {
        $this->externalService->notifyNewUser($event->getUser());
    } catch (\Exception $e) {
        // Log error but don't break registration
        $this->logger->error('Failed to notify external service', [
            'error' => $e->getMessage(),
            'user_id' => $event->getUser()->getId(),
        ]);
    }
}

Performance Considerations

Do:

• Keep event handlers fast

• Queue heavy operations

• Cache frequently accessed data

• Use lazy loading

Don't:

• Make external API calls synchronously

• Perform complex calculations

• Query large datasets

• Block for extended periods

Logging

Log important events for debugging:

public function onServerCreated(ServerCreatedEvent $event): void
{
    $this->logger->info('Plugin handling server creation', [
        'server_id' => $event->getServer()->getId(),
        'user_id' => $event->getUser()->getId(),
        'plugin' => 'my-plugin',
    ]);

    // Plugin logic
}

Testing Event Subscribers

use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;

class MyEventSubscriberTest extends KernelTestCase
{
    public function testUserRegisteredEvent(): void
    {
        $subscriber = new MyEventSubscriber();

        $user = new User();
        $user->setEmail('[email protected]');

        $event = new UserRegisteredEvent($user);

        $subscriber->onUserRegistered($event);

        // Assert expected behavior
    }
}

Documentation

Document your event subscribers:

/**
 * Event subscriber for my plugin functionality.
 *
 * Handles:
 * - User registration welcome emails
 * - Server creation notifications
 * - Payment tracking
 *
 * @package Plugins\MyPlugin
 */
class MyEventSubscriber implements EventSubscriberInterface
{
    /**
     * Send welcome email when user registers.
     *
     * @param UserRegisteredEvent $event
     */
    public function onUserRegistered(UserRegisteredEvent $event): void
    {
        // ...
    }
}

Troubleshooting

Event Not Firing

Check:

1. Subscriber registered in services.yaml

2. Event class name correct (including namespace)

3. Subscriber tagged with kernel.event_subscriber

4. Plugin enabled

Handler Not Called

Check:

1. Method name matches in getSubscribedEvents()

2. Event dispatcher injected properly

3. No exceptions thrown in previous handlers

4. Propagation not stopped by earlier handler

Multiple Handlers Conflict

Use priority:

return [
    ServerCreatedEvent::class => ['onServerCreated', 100], // Run first
];

Performance Issues

Profile event handlers:

php bin/console debug:event-dispatcher ServerCreatedEvent

Optimize:

• Move heavy work to message queue

• Cache results

• Reduce database queries

• Profile with Blackfire/Xdebug

Related Guides

• Event System - Basic event system usage

• Bootstrap & Lifecycle - Plugin initialization

• Best Practices - Plugin development guidelines

• Testing - Testing event subscribers

• Symfony Events - Symfony EventDispatcher documentation

Additional Resources

• Symfony EventDispatcher - https://symfony.com/doc/current/event_dispatcher.html

• Event Naming Conventions - Use clear, descriptive names in past tense

• Event Documentation - Document custom events in plugin README

• Performance Monitoring - Track event handler execution times