Download the PHP package sidalex/swoole-app without Composer

sidalex/swoole-app

ru

Swoole-app Framework for Working with Swoole

• Install
• Config
• List of config parameters
  • .env File Format or environment variables in docker
  • Server Configuration
    • Server Mode
    • Server Host and Port
  • Configuration Validation
• Task
  • Methods:
    • task
    • taskwait
• BasicTaskData
  • Parameters
• TaskResulted
  • Properties:
• Cyclic Job
• Middleware
  • Global Middleware
  • Controller-specific Middleware
  • Creating Custom Middleware
  • Configurable Middleware
  • Middleware Configuration Validation
• Controller
  • uri attribute parameter
  • method attribute parameter
  • Request processing
  • Response
  • Request
• notFoundController
• State Containers
  • Creating a State Container
  • Accessing State Containers
  • Best Practices State Containers
• Custom Event Handlers
  • Events
  • Handler Format
  • Priority
  • Error Handling
  • Examples

Install

To install, execute the following commands:

To run the Swoole application, you need to create a script named server.php with the following content:

The $config variable should be \stdClass and can contain parameters described here.

By default, the server runs on 0.0.0.0:9501. You can override these values via environment variables or config.json:

To run background processes that should execute periodically (not triggered by user action but by scheduler), the CyclicJobsInterface is implemented. For a more detailed description of its usage, see here. To automatically start background cyclic processes, they need to be specified in the config here.

To create application endpoints, you need to create controllers classes. For each endpoint, you need to create your own class. Alternatively, create your own routing rule via notFoundController.

All operations inside CyclicJobs and controllers must be non-blocking. Otherwise, instead of increasing performance, you may lose it significantly, and the next request will not be processed until the blocking operation is completed.

All blocking operations must be wrapped in TaskExecutorInterface and executed as separate Task.

Config

To run the application, you need to create a stdClass with a set of properties (described in more detail below).

The intended use is to initiate configuration data from a json file, see example server.php

List of config parameters

.env File Format or environment variables in docker

Variables must start with SWOOLE_APP_ prefix. Example:

Gets converted to:

Priority order:

1. Variables from .env file are loaded first
2. Environment variables from $_ENV or passed to constructor override .env values

This allows you to define default values in .env file and override them via Docker or system environment variables. ini SWOOLE_APP_SERVER_MODE=PROCESS

or

SWOOLE_APP_SERVER_MODE=BASE json { "server": { "mode": "PROCESS" } } json { "server": { "mode": "BASE" } } ini SWOOLE_APP_SERVER_HOST=0.0.0.0 SWOOLE_APP_SERVER_PORT=9501 json { "server": { "host": "0.0.0.0", "port": 9501 } } ini SWOOLE_APP_DEBUG=true SWOOLE_APP_SWOOLEWORKER_NUM=4 SWOOLE_APP_SWOOLETASK_WORKER_NUM=8 SWOOLE_APP_SWOOLEDAEMONIZE=false SWOOLE_APP_SWOOLE__LOG_FILE=/var/log/swoole.log SWOOLE_APP_SWOOLEREACTOR_NUM=2 SWOOLE_APP_SWOOLE__MAX_REQUEST=1000 SWOOLE_APP_SWOOLETASK_ENABLE_COROUTINE=true SWOOLE_APP_SWOOLEPACKAGE_MAX_LENGTH=1048576 SWOOLE_APP_SWOOLE__BUFFER_OUTPUT_SIZE=1048576 json { "SWOOLE": { "worker_num": 4, "task_worker_num": 8, "daemonize": false, "log_file": "/var/log/swoole.log", "reactor_num": 2, "max_request": 1000, "task_enable_coroutine": true, "package_max_length": 1048576, "buffer_output_size": 1048576 } } json { "StateContainerInitiation": [ "YourApp\StateContainers\DatabaseConnectionContainer", "YourApp\StateContainers\CacheConnectionContainer" ] }

composer require sidalex/swoole-app ini SWOOLE_APP_DEBUG=true SWOOLE_APP_DBHOST=localhost SWOOLE_APP_DBPORT=3306

Конфигурация сервера

Фреймворк позволяет настраивать параметры сервера Swoole через переменные окружения или config.json.

Режим работы сервера

Вы можете настроить сервер для работы в разных режимах:

• SWOOLE_PROCESS (по умолчанию) - Многопроцессорный режим (рекомендуется для продакшена)
• SWOOLE_BASE - Одноворкерный режим (проще, полезно для отладки)

Конфигурация через переменные окружения:

Конфигурация через config.json:

или

Хост и порт сервера

Вы можете настроить хост и порт сервера:

Конфигурация через переменные окружения:

Конфигурация через config.json:

При использовании класса Application вы можете создать и запустить сервер:

Параметры сервера Swoole

Вы можете настроить дополнительные параметры сервера Swoole через переменные окружения с префиксом SWOOLE__:

Или через config.json:

Параметры:

• worker_num - Количество рабочих процессов (по умолчанию: ядра CPU)
• task_worker_num - Количество процессов для задач (по умолчанию: ядра CPU * 10)
• daemonize - Запуск сервера в режиме демона
• log_file - Путь к файлу логов
• reactor_num - Количество потоков reactor
• max_request - Максимум запросов на воркер перед перезапуском
• task_enable_coroutine - Включить корутины в task-воркерах
• package_max_length - Максимальный размер пакета
• buffer_output_size - Размер буфера вывода

Полный список параметров см. в Документации Swoole

Полный пример конфигурации

См. config.json.example для полного примера конфигурационного файла со всеми параметрами приложения и сервера Swoole.

Валидация конфигурации

1. Создайте класс-валидатор:

2. Проверка конфигурации:

notFoundController - строка класс с классом , который обрабатывает роуты не найденные по стандартному флоу, данный клас должен имплементировать Sidalex\SwooleApp\Classes\Controllers\ControllerInterface

controllers - массив namespace в которых рекурсивно удет осуществляться поиск классов Контроллеров(имплементирующих интерфейс Sidalex\SwooleApp\Classes\Controllers\ControllerInterface) так же для реализации класса контроллера можно испрользовать наследование AbstractController более подробно тут.

CyclicJobs - мкассив слассов , которые имплементируют интерфейс CyclicJobsInterface которы запускаются при стапрте приложения и выполняются циклично раз в определенный интервал времени подробнее тут

Task Задача

Tasks (задачи) представляют собой процессы, которые выполняются вне асинхронного процесса выполнения и могут быть вызваны в любой части приложения.

В этих процессах могут содержаться блокирующие операции.

Для запуска задачи необходимо создать объект класса BasicTaskData или использовать собственный класс, реализующий интерфейс TaskDataInterface. Подробнее здесь.

Методы Task:

task: запускает задачу без ожидания её завершения.

$data: объект, реализующий интерфейс Sidalex\SwooleApp\Classes\Tasks\Data\TaskDataInterface. По умолчанию предлагается использовать класс BasicTaskData. Подробнее здесь.

$dstWorkerId: идентификационный номер рабочего процесса. Если параметр не передан, сервер Swoole выберет для вас случайный и незанятый рабочий процесс.

$finishCallback: колбэк, который будет выполнен перед завершением задачи. Параметр необязателен.

taskwait - запуск ззадачи с ожитанием завершения и получения результата. ожидание результата происходит неблокирующим образом. задачи можно запускать из контоллера.

$data: объект, реализующий интерфейс Sidalex\SwooleApp\Classes\Tasks\Data\TaskDataInterface. По умолчанию предлагается использовать класс BasicTaskData. Подробнее здесь.

$timeout: время ожидания завершения задачи в секундах. Если истекает время ожидания, будет возвращено значение false. Минимальное значение - 1 мс.

$dstWorkerId: идентификационный номер рабочего процесса. Если параметр не передан, сервер Swoole выберет для вас случайный и незанятый рабочий процесс.

$result: результат выполнения задачи, должен быть экземпляром класса TaskResulted. Подробнее здесь.

Класс BasicTaskData

В котором в конструкторе передается 2 параметра

1 параметр ('Sidalex\TestSwoole\Tasks\TestTaskExecutor') - это название класса, который будет создан в задаче для исполнения. Он должен имплементировать интерфейс TaskExecutorInterface

2 параметр ( ['test' => 'test1'] ) - это массив с данными контекста, который необходим для исполнения логики содержащейся в классе задачи ('Sidalex\TestSwoole\Tasks\TestTaskExecutor' для примера)

Пример применения например в контроллере или в Cyclic Job:

Класс TaskResulted

Описание: Класс TaskResulted представляет собой результат выполнения задачи. Он содержит информацию о успешном выполнении задачи и её результате.

Свойства TaskResulted:

$success - приватное свойство, содержащее информацию о успешном выполнении задачи.

$result - приватное свойство, содержащее результат выполнения задачи.

__construct(mixed $inData, bool $success = true) - конструктор класса, принимающий входные данные и информацию о успешном выполнении задачи.

Методы TaskResulted:

getResult(): mixed - метод, возвращающий результат выполнения задачи. Может выбрасывать исключение типа TaskException.

isSuccess(): bool - метод, возвращающий информацию о успешном выполнении задачи.

Пример:

Класс Cyclic Job

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

Для инициализации Cyclic Job необходимо объявить параметр CyclicJobs в файле конфигурации.

Пример инициализации конфига с использованием stdClass:

Пример инициализации конфига с использованием файла json:

Пример класса для Cyclic Job:

Любой класс, указанный в конфиге, должен реализовывать интерфейс CyclicJobsInterface.

Метод getTimeSleepSecond возвращает время в секундах, через которое будет выполняться метод runJob периодически.

Метод runJob содержит полезную нагрузку в плане бизнес-логики. Это метод содержит бизнес-логику, которая должна выполняться циклически.

Middleware

Приложение поддерживает систему Middleware для обработки HTTP-запросов.

Глобальные Middleware

Глобальные Middleware настраиваются в конфигурации приложения:

Middleware для контроллеров

Middleware можно прикреплять к конкретным контроллерам с помощью атрибутов:

Создание собственного Middleware

Middleware должен реализовывать MiddlewareInterface:

Конфигурируемые Middleware

Для Middleware, требующих конфигурации, реализуйте ConfigurableMiddlewareInterface:

Валидация конфигурации Middleware

Для проверки корректности конфигурации Middleware используйте MiddlewareConfigValidator:

Валидатор проверяет:

• Корректность формата конфигурации
• Существование классов Middleware
• Реализацию MiddlewareInterface

Класс Controller

Для создания новых маршрутов используется класс Controller. Чтобы добавить новый маршрут, вам необходимо создать класс, реализующий интерфейс ControllerInterface, и добавить пространство имен, в котором содержится этот класс, в файл конфигурации с ключом "controllers". Подробнее здесь

Также в фреймворке есть специальный абстрактный класс AbstractController, который может упростить создание класса Controller.

Чтобы создать маршрут для класса Controller, вам необходимо указать атрибут следующего вида:

или

Крайне важно, чтобы сначала был указан атрибут для этого класса.

Если подходящий контроллер не найден, будет вызван NotFoundController.

uri атрибутивный параметр

uri - этот параметр определяет, для какого маршрута будет использоваться данный контроллер.

Если вы укажете в маршруте, например, /test/version//items, то этот контроллер будет работать для uri, соответствующих /test/version/(любая строка)/items.

Если вы укажете /test/version/{version_number}/элементы в маршруте, поведение будет аналогично поведению с *, но $uri_params['version_number'] будет добавлен в конструктор контроллера.

параметр атрибута

method - показывает, какой метод будет уместен для вызова данного контроллера.

Обработка запроса

Метод execute класса Controller содержит основную бизнес-логику, которую приложение должно выполнить для этого запроса. Этот метод должен возвращать ответ (\Swoole\Http\Response), который содержится в

$this->response

Response

В классе Controller:

$this->response

Более подробное описание методов этого класса смотрите в официальной документации Swoole

Пример использования:

Запрос

В классе контроллера:

$this->request;

Более подробное описание методов этого класса смотрите в официальной документации Swoole

Пример использования:

notFoundController

Предназначен для обработки роутов, которые не были найдены роутером фреймворка, для выдачи ответа 404 или организации уникальной логики роутинга приложения.

Для инициализации необходимо передать имя класса в конфиге более подробно об этом тут

notFoundController должен имплементировать ControllerInterface

пример:

Контейнеры состояний

Контейнеры состояний предоставляют способ управления и совместного использования состояния приложения между различными компонентами. Они инициализируются во время запуска приложения и могут быть доступны на протяжении всего жизненного цикла приложения.

Создание контейнера состояний

Чтобы создать новый контейнер состояний: Создайте класс, который расширяет AbstractContainerInitiator или реализует StateContainerInitiationInterface

Реализуйте требуемые методы:

init() — инициализирует ваше состояние

getKey() — возвращает ключ, под которым будет храниться ваше состояние

getResultInitiation() — возвращает инициализированное состояние

Конфигурация JSON:

Доступ к контейнерам состояний

Доступ к контейнерам состояний возможен из любого места, где у вас есть доступ к экземпляру приложения:

Лучшие практики использования Контейнеров состояний

Инициализация: Контейнеры состояний инициализируются один раз во время запуска приложения. Убедитесь, что все необходимые ресурсы доступны в это время.

Безопасность потоков: Поскольку Swoole работает в многопроцессорной среде, убедитесь, что ваши контейнеры состояний:

Без сохранения состояния

Изолированы от процессов

Правильно синхронизированы для общих ресурсов

Управление ресурсами: Если ваш контейнер управляет ресурсами, такими как подключения к базе данных, при необходимости реализуйте надлежащую очистку в деструкторе.

Именование ключей: Используйте описательные и уникальные ключи для ваших контейнеров, чтобы избежать конфликтов.

Пользовательские обработчики событий

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

События

Доступные события для перехвата:

Формат обработчика

Обработчики могут быть определены как замыкания, методы классов или вызываемые классы. Важно: Все обработчики получают Application первым параметром.

Приоритет

• Приоритет по умолчанию: 0
• Меньшие числа выполняются первыми
• Дубликаты приоритетов запрещены (выбрасывается исключение при старте)

Обработка ошибок

• Дубликат приоритета: выбрасывает RuntimeException при старте
• Несуществующий класс: выбрасывает RuntimeException при старте
• Несуществующий метод: выбрасывает RuntimeException при старте
• Исключения в обработчиках: логируются, выполнение продолжается

Примеры