Primordyx Framework Documentation

Static event system for handling both fire-and-forget actions and returnable filters.

Internals:

This class maintains two internal registries:

• self::$actions : for non-returning, side-effect-driven event callbacks
• self::$filters : for value-transforming filter pipelines

Structure of $actions and $filters:

[ 'event.name' => [ // Event name (string) priority (int) => [ // Priority number (e.g., 10, 50, 100) [ // One or more callbacks at this priority 'callback' => callable, // Closure, function name, or [ClassName, 'method'] 'description' => string // Optional description for debugging ], ... ], ... ], ... ]

Priority Behavior:

• Callbacks are grouped by numeric priority.
• Higher priority numbers run before lower ones. (e.g., 100 before 90 before 10)
• Callbacks at the same priority execute in the order they were added.
• Execution order is handled via krsort() — descending numeric priority.

Filter Execution (via fire()):

• Filters run first, in descending priority order.
• All filters REGISTERED TO THE EVENT BEING FIRED run — they are not subject to the floor.
• Each filter receives the current value and additional arguments, and returns a transformed result.
• The final value after all filters is passed as the first argument to actions.

Action Execution (via fire()):

• Actions run after all filters, in descending priority order.
• An internal "floor" starts at 0 and defines the lowest action priority eligible to run.
• If an action callback returns a numeric value, it can raise the floor (but never lower it).
• Any subsequent actions with lower priority are skipped.
• Callbacks returning null or non-numeric values do not affect the floor.
• Skipped actions can optionally trigger __event.action.skipped if event_fire_skipped_actions is true in config.
• Actions do not affect the return value of fire().

Return Behavior:

• If filters are registered for the event:
  • fire() returns the final transformed value from the last filter.
• If no filters are present:
  • fire() returns the first argument passed (i.e., $args[0] ?? null).

Listener Inspection:

The listeners() method returns an array of all registered callbacks, grouped by event, including type (action/filter), priority, description, and callback metadata.

Example Usage:

// Register an action to send a welcome email after registration EventManager::add_action('user.register', function($user) { Mailer::sendWelcomeEmail($user); }, 100, 'Send welcome email');

// Register another action to log the registration EventManager::add_action('user.register', function($user) { Logger::info("User registered: " . $user->email); }, 50, 'Log user registration');

// Fire the event EventManager::fire('user.register', $user);

// Register a filter to sanitize content before rendering EventManager::add_filter('content.render', function($content) { return strip_tags($content); }, 80, 'Strip HTML tags');

// Register another filter to convert Markdown EventManager::add_filter('content.render', function($content) { return Markdown::parse($content); }, 60, 'Convert Markdown to HTML');

// Apply filters and get the final rendered output $safeHtml = EventManager::fire('content.render', $rawInput);

Advanced Example: Filters + Actions with Priority + Floor Control

Suppose you're preparing outbound content for publishing, and you want to:

• Filter the content (sanitize, transform)
• Log what's happening
• Allow a high-priority action to suppress lower-priority actions

// Filter to clean HTML (runs first) EventManager::add_filter('content.prepare', function ($content, $user) { return strip_tags($content); }, 100, 'Remove unwanted HTML');

// Filter to convert markdown to HTML (runs after cleaning) EventManager::add_filter('content.prepare', function ($content, $user) { return Markdown::toHtml($content); }, 90, 'Parse Markdown');

// Filter to append a footer EventManager::add_filter('content.prepare', function ($content, $user) { return $content . "\n\n-- Powered by Primordyx --"; }, 70, 'Append platform footer');

// Action to check user role and suppress lower-priority actions EventManager::add_action('content.prepare', function ($content, $user) { if (!$user->hasPermission('publish_advanced')) { return 90; // Raise floor: skip any action with priority < 90 } }, 95, 'Enforce user permission threshold');

// Action to log that publishing was attempted EventManager::add_action('content.prepare', function ($content, $user) { Logger::info("User {$user->id} is preparing content to publish."); }, 80, 'Log publishing intent');

// Fire the event $finalContent = EventManager::fire('content.prepare', $rawContent, $user);

// The result includes all filter modifications; actions can still be suppressed. echo $finalContent;