Архитектура Triangle Framework

Triangle — модульный набор PHP-библиотек и приложений поверх Localzet Server. Server отвечает за асинхронный runtime и сетевые протоколы; Triangle добавляет контейнер, приложение, компоненты и готовые Web/WS tracks. Цель — дать альтернативную модель долгоживущих PHP-процессов; сравнение с PHP-FPM зависит от нагрузки и deployment-модели, поэтому производительность следует подтверждать воспроизводимыми измерениями.

Два application tracks

• Web — основной HTTP/MVC track для сайтов, API и сервисов. Web-Managed — отдельный HTTP-шаблон с управляемыми ограничениями зависимостей и собственным Composer-именем triangle/web-managed.
• WS — отдельный WebSocket-first track для приложений реального времени. Он предоставляет lifecycle WebSocket-соединений и route callbacks; межпроцессная синхронизация, reconnect и backpressure не входят в шаблон как готовые возможности.

Track описывает набор пакетов и соглашений приложения; оба используют Localzet Server как нижележащий runtime. Composer manifests HTTP/WS engines явно запрещают совместную установку этих движков в одном dependency graph. Возможность запускать отдельные приложения/процессы на одном серверном deployment — другой вопрос и требует эксплуатационной проверки.

Общая структура

Triangle Framework состоит из следующих основных компонентов:

Ядро (Engine)

triangle/engine — это базовое ядро фреймворка, которое предоставляет:

• Абстракцию приложения (Triangle\Engine\App)
• Контейнер зависимостей (Triangle\Engine\Container)
• Систему конфигурации (Triangle\Engine\Config)
• Обработку запросов и ответов (Triangle\Engine\Request, Triangle\Engine\Response)
• Систему исключений и обработчиков ошибок
• Поддержку плагинов и автозагрузки
• Вспомогательные функции (кэширование, логирование, переводы)

Компоненты (Components)

Модульные библиотеки, расширяющие функциональность ядра:

• triangle/console — консольные команды и CLI-инструменты
• triangle/router — система маршрутизации
• triangle/middleware — промежуточное ПО (middleware)
• triangle/database — работа с базами данных (на основе Illuminate Database)
• triangle/view — система шаблонизации
• triangle/session — управление сессиями
• triangle/events — система событий
• triangle/cron — планировщик задач

Движки (Engines)

Слои приложений, построенные на основе Engine:

• triangle/engine-http — HTTP-слой для обработки HTTP-запросов
• triangle/engine-ws — WebSocket-слой для работы с WebSocket-соединениями

Ограничение текущих пакетов: engine-http и engine-ws объявляют взаимный Composer conflict, поэтому их нельзя установить вместе в одном Composer dependency graph. Эксплуатация отдельных Web и WS приложений на одном Localzet Server deployment не описывает совместное подключение движков.

Плагины (Plugins)

Дополнительные модули расширения:

• triangle/oauth — OAuth-клиент и провайдерные адаптеры; состояние интеграции сверяйте в каталоге плагинов
• triangle/media — приём и обработка изображений с ext-curl, ext-imagick и ограничениями для удалённых URL, размера, пикселей и кадров
• triangle/pusher — незавершённый прототип, не готовый сервис
• triangle/multiconnect — Localzet Server handler с локальным реестром и необязательным адаптером к Localzet Cluster для распределённых отправок

Фреймворки (Frameworks)

Готовые рабочие окружения:

• triangle/web — полнофункциональный HTTP-фреймворк (MVC)
• triangle/ws — WebSocket-фреймворк для real-time приложений

Панель и управляющая среда

• Full — шаблон приложения с frontend-набором административной панели. Он помогает начать собственный интерфейс, но не предоставляет готовый административный backend с CRUD, аутентификацией и управлением ролями.
• Maestro — прототип запуска нескольких приложений на Triangle/Localzet Server. Он объявляет отдельные application listeners и monitor-процесс, но не реализует reverse proxy, маршрутизацию host/path, health checks, политику перезапусков или лимиты ресурсов. Пока Maestro нельзя использовать как замену этим системам.
• Metronic — архивная сборка старого поколения; не входит в текущий release train.

Принцип модульности

Triangle Framework построен по принципу модульности:

1. Переиспользование — компоненты предназначены для Composer-подключения и вне готовых приложений; фактическая независимость от Engine различается и должна быть видна в constraints.
2. Интеграция в Triangle — Engine предоставляет общие соглашения, bootstrap и lifecycle, когда компонент его объявляет.
3. Гибкая конфигурация — конфигурационные файлы позволяют настраивать подключённые компоненты.
4. Заменяемость — возможность подмены зависит от интерфейсов и зависимостей конкретного компонента. Например, Router и Middleware сейчас объявляют Engine прямой зависимостью; перед самостоятельной заменой проверяйте контракт пакета.
5. Границы процессов — отдельный процесс может ограничить распространение некоторых ошибок, но сам по себе не обеспечивает лимиты ресурсов, перезапуск или отказоустойчивость. Это требует настройки супервизора и инфраструктуры.

Объявленные package constraints собраны в матрице совместимости. Ограничения Composer не заменяют интеграционные проверки совместно работающих пакетов.

Конфигурационные файлы

Конфигурационные файлы (с return)

Большинство файлов в папке config/ — это конфигурационные файлы, возвращающие массивы настроек:

<?php
// config/app.php
return [
    'debug' => true,
    'name' => 'My App',
];
 
// config/database.php
return [
    'default' => 'mysql',
    'connections' => [...],
];
 
// config/middleware.php
return [
    '' => [
        \App\Middleware\CorsMiddleware::class,
    ],
];
 

Эти файлы загружаются через Triangle\Engine\Config::load() и доступны через функцию config('key').

Исполняемые файлы (без return)

Исключение: config/route.php — это не конфигурационный файл, а выполняемый PHP-код:

<?php
// config/route.php
 
use Triangle\Router;
 
Router::get('/', [Controller::class, 'index']);
Router::post('/api/users', [ApiController::class, 'store']);
 

Этот файл подключается через require_once при инициализации Router и позволяет напрямую вызывать методы регистрации маршрутов.

Жизненный цикл приложения

1. Запуск сервера (Localzet Server)
   ↓
2. Инициализация Engine (Triangle\Engine\App)
   ↓
3. Загрузка конфигурации (Triangle\Engine\Config::loadAll())
   ↓
4. Автозагрузка компонентов (Triangle\Engine\Autoload)
   ↓
5. Bootstrap компонентов (Triangle\Engine\Bootstrap::start())
   ↓
6. Загрузка маршрутов (Router::collect() → require route.php)
   ↓
7. Обработка запросов через middleware
   ↓
8. Выполнение контроллеров или обработчиков
   ↓
9. Генерация ответа

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

HTTP-запросы (triangle/engine-http)

1. Получение HTTP-запроса
2. Поиск статического файла (если включено)
3. Диспетчеризация маршрута через Router
4. Применение middleware (глобальные → маршрутные → контроллерные)
5. Выполнение обработчика маршрута
6. Обработка ответа middleware (в обратном порядке)
7. Отправка HTTP-ответа

Автоматическая маршрутизация

Triangle поддерживает автоматическую маршрутизацию на основе структуры контроллеров:

/app/controller/UserController::index  → GET /user/index
/app/controller/UserController::show   → GET /user/show

Автоматические маршруты можно отключить через аннотацию #[DisableDefaultRoute].

Преимущества архитектуры

• Долгоживущие процессы — Localzet Server управляет асинхронными процессами; производительность относительно PHP-FPM зависит от сценария и должна подтверждаться нагрузочными тестами
• Модульность — используйте только нужные компоненты
• Расширяемость — легко добавлять плагины и компоненты
• Масштабируемость — приложение можно разделять на сервисы и процессы; распределённую координацию и изоляцию нужно проектировать отдельно
• Современный PHP — требование зависит от пакета; приложения Web/WS декларируют PHP ^8.2, отдельные библиотеки поддерживают ^8.1