Download the PHP package illusiard/yii2-base-entity-system without Composer

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

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

Entity Endpoints

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

List/Search 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

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

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

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

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

Wire Format

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

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

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

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

Dev host permissive ACL обычно возвращает 127 для полной маски.

Error Format

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

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

• 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

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 структур хранится в:

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

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

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

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

Основной API:

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

• entity.activityChanged с ActivityChangedPayload.
• entity.stateChanged с StateChangedPayload.

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

Schema API

Schema endpoints:

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

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

Для 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/ - локальный 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.

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

Live API base URL:

Smoke-check dev host:

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

Frontend SPA

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

Providers:

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

Запуск mock provider:

Запуск live API provider:

Во 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

Backend unit/integration tests:

Dev host HTTP smoke:

Frontend Vitest mock/integration suite:

Эта 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:

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

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

Browser E2E через Playwright:

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

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

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

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 status, host-app production contract и regression pack зафиксированы в:

На уровне репозитория 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.