Файл ServerEventMessageDto.php в Cotonti

Основное назначение файла ServerEventMessageDto.php в движке Cotonti CMF — это представление данных о сообщении серверного события (Server-Sent Event, SSE), которое может быть отправлено клиенту в реальном времени. Он определяет структуру данных, которые будут использоваться для таких сообщений, и предоставляет методы для удобного создания объектов сообщений и их преобразования в строковый формат для отправки через SSE.

Суть содержания кода:

1. Класс ServerEventMessageDto представляет структуру сообщения события. Он содержит несколько свойств, которые задают основные параметры события:

   • $id: Идентификатор события, используемый для отслеживания и определения последнего события.
   • $userId: Идентификатор пользователя, с которым связано событие.
   • $event: Тип события (имя события), которое будет использоваться для прослушивания события на клиентской стороне.
   • $initialEvent: Начальное значение события, не используется в текущей реализации.
   • $data: Данные, которые будут переданы вместе с событием. Эти данные могут быть в формате JSON.
   • $retry: Время повторного подключения в миллисекундах для клиентов, если событие не может быть отправлено.
   • $comment: Комментарий, который может быть использован как "keep-alive" сообщение, если события отправляются не часто.

2. Метод fromArray: Этот статический метод позволяет создать объект ServerEventMessageDto из ассоциативного массива данных. Он преобразует полученные значения в правильные типы (например, ID и userId в целые числа) и возвращает новый объект.

3. Метод __toString: Метод преобразует объект в строку, форматируя его в соответствии с требованиями SSE. Он добавляет информацию о комментарии, ID события, времени повторного подключения и данные события. Строка возвращается в формате, который сервер может отправить клиенту через протокол SSE.

Место в системе:

Этот файл является частью системы Cotonti CMF и служит для управления и отправки серверных событий через механизм Server-Sent Events. SSE используется для того, чтобы сервер мог отправлять обновления в реальном времени на клиентскую сторону (например, для чатов, уведомлений, обновлений состояния и других динамичных данных). Класс ServerEventMessageDto является DTO (Data Transfer Object), который помогает структурировать и упрощать обмен данными между сервером и клиентом.

Вместе с другими классами и сервисами, связанными с обработкой серверных событий, данный класс помогает организовать механизм передачи и управления такими событиями в системе.

Основное назначение класса: Этот класс используется для представления сообщения события, которое будет отправлено с сервера на клиент с помощью технологии Server-Sent Events (SSE). Класс включает в себя несколько свойств, которые описывают событие (например, ID, тип события, данные и комментарии). Он также предоставляет методы для создания объекта из массива данных и преобразования его в строку для отправки клиенту.

/system/serverEvents/ServerEventMessageDto.php

<?php

declare(strict_types=1); // Устанавливаем строгую типизацию (включаем проверку типов).

namespace cot\serverEvents; // Пространство имен для данного класса, указывающее на принадлежность к серверным событиям.

defined('COT_CODE') or die('Wrong URL'); // Проверка, что файл вызывается в рамках правильного контекста, иначе завершение выполнения.

class ServerEventMessageDto // Объявление класса, который представляет сообщение серверного события.
{
    /**
     * @var int The event ID to set the EventSource object's last event ID value.
     * Идентификатор события, который будет установлен в объекте EventSource.
     */
    public $id; // Свойство для хранения ID события.

    /**
     * @var int
     */
    public $userId; // Свойство для хранения ID пользователя, которому это событие связано.

    /**
     * @var string A string identifying the type of event described.
     *   If this is specified, an event will be dispatched on the browser to the listener for the specified event name;
     *   the website source code should use addEventListener() to listen for named events.
     *   The onmessage handler is called if no event name is specified for a message.
     */
    public $event; // Свойство для хранения типа события (имя события), которое будет отправлено на клиентскую сторону.

    /**
     * @var string The initial $event
     * @todo unused
     */
    public $initialEvent; // Неиспользуемое свойство для хранения начального значения события.

    /**
     * @var string The data field for the message. When the EventSource receives multiple consecutive lines that
     *   begin with data:, it will concatenate them, inserting a newline character between each one.
     *   Trailing newlines are removed.
     */
    public $data; // Свойство для хранения данных сообщения, которое будет отправлено клиенту.

    /**
     * @var int The reconnection time to use when attempting to send the event. This must be an integer,
     *   specifying the reconnection time in milliseconds. If a non-integer value is specified, the field is ignored.
     */
    public $retry; // Свойство для хранения времени повторного подключения (в миллисекундах), если событие не может быть отправлено.

    /**
     * @var string This is just a comment, since it starts with a colon character. As mentioned previously,
     *   this can be useful as a keep-alive if messages may not be sent regularly.
     */
    public $comment; // Свойство для хранения комментариев (начинается с двоеточия), которые могут быть полезны для keep-alive сообщений.

    // Метод для создания объекта ServerEventMessageDto из массива данных.
    public static function fromArray($data): self 
    {
        $event = new ServerEventMessageDto(); // Создание нового объекта ServerEventMessageDto.
        $event->id = (int) $data['id']; // Присваиваем ID события.
        $event->userId = (int) $data['user_id']; // Присваиваем ID пользователя.
        $event->event = $data['event']; // Присваиваем тип события.
        $event->data = $data['data']; // Присваиваем данные события.
        return $event; // Возвращаем объект.
    }

    // Метод для преобразования объекта в строку.
    public function __toString()
    {
        $event = []; // Инициализируем массив для хранения строковых представлений различных свойств.

        // Если есть комментарий, добавляем его в массив.
        if ($this->comment !== '') {
            $event[] = sprintf(': %s', $this->comment); // Добавляем комментарий.
        }
        // Если ID события задан, добавляем его в массив.
        if ($this->id !== '') {
            $event[] = sprintf('id: %s', $this->id); // Добавляем ID события.
        }
        // Если время повторного подключения задано, добавляем его в массив.
        if ($this->retry > 0) {
            $event[] = sprintf('retry: %s', $this->retry); // Добавляем время повторного подключения.
        }

        // Здесь закомментирован код, который был бы ответственный за добавление имени события, если оно задано.
        // if ($this->event !== '') {
        //     $event[] = sprintf('event: %s', $this->event); // Добавляем имя события.
        // }

        // Создаем данные для поля data, конвертируя их в JSON.
        $data = [
            'event' => empty($this->event) ? null : $this->event, // Если событие пустое, ставим null, иначе добавляем событие.
            'data' => empty($this->data) ? null : $this->data, // Если данные пустые, ставим null, иначе добавляем данные.
        ];

        // Добавляем строку с данными в массив.
        $event[] = sprintf('data: %s', json_encode($data, JSON_FORCE_OBJECT)); // Преобразуем данные в JSON-формат.

        // Возвращаем строковое представление сообщения, объединяя все элементы массива и добавляя два перевода строки в конец.
        return implode("\n", $event) . "\n\n"; 
    }
}