Система подій у Flight PHP (v3.15.0+)

Flight PHP пропонує легку та інтуїтивну систему подій, яка дозволяє реєструвати та викликати власні події у вашому застосунку. З додаванням методів Flight::onEvent() та Flight::triggerEvent(), ви тепер можете підключатися до ключових моментів життєвого циклу вашого додатку або визначати власні події, щоб зробити ваш код більш модульним і розширюваним. Ці методи є частиною mappable methods Flight, тобто ви можете перевизначити їхню поведінку відповідно до ваших потреб.

Цей посібник охоплює все, що вам потрібно знати, щоб розпочати роботу з подіями, включаючи те, чому вони корисні, як їх використовувати, та практичні приклади, які допоможуть новачкам зрозуміти їхню силу.

Події дозволяють розділити різні частини вашого застосунку, щоб вони не залежали одна від одної надто сильно. Це розділення — часто називається decoupling — робить ваш код легшим для оновлення, розширення або налагодження. Замість того, щоб писати все в одному великому блоці, ви можете розділити вашу логіку на менші, незалежні частини, які реагують на конкретні дії (події).

Уявіть, що ви створюєте застосунок для блогу:

• Коли користувач публікує коментар, ви можете захотіти:
  • Зберегти коментар у базі даних.
  • Надіслати електронний лист власнику блогу.
  • Зафіксувати дію для безпеки.

Без подій ви б запакували все це в одну функцію. З подіями ви можете розділити: одна частина зберігає коментар, інша викликає подію, наприклад 'comment.posted', а окремі слухачі обробляють електронний лист і фіксацію. Це робить ваш код чистішим і дозволяє додавати або видаляти функції (наприклад, сповіщення) без дотику до основної логіки.

Поширені випадки використання

• Logging: Фіксувати дії, як-от входи або помилки, без засмічення основного коду.
• Notifications: Надсилати електронні листи або сповіщення, коли щось відбувається.
• Updates: Оновлювати кеш або повідомляти інші системи про зміни.

Щоб слухати подію, використовуйте Flight::onEvent(). Цей метод дозволяє визначити, що має відбуватися, коли подія виникає.

Синтаксис

Flight::onEvent(string $event, callable $callback): void

• $event: Назва для вашої події (наприклад, 'user.login').
• $callback: Функція, яка виконується, коли подія викликається.

Як це працює

Ви "підписуєтеся" на подію, повідомляючи Flight, що робити, коли вона відбувається. Callback може приймати аргументи, передані з виклику події.

Система подій Flight є синхронною, що означає, що кожен слухач події виконується послідовно, один за одним. Коли ви викликаєте подію, всі зареєстровані слухачі для цієї події виконуються до кінця, перш ніж ваш код продовжиться. Це важливо розуміти, оскільки це відрізняється від асинхронних систем подій, де слухачі можуть виконуватися паралельно або пізніше.

Простій приклад

Flight::onEvent('user.login', function ($username) {
    echo "Welcome back, $username!";
});

Тут, коли подія 'user.login' викликається, вона вітає користувача за іменем.

Ключові аспекти

• Ви можете додати кілька слухачів до однієї події — вони виконуватимуться в порядку реєстрації.
• Callback може бути функцією, анонімною функцією або методом з класу.

Щоб викликати подію, використовуйте Flight::triggerEvent(). Це повідомляє Flight виконати всі слухачі, зареєстровані для цієї події, передаючи будь-які дані.

Синтаксис

Flight::triggerEvent(string $event, ...$args): void

• $event: Назва події, яку ви викликаєте (повинна збігатися з зареєстрованою подією).
• ...$args: Опціональні аргументи для передачі слухачам (може бути будь-яка кількість аргументів).

Простій приклад

$username = 'alice';
Flight::triggerEvent('user.login', $username);

Це викликає подію 'user.login' і передає 'alice' слухачеві, який ми визначили раніше, що виведе: Welcome back, alice!.

Ключові аспекти

• Якщо слухачів не зареєстровано, нічого не відбувається — ваш застосунок не зламається.
• Використовуйте оператор поширення (...), щоб гнучко передавати кілька аргументів.

Зупинка подальших слухачів

Якщо слухач повертає false, жодні додаткові слухачі для цієї події не виконуватимуться. Це дозволяє зупинити ланцюг подій на основі певних умов. Пам'ятайте, що порядок слухачів важливий, оскільки перший, хто поверне false, зупинить решту.

Приклад:

Flight::onEvent('user.login', function ($username) {
    if (isBanned($username)) {
        logoutUser($username);
        return false; // Зупиняє наступні слухачі
    }
});
Flight::onEvent('user.login', function ($username) {
    sendWelcomeEmail($username); // це ніколи не відправляється
});

Flight::onEvent() та Flight::triggerEvent() можна розширити, тобто ви можете перевизначити, як вони працюють. Це корисно для просунутих користувачів, які хочуть налаштувати систему подій, наприклад, додати фіксацію або змінити спосіб виклику подій.

Приклад: Налаштування onEvent

Flight::map('onEvent', function (string $event, callable $callback) {
    // Фіксує кожну реєстрацію події
    error_log("New event listener added for: $event");
    // Викликає стандартну поведінку (припускаючи внутрішню систему подій)
    Flight::_onEvent($event, $callback);
});

Тепер, щоразу, коли ви реєструєте подію, вона фіксується перед продовженням.

Чому перевизначати?

• Додати налагодження або моніторинг.
• Обмежити події в певних середовищах (наприклад, вимкнути в тестуванні).
• Інтегрувати з іншою бібліотекою подій.

Як новачок, ви можете задатися питанням: де мені реєструвати всі ці події в моєму застосунку? Простота Flight означає, що немає суворого правила — ви можете розміщувати їх там, де це логічно для вашого проєкту. Однак, підтримання порядку допомагає підтримувати код, коли ваш застосунок росте. Ось деякі практичні варіанти та найкращі практики, адаптовані до легкості Flight:

Варіант 1: У вашому головному index.php

Для малих застосунків або швидких прототипів ви можете реєструвати події безпосередньо в файлі index.php поряд з маршрутами. Це тримає все в одному місці, що добре, коли пріоритет — простота.

require 'vendor/autoload.php';

// Реєстрація подій
Flight::onEvent('user.login', function ($username) {
    error_log("$username logged in at " . date('Y-m-d H:i:s'));
});

// Визначення маршрутів
Flight::route('/login', function () {
    $username = 'bob';
    Flight::triggerEvent('user.login', $username);
    echo "Logged in!";
});

Flight::start();

• Переваги: Просто, без додаткових файлів, ідеально для малих проєктів.
• Недоліки: Може стати хаотичним, коли застосунок росте з більше подіями та маршрутами.

Варіант 2: Окремий файл events.php

Для трохи більшого застосунку розгляньте перенесення реєстрацій подій у спеціальний файл, як-от app/config/events.php. Підключіть цей файл у index.php перед маршрутами. Це імітує, як часто організовуються маршрути в app/config/routes.php у проєктах Flight.

// app/config/events.php
Flight::onEvent('user.login', function ($username) {
    error_log("$username logged in at " . date('Y-m-d H:i:s'));
});

Flight::onEvent('user.registered', function ($email, $name) {
    echo "Email sent to $email: Welcome, $name!";
});

// index.php
require 'vendor/autoload.php';
require 'app/config/events.php';

Flight::route('/login', function () {
    $username = 'bob';
    Flight::triggerEvent('user.login', $username);
    echo "Logged in!";
});

Flight::start();

• Переваги: Тримає index.php зосередженим на маршрутах, організовує події логічно, легко знайти та редагувати.
• Недоліки: Додає трохи структури, що може здатися зайвим для дуже малих застосунків.

Варіант 3: Поруч з місцем виклику

Інший підхід — реєструвати події поруч з місцем їх виклику, наприклад, всередині контролера або визначення маршруту. Це добре працює, якщо подія специфічна для однієї частини застосунку.

Flight::route('/signup', function () {
    // Реєстрація події тут
    Flight::onEvent('user.registered', function ($email) {
        echo "Welcome email sent to $email!";
    });

    $email = 'jane@example.com';
    Flight::triggerEvent('user.registered', $email);
    echo "Signed up!";
});

• Переваги: Тримає пов'язаний код разом, добре для ізольованих функцій.
• Недоліки: Розкидає реєстрації подій, роблячи важче бачити всі події одразу; ризикує дублювання реєстрацій, якщо не обережно.

Найкращі практики для Flight

• Почніть просто: Для малих застосунків розміщуйте події в index.php. Це швидко і відповідає мінімалізму Flight.
• Розвивайте розумно: Коли ваш застосунок розростається (наприклад, більше 5-10 подій), використовуйте файл app/config/events.php. Це природний крок, як організація маршрутів, і тримає ваш код акуратним без додавання складних фреймворків.
• Уникайте перевиробництва: Не створюйте повноцінний "менеджер подій" клас або директорію, якщо ваш застосунок не стає величезним — Flight процвітає на простоті, тож тримайте це легким.

Порада: Групуйте за метою

У events.php, групуйте пов'язані події (наприклад, всі події, пов'язані з користувачем, разом) з коментарями для ясності:

// app/config/events.php
// Події користувача
Flight::onEvent('user.login', function ($username) {
    error_log("$username logged in");
});
Flight::onEvent('user.registered', function ($email) {
    echo "Welcome to $email!";
});

// Події сторінок
Flight::onEvent('page.updated', function ($pageId) {
    unset($_SESSION['pages'][$pageId]);
});

Ця структура добре масштабується і залишається дружньою для новачків.

Давайте пройдемося кількома реальними сценаріями, щоб показати, як працюють події та чому вони корисні.

Приклад 1: Фіксація входу користувача

// Крок 1: Реєстрація слухача
Flight::onEvent('user.login', function ($username) {
    $time = date('Y-m-d H:i:s');
    error_log("$username logged in at $time");
});

// Крок 2: Виклик у вашому застосунку
Flight::route('/login', function () {
    $username = 'bob'; // Припустимо, це приходить з форми
    Flight::triggerEvent('user.login', $username);
    echo "Hi, $username!";
});

Чому це корисно: Код входу не потребує знати про фіксацію — він просто викликає подію. Ви можете пізніше додати більше слухачів (наприклад, надіслати вітальний електронний лист) без змін у маршруті.

Приклад 2: Сповіщення про нових користувачів

// Слухач для нових реєстрацій
Flight::onEvent('user.registered', function ($email, $name) {
    // Симулює надсилання електронного листа
    echo "Email sent to $email: Welcome, $name!";
});

// Виклик, коли хтось реєструється
Flight::route('/signup', function () {
    $email = 'jane@example.com';
    $name = 'Jane';
    Flight::triggerEvent('user.registered', $email, $name);
    echo "Thanks for signing up!";
});

Чому це корисно: Логіка реєстрації зосереджується на створенні користувача, тоді як подія обробляє сповіщення. Ви могли б додати більше слухачів (наприклад, зафіксувати реєстрацію) пізніше.

Приклад 3: Очищення кешу

// Слухач для очищення кешу
Flight::onEvent('page.updated', function ($pageId) {
    unset($_SESSION['pages'][$pageId]); // Очищає кеш сесії, якщо застосовується
    echo "Cache cleared for page $pageId.";
});

// Виклик, коли сторінка редагується
Flight::route('/edit-page/(@id)', function ($pageId) {
    // Припустимо, ми оновили сторінку
    Flight::triggerEvent('page.updated', $pageId);
    echo "Page $pageId updated.";
});

Чому це корисно: Код редагування не турбується про кеш — він просто сигналізує про оновлення. Інші частини застосунку можуть реагувати за потребою.

Система подій у Flight PHP з Flight::onEvent() та Flight::triggerEvent() надає простий, але потужний спосіб створювати гнучкі застосунки. Дозволяючи різним частинам вашого застосунку спілкуватися через події, ви можете тримати код організованим, повторно використовуваним і легким для розширення. Чи то фіксація дій, відправка сповіщень, чи управління оновленнями, події допомагають робити це без заплутування логіки. Крім того, з можливістю перевизначення цих методів, у вас є свобода налаштувати систему під свої потреби. Почніть з однієї події і побачите, як це трансформує структуру вашого застосунку!

Flight PHP містить кілька вбудованих подій, які ви можете використовувати, щоб підключитися до життєвого циклу фреймворку. Ці події викликаються в певні моменти циклу запиту/відповіді, дозволяючи виконувати власну логіку, коли відбуваються певні дії.

Список вбудованих подій

• flight.request.received: function(Request $request) Викликається, коли запит отримано, розібрано та оброблено.
• flight.error: function(Throwable $exception) Викликається, коли виникає помилка під час циклу запиту.
• flight.redirect: function(string $url, int $status_code) Викликається, коли ініціюється перенаправлення.
• flight.cache.checked: function(string $cache_key, bool $hit, float $executionTime) Викликається, коли перевіряється кеш для певного ключа і чи було попадання в кеш.
• flight.middleware.before: function(Route $route) Викликається після виконання before middleware.
• flight.middleware.after: function(Route $route) Викликається після виконання after middleware.
• flight.middleware.executed: function(Route $route, $middleware, string $method, float $executionTime) Викликається після виконання будь-якого middleware.
• flight.route.matched: function(Route $route) Викликається, коли маршрут збігається, але ще не виконано.
• flight.route.executed: function(Route $route, float $executionTime) Викликається після виконання маршруту та обробки. $executionTime — це час, який пішов на виконання маршруту (виклик контролера тощо).
• flight.view.rendered: function(string $template_file_path, float $executionTime) Викликається після рендерингу виду. $executionTime — це час, який пішов на рендеринг шаблону. Примітка: Якщо ви перевизначаєте метод render, вам потрібно буде повторно викликати цю подію.
• flight.response.sent: function(Response $response, float $executionTime) Викликається після відправки відповіді клієнту. $executionTime — це час, який пішов на побудову відповіді.