Lithe Events: A Lightweight and Powerful Event Handling Library for PHP

Lithe Events is a lightweight yet powerful library for event management in PHP applications. It allows you to easily create, register, emit, and remove events, creating a decoupled and flexible architecture. This detailed guide will walk you through how to use the library from installation to full implementation.

Table of Contents

1. Installation
2. Usage
   • Using the EventDispatcher Class
   • Creating an Event
   • Registering Listeners
   • Emitting Events
   • Removing Listeners
3. Using Lithe Orbis
4. Full Example

Installation

To install lithemod/events in your PHP project, you will need to use Composer. Run the following command in your project directory:

composer require lithemod/events

This command will download the package and update your project's composer.json file automatically, allowing you to start using the library.

Usage

Using the EventDispatcher Class

The EventDispatcher class is the central piece for managing events and listeners. It allows you to register listeners, emit events, and remove listeners. Let’s go through how to use it step by step.

Creating an Event

To create an event, you instantiate the Event class, which stores the event name and any additional data you want to associate with it. Here's an example:

use Lithe\Events\Event;

$event = new Event('event.name', ['key' => 'value']);

• event.name: The name of the event, which is a string that identifies the event.
• ['key' => 'value']: An optional associative array containing any additional data you want to pass with the event.

Registering Listeners

Now that you have the event, it’s time to register a listener that will be triggered when the event is emitted. To do this, use the on method of the EventDispatcher class.

use Lithe\Events\EventDispatcher;

$dispatcher = new EventDispatcher();

$listener = function ($data) {
    echo "Event data: " . json_encode($data);
};

// Register the listener
$dispatcher->on('event.name', $listener);

Here, the listener is an anonymous function that will be called whenever the 'event.name' event is emitted. The listener receives the data passed by the event.

Emitting Events

To emit an event and trigger all registered listeners, use the emit method of the EventDispatcher class.

$event = new Event('event.name', ['key' => 'value']);
$dispatcher->emit($event);

When the event is emitted, all listeners registered for 'event.name' are called and receive the event data.

Removing Listeners

If you no longer need a listener for a specific event, you can remove it using the off method.

$dispatcher->off('event.name', $listener);

This code removes the listener from the list of listeners for the 'event.name' event.

Using Lithe Orbis

Lithe Orbis is a powerful class that acts as a global instance manager, allowing you to abstract complex functionalities into simple, reusable components. This makes event management even easier and more direct.

With Lithe Orbis, you can use event management functions more simply. Here’s how you can register listeners, emit events, and remove them using the Orbis class:

Registering Listeners with Lithe Orbis

To register a listener using Lithe Orbis, you can directly use the on function:

use Lithe\Orbis\Events;

$listener = function ($data) {
    echo "Event data: " . json_encode($data);
};

// Register the listener
Events\on('event.name', $listener);

Emitting Events with Lithe Orbis

To emit an event using Lithe Orbis, use the emit function:

use Lithe\Orbis\Events;
use Lithe\Events\Event;

$event = new Event('event.name', ['key' => 'value']);
Events\emit($event);

Removing Listeners with Lithe Orbis

Removing listeners with Lithe Orbis is as simple as using the off function:

Events\off('event.name', $listener);

For more information and detailed documentation on Lithe Orbis, you can check the Orbis documentation.

Full Example

Now, let’s look at a full example using the functions and classes mentioned. This example shows how to register listeners, emit events, and remove them.

use Lithe\Events\Event;
use Lithe\Orbis\Events;

// Creating a listener
$listener = function ($data) {
    echo "Event received with data: " . json_encode($data) . "\n";
};

// Registering the listener
Events\on('my.event', $listener);

// Emitting the event
$data = ['msg' => 'Hello, world!'];
Events\emit(new Event('my.event', $data));

// Removing the listener
Events\off('my.event', $listener);

Explanation of the Example:

1. Creating a listener: This listener will display the event data every time it’s triggered.
2. Registering the listener for the 'my.event' event.
3. Emitting the event with associated data.
4. Removing the listener after it’s used.

Lithe Events is a simple yet powerful library that allows you to efficiently manage events in your PHP applications. Whether you're registering listeners, emitting events, or removing them, the library provides all the tools you need to create a modular and decoupled architecture.

Try Lithe Events in your next project and see how it can improve the flexibility and maintainability of your code!