romanfedorskij / table-registry
PHP-first table registry core for explicit column contracts, PostgreSQL query compilation, row projection and XLSX export.
Requires
- php: ^8.2
- ext-json: *
- ext-mbstring: *
- openspout/openspout: ^4.28 || ^5.0
- psr/container: ^1.1 || ^2.0
Requires (Dev)
- phpstan/phpstan: 2.2.16
- testo/testo: 0.10.54
Suggests
- llm/skills: Synchronizes the bundled TableRegistry AI-agent skills into the consumer project.
Provides
None
Conflicts
None
Replaces
None
README
TableRegistry — framework-agnostic PHP-библиотека для описания табличных и самостоятельных read-моделей,
компиляции PostgreSQL-запросов, нормализации строк под frontend-контракт и выгрузки XLSX.
Библиотека полезна, когда backend должен явно зафиксировать колонки, фильтры, поиск, сортировку, пагинацию и форму ответа, но выполнение SQL, HTTP, авторизация и бизнес-действия должны оставаться в приложении.
Русский — основной язык документации; English edition поддерживается рядом. Имена public API, команды и исполняемые
примеры общие для всех потребителей. Документация ветки main описывает линию v0.7.
Что Даёт Библиотека
TableRegistryDefinitionдля таблиц с обязательным primary key и сериализуемым frontend-контрактом;- Attribute compiler для описания static relations, JOIN aggregates и finite variants над обычными PHP-классами;
SelectDefinitionдля options, списков и небольших read-моделей без table metadata;- строгую валидацию canonical query input;
- PostgreSQL-компиляцию rows/count/export SQL и параметров без выполнения запроса;
- projection raw rows в стабильные table и option payload;
- runtime constraints для actor-, tenant- и scope-зависимых условий;
- policy выбора экспортируемых колонок и запись XLSX через OpenSpout.
Библиотека не открывает соединение с БД, не читает HTTP request, не авторизует route, не определяет CRUD-команды и не управляет layout или действиями frontend. Эти обязанности принадлежат host application.
Требования И Установка
- PHP 8.2 или новее;
ext-jsonиext-mbstring;- PostgreSQL для SQL, который компилирует библиотека;
psr/container^1.1 || ^2.0;openspout/openspout^4.28 || ^5.0для XLSX.
Установите minor line из Packagist:
composer require romanfedorskij/table-registry:^0.7
Обновление существующего consumer-а с v0.6.x описано в
docs/migration-v0.6-to-v0.7.md.
Быстрый Старт
Создайте quick-start.php рядом с vendor/:
<?php declare(strict_types=1); use Wolfcharaa\TableRegistry\Column\ColumnRegistryDefinition; use Wolfcharaa\TableRegistry\Column\PrimaryKeyColumnRegistryDefinition; use Wolfcharaa\TableRegistry\Definition\TableRegistryDefinition; use Wolfcharaa\TableRegistry\Source\RegistrySourceDefinition; require __DIR__ . '/vendor/autoload.php'; $definition = new TableRegistryDefinition( registryKey: 'users', title: 'Users', source: RegistrySourceDefinition::from('public.users'), columns: [ new PrimaryKeyColumnRegistryDefinition('id'), new ColumnRegistryDefinition('email', 'Email'), ] ); $contract = $definition->jsonSerialize(); echo sprintf( "registry=%s primary=%s columns=%d\n", $contract['registryKey'], $contract['primaryKey'], count($contract['columns']) );
Запустите:
php quick-start.php
Ожидаемый результат:
registry=users primary=id columns=2
Этот результат подтверждает первый публичный контракт библиотеки без БД и web-фреймворка. Поддерживаемый исходник
примера находится в docs/examples/00-quick-start.php.
Для новых static table definitions в v0.7 рекомендуются Attributes. Первый запускаемый вариант находится в
docs/examples/08-attribute-table.php, подробный путь — в
docs/attributes.md. Object API из quick start остаётся поддерживаемым для dynamic definitions.
Как Устроена Интеграция
HTTP/CLI adapter → validate input → compile SQL + params → application executes SQL
→ project raw rows → serialize response / export XLSX
TableRegistryDefinition нужен, когда frontend получает описание таблицы и rows payload. SelectDefinition подходит
для options и других read-моделей, которым не нужны primary key и table metadata. В обоих вариантах приложение
владеет transport parsing, DB adapter, authorization и response envelope.
Документация
Начните с карты документации или сразу выберите задачу:
- построить table read-model от definition до response;
- описать relation/aggregate через Attributes;
- сверить точную Attribute semantics;
- подключить provider, resolver или другой extension port;
- построить standalone select или typed option list;
- запустить исполняемые примеры;
- проверить поддерживаемые public symbols;
- обновиться с
v0.5.xнаv0.6.0; - перейти с
v0.6.xна additivev0.7.0; - понять стратегию совместимости
v0.6.x.
Скиллы Для AI-Агентов
Пакет поставляет два скилла:
table-registry-install— установка, обновление и проверка Composer-пакета;table-registry-use— создание definition и интеграция validation, compilation, projection и export.
С Composer-плагином llm/skills их можно синхронизировать в проект:
composer require --dev llm/skills composer skills:init --quick composer skills:update romanfedorskij/table-registry
Composer запросит отдельное разрешение на запуск плагина. Без плагина скопируйте нужный каталог из
vendor/romanfedorskij/table-registry/skills/ в configured skills root агента; не редактируйте копию внутри
vendor/.
Совместимость
Поддерживаемая поверхность v0.7.x перечислена в docs/public-api.md и проверяется signature
snapshot-ом. Наличие класса под src/ само по себе не означает compatibility promise; consumer code должен зависеть
только от символов с @api из allowlist.
Разработка
composer install composer check
composer check валидирует Composer metadata, запускает unit/contract/characterization suites, PHPStan и все
примеры из docs/examples/.