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

Важна семантика показателей. SQL timing не включает чтение всего результата и гидратацию. Flush и batch могут включать время SQL, поэтому складывать их длительности нельзя. Успешно выполненный UPDATE ещё не означает, что транзакция позже была зафиксирована.
Панель различает запланированные операции UnitOfWork и реально выполненные DML, если подключённое ядро передаёт соответствующие метрики. Один INSERT с несколькими строками — один SQL statement и несколько affected rows. Для старых профилей недоступные данные показываются как недоступные, а не подменяются похожими счётчиками.
UnitOfWork: где проходит время flush
Экран разделяет вычисление changesets, запись и commit-фазу. Это помогает отличить стоимость обхода объектов от ожидания базы. План последней записи показан отдельно от фактически выполненного SQL.

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

6. История SQL: включать осознанно и с ограничениями
Счётчики и текст SQL — разные уровни наблюдения. Текст запросов по умолчанию не собирается. Для разработки можно включить его отдельно:
# config/packages/dev/modernorm.yaml
modernorm:
profiler:
collect_sql: true
max_queries: 200
max_sql_length: 10000DBAL middleware сохраняет текст, длительность, метод драйвера и SQLSTATE ошибки в активном профилируемом HTTP-запросе. Bindings и сообщения исключений не сохраняются. Однако литералы, вписанные прямо в SQL, остаются видимыми: чувствительные значения нужно передавать параметрами и учитывать доступ к профилям.
Лимит истории ограничивает сохранённые записи, а не агрегатные счётчики. Повторяющиеся запросы группируются по полному точному SQL-тексту; разные bindings не мешают объединить одинаковый шаблон. Группа из множества повторений помогает найти потенциальный N+1, но сама по себе его не доказывает.
При выключенном collect_sql соответствующий middleware не устанавливается. Это позволяет оставить агрегатную статистику без хранения текста запросов.

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, не доказывает наличие индекса и не вычисляет гарантированное время, которое можно «вернуть» оптимизацией. Рекомендации ранжируются по важности и измеренной длительности; пересекающиеся времена нельзя суммировать.
Панели, ограничения измерений и пороги AdvisorBatch Fetching: проверить фактический размер групп

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

8. Три вида кеша и наблюдение за L2
Entity L2 подключается через настроенный приложением общий PSR-6 pool. Например, если cache.modernorm_l2 уже объявлен в Symfony Cache:
modernorm:
l2_cache:
pool: cache.modernorm_l2
namespace: catalog_appBundle подключает pool, но правила кеширования сущностей определяет ядро и их mapping. Нельзя ожидать, что включение pool автоматически закеширует произвольные графы связей или результаты SQL.
В Profiler доступны hits, misses, puts и invalidations. Они помогают проверить, действительно ли справочник повторно используется. Низкий hit rate нужно оценивать вместе с числом обращений и характером нагрузки, а не по одному первому холодному запросу.
Метрики L2 не заменяют наблюдение за самим Redis: давление памяти, вытеснения и состояние сервера требуют отдельных инструментов. Счётчики кеша также могут работать независимо от включения основной Statistics.

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

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-diffmanaged_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 filter10. Fixtures: воспроизводимые данные для разработки и тестов
composer require --dev 'doctrine/data-fixtures:^2.2'Включите fixtures только в окружениях, где установлен дополнительный пакет. Ниже конфигурация для разработки; такой же блок можно добавить в test. Фильтр должен соответствовать именам ваших таблиц.
# config/packages/dev/modernorm.yaml
modernorm:
managed_schema_filter: '~^modernorm_~'
fixtures:
enabled: trueuse 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 → GrafanaOperationMetrics подписывается на операции через 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-запрос.

13. Как проверить bundle на одном рабочем сценарии
- Зафиксируйте среду. PHP, PostgreSQL, Symfony и версии обоих пакетов в composer.lock.
- Подключите небольшую модель. Один справочник и одну связь; проверьте mapping и сгенерированный SQL.
- Откройте реальный экран. Посмотрите SQL, число созданных объектов, batch и UnitOfWork в Profiler.
- Проверьте одну рекомендацию. Измените загрузку данных и повторите тот же запрос с сопоставимым состоянием кеша.
- Проведите цикл схемы. Diff, чтение SQL, применение в тестовой базе и повторный пустой diff.
- Проверьте обработчик сообщений. Несколько последовательных задач, ошибка посередине и чистый контекст следующего задания.
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.
- Исходный код ModernORMBundle
- Установка и сервисы
- Profiler и Performance Advisor
- Миграции
- Fixtures
- Наблюдение и воркеры
Новые команды beta.6 разобраны отдельно: переезд с MySQL на PostgreSQL: mapping, проверка данных и репетиция загрузки.