PHPackages                             illusiard/yii2-base-entity-system - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. illusiard/yii2-base-entity-system

ActiveYii2-extension[Utility & Helpers](/categories/utility)

illusiard/yii2-base-entity-system
=================================

Base Entity System for Yii2 (meta layer, bulk events, universal API)

v1.1.0(2d ago)00BSD-3-ClausePHPPHP >=8.5

Since Apr 6Pushed 2d ago1 watchersCompare

[ Source](https://github.com/Illusiard/yii2-base-entity-system)[ Packagist](https://packagist.org/packages/illusiard/yii2-base-entity-system)[ RSS](/packages/illusiard-yii2-base-entity-system/feed)WikiDiscussions master Synced yesterday

READMEChangelogDependencies (8)Versions (6)Used By (0)

yii2-base-entity-system
=======================

[](#yii2-base-entity-system)

`illusiard/yii2-base-entity-system` (BES) - meta-driven CRUDL/search/schema слой для Yii2 с reference SPA и локальным dev host для проверки живого API.

Состав Репозитория
------------------

[](#состав-репозитория)

- `src/` - основной backend package BES: Yii2 module, bootstrap, registry, entity runtime, HTTP controllers, search, schema tooling, ACL integration, DTO и event facade.
- `tests/` - backend unit/integration tests для package contract.
- `dev/host/` - локальное Yii2-приложение на `yii2-testkit`, которое поднимает BES API на SQLite/FileCache для ручной проверки, live integration и browser E2E.
- `view/` - reference frontend SPA для BES. Поддерживает mock provider и live API provider.
- `protocol/` - protocol snapshots, mock payloads и `meta-state.json` для ревью meta/UI состояния.

Ключевые backend-слои:

- `Module` - конфигурация BES в Yii2 application.
- `Bootstrap` - подключает модуль, строит runtime и регистрирует routes.
- `BaseEntitySystem` - центральный runtime object: DB/cache, registry, ACL, formatter, `EventHub`, `urlPrefix`.
- `BaseEntitySystemBuilder` - сборка BES runtime из module config.
- `EntityRegistry` - регистрация entity classes, meta providers и relation introspection.
- `EntityController` - CRUDL HTTP surface.
- `EntityMetaController` - entity index, meta и ACL/actions manifest.
- `SchemaController` - schema introspection и controlled schema write tooling.
- `BaseActiveRecord` и `BaseActiveRecordQuery` - model/query foundation, включая soft delete.
- `SearchEngine` - list/search pipeline: filters, sort, view presets, pagination, deleted filter.
- `ACL` - integration с `yii2-entity-acl`, compact operation masks и relation ACL.
- `DTO` - typed meta/UI contract: `EntityMeta`, `EntityUi`, `FieldMeta`, `RelationMeta`, `RelationViaMeta`, `ViewPreset` и related DTO.

Backend API
-----------

[](#backend-api)

Dev host по умолчанию использует prefix:

```
http://127.0.0.1:8081/api/v1

```

### Entity Endpoints

[](#entity-endpoints)

```
GET  /entity
GET  /{entity}/meta
GET  /{entity}/actions
GET  /{entity}/actions?id={id}

GET  /{entity}/list
GET  /{entity}/view?id={id}
POST /{entity}/create
POST /{entity}/update?id={id}
POST /{entity}/delete?id={id}
POST /{entity}/restore?id={id}
POST /{entity}/permanentDelete?id={id}
POST /{entity}/permanent-delete?id={id}

```

`delete` использует model-level semantics: для моделей с activity field `is_active` выполняется soft delete, для моделей без activity field остается hard delete. `restore` восстанавливает soft-deleted запись. `permanentDelete` и alias `permanent-delete` удаляют запись физически.

### List/Search Query

[](#listsearch-query)

`GET /{entity}/list` поддерживает:

- `page` - номер страницы.
- `pageSize` - размер страницы.
- `sort` - поле сортировки, `-field` для descending.
- `view` - имя `ViewPreset`.
- `filter[field]=value` - field filters.
- `deleted=0` - только активные записи.
- `deleted=1` - только soft-deleted записи.
- `deleted=-1` - все записи.

По умолчанию soft-deleted записи скрыты, если у модели есть activity field. Для сущностей без activity field параметр `deleted` не навязывает искусственный фильтр.

### Body И Headers

[](#body-и-headers)

`create` и `update` принимают JSON body с полями модели:

```
{
  "title": "Runtime Notes",
  "author_id": 1,
  "is_active": true
}
```

Для JSON requests используйте `Content-Type: application/json`. Dev host не требует отдельного auth header и работает с permissive ACL; в production-приложении authentication/authorization остаются ответственностью host app и ACL policy.

Пагинация list response передается через headers:

```
X-Pagination-Total-Count
X-Pagination-Page-Count
X-Pagination-Current-Page
X-Pagination-Per-Page

```

Для browser clients dev host также выставляет CORS headers и expose headers для pagination.

### Wire Format

[](#wire-format)

Успешные ответы intentionally small:

```
{"items": []}
```

```
{"item": {}}
```

```
{"success": true}
```

`actions` возвращает compact ACL manifest:

```
{
  "entityAcl": 127,
  "recordAcl": 127,
  "relationsAcl": {
    "author": {
      "entityAcl": 127,
      "recordAcl": null
    }
  }
}
```

Formatted entity rows/items включают business fields, `refs` и `acl`. `refs` используются frontend runtime для relation labels:

```
{
  "author_id": {
    "entity": "author",
    "id": 1,
    "title": "Dana Writer"
  },
  "id": {
    "entity": "tag",
    "title": "Tags",
    "count": 2
  }
}
```

`acl` содержит compact bit mask операций:

OperationBit`list`1`read`2`create`4`update`8`delete`16`restore`32`permanentDelete`64Dev host permissive ACL обычно возвращает `127` для полной маски.

### Error Format

[](#error-format)

Ошибки нормализуются в envelope:

```
{
  "error": {
    "type": "not_found",
    "message": "Record not found",
    "details": {}
  }
}
```

Типичные типы:

- `bad_request` - некорректный query/body.
- `forbidden` - ACL запретил операцию.
- `not_found` - сущность или запись не найдена.
- `conflict` - generic HTTP 409 conflict.
- `validation` - ошибки валидации модели, обычно HTTP 422.
- `integrity` - DB/reference integrity conflict, обычно HTTP 409.
- `internal_error` - непредвиденная ошибка, generic message для клиента.

Meta/UI Contract
----------------

[](#metaui-contract)

BES использует typed DTO для meta и UI contract:

- `EntityMeta` - fields, relations, operations, UI и views.
- `EntityUi` - `listFields`, `viewFields`, `formFields`, `filterFields`, `readOnlyFields`, `hiddenFields`, `hiddenRelations`, `sortFields`, `titleField`, `fieldUi`, `relations`.
- `FieldMeta` - field type, label, required/writable/readable flags.
- `RelationMeta` - `link`, `targetEntity`, `kind`, optional via metadata.
- `RelationViaMeta` - `type`, `table`, `name`, `link`, `targetEntity`.
- `ViewPreset` - named list preset: fields, filter, sort, page size and title field.

Meta, ActiveRecord model, DB schema и relation getters должны быть согласованы. Нельзя объявлять writable поле, которое модель не принимает через `load()`, или relation в meta без рабочего AR relation getter.

Текущий snapshot всех зарегистрированных meta/UI структур хранится в:

```
protocol/meta-state.json

```

Его можно обновить через dev host helper:

```
/usr/bin/php8.5 dev/host/bin/export-meta-state.php
```

Snapshot read-only: он не генерирует и не меняет runtime meta.

Soft Delete
-----------

[](#soft-delete)

Foundation-level semantics:

- Activity field на текущем этапе определяется конвенцией `is_active`.
- `BaseActiveRecord::find()` возвращает `BaseActiveRecordQuery`.
- Query API: `deleted(0)`, `deleted(1)`, `deleted(-1)`.
- `find()` и list/search по умолчанию скрывают soft-deleted записи.
- `delete()` делает soft delete для моделей с activity field.
- `restore()` устанавливает activity field обратно в active.
- `forceDelete()` и API `permanentDelete` удаляют физически.
- Для моделей без activity field `delete()` остается hard delete.

Mass operations вроде `deleteAll()` этим foundation-слоем автоматически не перехватываются.

Event Facade
------------

[](#event-facade)

BES содержит централизованный `EventHub`, доступный через `BaseEntitySystem::getEventHub()`.

Основной API:

```
$hub->on($eventName, $callback);
$hub->off($eventName, $callback);
$hub->trigger($eventName, $payload);
```

Поддерживаемые BES events:

- `entity.activityChanged` с `ActivityChangedPayload`.
- `entity.stateChanged` с `StateChangedPayload`.

MEL events также прокидываются через этот facade, чтобы клиенты могли подписываться через одну точку. Soft delete/restore/permanentDelete не имеют отдельной скрытой event-магии: события активности и состояния срабатывают через существующий `afterSave`/behavior path.

Schema API
----------

[](#schema-api)

Schema endpoints:

```
GET  /schema/tables
GET  /schema/table/{name}
POST /schema/diff
POST /schema/migration

```

Read endpoints доступны для introspection. `table/{name}` принимает только имена с символами `a-zA-Z0-9_.-`.

`diff` и `migration` принимают JSON body с обязательным объектом `desired` в формате schema DTO из `illusiard/dbtoolkit`:

```
{
  "desired": {
    "tables": []
  },
  "options": {
    "className": "m260101_000001_update_schema",
    "namespace": "app\\migrations",
    "transactional": true,
    "useTablePrefix": false
  }
}
```

Для migration options также поддерживается flat form на root-level: `className`, `namespace`, `transactional`, `useTablePrefix`. `diff` возвращает `{"actions": [...]}`, `migration` возвращает `{"className": "...", "code": "..."}`. Write tooling (`diff`, `migration`) должен включаться явно через controlled module config, например `allowSchemaWriteTools`, и не предназначен для открытой production-среды.

Dev Host
--------

[](#dev-host)

`dev/host/` - локальный integration host. Он нужен для ручной проверки, live API integration tests и browser E2E.

Особенности:

- Собирается через `illusiard/yii2-testkit`.
- Использует SQLite: `dev/host/runtime/bes-dev.sqlite`.
- Использует Yii `FileCache` в `dev/host/runtime`.
- Создает schema и seed при первом запуске.
- Регистрирует demo entities: `post`, `author`, `tag`.
- Использует permissive ACL policy для ручной проверки всех операций.
- Подключает CORS для frontend dev server.

Запуск из корня репозитория:

```
composer install
/usr/bin/php8.5 -S 127.0.0.1:8081 -t dev/host/web dev/host/web/router.php
```

Live API base URL:

```
http://127.0.0.1:8081/api/v1

```

Smoke-check dev host:

```
bash dev/host/bin/smoke-http.sh
```

Dev host stateful. Если нужно начать с чистого состояния, удалите SQLite/cache runtime файлы в `dev/host/runtime/` и запустите host снова.

Frontend SPA
------------

[](#frontend-spa)

`view/` - reference SPA для проверки backend protocol в реальном runtime. Runtime architecture сохраняет направление:

```
container components -> screen model -> composables -> small UI components

```

Providers:

- `mock` - isolated frontend/dev/test режим без backend.
- `api` - live provider поверх BES HTTP API.

Запуск mock provider:

```
cd view
npm install
VITE_BES_PROVIDER=mock npm run dev
```

Запуск live API provider:

```
/usr/bin/php8.5 -S 127.0.0.1:8081 -t dev/host/web dev/host/web/router.php
cd view
VITE_BES_PROVIDER=api VITE_BES_API_BASE_URL=http://127.0.0.1:8081/api/v1 npm run dev
```

Во frontend `refs` и ACL bit masks нормализуются через `EntityFormatter`/runtime provider path. `listFields`, popup stack и related popup flows закреплены в runtime. Нестандартные scenario/debug controls остаются dev/test harness и не являются частью production UI contract.

Tests
-----

[](#tests)

Backend unit/integration tests:

```
composer install
vendor/bin/phpunit
```

Dev host HTTP smoke:

```
/usr/bin/php8.5 -S 127.0.0.1:8081 -t dev/host/web dev/host/web/router.php
bash dev/host/bin/smoke-http.sh
```

Frontend Vitest mock/integration suite:

```
cd view
npm install
npm test
```

Эта suite включает provider/runtime contract tests, включая `view/src/integration/__tests__/api-provider.integration.test.js`, и работает без backend через mock/stub providers.

Live API integration tests against running dev host:

```
cd view
npm run test:live
```

`test:live` использует:

```
BES_LIVE_API=1
VITE_BES_PROVIDER=api
VITE_BES_API_BASE_URL=http://127.0.0.1:8081/api/v1

```

Основной live integration файл: `view/src/integration/__tests__/live-api.integration.test.js`. Dev host должен быть уже поднят на `http://127.0.0.1:8081/api/v1`.

Browser E2E через Playwright:

```
cd view
npm run test:e2e
```

Только live API E2E сценарии:

```
cd view
npm run test:e2e-live
```

Playwright config поднимает dev host и Vite frontend с live API provider. По умолчанию Chromium-compatible browser ожидается как:

```
/usr/bin/google-chrome

```

Если Chrome установлен в другом месте, настройте environment для Playwright, например `PLAYWRIGHT_CHROMIUM_EXECUTABLE`. Base URLs также можно переопределять через `PLAYWRIGHT_FRONTEND_BASE_URL` и `PLAYWRIGHT_BACKEND_BASE_URL`.

Current Coverage
----------------

[](#current-coverage)

Backend tests закрепляют:

- meta/DTO/schema contract;
- CRUDL endpoints;
- soft delete foundation;
- `restore` и `permanentDelete`;
- `deleted=-1|0|1` search/list semantics;
- ACL operation masks;
- `EventHub` subscription/unsubscription и payload triggers;
- meta-state snapshot generation.

Live frontend integration и browser E2E покрывают:

- root list;
- view popup из list;
- update popup из view;
- root create;
- FK selectors и create-select popup chain;
- refs и ACL bits на live API;
- soft delete, restore, permanentDelete;
- `deleted` query parameter;
- validation, forbidden, not\_found, integrity/internal error paths где они относятся к provider/UI contract.

Mock provider tests остаются отдельным isolation layer для frontend-only сценариев.

Release Readiness
-----------------

[](#release-readiness)

Текущий release status, host-app production contract и regression pack зафиксированы в:

```
RELEASE.md

```

На уровне репозитория known release blockers отсутствуют. Production-готовность зависит от host app: authentication, `yii2-entity-acl` policy, инфраструктура cache/db и закрытый доступ к schema write tooling.

Ограничения
-----------

[](#ограничения)

- Dev host использует permissive ACL, поэтому он удобен для ручных CRUDL проверок, но не моделирует production policy.
- SQLite/FileCache изолированы в `dev/host/runtime` и предназначены только для локального dev/test.
- Soft delete автоматически работает только для моделей с activity field `is_active`.
- `deleteAll()` и другие mass delete operations не переводятся автоматически в soft delete.
- Schema write endpoints должны быть включены явно и не должны быть открыты в production без дополнительной защиты.
- Frontend scenario/debug controls относятся только к dev/test harness.

###  Health Score

42

—

FairBetter than 88% of packages

Maintenance99

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~15 days

Total

5

Last Release

2d ago

Major Versions

v0.2.0 → v1.0.02026-06-06

PHP version history (2 changes)v0.1.0PHP >=8.1

v1.1.0PHP >=8.5

### Community

Maintainers

![](https://www.gravatar.com/avatar/514a2bdbd1dfc61512460d4026da34187fb5e20e69be3ada0a8594b593dd269a?d=identicon)[Illusiard](/maintainers/Illusiard)

---

Top Contributors

[![Illusiard](https://avatars.githubusercontent.com/u/27963611?v=4)](https://github.com/Illusiard "Illusiard (69 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/illusiard-yii2-base-entity-system/health.svg)

```
[![Health](https://phpackages.com/badges/illusiard-yii2-base-entity-system/health.svg)](https://phpackages.com/packages/illusiard-yii2-base-entity-system)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)