ModernORMBundle: ModernORM в Symfony — от первого запроса до Profiler и миграций

Подключить ORM к Symfony — значит не только создать EntityManager. Разбираем, как ModernORMBundle связывает запросы, диагностику, изменение схемы и жизненный цикл приложения в один рабочий процесс.

Содержание статьи
  1. 1. Зачем ORM нужен отдельный Symfony bundle
  2. 2. Установка: два пакета и регистрация bundle
  3. 3. Конфигурация, которую удобно читать и проверять
  4. 4. Внедрение EntityManager и DBAL без ручной фабрики
  5. 5. Profiler: увидеть стоимость ORM внутри одного запроса
  6. 6. История SQL: включать осознанно и с ограничениями
  7. 7. Performance Advisor: от числа на экране к следующему действию
  8. 8. Три вида кеша и наблюдение за L2
  9. 9. Миграции: знакомый движок с явной областью владения
  10. 10. Fixtures: воспроизводимые данные для разработки и тестов
  11. 11. Messenger и долгоживущие процессы: границы состояния
  12. 12. OpenTelemetry и Grafana: перейти от запроса к динамике
  13. 13. Как проверить bundle на одном рабочем сценарии
  14. 14. Версии и исходный код

1. Зачем ORM нужен отдельный Symfony bundle

Подключить библиотеку к Composer — только начало. Приложению ещё нужны соединение с базой, EntityManager, кеш metadata, команды проверки mapping, понятная диагностика и правила очистки состояния между задачами. Если собирать всё вручную, команда поддерживает собственный инфраструктурный слой поверх ORM.

ModernORMBundle переносит эту работу в Symfony: регистрирует сервисы, связывает их с контейнером, добавляет панель Profiler и предоставляет интеграции для миграций и fixtures. Разработчик пишет прикладной код с EntityManagerInterface, а настройки подключения и наблюдения находятся в конфигурации приложения.

Сам ModernORM отвечает за mapping, SQL-first запросы, Identity Map, flush и загрузку связей. Bundle отвечает за их использование в Symfony. Подробный разбор ядра — в статье ModernORM: возможности, ограничения и переход с Doctrine.

2. Установка: два пакета и регистрация bundle

Текущий контракт — PHP 8.4+, PostgreSQL, Symfony 7.4 или 8.x и DBAL 4.6. Bundle требует ModernORM ^0.1.0-beta.5. Для beta-версий явно укажите допустимую стабильность обоих пакетов:

composer require 'andreybolonin/modernorm:^0.1.0-beta.5' 'andreybolonin/modernorm-bundle:^0.1.0-beta.5'

В config/bundles.php добавьте запись в возвращаемый массив:

ModernORM\Bundle\ModernORMBundle::class => ['all' => true],

Это не конфигурация нескольких EntityManager: bundle управляет одним основным ORM-соединением PostgreSQL. Doctrine ORM как зависимость ему не нужна. При этом используются самостоятельные компоненты экосистемы Doctrine, включая DBAL и Persistence; дополнительные миграции и fixtures подключаются отдельно.

Для отладочной панели нужны TwigBundle, WebProfilerBundle и стандартные маршруты Symfony Profiler. Коллектор ModernORM регистрируется автоматически, но bundle не заменяет настройку самого Symfony Profiler.

3. Конфигурация, которую удобно читать и проверять

# config/packages/modernorm.yaml
modernorm:
    url: '%env(resolve:DATABASE_URL)%'
    server_version: '17' # Укажите фактическую версию PostgreSQL.
    mapping_paths:
        - '%kernel.project_dir%/src/Entity'
    batch_size: 32
    metadata_cache_pool: cache.system
    query_cache_pool: cache.system
    statistics:
        enabled: '%kernel.debug%'
    profiler:
        enabled: true
        collect_sql: false
        max_events: 200
        max_queries: 200

server_version позволяет не открывать соединение ради определения платформы, но значение должно соответствовать вашей базе. mapping_paths задаёт каталоги PHP-атрибутов. У batch_size значение по умолчанию — 1: размер 32 в примере выбран явно, а не включается у всех приложений автоматически. Атрибут связи может переопределять размер группы.

Кеш планов запросов не является кешем результатов: query_cache_pool не избавляет от выполнения SELECT. Metadata cache, query-plan cache и entity L2 — три разных механизма с разным назначением.

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

Полная инструкция по подключению

4. Внедрение EntityManager и DBAL без ручной фабрики

В прикладном сервисе используйте autowiring. Ниже Product — ваша mapped-сущность, а limit ограничен на уровне входного параметра:

use App\Entity\Product;
use ModernORM\EntityManagerInterface;

final class ProductCatalog
{
    public function __construct(private EntityManagerInterface $em)
    {
    }

    public function latest(int $limit = 20): array
    {
        return $this->em->createQueryBuilder()
            ->fromEntity(Product::class, 'p')
            ->orderBy('p.id', 'DESC')
            ->setMaxResults(max(1, min($limit, 100)))
            ->getQuery()
            ->getResult();
    }
}

Для прямого SQL доступен именованный alias соединения. Это удобно для отчёта или агрегата, которому не нужны managed-сущности:

use Doctrine\DBAL\Connection;

final class ProductReport
{
    public function __construct(private Connection $modernormConnection)
    {
    }

    public function count(): int
    {
        // app_product — явно заданное имя таблицы вашего приложения.
        return (int) $this->modernormConnection->fetchOne(
            'SELECT COUNT(*) FROM app_product',
        );
    }
}

Имя аргумента modernormConnection важно: bundle не перехватывает соединение DoctrineBundle по умолчанию. Есть и ModernORM\Bundle\Registry — реализация контракта Doctrine Persistence для одного менеджера. Именованный alias ManagerRegistry $modernormRegistry позволяет явно выбрать нужный registry.

Эта совместимость не превращает ModernORM в замену любого Doctrine-расширения. Код, ожидающий Doctrine ORM EntityManager, DQL или его внутренние классы, требует адаптации.

5. Profiler: увидеть стоимость ORM внутри одного запроса

Медленная страница не всегда означает медленный SELECT. Время может уходить на создание тысяч объектов, вычисление изменений или множество небольших обращений к справочнику. Общая длительность запроса не объясняет, где именно возникла цена.

Панель ModernORM собирает картину по восьми вкладкам: обзор, запросы, UnitOfWork, гидратация, batch fetching, L2 cache, bulk-операции и контекст PostgreSQL. Toolbar даёт быстрый ориентир: SQL, flush, batch, попадания в кеш и рекомендации Advisor.

Панель ModernORM в Symfony Profiler с показателями запроса и рекомендациями
Реальный интерфейс на демонстрационной нагрузке. Значения на экране не являются обещанием производительности.

Важна семантика показателей. SQL timing не включает чтение всего результата и гидратацию. Flush и batch могут включать время SQL, поэтому складывать их длительности нельзя. Успешно выполненный UPDATE ещё не означает, что транзакция позже была зафиксирована.

Панель различает запланированные операции UnitOfWork и реально выполненные DML, если подключённое ядро передаёт соответствующие метрики. Один INSERT с несколькими строками — один SQL statement и несколько affected rows. Для старых профилей недоступные данные показываются как недоступные, а не подменяются похожими счётчиками.

UnitOfWork: где проходит время flush

Экран разделяет вычисление changesets, запись и commit-фазу. Это помогает отличить стоимость обхода объектов от ожидания базы. План последней записи показан отдельно от фактически выполненного SQL.

Symfony Profiler ModernORM — unitofwork
UnitOfWork: фазы flush и сохранённые события демонстрационного запроса. Нажмите, чтобы открыть в полном размере.

Hydration: сколько объектов создаёт выборка

Входные строки и новые экземпляры сущностей — разные показатели: JOIN может повторять строки, а Identity Map переиспользует объекты. Вкладка показывает активное время гидратации и распределение по гидраторам.

Symfony Profiler ModernORM — hydration
Hydration: строки результата, новые объекты и активное время гидратации. Нажмите, чтобы открыть в полном размере.

6. История SQL: включать осознанно и с ограничениями

Счётчики и текст SQL — разные уровни наблюдения. Текст запросов по умолчанию не собирается. Для разработки можно включить его отдельно:

# config/packages/dev/modernorm.yaml
modernorm:
    profiler:
        collect_sql: true
        max_queries: 200
        max_sql_length: 10000

DBAL middleware сохраняет текст, длительность, метод драйвера и SQLSTATE ошибки в активном профилируемом HTTP-запросе. Bindings и сообщения исключений не сохраняются. Однако литералы, вписанные прямо в SQL, остаются видимыми: чувствительные значения нужно передавать параметрами и учитывать доступ к профилям.

Лимит истории ограничивает сохранённые записи, а не агрегатные счётчики. Повторяющиеся запросы группируются по полному точному SQL-тексту; разные bindings не мешают объединить одинаковый шаблон. Группа из множества повторений помогает найти потенциальный N+1, но сама по себе его не доказывает.

При выключенном collect_sql соответствующий middleware не устанавливается. Это позволяет оставить агрегатную статистику без хранения текста запросов.

Symfony Profiler ModernORM — queries
Queries: сохранённый SQL, длительность, метод драйвера и результат выполнения. Нажмите, чтобы открыть в полном размере.

7. Performance Advisor: от числа на экране к следующему действию

Advisor ищет повторяющийся SQL, медленные выполнения, частые flush, дорогую гидратацию, большой persistence context, одноэлементные batch-группы и низкое повторное использование L2. Рекомендация содержит измеренные признаки и ссылку на нужную вкладку.

Представим список товаров с производителем. Advisor обнаружил повторяющийся SELECT. Следующий шаг — открыть Queries, сопоставить вызовы с загрузкой связи и проверить batching. Если при настроенном размере 32 фактически выбирается по одному элементу, полезнее сначала изучить порядок доступа к объектам, чем ещё увеличивать размер группы.

modernorm:
    profiler:
        advisor:
            enabled: true
            max_findings: 10
            repeated_query_threshold: 5
            slow_query_ms: 10
            hydration_ms: 50
            managed_entities_threshold: 1000
            flush_count_threshold: 5

Это диагностические пороги, а не нормативы для любого проекта. Частый flush иногда нужен по бизнес-смыслу. Большой UnitOfWork может быть ожидаемым для импорта. Совет должен привести к проверке гипотезы и повторному измерению того же сценария.

Advisor не выполняет EXPLAIN, не доказывает наличие индекса и не вычисляет гарантированное время, которое можно «вернуть» оптимизацией. Рекомендации ранжируются по важности и измеренной длительности; пересекающиеся времена нельзя суммировать.

Панели, ограничения измерений и пороги Advisor

Batch Fetching: проверить фактический размер групп

Symfony Profiler ModernORM — batch
Batch Fetching: группы ManyToOne, OneToMany и ManyToMany; настроенный максимум и фактически выбранные элементы. Нажмите, чтобы открыть в полном размере.

Bulk Operations: видеть результат массовой записи

Здесь рядом показаны тип операции, политика persistence context, число затронутых строк и известный исход в базе. Это помогает разбирать импорт отдельно от обычного flush.

Symfony Profiler ModernORM — bulk
Bulk Operations: INSERT, UPDATE и DELETE на демонстрационных данных с политикой CLEAR. Нажмите, чтобы открыть в полном размере.

8. Три вида кеша и наблюдение за L2

Entity L2 подключается через настроенный приложением общий PSR-6 pool. Например, если cache.modernorm_l2 уже объявлен в Symfony Cache:

modernorm:
    l2_cache:
        pool: cache.modernorm_l2
        namespace: catalog_app

Bundle подключает pool, но правила кеширования сущностей определяет ядро и их mapping. Нельзя ожидать, что включение pool автоматически закеширует произвольные графы связей или результаты SQL.

В Profiler доступны hits, misses, puts и invalidations. Они помогают проверить, действительно ли справочник повторно используется. Низкий hit rate нужно оценивать вместе с числом обращений и характером нагрузки, а не по одному первому холодному запросу.

Метрики L2 не заменяют наблюдение за самим Redis: давление памяти, вытеснения и состояние сервера требуют отдельных инструментов. Счётчики кеша также могут работать независимо от включения основной Statistics.

Symfony Profiler ModernORM — cache
L2 Cache: hits, misses, puts, invalidations и hit rate в пределах одного запроса. Нажмите, чтобы открыть в полном размере.

PostgreSQL: контекст подключения и границы диагностики

Symfony Profiler ModernORM — postgresql
PostgreSQL: сохранённый контекст запроса. Планы EXPLAIN, буферы и блокировки в этом профиле не собирались. Нажмите, чтобы открыть в полном размере.

9. Миграции: знакомый движок с явной областью владения

Для версионирования схемы bundle интегрирует doctrine/migrations через DBAL. DoctrineMigrationsBundle и Doctrine ORM для этого не требуются.

composer require 'doctrine/migrations:^3.9'
modernorm:
    managed_schema_filter: '~^modernorm_~'
    migrations:
        enabled: true
        paths:
            ModernORMMigrations: '%kernel.project_dir%/modernorm-migrations'
        table_name: modernorm_migration_versions
        all_or_nothing: true

Префикс в примере — договорённость о владении таблицами, не автоматическое переименование. Явно назовите mapped-таблицы, join tables и sequences в выбранной области. До генерации создайте каталог modernorm-migrations.

bin/console modernorm:migrations:sync-metadata-storage
bin/console modernorm:migrations:diff
bin/console modernorm:migrations:migrate --dry-run
# После проверки SQL примените миграцию:
bin/console modernorm:migrations:migrate
bin/console modernorm:migrations:diff --allow-empty-diff

managed_schema_filter обязателен для этой интеграции. Diff рассматривает принадлежащие приложению таблицы и sequences, исключает историю миграций и отвергает mapping за пределами области. Это особенно полезно в общей базе: сгенерированный diff не должен предлагать удалить чужие таблицы.

Фильтр не ограничивает произвольный SQL, написанный вручную в доверенной миграции. Сгенерированные up/down всё равно нужно читать. CREATE INDEX CONCURRENTLY требует отдельного нетранзакционного режима; транзакционный DDL не обещает отсутствие блокировок.

Миграции используют отдельные соединения. Их SQL не входит в статистику исходного ORM-соединения. После изменения схемы остаются задачи деплоя: кеш metadata, планы запросов и перезапуск воркеров.

Для FullTextIndex есть дополнительная версия-зависимость: генерация FTS-объектов требует ядра с SchemaTool::getSchemaMigrationSql() и PostgreSQL 17+. Минимально допустимая версия core сама по себе не гарантирует этот путь; проверяйте документацию совместимой версии. Некоторые удаления и изменения FTS требуют явной миграции.

Миграции, FTS и границы schema filter

10. Fixtures: воспроизводимые данные для разработки и тестов

composer require --dev 'doctrine/data-fixtures:^2.2'

Включите fixtures только в окружениях, где установлен дополнительный пакет. Ниже конфигурация для разработки; такой же блок можно добавить в test. Фильтр должен соответствовать именам ваших таблиц.

# config/packages/dev/modernorm.yaml
modernorm:
    managed_schema_filter: '~^modernorm_~'
    fixtures:
        enabled: true
use Doctrine\Persistence\ObjectManager;
use ModernORM\Bundle\Fixtures\Fixture;

final class DemoFixtures extends Fixture
{
    public function load(ObjectManager $manager): void
    {
        // Product и его конструктор определяются вашим приложением.
        $product = new \App\Entity\Product('DEMO-001', 'Тестовый товар');
        $manager->persist($product);
    }
}

При обычной Symfony autoconfiguration наследник Fixture получает тег modernorm.fixture. Runner автоматически делает flush после каждой fixture и очищает контекст. Для зависимостей есть references, интерфейсы порядка и группы. Существующие Doctrine fixtures автоматически не подхватываются.

# Добавить данные без предварительной очистки:
bin/console modernorm:fixtures:load --append
# Выбрать fixture по короткому имени класса:
bin/console modernorm:fixtures:load --append --group=DemoFixtures

Без --append команда очищает все mapped-таблицы ModernORM, включая таблицы связей, с RESTART IDENTITY. Выбор группы ограничивает исполняемые fixtures, но не область предварительной очистки. CASCADE не используется: внешняя FK-зависимость должна остановить очистку, а не затронуть чужое приложение.

Загрузка и очистка выполняются в общей транзакции с отдельным EntityManager и выключенным L2. HTTP-вызовы, отправку почты и другие внешние эффекты внутрь fixtures помещать не стоит: откат PostgreSQL их не отменит. Для начальных production-справочников обычно лучше версионированная миграция данных.

Группы, references и транзакционные гарантии

11. Messenger и долгоживущие процессы: границы состояния

В HTTP-приложении легко привыкнуть, что завершение процесса уничтожит объекты. Воркер обрабатывает много сообщений в одном процессе: старые managed-сущности, незавершённая транзакция или накопленная история могут повлиять на следующую задачу.

Bundle регистрирует сброс Statistics, кеш-счётчиков, SQL history и истории операций через kernel.reset. Фабрика EntityManager очищает и сбрасывает lazy proxy, закрывает соединение и отбрасывает незавершённые транзакции. Внедрённая ссылка на менеджер остаётся пригодной после сброса закрытого экземпляра.

Стандартный reset Symfony/Messenger должен оставаться включённым. В собственном бесконечном цикле границу сброса между заданиями нужно организовать самостоятельно. Reset не заменяет осмысленные границы транзакций и flush внутри одной большой задачи.

Основной HTTP-запрос начинает новый scope измерений; subrequest не обнуляет счётчики родительского запроса. Сохранённый профиль содержит снимок значений и остаётся читаемым после очистки сервисов.

12. OpenTelemetry и Grafana: перейти от запроса к динамике

Profiler отвечает на вопрос «почему медленно выполнился этот запрос». Эксплуатации нужны другие ответы: растёт ли время flush, изменился ли hit rate, сколько строк проходит через bulk и что происходит у воркеров.

Для этого есть необязательные адаптеры OperationMetrics, CacheMetrics и FlushMetrics. Приложение предоставляет OpenTelemetry MeterProvider; зависимости SDK и exporter устанавливаются отдельно. Наличие bundle не включает отправку метрик во внешнюю систему автоматически.

ModernORM → OpenTelemetry PHP SDK → OTLP/HTTP → Collector → VictoriaMetrics → Grafana

OperationMetrics подписывается на операции через modernorm.statistics_observer. CacheMetrics подключается отдельно как modernorm.cache_logger и использует ограниченные aliases сущностей вместо бесконтрольного числа label values. FlushMetrics помогает выгружать накопленные данные на границах HTTP, console и обработки Messenger.

В репозитории есть запускаемый пример со стеком Collector → VictoriaMetrics → Grafana и четырнадцатью панелями. Это локальный прототип с документированной best-effort доставкой, а не готовая production-платформа мониторинга. Провайдер метрик сохраняется между заданиями, даже когда ORM-контекст сбрасывается.

Для длинной задачи может потребоваться промежуточный flush SDK: фоновый таймер сам по себе не появляется. Активные tracing spans этот адаптер не создаёт; метрики и распределённые трассировки — разные уровни инструментария.

Метрики, lifecycle и запускаемый пример

Как выглядит дашборд Grafana

На экране локального прототипа видны частота SQL-операций, p95 времени SQL, потоки bulk-записи, средний размер batch-групп и скорость создания объектов. Здесь уже можно сравнивать поведение во времени, а не только разбирать один HTTP-запрос.

Grafana ModernORM Operations с метриками через OpenTelemetry
Снимок локального OpenTelemetry-прототипа из репозитория ModernORM. Демонстрационная нагрузка; версия дашборда на снимке может отличаться от текущего provisioning. Нажмите, чтобы открыть в полном размере.

13. Как проверить bundle на одном рабочем сценарии

  1. Зафиксируйте среду. PHP, PostgreSQL, Symfony и версии обоих пакетов в composer.lock.
  2. Подключите небольшую модель. Один справочник и одну связь; проверьте mapping и сгенерированный SQL.
  3. Откройте реальный экран. Посмотрите SQL, число созданных объектов, batch и UnitOfWork в Profiler.
  4. Проверьте одну рекомендацию. Измените загрузку данных и повторите тот же запрос с сопоставимым состоянием кеша.
  5. Проведите цикл схемы. Diff, чтение SQL, применение в тестовой базе и повторный пустой diff.
  6. Проверьте обработчик сообщений. Несколько последовательных задач, ошибка посередине и чистый контекст следующего задания.
bin/console modernorm:mapping:info
bin/console modernorm:schema:validate
bin/console modernorm:schema:create --dump-sql

Для нового Symfony-проекта на PostgreSQL bundle даёт готовые точки подключения: сервисы, конфигурацию, команды, диагностику и сброс состояния. Команде проще сосредоточиться на модели и запросах, чем создавать эту связку заново.

Для существующего проекта переход стоит начать с отдельного сценария и проверки совместимости. Именованные aliases помогают явно обращаться к ModernORM, но не обеспечивают автоматическую общую транзакцию двух менеджеров, перенос Doctrine mapping или совместимость сторонних bundles.

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

14. Версии и исходный код

Материал подготовлен 17 ноября 2026 года по текущему коду и документации локального репозитория ModernORMBundle. Установка использует диапазон beta.5; отдельные панели и расширенные события зависят от выбранной версии ядра. Ссылки на main отражают развивающуюся реализацию: перед использованием сверяйте их с установленным тегом и composer.lock.

Новые команды beta.6 разобраны отдельно: переезд с MySQL на PostgreSQL: mapping, проверка данных и репетиция загрузки.

ModernERP Integration Monitor

Узнавайте о сбоях обменов раньше, чем о них сообщат сотрудники

Ошибки, задержки и история обменов между 1С, CRM, WMS и API — в одном сервисе. Контролируйте критичные интеграции с Integration Monitor.

Посмотреть Integration Monitor ↗

Работает на наших серверах · До 15 интеграций · 90 дней истории