brunoggdev/ci4-events-extended

Lightweight and easy to use helpers and tooling to enhance CodeIgniter4 event system on user code to a more OOP approach.

v0.2.0 2026-03-28 21:51 UTC

Requires (Dev)

• codeigniter4/framework: ^4.3

MIT

• Bruno Gomes

README

Lightweight, developer-friendly helpers and tooling that enhance the way you work with the CodeIgniter 4 Events system using a more OOP approach. This package provides a cleaner, more expressive way to register and trigger events using simple event classes and invokable or handle()-based listeners.

📦 Installation

Install via Composer:

composer require brunoggdev/ci4-events-extended

The package auto-loads itself — no configuration or publishing required.

🚀 Features

• Event classes instead of string names
• Automatic listener resolution
  • Invokable listeners (__invoke)
  • Or listeners with a handle() method
• Simple listen() helper to register multiple listeners at once
• Simple event() helper to dispatch event objects
• Configurable error handling for listener failures
• Optional make commands
  • make:event
  • make:listener
• Publish command to customize default configuration
  • events:publish

🧩 Usage

1. Create an Event Class

<?php

namespace App\Events;

use App\Entities\User;

class UserUpdated
{
    public function __construct(
        public readonly User $user,
    ) {}
}

2. Create a Listener

Invokable listener:

<?php

namespace App\Listeners;

class SendWelcomeEmail
{
    public function __invoke(UserUpdated $event)
    {
        // your logic here
    }
}

Or listener with handle():

<?php

namespace App\Listeners;

class SendWelcomeEmail
{
    public function handle(UserUpdated $event)
    {
        // your logic
    }
}

3. Register Listener(s)

The best place to register your listeners is app/Config/Events.php:

listen([
    UserUpdated::class => [
        SendWelcomeEmail::class,
        // YourSecondListener::class,
        // YourThirdListener::class,
        // ...
    ],

    YourOtherEvent::class => [
        AnotherListener::class,
    ],
]);

Listeners are executed in the order they are indexed. As we use the underlying CI4 events system, returning false from a listener stops subsequent listeners from being executed.

4. Trigger the Event

event(new UserUpdated($user));

🧠 How It Works

When a listener string like \App\Listeners\SendWelcomeEmail::class is registered, the helper:

1. Creates an instance if __invoke exists
2. Registers [ClassName::class, 'handle'] if handle() exists
3. Throws otherwise

event($object) dispatches using the event object's fully qualified class name as the event identifier.

⚠️ Error Handling

By default, listener exceptions are swallowed and logged so a failing listener never interferes with your application's main workflow.

Per-call handler

You can provide a callable as a second argument to event() to handle errors on a per-call basis. When provided, it takes precedence over the default handler and the exception is always swallowed after it runs:

event(new UserUpdated($user), fn($e, $event) => report($e));

Global configuration

To customize the default behavior, publish the config file:

php spark events:publish

This creates app/Config/EventsConfig.php where you can configure:

<?php

namespace Config;

use Brunoggdev\EventsExtended\Config\EventsConfig as BaseEventsConfig;

class EventsConfig extends BaseEventsConfig
{
    /**
     * Whether events should throw on listener failure.
     * When false, errors are passed to $default_error_handler or logged.
     */
    public bool $throw_on_error = false;

    /**
     * Default error handler called when a listener fails and no per-call
     * handler is provided. Receives (Throwable $e, object $event): void.
     * If null, falls back to log_message('error', ...).
     */
    public $default_error_handler = null;
}

Behavior matrix

throw_on_error	on_error param	Result
false (default)	not passed	log as error and swallow
false (default)	passed	call handler and swallow
true	not passed	rethrow
true	passed	call handler and swallow

🎮 CLI Commands

make:event

Creates a skeleton event class:

php spark make:event UserUpdated

make:listener

Creates a listener class (invokable by default). Optionally specify the event class name as a second argument:

php spark make:listener SendWelcomeEmail UserUpdated

events:publish

Publishes the EventsConfig file into your app's Config/ folder for customization:

php spark events:publish

📋 Requirements

• PHP 8.1+
• CodeIgniter 4.x