delvark / yii2-db-toolkit
Yii2 DB toolkit
Package info
gitverse.ru/delvark/yii2-db-toolkit
Type:yii2-extension
pkg:composer/delvark/yii2-db-toolkit
Requires
- php: >=8.5
- yiisoft/yii2: ^2.0.55
Requires (Dev)
- delvark/yii2-testkit: ^0.3.1
- phpunit/phpunit: ^10.5
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is not auto-updated.
Last update: 2026-11-16 22:01:17 UTC
README
Yii2 DB toolkit — набор инфраструктурных утилит для работы с БД на уровне миграций и DDL.
Пакет даёт синтаксический и архитектурный сахар для создания таблиц, индексов и внешних ключей, а также небольшие вспомогательные инструменты для унификации миграций между PostgreSQL и MySQL. Использование позволяет просто заводить новые таблицы, получая единую стилистику, на которую можно опираться при дальнейшем проектировании.
What's included
CreateTable— базовый класс миграции для создания таблиц:- автоматические дефолтные колонки:
id,created_at,updated_at,is_active(можно отключать черезfalse) - декларативное описание индексов и внешних ключей
- автоматическое создание индекса под каждый внешний ключ
onDelete/onUpdateдля FK (с валидацией значений)- авто-создание FK-колонки при отсутствии в
getColumns()
- автоматические дефолтные колонки:
ForeignKeyDTO— DTO для применения FK внутриCreateTableBaseDictionaryCreateTableMigration— базовая миграция “таблица-справочник”:- колонки:
code,name,description - unique индекс на
code
- колонки:
SchemaIntrospector(read-only) — библиотечная интроспекция схемы БД:- DTO:
SchemaDTO,TableDTO,ColumnDTO,IndexDTO,ForeignKeyDTO - сбор таблиц/PK/columns/indexes/foreignKeys/comments
- поддержка SQLite (
PRAGMA) и общая ветка для остальных драйверов
- DTO:
Функции-утилиты:
- генерация имён idx/fk
- нормализация конфигов
- дефолтные поля
- (опционально) провайдеры/разделение логики по драйверу (PG/MySQL)
What's NOT included
- сущности / ActiveRecord
- meta-layer BES
Requirements
- PHP >= 8.5
- yiisoft/yii2 ^2.0.55
Installation
Добавьте GitVerse и Asset Packagist в корневой проект Composer.
composer config repositories.asset-packagist composer https://asset-packagist.org
composer config repositories.yii2-db-toolkit vcs https://gitverse.ru/delvark/yii2-db-toolkit.git
composer require delvark/yii2-db-toolkit
PHP-пространство имён пакета — illusiard\dbtoolkit\.
Quick start
CreateTable
Создайте миграцию, унаследовавшись от CreateTable:
use illusiard\dbtoolkit\components\CreateTable;
final class m240101_000001_create_post_table extends CreateTable
{
public function getTableName(): string
{
return 'post';
}
public function getColumns(): array
{
return [
'title' => $this->string(255)->notNull()->comment('Заголовок'),
'body' => $this->text()->null()->comment('Текст'),
];
}
public function getIndexes(): array
{
return [
['title'],
];
}
public function getForeignKeys(): array
{
return [
'user_id' => ['user', 'id', 'onDelete' => 'RESTRICT', 'onUpdate' => 'CASCADE'],
];
}
}
Disabling default columns
Любую дефолтную колонку можно отключить, вернув false по соответствующему ключу:
public function getColumns(): array
{
return [
'id' => false,
'created_at' => false,
'updated_at' => false,
'is_active' => false,
'code' => $this->string(64)->notNull()->comment('Код'),
];
}
BaseDictionaryCreateTableMigration
Отдельно выделен класс для создания таблиц-словарей.
use illusiard\dbtoolkit\components\BaseDictionaryCreateTableMigration;
final class m240101_000002_create_country_dict extends BaseDictionaryCreateTableMigration
{
public function getTableName(): string
{
return 'dict_country';
}
}
SchemaIntrospector (read-only)
Интроспекция работает с любым yii\db\Connection:
use illusiard\dbtoolkit\schema\SchemaIntrospector;
$introspector = new SchemaIntrospector($db);
$schema = $introspector->introspectSchema();
$table = $introspector->introspectTable('post');
Формат данных для endpoint-слоя:
SchemaDTO::toArray()->{tables:[...], driver, serverVersion?}TableDTO::toDetailsArray()->table,primaryKey, optionalprimaryKeyName,columns,indexes,foreignKeys
Schema tooling
Для схемного синка доступны четыре шага:
SchemaIntrospector:Connection -> SchemaDTO(текущая схема)SchemaParser:array -> SchemaDTO(желаемая схема)SchemaDiffService:current + desired -> SchemaDiffResult(actions в безопасном порядке)MigrationGeneratorService:SchemaDiffResult -> MigrationCodeResult(php-код миграции)
Минимальный пример desired schema:
$desired = [
'tables' => [
[
'name' => 'device',
'primaryKey' => ['id'],
'columns' => [
['name' => 'id', 'type' => 'uuid', 'allowNull' => false],
['name' => 'status', 'type' => 'string(32)', 'defaultValue' => 'draft'],
],
'indexes' => [
['columns' => ['status'], 'unique' => false],
],
'foreignKeys' => [
[
'columns' => 'tenant_id,author_id',
'refTable' => 'author',
'refColumns' => ['tenant_id', 'id'],
'onDelete' => 'CASCADE',
'onUpdate' => 'NO ACTION',
],
],
],
],
];
primaryKey не зависит от типа колонки: schema diff создаёт и удаляет PK constraint отдельными actions.
Для PostgreSQL можно использовать native uuid; для MySQL/MariaDB — выбранное приложением строковое или бинарное представление, например char(36). Составные PK поддерживаются тем же массивом primaryKey.
Ошибки endpoint-слоя (например в BES) остаются на стороне контроллера:
- несуществующая таблица:
404 {error:{type:"not_found",table:"..."}} - невалидное имя таблицы:
400 {error:{type:"bad_request",...}}
Tests
Есть unit-тесты (SQLite in-memory) и интеграционные тесты (реальные БД в Docker).
Launching the database
docker compose up -d
Environment variables
Пример .env (используется тестами):
DB_DRIVER=pgsqlилиDB_DRIVER=mysql- PostgreSQL:
DB_PG_HOST,DB_PG_PORT,DB_PG_NAME,DB_PG_USER,DB_PG_PASS - MySQL:
DB_MY_HOST,DB_MY_PORT,DB_MY_NAME,DB_MY_USER,DB_MY_PASS
Running tests
Unit (SQLite in-memory):
vendor/bin/phpunit tests/Unit
PostgreSQL:
export $(cat .env | xargs)
DB_DRIVER=pgsql vendor/bin/phpunit
MySQL:
export $(cat .env | xargs)
DB_DRIVER=mysql vendor/bin/phpunit
LICENCE
BSD-3-Clause