# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cmsfullform.com/documents/libraries/events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.