# Events

The `Events` class is part of the Libraries namespace and is designed to manage and handle events in the system. It provides methods to register, trigger, and process events. Below is a detailed explanation of each function and its purpose.

## **Funtions in Events Libraries**

### **Property `$listeners`**

```php
<?php
protected static $listeners = [];
```

* This is a static array that stores the list of listeners for each event.
* Structure of `$listeners`:

```php
<?php
[
    'EventName' => [
        priority => [listener1, listener2, ...],
        ...
    ],
    ...
]
```

* **`EventName`**: The name of the event.
* **`priority`**: The priority of the listener (higher numbers are executed first).
* **`listener1, listener2`**: Callbacks or classes that handle the event.

### **`on()`**

```php
<?php
public static function on($eventName, $listener, $priority = 0) {}
```

* **Purpose**: Registers a listener (callback or class) for a specific event.
* **Parameters**:
  * `$eventName`: The name of the event (e.g., `'PostsAddEvent'`).
  * `$listener`: A callback function or class name that will be executed when the event is triggered.
  * `$priority`: The priority of the listener (default is `0`).

### **`run()`**

<pre class="language-php"><code class="lang-php">&#x3C;?php
<strong>public static function run($eventName, $payload = null) {}
</strong></code></pre>

* **Purpose**: Triggers (dispatches) an event.
* **Parameters**:
  * `$eventName`: The name of the event to trigger.
  * `$payload`: Data to pass to the event (can be an array, object, etc.).

### **`runs()`**

```php
<?php
public static function runs(array $events) {}
```

* **Purpose**: Triggers multiple events at once.
* **Parameters**:

  * `$events`: An array of events and their associated data, in the format

  ```php
  <?php
  [
      'EventName1' => $payload1,
      'EventName2' => $payload2,
      ...
  ]
  ```

### **General Workflow**

1. **Registering Listeners**:
   * Use the `on()` method to register listeners for events.
   * Listeners can be either callback functions or classes with a `handle()` method.
2. **Triggering Events**:
   * Use the `run()` method to trigger a single event.
   * When an event is triggered:
     * Registered listeners are executed in order of priority.
     * If no listeners are registered, a default event class in the `\App\Events` namespace is checked and executed.
3. **Triggering Multiple Events**:
   * Use the `runs()` method to trigger multiple events at once.

## Example

### Using basically

```php
Events::on('UserRegistered', function ($user) {
    echo "Welcome, {$user['name']}!<br>";
}, 10); // Priority 10


Events::on('UserRegistered', function ($user) {
    echo "Sending welcome email to {$user['email']}...<br>";
}, 5); // Priority 5

$user = ['name' => 'John Doe', 'email' => 'john.doe@example.com'];
Events::run('UserRegistered', $user);

// ------------------------------ Output ------------------------------
// Welcome, John Doe!
// Sending welcome email to john.doe@example.com...
```

### Using in Class

```php
class NotifyAdmin
{
    protected $user;

    public function __construct($user)
    {
        $this->user = $user;
    }

    public function handle()
    {
        echo "Notifying admin about new user: {$this->user['name']}<br>";
    }
}
```

```php
Events::on('UserRegistered', NotifyAdmin::class, 8); // Priority 8

// ------------------------------ Output ------------------------------
// Welcome, John Doe!
// Notifying admin about new user: John Doe
// Sending welcome email to john.doe@example.com...
```

### Using multiple Events

<pre class="language-php"><code class="lang-php">&#x3C;?php
// Register event 'OrderPlaced'
Events::on('OrderPlaced', function ($order) {
    echo "Order #{$order['id']} has been placed.&#x3C;br>";
});

// Triggering Mmultiple Events
$events = [
    'UserRegistered' => $user,
    'OrderPlaced' => ['id' => 12345],
];

Events::runs($events);

// ------------------------------ Output ------------------------------
<strong>// Welcome, John Doe!
</strong>// Notifying admin about new user: John Doe
// Sending welcome email to john.doe@example.com...
// Order #12345 has been placed.
</code></pre>

{% hint style="success" %}
Summary

* You can register multiple listeners for an event with different priority levels.
* Listeners can be either callback functions or classes with a `handle()` method.
* Use `Events::run()` to trigger a single event or `Events::runs()` to trigger multiple events at once.
* The output depends on the priority order of the listeners.
  {% endhint %}