Search by

romanfedorskij / table-registry

wolfcharaa

PHP-first table registry core for explicit column contracts, PostgreSQL query compilation, row projection and XLSX export.

Package info

github.com/wolfcharaa/table-registry

pkg:composer/romanfedorskij/table-registry

Statistics

Installs: 164

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v0.7.1 2026-11-11 07:15 UTC

This package is auto-updated.

Last update: 2026-11-11 07:16:57 UTC


README

English

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.

Документация

Начните с карты документации или сразу выберите задачу:

Скиллы Для 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/.

Лицензия

MIT