Download the PHP package on1kel/hyperf-lighty without Composer

Hyperf Lighty

Набор инструментов для быстрого и стандартизированного создания REST API на базе Hyperf.
Предоставляет модульную архитектуру для CRUD-операций, валидации, событий моделей и генерации OpenAPI-документации.

Основные возможности

• Быстрая генерация CRUD-эндпоинтов — автоматическое создание контроллеров, ресурсов и сервисов.
• Единая архитектура слоёв — строгая структура Controller → Service → Model.
• Встроенная валидация и ресурсы — использует стандартные механизмы Hyperf\Validation и Hyperf\Resource.
• Асинхронные очереди и события — поддержка hyperf/async-queue и гибкое управление событиями моделей.
• Документация API из кода — интеграция с on1kel/hyperf-fly-docs.
• Расширяемость и переопределение — возможность легко подключать собственные адаптеры, трейты и кастомные события.
• Минимальная зависимость от фреймворка — пакет можно использовать как библиотеку.

Установка

Требуется PHP 8.1+ и Hyperf 3.1+

Быстрый старт

1. Подключение конфигурации

После установки зарегистрируйте конфиг-провайдер в вашем config/autoload/dependencies.php (обычно добавляется автоматически):

2. Публикация конфигураций

Будут созданы файлы:

• config/autoload/model_events.php
• config/events/attendance.php (пример событий моделей)

3. Создание CRUD-контроллера

Будут автоматически сгенерированы:

• App/Http/Controllers/UserController.php
• App/Services/UserService.php
• App/Models/User.php
• ресурсы и валидации

4. Генерация файла _ide_helper_models.php

Для корректной работы автоматической генерации OpenAPI-документации пакет требует наличия актуального файла _ide_helper_models.php, содержащего метаданные всех моделей проекта.

Требования

• Установленный пакет friendsofhyperf/ide-helper

Установка

Генерация моделей

После установки выполните команду:

В результате будет создан (или обновлён) файл:

Этот файл обеспечивает:

• корректную работу IDE-подсказок (PhpStorm, VSCode и др.);
• автоматическую генерацию схем моделей для OpenAPI-документации;
• улучшенное автодополнение в коде при работе с моделями.

Совет: рекомендуется добавить команду генерации в ваши dev-скрипты Composer, например:

Архитектура

4. Создание _ide_helper_models.php

Для полноценной работы пакета необходимо установленный пакет friendsofhyperf/ide-helper и выполненная команда для полноценной работы автоматической генерации OpenApi документации

Ниже — продуктовое, аккуратное описание, без учебного тона и лишней техники, с акцентом на зачем, что даёт, как использовать в проде.

5. Разделение процессов по ролям (для запуска в отдельных контейнерах)

Пакет on1kel/hyperf-lighty вводит единый, декларативный механизм управления процессами Hyperf, предназначенный для чёткого разделения ролей приложения и безопасного деплоя в Docker/Kubernetes.

Цель:

• запускать разные группы процессов в разных контейнерах (api, queue, cron, и т.д.);
• исключить дублирование cron/consumer при горизонтальном масштабировании;
• сохранить один Docker-образ и управлять поведением через переменные окружения.

Публикация конфигурации

Опубликуйте конфигурацию пакета:

После публикации конфиг пакета становится единственным источником истины для определения:

• какие процессы существуют в приложении;
• в каких ролях они могут запускаться.

Замена стандартного processes.php

Замените стандартный config/autoload/processes.php на версию, предоставляемую пакетом.

Этот файл:

• читает активные роли из APP_ROLES;
• фильтрует процессы на основе атрибутов ролей;
• возвращает строго тот набор процессов, который допустим для текущего контейнера.

Назначение ролей процессам

Для указания ролей используется атрибут DeployRoles. Процесс сам декларативно описывает, в каких ролях он допустим.

Пример: процесс cron

Такой процесс будет запущен только в контейнере с:

Переопределение стандартных процессов Hyperf

Пакет предоставляет собственные реализации стандартных процессов Hyperf с уже назначенными ролями.

Cron

Queue consumers

Это позволяет:

• использовать стандартные компоненты Hyperf;
• контролировать их запуск без условий и if-логики;
• централизованно управлять поведением через APP_ROLES.

Поддержка процессов из внешних пакетов (final, без атрибутов)

Не все процессы можно или целесообразно помечать атрибутами ролей:

• класс объявлен как final;
• процесс находится во внешнем пакете;
• пакет не должен знать о деплое и инфраструктуре.

Для таких случаев process_registry.php поддерживает явное назначение ролей.

Таким образом:

• пакет Kafka не зависит от hyperf-lighty;
• роли определяются исключительно на уровне приложения;
• деплой остаётся декларативным и прозрачным.

Приоритет правил:

1. Явное указание ролей в process_registry.php
2. Атрибут DeployRoles
3. Отсутствие ролей → процесс считается универсальным

Как это используется в контейнерах

Один и тот же Docker-образ, разные роли:

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

6. Единый логгер и вывод в stdout (prod-ready)

on1kel/hyperf-lighty предоставляет готовое решение для унификации логирования в Hyperf-приложениях и корректной работы в Docker / Kubernetes.

Проблема, которую решает пакет

По умолчанию в Hyperf существуют два разных источника логов:

• логи приложения — через monolog и config/autoload/logger.php;
• системные логи Hyperf (startup, workers, signals) — через StdoutLogger, использующий print_r().

Это приводит к проблемам в проде:

• смешанные форматы логов;
• отсутствие структурированных данных;
• невозможность нормально парсить stdout лог-агрегаторами (Loki / ELK / CloudWatch);
• “мусорные” строки в логах при инцидентах.

Что делает Hyperf Lighty

Пакет предоставляет production-ready реализацию StdoutLoggerFactory, которая:

• подменяет стандартный StdoutLogger Hyperf;
• перенаправляет все системные логи фреймворка в Monolog;
• использует единый формат и уровни логирования;
• полностью совместима с config/autoload/logger.php.

В результате:

• все логи (и приложения, и фреймворка) проходят через Monolog;
• stdout/stderr становятся управляемыми и предсказуемыми;
• логирование готово к прод-эксплуатации.

Подключение StdoutLoggerFactory

В каждом приложении биндинг выполняется один раз — в config/autoload/dependencies.php:

После этого:

• Hyperf перестаёт писать print_r() в stdout;
• все системные сообщения логируются через Monolog (channel sys).

Настройка формата логов (logger.php)

StdoutLoggerFactory не заменяет конфигурацию логов — она лишь направляет вывод в Monolog. Формат, уровни и handlers задаются стандартным способом через config/autoload/logger.php.

Рекомендуемая схема:

• dev / local — человекочитаемые логи (LineFormatter, с цветами);
• prod — структурированные JSON-логи.

Пример минимальной конфигурации:

⚠️ В Docker/Kubernetes рекомендуется использовать только stdout/stderr, без файловых логов внутри контейнера.

Каналы логирования

Рекомендуется использовать фиксированные каналы, а не динамические имена:

• sys — системные логи Hyperf;
• http — HTTP-запросы;
• queue — очереди;
• kafka.* — Kafka consumers;
• cron — cron-задачи.

❗ Не используйте request_id или user_id в качестве имени канала — это приводит к утечкам памяти, так как LoggerFactory кеширует логгеры.

Контекст (request_id, trace_id и т.п.) должен передаваться через context или processors.

Безопасность

• Используется расширение ext-sodium для безопасного шифрования (sodium_crypto_secretbox).
• Все ключи и токены рекомендуется хранить в .env.
• Поддержка строгой типизации (declare(strict_types=1)).

Index Action (Поиск и аналитика)

Метод POST /search поддерживает расширенные возможности поиска, фильтрации, сортировки и аналитики.

Структура запроса

Select (Выбор полей)

Позволяет указать конкретные поля для выборки и применять агрегации.

Важно: При использовании агрегаций ответ возвращается как сырые данные, а не через ресурс.

Where (Фильтрация)

Поддерживает одиночные условия и группы с логическими операторами.

Order (Сортировка)

Join (Присоединение таблиц)

Используется для фильтрации/сортировки по связанным таблицам или аналитических запросов.

Примечание: Для получения связанных данных в обычных запросах лучше использовать with (relationships).

Group By (Группировка)

Используется вместе с агрегациями в select.

With (Relationships)

Загрузка связанных сущностей через Eloquent relationships.

Пагинация

Для аналитических запросов (с агрегациями или group_by) используется простой LIMIT/OFFSET вместо Laravel paginate().

Аналитические запросы

При наличии агрегаций или group_by запрос считается аналитическим:

• Ответ возвращается как сырые данные, а не через ресурс
• Relationships не загружаются
• Пагинация работает через LIMIT/OFFSET

Пример аналитического запроса:

Ответ:

Фильтрация полей в ресурсах

При указании конкретных полей в select (без агрегаций), ресурс вернёт только запрошенные поля:

Для работы этой функции в вашем ресурсе используйте метод filterByRequestedFields():

Лицензия

Лицензия MIT. Для получения большей информации обращайтесь к тексту лицензии.