> For the complete documentation index, see [llms.txt](https://docs.johncms.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.johncms.com/10.0/moduli/collections.md).

# Коллекции: PHP API

Коллекция хранит базовые свойства записи и дополнительные поля. Для записи используйте `Johncms\Modules\Collections\Application\Api\CollectionsApiInterface` через DI. Модуль-потребитель объявляет зависимость от `johncms/collections` в `requires.modules` своего `module.php`.

## Создание и изменение

```php
use Johncms\Modules\Collections\Application\Api\CollectionsApiInterface;
use Johncms\Modules\Collections\Application\DTO\CollectionItemFormDTO;

$form = new CollectionItemFormDTO(
    collectionId: $collectionId,
    sectionId: null,
    code: 'Release.V10+RC_1',
    name: 'Release',
    active: true,
    activeFrom: '2026-11-02T12:30',
    activeTo: null,
    sort: 100,
    previewText: '<p>Preview</p>',
    detailText: '<p>Content</p>',
    values: ['author' => 'Alice', 'tag' => ['php', 'cms']],
);

$id = $collections->addItem($form, actorId: $currentUserId);
$collections->updateItem($id, $form, actorId: $currentUserId);
```

`$collections` — внедрённый `CollectionsApiInterface`. ID пользователя берётся из доверенного контекста операции. Если `actorId` не передан, операция считается системной. Создание заполняет `created_by`, изменение — `updated_by`, сохраняя первоначального автора.

`updateItem()` требует существующую запись именно этой коллекции. Отсутствующий ID и попытка переноса в другую коллекцию возвращают ошибку. Обновление полностью заменяет дополнительные значения: необходимо передать весь набор полей; отсутствующие значения очищаются.

## Формат данных и ошибки

Название обязательно и ограничено 255 символами. Явный код допускает латинские буквы обоих регистров, цифры, точку, плюс, дефис и подчёркивание. Пустой код создаётся из названия как slug, при совпадении получает числовой суффикс. Код уникален в коллекции и разделе, включая записи без раздела. Формы разделов допускают тот же алфавит.

Даты публикации принимаются в формате `Y-m-d H:i:s`, `Y-m-d H:i`, `Y-m-dTH:i:s` или `Y-m-dTH:i`; пустая дата означает отсутствие границы. Дата окончания не может предшествовать дате начала. В БД даты сохраняются как `Y-m-d H:i:s` без форматирования для интерфейса.

Дополнительные значения передаются строками; множественные — списками строк. Проверяются обязательность, множественность и тип. Некорректное число не становится нулём, некорректная дата не исчезает. Boolean принимает `0`, `1` и пустое значение как false; integer ограничен диапазоном PHP int, relation — положительным integer, double — конечным числом. Поля Select проверяют варианты; проверка связей и файлов описана в разделах соответствующих типов.

Date принимает `Y-m-d` либо каноническую дату с нулевым временем, datetime — форматы даты-времени выше. Короткие строковые поля ограничены 255 символами; анонс — 65535 байт.

`CollectionItemFormException::$errors` содержит сообщения по полям: `name`, `code`, `section_id`, `active_from`, `active_to`, `sort`, `values.<код поля>` и другим проверяемым атрибутам. Для занятого кода сохраняется отдельный `CollectionItemCodeAlreadyExistsException`. Форма админки использует тот же сценарий и показывает ошибки у полей.

## Транзакции и конкуренция

Запись и дополнительные значения сохраняются одной транзакцией. Для более крупной атомарной операции другой модуль использует `Johncms\Database\ConnectionInterface::transaction()`: вложенное сохранение становится savepoint. Действие после commit такой операции регистрирует `CollectionItemRelationsApiInterface::afterCommit()`. Исключение при сохранении возвращает прежние данные; откат вызывающего кода откатывает и созданные записи. В сценариях сохранения нет DDL.

Сохранения одной коллекции сериализуются блокировкой её строки. Проверка занятого кода и изменяемой записи выполняется locking read, а не чтением старого снимка внешней транзакции. Гарантии действуют для записи через API или `SaveCollectionItemUseCase`; прямые записи в репозитории/таблицы обходят этот протокол.

`CollectionWriteConflictException` означает, что из-за конкуренции нужно повторить всю внешнюю операцию. Сам savepoint не обновляет старый снимок внешней транзакции. Такое поведение возможно, в частности, при включённом [snapshot isolation MariaDB](https://mariadb.com/docs/server/server-usage/storage-engines/innodb/innodb-system-variables#innodb_snapshot_isolation). Настройки сервера модуль не меняет. Админка предлагает повторить сохранение, сохраняя введённые данные.

## Чтение и постраничная выборка

Методы `findCollection()`, `getItem()` и `getItemByCode()` возвращают неизменяемые DTO, а `getItems()` — обычный список `CollectionItemDTO`, без моделей и коллекций Eloquent. Свойства именуются в camelCase: `collectionId`, `sectionId`, `previewText`, `createdAt`, `createdBy`, `viewCount`. Значения дополнительных полей доступны в `$item->values` по коду. Незаполненные и не загруженные поля отсутствуют в этой карте.

Даты записи и дополнительные поля Date/Datetime возвращаются как `DateTimeImmutable` в UTC; исторически отсутствующие даты — как null. HTML возвращается исходным: подготовка для Twig выполняется общим content pipeline в потребителе.

```php
use Johncms\Modules\Collections\Domain\Enums\FilterOperator;
use Johncms\Modules\Collections\Domain\Enums\SortDirection;
use Johncms\Modules\Collections\Domain\Query\ContentCollectionItemQuery;
use Johncms\Modules\Collections\Domain\Query\FieldFilterDTO;
use Johncms\Modules\Collections\Domain\Query\OrderByDTO;

$page = $collections->getPage(new ContentCollectionItemQuery(
    collectionId: $collectionId,
    filters: [new FieldFilterDTO('field.author', FilterOperator::Eq, 'Alice')],
    orderBy: [new OrderByDTO('item.created_at', SortDirection::Desc)],
    limit: 20,
    offset: 0,
    fields: ['author', 'tag'],
));

foreach ($page->items as $item) {
    // $item->id, $item->name, $item->values['author']
}
$total = $page->total;
```

`getPage()` возвращает `items`, `total`, `limit`, `offset`. Total не ограничивается limit/offset. По умолчанию limit равен 100; допустимы 1–1000, offset — 0–1000000. Сортировка при равенстве значений дополняется ID, если он не указан явно. Сортировка множественного поля использует первое значение в порядке sort/id. Произвольного неограниченного чтения через этот API нет.

`fields: null` загружает все дополнительные значения, `fields: []` — ни одного, список кодов — только выбранные. Загрузка выполняется пакетно, без отдельного запроса на запись.

### Адреса полей и фильтры

Базовые колонки адресуются как `item.name`, `item.id`, `item.active_from`, дополнительные — как `field.name`, `field.author`. Одинаковый код дополнительного и базового поля не меняет смысл запроса. Bare-коды без префикса не принимаются. Неизвестное поле, сортировка или выбранный код, неверный тип значения и неподдерживаемый оператор дают `InvalidArgumentException`.

Integer/Relation-фильтры принимают int, Double — int/конечный float, Boolean — bool, Date/Datetime — `DateTimeImmutable`, текстовые — string. `In` принимает список до 1000 значений одного подходящего типа. `Like` поддерживается текстовыми типами, сравнения порядка — числовыми и датами. `Eq` с null выбирает базовое NULL либо отсутствие дополнительного значения; null внутри `In` не поддерживается. Фильтры соединяются через AND.

`includeSubsections: true` выбирает записи поддерева указанного `sectionId`. `onlyActive: true` включает общую политику публикации: активность коллекции, записи, всей цепочки разделов и окно дат. Для вывода посетителям используйте отдельный публичный API, который применяет эту политику независимо от переданного `onlyActive`.

## Частичное обновление

`updateItem()` сохраняет полную форму. Для изменения отдельных свойств используйте `patchItem()`, он проверяет только то, что меняет, поэтому старые значения других полей ему не мешают:

```php
use Johncms\Modules\Collections\Application\DTO\CollectionItemPatchDTO;

$collections->patchItem($id, new CollectionItemPatchDTO(
    attributes: ['name' => 'New title', 'previewText' => null],
    values: ['tag' => ['php', 'news'], 'author' => null],
), actorId: $currentUserId);
```

Пропущенные базовые свойства и дополнительные поля сохраняются. Ключи `attributes` совпадают со свойствами формы: `name`, `code`, `sectionId`, `active`, `activeFrom`, `activeTo`, `sort`, `previewText`, `detailText`. Null допустим для sectionId, текстов и дат; название очищать нельзя.

Дополнительные значения передаются строками, множественные — списками строк, как в полной форме. Переданный список заменяет весь набор значений поля. Null удаляет значение, включая необязательный Boolean; строка `0` сохраняет Boolean false. Обязательное поле очистить нельзя. Пропущенное поле не удаляется и не создаётся заново. Изменение коллекции, системных дат, авторов или просмотров через `attributes` не допускается.

Чтение актуальной записи, слияние и сохранение находятся под одной транзакционной блокировкой. Параллельные изменения разных свойств не перезаписывают друг друга.

## Просмотры

Чтение через API не меняет счётчики. Для публичного просмотра вызывайте `$collections->incrementViews($id)` отдельно: увеличение атомарно и не меняет `updated_at`, автора, редактора и содержимое. Отсутствующие, выключенные и находящиеся вне временного окна записи, а также записи выключенной коллекции или скрытой/недостижимой цепочки разделов отклоняются. Флаг `public` коллекции на возможность засчитать просмотр через API не влияет.

Предпросмотр использует только чтение. Правило повторных просмотров (например, один просмотр за сессию) остаётся у модуля-потребителя.

## Исторический импорт из хука обновления

`CollectionsImportApiInterface` создаёт записи и разделы с исходными датами. Он доступен внутри доверенного контекста `SystemOperationContext`, который ядро открывает на время `Installer::update()`. Обычный вызов импорта вне такого контекста отклоняется `LogicException`; HTTP-параметра для включения контекста нет. Контекст закрывается и при исключении в хуке.

Внутри хука:

```php
use Johncms\Modules\Collections\Application\Api\CollectionsImportApiInterface;
use Johncms\Modules\Collections\Application\DTO\CollectionItemHistoryDTO;

$importer = di(CollectionsImportApiInterface::class);
$id = $importer->importItem($form, new CollectionItemHistoryDTO(
    createdAt: new DateTimeImmutable('2001-02-03T04:05:06Z'),
    updatedAt: new DateTimeImmutable('2002-03-04T05:06:07Z'),
    createdBy: 7,
    updatedBy: 8,
    viewCount: 123,
));
$sectionId = $importer->importSection($sectionForm, $createdAt, $updatedAt);
```

Импорт создаёт новые ID. Сопоставление старых и новых ID ведёт вызывающий код. Исторические атрибуты не заменяются текущими; даты приводятся к UTC и проверяются на диапазон DATETIME. У записи сохраняются исходные авторы, редактор и просмотры; у раздела — даты создания и изменения. Проверки содержимого и принадлежности коллекции сохраняются. Ошибки раздела представлены `CollectionSectionFormException`, записи — `CollectionItemFormException`.

Импорт использует общий транзакционный механизм, включая внешнюю транзакцию вызывающего. Отсутствующие исторические даты передаются как `null` и сохраняются как SQL NULL: время импорта вместо них не подставляется. Даты создания и изменения независимы.

DDL внутри операций импорта не выполняется. Изменять исторические атрибуты обычным patch нельзя.

## API иерархических разделов

Внедряйте `CollectionSectionsApiInterface`. Интерфейс возвращает неизменяемые DTO, независимые от Eloquent. Это административное чтение: неактивные разделы также доступны. Публичные записи читайте через `CollectionsPublicApiInterface`, который проверяет всю цепочку разделов.

```php
use Johncms\Modules\Collections\Application\Api\CollectionSectionsApiInterface;
use Johncms\Modules\Collections\Application\DTO\CollectionSectionFormDTO;
use Johncms\Modules\Collections\Domain\Query\ContentCollectionItemQuery;

$sectionId = $sections->addSection(new CollectionSectionFormDTO(
    collectionId: $collectionId,
    parent: null,
    code: 'technology',
    name: 'Technology',
    description: 'Section description',
    active: true,
    sort: 100,
    metadata: ['seo' => ['title' => 'Technology news']],
));

$section = $sections->findSection($collectionId, $sectionId);
$path = $sections->getPath($collectionId, $sectionId);
$resolved = $sections->resolvePath($collectionId, ['technology', 'php']);
$tree = $sections->getTree($collectionId);

$page = $collections->getPage(new ContentCollectionItemQuery(
    collectionId: $collectionId,
    sectionId: $sectionId,
    includeSubsections: true,
));
```

`findSection()` возвращает null для отсутствующего или чужого раздела. `getPath()` возвращает путь от корня до самого раздела; для отсутствующего или чужого раздела — пустой список. `resolvePath()` принимает полную цепочку кодов от корня, не ищет совпадения только по последнему коду и возвращает null, если цепочка не разрешается; пустая цепочка также даёт null. Некорректные сегменты пути дают `InvalidArgumentException`.

`getTree()` возвращает плоский список `CollectionSectionTreeNodeDTO` в порядке обхода дерева. В каждом узле: `section`, `depth`, `items` (только свой раздел), `itemsInSubtree` (с потомками). Порядок соседей — sort, name, id. Количества включают скрытые и запланированные записи, как в админке; для публичных количеств используйте `countItems()` с нужным запросом. Дерево и количества загружаются одним запросом, без отдельного запроса на каждый раздел.

### Область выборки записей

* Вся коллекция: `sectionId: null` (по умолчанию), включая записи без раздела.
* Только записи без раздела: `withoutSection: true`.
* Только выбранный раздел: `sectionId: $id`, `includeSubsections: false`.
* Выбранный раздел со всеми потомками: `sectionId: $id`, `includeSubsections: true`.

Противоречивые сочетания отклоняются: `withoutSection` вместе с `sectionId` или `includeSubsections`, а также `includeSubsections` без раздела. Неизвестный или чужой ID поддерева даёт пустую выборку. `countItems()`, `getItems()` и `getPage()` используют одну область; фильтр раздела в админке включает то же поддерево.

### Сохранение, перемещение и метаданные

`addSection()` возвращает ID. `updateSection($id, $form)` заменяет форму целиком, включая описание и метаданные. Для перемещения передайте новый `parent`, для переноса в корень — null. Родитель должен существовать в той же коллекции. Перенос раздела в себя, в потомка или между коллекциями отклоняется; обновление отсутствующего ID не создаёт новый раздел.

Коды уникальны среди соседей. Проверки и запись выполняются в одной транзакции под блокировкой коллекции: параллельные перемещения не образуют цикл, параллельное создание корневых разделов не создаёт одинаковые коды. Ошибки полей приходят в `CollectionSectionFormException::errors`, дубликат кода — `CollectionSectionCodeAlreadyExistsException`, конфликт транзакций — `CollectionWriteConflictException`. Внешняя транзакция может откатить сохранение.

`metadata` — ассоциативный массив с именованными ключами и JSON-совместимыми значениями; пустой массив очищает настройки. Объекты PHP и ресурсы не принимаются, сериализованный объём ограничен 1 МиБ (колонка LONGTEXT), глубина — 32 уровнями. Описание сохраняется без HTML-экранирования: при выводе текста используйте Twig, при выводе HTML — штатный рендерер контента.

В форме раздела доступны выбор родителя и поле JSON-объекта метаданных. Раздел и его потомки исключены из списка родителей; поддельный POST проверяется тем же use case, что API. Исторический `importSection()` также использует это сохранение и сохраняет исходные даты. Для хранения метаданных добавлена миграция `add_metadata_to_collection_sections`; на существующем сайте примените её через штатное обновление системы.

`deleteSection()` требует явного `SectionDeletionMode`: удалить записи поддерева или перенести их в сохраняемый раздел той же коллекции. Подробности и подтверждение операции описаны ниже.

## Публикация и публичное чтение

Для вывода посетителям внедряйте `CollectionsPublicApiInterface`. Он предоставляет `getItems()`, `countItems()`, `getPage()`, `findItem($collectionId, $id)`, `findItemByCode($collectionId, $sectionId, $code)` и `incrementViews($id)`. Типы результатов и параметры выборки совпадают с административным `CollectionsApiInterface`. Административные `getItem()`/`getItemByCode()` читают также скрытые записи и нужны для управления. Публичный API принудительно применяет политику публикации даже при `onlyActive: false`.

Запись доступна, если одновременно:

* коллекция активна;
* запись активна;
* `active_from` отсутствует или не позже момента чтения;
* `active_to` отсутствует или не раньше момента чтения;
* раздел и все его предки активны, цепочка доходит до корня этой же коллекции.

Записи без раздела проверяются без цепочки. Циклы и недостижимые разделы закрыты для публичного чтения. Те же правила применяются к собственным страницам, sitemap и счётчику просмотров. `public` коллекции разрешает собственные URL и включение в sitemap; значение false не запрещает модулю-владельцу выводить активный контент коллекции через публичный PHP API.

### Дата публикации и момент чтения

`CollectionItemDTO::publishedAt` равна `activeFrom ?? createdAt`; это `DateTimeImmutable` в UTC (либо null, если обе исходные даты отсутствуют). В фильтре и сортировке доступна виртуальная колонка `item.published_at` с той же семантикой. Дата создания не ограничивает доступность: расписание задаётся только `active_from`/`active_to`.

Публичный API и собственные публичные списки по умолчанию сортируют по дате публикации по убыванию, затем по ID по убыванию. Явный `orderBy` сохраняется, со стабильным ID при равенстве. Административная сортировка по умолчанию остаётся sort/id.

Запрос фиксирует `at` при создании. Один `getPage()` использует этот момент для списка и total; собственная публичная страница также передаёт один момент в count/list, sitemap — во все выборки. При необходимости PHP-потребитель передаёт явный `at: new DateTimeImmutable(...)` в `ContentCollectionItemQuery`. Значение переводится в UTC; сравнение дат выполняется с точностью до секунды, обе границы включены. Карточки и увеличение просмотров используют текущее время. Чтение контента само по себе не увеличивает просмотры: правило повторных просмотров остаётся у потребителя, который вызывает `incrementViews()` отдельно.

### Защищённый предпросмотр

В списке записей админки есть действие «Предпросмотр», доступное также для скрытых материалов и приватных/выключенных коллекций. Адрес: `/admin/collections/{collectionId}/items/{id}/preview`. Предпросмотр остаётся в админке, использует тот же вывод текста и дополнительных значений, что публичная карточка, и возвращает `Cache-Control: private, no-store` и `X-Robots-Tag: noindex, nofollow`. Он не изменяет публикацию, дату редактирования или просмотры.

Для собственного шаблона внедряйте `CollectionsPreviewApiInterface` и вызывайте `findItem($collectionId, $id)`. API проверяет право `collections.manage` у текущей авторизованной личности через `AccessCheckerInterface`, в том числе при прямом PHP-вызове. Передать ID пользователя или флаг обхода проверки нельзя. При отказе выбрасывается `CollectionPreviewAccessDeniedException`; отсутствующая или чужая запись возвращает null. HTTP-маршрут дополнительно защищён middleware админки. Параметр публичного URL не включает предпросмотр и не меняет правила публикации.

## Предсказуемое удаление

Удаление окончательное. Запись удаляется вместе с дополнительными значениями через `DeleteCollectionItemUseCase`, независимо от поддержки каскадов внешних ключей БД. Та же операция вызывается для каждой записи при удалении раздела или всей коллекции; обработчики C6 удаляют связанные данные владельца в той же транзакции, а общие файлы — после внешнего commit с проверкой оставшихся ссылок. Несуществующая или чужая запись отклоняется через `CollectionItemFormException`.

### Удаление раздела

```php
use Johncms\Modules\Collections\Domain\Enums\SectionDeletionMode;

$preview = $sections->previewDeletion($collectionId, $sectionId);
// Show $preview->name, $preview->sections - 1 (subsections) and $preview->items.
$sections->deleteSection(
    $collectionId,
    $sectionId,
    SectionDeletionMode::MoveItems,
    targetId: $destinationSectionId,
    expectedRevision: $preview->revision,
);
```

`CollectionDeletionPreviewDTO` содержит `collectionId`, `sectionId`, `name`, `sections`, `items`, `fields`, `revision`. Для раздела `sections` включает выбранный раздел, а `items` считает все записи его поддерева, включая скрытые, запланированные и истёкшие; `fields` равен 0.

Режим обязателен:

* `SectionDeletionMode::DeleteItems` удаляет записи и их значения, затем разделы от листьев к корню. `targetId` в этом режиме не передаётся.
* `SectionDeletionMode::MoveItems` переносит все записи поддерева непосредственно в `targetId`, затем удаляет старые разделы. Вложенность прежних разделов не переносится.

Раздел назначения должен существовать в той же коллекции и находиться вне удаляемого поддерева. Корень без раздела не считается назначением. Коды, авторство, просмотры, дата создания, активность, окно публикации и значения полей сохраняются; дата редактирования при переносе обновляется. Доступность после переноса определяется цепочкой раздела назначения.

Коды записей должны оставаться уникальными в новом разделе. Конфликты как с существующими записями назначения, так и между записями разных исходных подразделов откатывают всю операцию, включая уже выполненные перемещения. Автоматического переименования кодов нет: выберите другой раздел или исправьте коды до переноса. Проверка использует правила сравнения кодов самой БД.

### Удаление коллекции

```php
$preview = $collections->previewCollectionDeletion($collectionId);
// Show $preview->items, $preview->sections and $preview->fields.
$collections->deleteCollection($collectionId, expectedRevision: $preview->revision);
```

Удаляются все записи (в том числе корневые), их значения, разделы и определения полей, затем сама коллекция. Карта собственных публичных URL инвалидируется. Содержимое других коллекций не затрагивается; ошибочные связи разделов/записей из другой коллекции блокируют удаление.

### Подтверждение и транзакции

Админка показывает один диалог для обычной страницы и модального окна. Для раздела нет предвыбранного режима: действие выбирается явно. В списке назначений отсутствуют удаляемый раздел и его потомки. POST обязательно передаёт `revision`; пропуск режима, назначения при переносе или подтверждения не выполняет удаление.

`revision` фиксирует состав и расположение затрагиваемых записей и разделов, их коды и даты редактирования; для коллекции также учитываются определения полей. При изменении этого состояния действие отклоняется, диалог показывает свежие количества и новое подтверждение. Это проверка актуальности, а не замена права доступа и CSRF-защиты. PHP-потребитель может передать `expectedRevision`, чтобы связать действие с предварительным просмотром; при отсутствии этого аргумента операция охватывает текущее содержимое под блокировкой.

План заново строится внутри транзакции с текущими блокирующими чтениями и общей блокировкой коллекции. Параллельное сохранение не оставляет записи в корне после удаления раздела. Внешняя транзакция может откатить всю очистку или перенос. Ошибки выбора, конфликты кодов и устаревшее подтверждение приходят в `CollectionDeletionException::errors`; конфликт транзакций — в `CollectionWriteConflictException`, после которого повторяется вся внешняя операция. Прямые удаления строк репозиторием не предоставляют этих гарантий.

## Обработчики изменений и кэш

Реализуйте `CollectionChangeHandlerInterface` и зарегистрируйте сервис в DI модуля:

```php
$services->set(MyCollectionHandler::class)
    ->autowire()
    ->tag('johncms.collections.change_handler');
```

Оба метода получают неизменяемый `CollectionChangeDTO`: `entity` (`item`, `section`, `collection`, `field`), `action` (`saved`, `moved`, `deleted`), `collectionId`, `id`, `before`, `after`, `imported`. Состояние `CollectionChangeStateDTO` содержит `containerId` (раздел записи или родитель раздела), `active` и `code`. Для создания `before` равен null, для удаления — `after`. У поля `active` не применяется и равен null. При смене раздела/родителя действие — `moved`, при остальных сохранениях — `saved`. Счётчик просмотров — отдельная операция чтения/учёта, без обработчиков изменения контента.

`withinTransaction()` выполняется синхронно в транзакции изменения. В нём удаляются связанные комментарии, голоса и другие обязательные строки владельца через общее подключение БД. Исключение откатывает исходное изменение и связанные строки. Обработчик удаления записи вызывается до очистки её значений; удаление раздела и всей коллекции проходит тот же путь для каждой затронутой записи. Коллекции не удаляют таблицы другого модуля сами.

`afterCommit()` выполняется только после фиксации самой внешней транзакции, включая ORM savepoints и операции внутри `ConnectionInterface::transaction()`. Откат отменяет производную фазу. Здесь обновляют поисковый индекс, сбрасывают кэш и удаляют физические файлы. Данные состояния фиксируют конкретное изменение; при построении производных представлений обработчик может перечитать окончательное состояние через API.

Сбой одного производного обработчика не отменяет уже выполненное изменение и не препятствует остальным callbacks. Исключения собираются в `Johncms\Database\AfterCommitException::failures`. HTTP-ответ явно предупреждает, что операция уже выполнена и её нельзя повторять. Исправьте причину, пересоберите производные данные; подробности находятся в журнале. CLI/PHP-потребитель должен отличать этот сбой от отказа до commit.

Исторический импорт передаёт `imported: true`: обязательные обработчики работают, производная фаза пропускается. Импортирующий хук один раз пересобирает индекс и кэш после переноса. Не открывайте внешнюю транзакцию непосредственным `PDO::beginTransaction()` для операций коллекций: её окончательный commit нельзя наблюдать. Используйте `ConnectionInterface` или ORM.

### Недоступный владелец

`collections.owner_module` хранит ключ модуля-владельца (например, `johncms/news`), null означает независимую коллекцию. Если модуль не загружен, его обработчики не могут убрать зависимые данные: удаление записи, поддерева и коллекции отклоняется до очистки, с сообщением о необходимости включить владельца. Чтение и редактирование остаются доступны. Поле владельца не редактируется обычной формой коллекции; декларации модулей используют его на следующем этапе. Требуется миграция `add_owner_module_to_collections`.

### Адресная инвалидация

Производные данные коллекции помечайте `CollectionCacheInvalidator::tag($collectionId)` (`collections_<id>`). Штатный обработчик сбрасывает этот тег после изменений записей, разделов, схемы и самой коллекции. Теги других коллекций остаются действительны. Карта собственных URL инвалидируется отдельным тегом при изменении коллекции; её чтение внутри транзакции обходит постоянный кэш, поэтому откат не оставляет незакоммиченную карту.

Опубликованные записи, количества и цепочки доступности сейчас не кэшируются. Их временные окна проверяются SQL-запросом на момент операции, поэтому наступление/окончание публикации не требует события записи и не задерживается кэшем. Это распространяется на публичные API, собственные страницы и sitemap при его построении.

## Декларации модулей

Модуль регистрирует `CollectionDeclarationProviderInterface` с тегом `johncms.collections.declaration_provider`. `owner()` возвращает ключ установленного модуля, `collections()` — декларации `CollectionDeclarationDTO`. Пара `(owner, key)` стабильна: получайте коллекцию через `findDeclaredCollection()`, не сохраняйте её числовой ID в коде. Подписи задаются `CollectionLabelDTO::translatableLabel('news', 'News')`: в БД сохраняются исходный msgid и домен, перевод выбирается при чтении. Метод распознаётся сканером переводов.

Синхронизатор выполняется до обработчиков обновления при установке, включении и `system:update`. Он создаёт коллекцию и поля, добавляет настройки по умолчанию, сохраняя выбор администратора, переименовывает поле по `renamedFrom` без изменения ID и значений. Пользовательские поля не присваиваются владельцу; конфликт кода требует явного переименования администратором. Поля декларации защищены от изменения и удаления обычными формами.

Изменение типа или множественности заполненного поля требует доверенного обработчика обновления: через `CollectionSchemaApiInterface` подготовьте совместимую структуру, перенесите значения, затем удалите старое поле. `saveOwnedField()` позволяет создать временное поле владельца; `saveField()` возвращает ID. Оборачивайте структуру и перенос в общую транзакцию. После обработчиков финальная проверка требует соответствия декларации. Синхронизатор не удаляет лишние поля и не преобразует данные автоматически. Системная проверка `collections.declarations` сообщает оставшиеся расхождения.

Для ссылок реализуйте `CollectionOwnerUrlProviderInterface`, тег `johncms.collections.owner_urls`: URL рабочего пространства на сайте, записи, раздела, предпросмотра и настроек. `itemUrls()` отдаёт адреса целого списка и не должен читать разделы на каждую запись: используйте `getPaths()` API разделов. Допустимы корневые относительные и HTTP(S) адреса. Отсутствующий или отключённый владелец оставляет ссылки пустыми. Коллекция владельца не получает дублирующих страниц через общий роутер и sitemap коллекций.

Требуется миграция `add_declaration_metadata`. Право наполнения декларации сохраняется в настройке `_content_permission` и проверяется при пользовательских операциях.

## Права наполнения

`collections.manage` управляет схемой и даёт полный доступ ко всем коллекциям. Редактору достаточно права `_content_permission` конкретной коллекции: декларация модуля задаёт его в коде, для независимой коллекции администратор выбирает право в настройках. По умолчанию используется `collections.manage`. Настройки владельца нельзя подменить формой.

Маршруты записей, разделов и предпросмотра проверяют право конкретной коллекции на сервере. Редактору недоступны список всех коллекций, поля, настройки схемы и удаление коллекции. Вкладки скрываются, собственные коллекции доступны прямыми ссылками в меню. Модуль-владелец может вести свой пункт сразу на `CollectionWorkspaceMapper::url($collectionId)`; его alias остаётся активным в рабочем пространстве. Контракт URL владельца добавляет вкладку настроек.

Для операций от имени посетителя внедряйте `CollectionsUserApiInterface`: чтение, создание, редактирование и удаление записей и разделов ограничены разрешённой коллекцией. ID автора берётся из `CurrentUser`; чужой ID записи не позволяет перенести её в доступную коллекцию. Отказ выбрасывает `CollectionAccessDeniedException`; HTTP-контроллер потребителя отображает его как 403. `CollectionsPreviewApiInterface` применяет ту же политику.

`CollectionsApiInterface`, API разделов и схемы остаются доверенными PHP API для внутренних сервисов модулей. Они не являются HTTP API и не заменяют пользовательский guard. Исторический импорт дополнительно требует активного `SystemOperationContext`, синхронизация выполняется только штатным процессом обновления. Публичное чтение использует `CollectionsPublicApiInterface`.

## Изображения в текстах и срок жизни файлов

Административные редакторы анонса и текста загружают изображения через общий `StoreEditorImageUseCase` и `FileStore`: действуют штатные ограничения размера, формата и масштабирования. Endpoint `POST /admin/collections/{id}/uploads?context={token}` проверяет право наполнения. Контекст создаётся формой или `POST .../uploads/context` (`item_id` для редактирования) и привязан к коллекции, редактору и, при редактировании, конкретной записи. Подстановка чужого ID файла или контекста не даёт права присвоить загрузку.

`CollectionItemFormDTO::uploadContext` передаёт контекст при сохранении, частичный API принимает `uploadContext` в attributes. Сохранение записи и перенос её временных ссылок выполняются одной транзакцией. Ошибка валидации сохраняет контекст для повторной отправки. Успешная отправка потребляет его; повторно использовать контекст нельзя. API клиента самостоятельно не присваивает `attached_files[]` из запроса: источником служит серверный реестр контекста.

Новые загрузки контекст принимает 24 часа. Форма живёт дольше: сохранение проходит и с устаревшим контекстом, забирая его файлы, а повторный показ формы продлевает его. Контекст, уже удалённый уборкой, файлов не содержит, и сохранение проходит без них. Команда `collections:cleanup-uploads` запускается планировщиком ежечасно; доступны `--ttl-hours` и `--batch-size` (1..10000). Она убирает отменённые загрузки после срока, свежие контексты сохраняет. Изображения остаются зарегистрированы за записью до её удаления, в том числе если автор убрал изображение из текста.

Удаление записи очищает ссылки внутри транзакции. Байты и строка `files` удаляются после внешнего commit, только когда на файл больше не ссылается ни запись, ни временный контекст. Запись, в чьём анонсе, тексте или текстовом поле есть адрес файла, тоже удерживает его: перед удалением она становится держателем файла. Тексты других модулей эта проверка не просматривает. Откат сохраняет файлы. Отдельные записи `files` с одинаковым путём также защищают общие байты.

Доверенный импорт вызывает `CollectionFileReferencesApiInterface::registerExisting()` внутри `SystemOperationContext`: регистрируются ссылки на существующие ID из `FileStore` без копирования. Откат общей транзакции откатывает ссылки. По умолчанию ответственность за физическое удаление остаётся у внешнего владельца; `transferOwnership: true` передаёт её коллекциям. Используйте этот флаг только при передаче исключительной ответственности за файл: ссылки других модулей на тот же ID не входят в реестр коллекций.

Требуется миграция `create_collection_file_links`: контексты, реестр ответственности и ссылки.

## HTML и метаданные

API записей возвращает исходные `previewText`, `detailText` и значения HTML-полей, без очистки при сохранении. Перед выводом используйте `GetPublicItemUseCase::format()` или `ItemContentFormatter`: анонс, текст и HTML-поля проходят общий `ContentRendererInterface`, включая очистку, медиа и преобразователи CMS. Пустой результат — null. Подготовленное представление использует `Twig\Markup`; обычные строковые поля остаются строками и экранируются Twig. Не применяйте `raw` к исходным DTO API. Множественные HTML-значения выводятся отдельно, чтобы объединение строк не теряло тип безопасной разметки.

HTML-поля используют общий редактор админки с загрузками C9. Для множественного HTML каждое значение передаётся отдельным `field_code[]`, включая многострочный HTML. Пустой дополнительный редактор добавляет значение; сохранение открывает следующий, очистка удаляет значение.

SEO-поля имеют роли `meta_title`, `meta_description`, `meta_keywords`; код поля произвольный. Роль задаётся в схеме или декларации и уникальна внутри коллекции. Такие поля не дублируются в блоке обычных значений. `PublicItemDetailDTO` содержит подготовленные `metaTitle`, `metaDescription`, `metaKeywords`. Все три проходят `ContentRendererInterface::toPlainText()`. Описание по умолчанию берётся из анонса, затем текста; пустая очищенная строка не препятствует fallback. Собственные страницы коллекций используют эти данные для метатегов.

В разделах те же ключи хранятся в `metadata`: универсальная форма даёт отдельные поля и сохраняет остальные пользовательские ключи JSON. Заголовок, описание и ключевые слова раздела применяются к его списку, с обычным суффиксом пагинации. Исходные HTML-значения метаданных преобразуются в plain text на выводе.

## Поиск и теги

`ContentCollectionItemQuery::search` принимает `CollectionTextSearchDTO($term, fields: ['extra'])`. Пустой или длиннее 255 символов термин DTO отклоняет: ввод посетителя сначала пропустите через `CollectionTextSearchDTO::normalizeTerm()`, а пустой результат считайте отсутствием запроса. Название, анонс и текст входят всегда; `fields` явно добавляет коды строковых, текстовых и HTML-полей. Неизвестные или неподходящие поля отклоняются. Список, количество и `getPage()` используют один поиск; публичный API принудительно сохраняет политику публикации C4.

Индекс `collection_search_documents` содержит plain text из общего pipeline, с приведением регистра и пробелов. HTML-теги, удалённый опасный контент и разметка медиа не становятся поисковыми словами. Поиск — буквальная подстрока, включая `%`, `_` и короткие слова; FULLTEXT и его зависимость от языка/минимальной длины пока не используются.

`CollectionSearchIndexer` обновляет индекс через afterCommit C6. Сбой не отменяет уже сохранённый материал и виден вызывающему. Откат не индексирует незакоммиченные данные. Исторический импорт пропускает производные callbacks и вызывает `CollectionsImportApiInterface::rebuildSearch()` один раз после переноса; пересборка может входить в общую транзакцию импорта. `rebuildAll()` вызывается обработчиком установки/обновления. Ручная команда: `collections:rebuild-search [--collection=ID]`. Каждая коллекция пересобирается атомарно, с блокировкой её записи и пакетным чтением ID.

Поиск админки дополнительно сохраняет фильтр по ID и коду. Настройки коллекции позволяют выбрать дополнительные текстовые поля (`settings.search_fields`), без доступа редактора к схеме.

Теги — множественное поле типа `string` с ролью `tags` (код может быть любым). Единая граница сохранения приводит значения к нижнему регистру, убирает крайние и повторные пробелы и дубли, сохраняя порядок первого появления. Точное сравнение `Eq` или `In` также нормализует запрос; `Like` для тегов отклоняется. `php` и `phpstorm` — разные значения.

В форме работает добавление/удаление отдельных тегов и подсказки. Без JavaScript остаётся textarea «одно значение на строку». `CollectionsPublicApiInterface::suggestTags()` применяет доступность коллекции, записи, всех разделов и окно публикации; пользовательский API и административный endpoint проверяют право наполнения конкретной коллекции и могут показывать теги черновиков разрешённому редактору. Подсказки ограничены полем, коллекцией, префиксом и лимитом.

Требуется миграция `create_collection_search_documents` и `system:update` для первичной пересборки.

## Коллекция новостей

`johncms/news` объявляет коллекцию со стабильным ключом `articles`, кодом `news` и правом наполнения `news.manage`. Получение: `findDeclaredCollection('johncms/news', 'articles')`. Модуль зависит от коллекций; менеджер модулей учитывает эту связь при отключении и удалении.

`name`, публикация, авторы, даты, просмотры и анонс используют базовые поля записи, `news_articles.text` соответствует `detail_text`. Поля владельца: `page_title` (роль `meta_title`), `description` (`meta_description`), `keywords` (`meta_keywords`) и множественные строковые `tags` (роль `tags`). `keywords` и `description` имеют тип `text`, чтобы перенос не сужал вместимость старых столбцов. Исходные подписи хранятся в домене `news`. Текст раздела соответствует `description` раздела коллекции, SEO — ключам metadata; существующие файлы при переносе регистрируются через C9 без копирования.

Владелец строит прежние адреса `/news/`, `/news/path/` и `/news/path/article.html` по API дерева коллекций, добавляет защищённый предпросмотр и ссылку `/admin/news/settings`. У коллекции нет второй копии страниц через catch-all или sitemap коллекций.

Маршруты, главная, меню, поиск, sitemap и лента комментариев используют API коллекций. Пункт «Новости» ведёт прямо в рабочее пространство; прежние CRUD-страницы и маршруты `/admin/news` удалены без перенаправления. `/admin/news/settings` остаётся для настроек представления, главной и SEO. Синхронизация создаёт схему, а перенос выполняет хук обновления.

## Связанные данные модулей и чтение новостей

`CollectionLookupApiInterface::findDeclared()` — лёгкий поиск коллекции, подходящий для обработчиков жизненного цикла: он не зависит от сервисов записи и не создаёт циклов DI. Для комментариев, голосов и других связанных данных используйте `CollectionItemRelationsApiInterface::withItemLock($collectionId, $itemId, $operation, publishedOnly: true)`. Операция выполняется в общей транзакции после блокировки коллекции и записи; публикация C4 проверяется блокирующим чтением, включая разделы и коллекцию. Это важно внутри внешней транзакции со старым snapshot. Проверка прав текущего посетителя остаётся обязанностью потребителя. Несуществующая, чужая или недоступная запись отклоняется. `withCollectionLock()` сериализует уборку после commit; она выполняется и для уже удалённой коллекции. В этой транзакции `CollectionFileReferencesApiInterface::isReferenced()` блокирует реестр файла и проверяет актуальные ссылки перед физическим удалением файла владельцем.

`ContentCollectionItemQuery(includeText: false)` исключает анонс и текст из выборки: соответствующие свойства DTO равны null, остальные базовые поля сохранены. Вместе с `fields: []` это позволяет строить sitemap и служебные списки без загрузки больших текстов и EAV-значений.

Новый слой новостей использует `NewsReadServiceInterface`: списки с поддеревьями, карточки, разделы и путь, поиск C11, точные теги, главная, счётчик новых материалов, sitemap и предпросмотр. `NewsArticleViewDTO`/`NewsSectionViewDTO` готовят безопасный HTML, plain-text SEO и представление для существующих Twig-шаблонов через `toTemplate()`. Авторы загружаются пакетно; отсутствующий автор представлен null. Счётчики комментариев, рейтинг и текущий голос также выбираются пакетно. Просмотры регистрируются отдельно, один раз за сессию (`news_viewed_items`), без учёта предпросмотра.

`NewsDiscussionServiceInterface` читает и изменяет обсуждения по `item_id`: запись должна принадлежать коллекции новостей и быть опубликована. Автор действия всегда берётся из `CurrentUser`. Публикация проверяется повторно блокирующим чтением непосредственно перед записью. Комментарии требуют `news.comments.post`, голоса — `news.vote` (по умолчанию User), удаление чужих комментариев и лента модерации — `news.comments.moderate`. IP и другие служебные сведения доступны только модератору. Прямое обращение к сервису применяет те же правила, что HTTP. Повторный голос заменяет предыдущий; уникальность `(item_id, user_id)` дополнительно защищена БД. Чужие и незарегистрированные вложения отклоняются.

Обработчик C6 удаляет комментарии и голоса вместе с записью или поддеревом в одной транзакции. Файлы комментариев удаляются после внешнего commit, с проверкой оставшихся комментариев и ссылок коллекций; файлы чужих каталогов не удаляются. Откат восстанавливает обсуждение и сохраняет файлы. Лента модерации строит ссылки `#article-comments` через владельца.

Требуется миграция news `add_collection_item_to_discussions`: nullable `item_id`, индексы и уникальность голосов. Временные `article_id` и старые FK удаляются хуком обновления после успешного переноса. В работающем модуле связанных FK на таблицы коллекций нет.

### Перенос новостей при обновлении

`NewsLegacyImporter::import()` — фаза данных хука обновления news. Она доступна только в доверенном системном контексте, выполняется под блокировкой коллекции и откатывается целиком при ошибке, включая разделы, EAV, ссылки на файлы и `item_id` обсуждений. Старые строки не удаляются сервисом: вызывающий хук удаляет их после сверки в той же внешней транзакции. Отдельной команды переноса нет: запускается `system:update`.

Переносятся дерево, исходные тексты без экранирования, публикация, даты, авторы, просмотры, SEO и CSV-теги. Удалённые разделы вместе с потомками и статьи этих ветвей исключаются. `NewsLegacyImportReportDTO` содержит карты ID, проверенные URL, количества и предупреждения. Канонические URL статей сохраняются: одинаковые коды в разных разделах обозначают собственные статьи. Старая ошибка поиска только по коду не воспроизводится. При совпадении одного адреса первый ID сохраняет код, остальные получают `-legacy-<ID>`; сначала резервируются все исходные коды. Пустые коды генерируются из названия. Все изменения перечисляются в отчёте. Конфликт с уже существующей записью коллекции останавливает перенос, не изменяя её. Повреждённое дерево, JSON вложений или даты также требуют явного исправления данных. Нулевые даты MySQL заменяются на NULL с предупреждением; отсутствующий реестр файла попадает в предупреждения, остальные файлы регистрируются без копирования.

Кандидаты на уборку файлов исключённых статей сохраняются транзакционно в `news_legacy_cleanup_files`, чтобы сбой после commit не потерял очередь. После commit хук удаляет сиротские обсуждения, обрабатывает очередь файлов и удаляет старые таблицы и `article_id`. Общие файлы статей и комментариев сохраняются до последней ссылки. Внутренний `CollectionFileReferencesApiInterface::transferOwnership($fileId, $toCollections)` передаёт ответственность за физическую уборку под блокировкой отношений вызывающего: добавляя внешнюю ссылку, владелец принимает ответственность; после удаления последней внешней ссылки передаёт её коллекциям, если там остались ссылки. `registeredFileIds()` позволяет доверенному интегратору сверить ссылки конкретной записи. Эти методы не дают посетителю права читать или присваивать файл.

Хук `NewsStorageUpdater` сначала снимает старые FK вне транзакции данных. Импорт, сверка, запись `item_id` и удаление старых строк выполняются одной транзакцией без DDL. При сбое данные откатываются целиком; повторный запуск строит карты ID заново. Если строки уже удалены, повторный запуск выполняет только оставшуюся уборку. Очередь файлов подтверждается по одному ID, поиск пересобирается перед окончательным удалением старой схемы. Сбой уборки останавливает обновление; частично выполненный MySQL DDL не откатывается, поэтому перед обновлением обязательна резервная копия БД и загрузок. Отчёт виден в выводе `system:update` (в том числе журнала административной задачи) и общем логе приложения.

Пока обновление не завершено, публичные маршруты возвращают 503 с `Retry-After`, а рабочее пространство, загрузки и изменения новостей через PHP API запрещены. Дополнительные ограничения владельца реализует `CollectionContentAccessProviderInterface` (тег `johncms.collections.content_access`): они применяются и к управляющему схемой. Обработчик C6 защищает также прямые доверенные операции записи вне системного контекста. Разрешение доверенного хука не активируется входными данными HTTP. Вызовы голосования, добавления и удаления комментариев и загрузок принимают POST с CSRF; публичные чтения — прежние GET URL. Полный `system:update` после всех хуков пересобирает sitemap перед отметкой завершения.

## Настройки ввода и defaults полей

`CollectionFieldFormDTO.settings` хранит `hint` (до 2000 символов), `default`, `min_length`, `max_length`, `min_value`, `max_value` и `max_values`. Эти параметры доступны в форме поля; подсказка выводится как текст с экранированием. Для объявленных модулем полей в `hint` сохраняется исходный msgid, при показе используется `label_domain` поля. Для извлечения строки в декларации задавайте `CollectionLabelDTO::translatableLabel('news', 'English hint')->message`. Пользовательские поля без домена выводят подсказку буквально. Длина измеряется в Unicode-символах исходного значения, числовые границы включаются в диапазон. Для integer границы — целые числа, сравнение сохраняет точность 64-битных целых. Для double принимаются конечные числа. Строковое хранилище по-прежнему ограничено 255 символами; ограничение количества значений — от 1 до 1000 (по умолчанию 1000). Неподходящие ограничения и default отклоняются при сохранении схемы, в том числе в декларациях. Дополнительные настройки расширений сохраняются; весь объект — JSON-совместимые значения, глубина до 32, размер до 65535 байт.

Default передаётся строкой, а для множественного поля — списком строк, как вход PHP API. Например, integer: `'12'`, date: `'2001-02-03'`, boolean: `'0'`/`'1'`, multiple boolean: `['1', '0']`. Он применяется до общей валидации только при создании записи без ключа поля. Явная пустая строка или пустой список подавляют default. Обновление и patch не подставляют его заново, исторический импорт также сохраняет отсутствие значений. Даты и Boolean возвращаются через API с обычными типами DTO. Пустые строки множественного Boolean пропускаются, явный `'0'` сохраняет false и его позицию.

Обычная форма или `CollectionSchemaApiInterface::saveField()` не меняет тип/множественность поля, пока существуют значения: проверка выполняется актуальным блокирующим чтением под блокировкой коллекции. Пустое поле менять можно. Явное преобразование остаётся задачей доверенного системного хука: изменение схемы и преобразование всех значений должны идти в одной внешней транзакции. Наличие доверенного контекста не преобразует EAV автоматически.

Множественные значения в форме передаются отдельными контролами: многострочные Text/HTML не разбиваются по переводам строк, Boolean false сохраняется как отдельное значение.

### Добавление и порядок множественных значений

В форме записи и в списке defaults доступны «Добавить значение», «Удалить значение», «Поднять» и «Опустить». Контролы каждого значения отправляются отдельным элементом массива; порядок DOM соответствует порядку EAV. Переводы строк в Text/HTML и Boolean false сохраняются. Теги продолжают использовать собственный ввод с нормализацией и подсказками.

Без JavaScript кнопки отправляют обычный POST с CSRF и повторно показывают введённую форму: не сохраняют запись или схему, не теряют другие поля и загрузочный контекст. Только «Сохранить» применяет данные и запускает общую валидацию. Сервер проверяет принадлежность записи, известную множественную группу, индекс, действие и лимит. Ошибка сохраняет точные введённые строки, включая пустые контролы, и показывает сообщение у группы.

JavaScript выполняет те же операции на странице и сохраняет обычную отправку формы. Новые HTML-контролы получают независимые административные редакторы, удалённые экземпляры освобождаются вместе с обработчиками формы. Во время загрузки редактора или изображения удаление соответствующего значения и отправка формы блокируются с сообщением. Идентификаторы и подписи остаются уникальными после добавления, удаления и перестановки.

### Select: постоянные коды и доступность вариантов

В `settings.options` передаётся упорядоченный список до 500 объектов: `['code' => 'small', 'label' => 'Small', 'active' => true]`. Код — до 255 латинских букв, цифр, точек, плюсов, дефисов или подчёркиваний; коды уникальны без учёта регистра. Подпись — до 255 символов. `active` — boolean, по умолчанию true. Общий предел settings в 65535 байт также действует. Форма поля позволяет добавлять, удалять и переставлять варианты; без JS работают POST-кнопки предварительного редактирования. При повторном выводе не теряются соответствия кодов, подписей и доступности.

API возвращает коды. Административные списки и общий публичный вывод показывают подписи с обычным экранированием; изменение подписи не переписывает EAV. Одиночный выбор использует select, множественный — повторяемые select-контролы. Дубли выбираемых кодов сохраняются один раз, в порядке первого появления. Default должен ссылаться на доступный вариант.

Отключённый вариант можно оставить только в записи, где он уже сохранён; после удаления этого выбора назначить его заново нельзя. Это проверяется общей валидацией формы, add/update и patch по актуальным значениям записи. Доверенный исторический импорт может регистрировать объявленный неактивный вариант. Неизвестный старый код показывается как прежний вариант и сохраняется при редактировании его записи, но не назначается новым записям.

Использованный код нельзя удалить или изменить, включая регистр: его можно отключить. Неиспользованные варианты разрешено удалять. Синхронизация деклараций сохраняет использованные варианты до явного преобразования владельцем; финальная проверка сообщает о необходимости хука. Замена options и переписывание всех затронутых значений выполняются доверенным хуком в одной внешней транзакции. Обычные операции схемы это ограничение не обходят.

Сохранение и patch используют актуальные блокирующие определения полей и повторно применяют эти же определения при записи EAV. Устаревшая транзакция не может выбрать уже отключённый вариант по старому snapshot; конкурентный конфликт требует повторения всей операции.

Формы записей и схемы отмечают начало и конец полного набора контролов. Если PHP усёк автоматически отправленную большую форму, сохранение и предварительные действия отклоняются: частичный набор не заменяет записи или options. Уменьшите форму или настройте `max_input_vars` на сервере. Прямые PHP API и старые явные POST-клиенты без этих маркеров сохраняют свои контракты полной/частичной записи.

### Relation: целевая коллекция и целостность ссылок

Поле `Relation` задаёт `settings.target_collection_id` — положительный целочисленный ID существующей коллекции. Настройка доступна и в форме поля. API принимает ID записей строками, для множественного поля — списком строк; возвращает целые числа. Общая запись add/update/patch проверяет существование каждой цели и принадлежность именно указанной коллекции. Это действует также для defaults и исторического импорта. Цели читаются с блокировкой по возрастанию ID.

По умолчанию удаление запрещено, если на запись ссылаются другие сохраняемые записи. Сначала очистите эти связи. Проверка происходит в одной транзакции до обработчиков удаления и использует актуальное блокирующее чтение, включая определения полей: старый snapshot не скрывает только что созданную связь. При конкурентном конфликте повторите всю транзакцию. Ссылки внутри атомарно удаляемой ветки/коллекции, включая циклы, не препятствуют её удалению; внешняя ссылка откатывает всю операцию. Одиночная запись может ссылаться на себя.

Удаление целой коллекции требует предварительно удалить или перенастроить поля связи в других коллекциях, даже если они пусты. Это сохраняет корректность схемы. Поля самой удаляемой коллекции удаляются вместе с ней. Смена цели заполненного поля требует явного преобразования в доверенном хуке в одной транзакции; обычная форма/API её не допускают. Синхронизация декларации сохраняет прежнюю цель заполненного поля до такого преобразования.

Форма записи показывает одиночные и повторяемые select-контролы с названиями целей. Поиск по названию выводит до 30 результатов; выбранные записи остаются доступными независимо от текущей страницы результатов. Названия экранируются, специальные символы поиска трактуются буквально. Поиск использует актуальные названия записей без ожидания перестроения индекса. JavaScript обновляет варианты на месте, сохраняет выбор и обновляет шаблон новых строк. Без JavaScript кнопка поиска отправляет POST с CSRF и сохраняет введённые поля, порядок, тексты и контекст загрузки; запись сохраняется только кнопкой сохранения.

`GET /admin/collections/{id}/relations/{code}?q=...` возвращает `options` с `code` (ID-строка) и `label` (название). Нужны права заполнения исходной и целевой коллекции; права на публичный просмотр не предоставляют доступ к закрытым и неопубликованным целям. Ответ содержит только ID и название. Отказ не раскрывает названия в форме, включая уже выбранную недоступную цель.

`CollectionsUserApiInterface` и административная форма проверяют права текущего посетителя на целевую коллекцию перед новыми назначениями, включая defaults. Значение, которое запись уже хранит, повторно не проверяется: редактор исходной коллекции сохраняет запись, не открывая цель. Явная очистка и patch других полей права на прежнюю цель тоже не требуют. Определения полей читаются актуально под блокировкой исходной коллекции в одной транзакции с записью; смена схемы не может вклиниться между проверкой прав и назначением. `CollectionsApiInterface` остаётся доверенным PHP API для модулей: проверяет структуру, но не права HTTP-посетителя.

#### Политика удаления и подтверждение последствий

`settings.on_delete` принимает `restrict` (по умолчанию) или `clear`. Для обязательных полей допустим только `restrict`; даже старое несовместимое определение никогда не очищается молча. `clear` удаляет только значения, ссылающиеся на удаляемую цель. Другие значения множественного поля и их порядок сохраняются. Политика доступна в форме схемы.

Изменённые исходные записи получают системного редактора (`updated_by = null`), актуальное `updated_at` и обычное событие C6 `item/saved`. Обязательные обработчики выполняются в той же транзакции; ошибка любого из них откатывает и очистку, и удаление цели. Производные работы запускаются после внешнего commit. Отсутствующий модуль-владелец связанной записи блокирует операцию: его обязательные обработчики нельзя пропустить.

Defaults всегда препятствуют удалению целей: сначала измените значение по умолчанию в схеме, даже если включён `clear`. Иначе новое заполнение использовало бы несуществующий ID. Удаление коллекции не учитывает defaults её собственных удаляемых полей. Внешние поля, нацеленные на удаляемую коллекцию, по-прежнему требуют удаления/перенастройки.

Подтверждение показывает числа очищаемых и блокирующих значений, полей с defaults и внешних полей схемы, без названий или содержимого связанных записей. При переносе записей связи сохраняются. Ревизия подтверждения удаления ветки/коллекции включает текущие входящие связи и их определения. Новая связь, смена политики или изменение связанной записи требуют повторного подтверждения. Внутренние связи атомарно удаляемой группы исключаются из последствий.

`CollectionsApiInterface::previewItemDeletion(id)` и пользовательский вариант `previewItemDeletion(collectionId, id)` возвращают `CollectionRelationImpactDTO` со счётчиками `clearValues`, `blockedValues`, `defaultFields`, `schemaFields` и `revision`. В `deleteItem()` можно передать `expectedRelations` для проверки этой ревизии. Доверенный PHP API может выполнять удаление без предварительного просмотра. HTTP передаёт `relation_revision`; очистка чужих значений без свежего подтверждения отклоняется. Обычное удаление без побочных очисток сохраняет совместимость со старыми явными POST-клиентами. Конкурентные конфликты блокировок требуют повторения всей внешней транзакции.

### File: зарегистрированные значения и отдельные ссылки

Новые поля, создаваемые формой или `saveField()`, используют `settings.file_storage = 'registry'`. В EAV хранятся положительные ID реестра `files` строками; множественное поле принимает список строк и сохраняет его порядок. ID возвращаются строками, как остальные прежние значения File. Допускаются зарегистрированные файлы уже сохранённого контента/defaults этой коллекции или файлы текущего действующего контекста загрузки редактора. Случайный ID из реестра, файл другой коллекции или неподходящий контекст не дают права назначения. Проверка и создание ссылок выполняются в транзакции записи с блокировкой коллекции и assets.

Таблица `collection_file_value_links` хранит отдельные ссылки полей. Строка с `item_id = null` представляет значение по умолчанию; остальные строки принадлежат значениям записи. Общие вложения текста C9 остаются в `collection_file_links`. Очистка поля не удаляет самостоятельную ссылку из текста или другого поля/default. Defaults удерживают файл после удаления исходной записи. Общий `hasLinks()` и интеграция владельцев учитывают оба вида ссылок.

Замена значений, удаление записи/поля и изменение default освобождают только соответствующие ссылки. Физическая уборка выполняется после внешнего commit, при отсутствии всех ссылок, и только для assets, которыми владеют коллекции. Откат восстанавливает EAV и ссылки, сохраняя байты. Внешние файлы не становятся собственностью коллекций автоматически. Исторический импорт в доверенном системном контексте может регистрировать существующие ID с внешним владением; передача владения по-прежнему выполняется явно через C9.

Существующие File без `file_storage` сохраняют режим `legacy`: строки-пути остаются строками, включая строки, похожие на ID. Обычное изменение режима заполненного поля запрещено. Для преобразования выполните замену EAV путей на реальные зарегистрированные ID и смену режима в одной доверенной внешней транзакции. Общий обработчик схемы проверит ID и восстановит ссылки для каждого значения и default. Ничего не преобразуется по числовому виду строки.

Декларации модулей указывают `file_storage = 'registry'` явно; старое определение без режима остаётся совместимым с legacy. Синхронизация не меняет режим заполненного поля до хука преобразования и применяет обязательные файловые инварианты для зарегистрированных полей.

#### Загрузка и ограничения файлового поля

Для `registry` задаются `max_file_bytes` (целое число 1..1073741824, по умолчанию 10485760) и `allowed_mime_types` (непустой список поддерживаемых MIME, по умолчанию все поддерживаемые). Форма схемы показывает размер в байтах и список форматов. Поддерживаются JPEG, PNG, GIF, WebP, PDF, TXT, ZIP, MP3, OGG и MP4: соответствующие MIME — ключи `CollectionFilePolicy::TYPES`. Серверные лимиты HTTP и глобальные ограничения обработки изображений продолжают действовать. Legacy-пути сохраняют прежнюю семантику и не переинтерпретируются этими настройками.

`POST /admin/collections/{id}/uploads?field={code}&context={token}` принимает multipart `upload` с CSRF. Контекст должен принадлежать текущему редактору и этой коллекции, поле — существовать и использовать registry. Размер берётся из временного файла, MIME определяется по содержимому; переданные браузером имя, MIME и размер не предоставляют обхода. Расширение пути хранения выбирается из подтверждённого типа. Изображения проходят общий обработчик с сохранением исходного формата поля, независимо от настройки перекодирования редактора.

После обработки ещё раз проверяются размер/тип сохранённого файла и актуальные настройки поля под блокировкой коллекции. Удаление поля, изменение кода/типа/режима, нарушение новых ограничений либо чужой/ истёкший контекст отменяют регистрацию загрузки с компенсацией новых байтов. JSON успеха сохраняет контракт C9: `id`, `name`, `url`, `uploaded = 1`; ошибки полей возвращаются с 422. Запрос без `field` остаётся загрузкой изображения редактора.

Ссылки контекста файлового поля помечены `field_id` и при сохранении не копируются в общие вложения текста. Выбранные файлы удерживаются ссылками значений, невыбранные удаляются после внешнего commit. При ошибке формы/откате контекст и файлы сохраняются; действует обычный срок уборки C9. Самостоятельные вложения текста продолжают удерживать свои файлы.

Общие проверки сохранения, patch, defaults и изменений схемы проверяют доступность файла, его размер и MIME на хранилище. Сужение ограничений, делающее сохранённые значения/defaults некорректными, отклоняется до явного преобразования. Старый NULL-размер реестра читается с диска без изменения исходной записи. Недоступный файл выдаёт ошибку восстановления/повторной загрузки.

#### Выбор, предпросмотр и работа формы

Registry-поля используют select с именами и размерами доступных файлов. Поиск по имени возвращает до 30 подходящих файлов этой коллекции и собственных загрузок текущего контекста; действуют MIME/размер поля. Выбранные значения сохраняются независимо от результатов поиска. Путь, похожий на ID, в legacy-поле остаётся обычным текстом.

`GET /admin/collections/{id}/files/{code}?context=...&q=...` возвращает `files` — список `CollectionFileChoiceDTO` (`code`, `label`, `url`, `size`, `sizeLabel`, `image`, `inResults`). Для чтения нужен доступ заполнения коллекции; чужой контекст не раскрывает файлы. Недоступные или несовместимые записи не предлагаются. Текущий некорректный выбор показывается явно, с возможностью замены/очистки, без раскрытия метаданных постороннего ID.

Форма показывает ссылку, размер и превью изображения; каждое множественное значение имеет собственные выбор, загрузку и очистку. Названия экранируются, в JavaScript используются текстовые узлы. «Очистить выбор» и удаление строки меняют черновик; EAV/ссылки освобождаются при сохранении. Административный список показывает имена файлов, общий публичный вывод — ссылки и размеры. Системные DTO значений сохраняют ID-строки.

JavaScript обновляет поиск и загрузку на месте, сохраняя выбранные файлы. Новые повторяемые строки получают актуальную библиотеку, имена multipart-контролов следуют порядку строк. Загрузка привязана к самому контролу: перестановка не направляет результат в другую строку. Удаление загружаемой строки и сохранение во время загрузки блокируются с сообщением. Сброс отменяет ожидание ответа и восстанавливает исходный выбор; поздний ответ его не меняет.

Без JavaScript форма использует multipart POST. Перед поиском, перестановкой или сохранением новые выбранные файлы загружаются в контекст и становятся выбранными значениями черновика. Ошибка следующего файла сохраняет уже успешные загрузки и остальные введённые поля; запись не сохраняется. Кнопка «Загрузить» позволяет сделать это отдельно от сохранения.

При достижении `max_file_uploads` обычная отправка отклоняется целиком: PHP может незаметно отбросить лишние файловые части, поэтому полное получение на границе лимита не доказуемо. Отправляйте меньше файлов за раз или используйте отдельные загрузки с JavaScript. Проверяется также превышение `post_max_size`; маркеры полной формы продолжают защищать от усечения полей.

Физическая уборка сохраняет правила C9/P1e.2: невыбранные загрузки очищаются после commit, неудача формы и откат сохраняют контекст, самостоятельные и разделяемые ссылки учитываются.

### Подписи и действия рабочего пространства

`CollectionFormDTO::workspace` задаёт пользовательские настройки интерфейса. `null` сохраняет ранее заданные настройки, `[]` сбрасывает их. Пока поддерживается `labels` с ключами `singular`, `plural`, `new`, `create`, `edit`, `delete`: непустые строки до 120 символов. Они выводятся буквально с экранированием. В настройках коллекции пустое поле означает наследование переведённой подписи по умолчанию.

Модуль задаёт исходные подписи через `settings['_workspace']['labels']` декларации; `CollectionLabelDTO::translatableLabel('news', 'News item')->toArray()` сохраняет домен и msgid, а перевод выполняется при показе. Синхронизация обновляет эти defaults, сохраняя пользовательский `settings['workspace']`. Новости используют подписи «Новость», «Новости», «Добавить новость».

Форма записи предлагает «Сохранить и продолжить редактирование», предпросмотр и переход на сайт. Ссылки используют существующие проверки владельца и публикации; они показывают сохранённую версию. Создание, редактирование и отмена сохраняют фильтры и страницу исходного списка через `back`. Принимается только URL списка этой коллекции, внешние адреса и управляющие символы отклоняются. Усечённая форма настроек не сохраняется.

### Группы, порядок и скрытые блоки формы

`workspace.layout.fields` — карта кодов существующих полей. Каждая запись допускает `group` (название группы до 120 символов) и `sort` (целое от −1000000 до 1000000). Пустые поля настроек наследуют defaults владельца, затем исходный порядок схемы. Группы идут по первому полю в отсортированном списке; поля без группы объединяются в «Поля коллекции». Настройки не меняют `sort`, роли или защищённость самих определений полей. Поля, добавленные позже, остаются видимыми.

Владелец может объявить `settings['_workspace']['layout']` с той же структурой; название группы допускает `CollectionLabelDTO::translatableLabel(...)->toArray()`. Пользовательские названия буквальны. Новости по умолчанию выводят теги в группе «Содержимое», метаданные — в «SEO».

`workspace.layout.hidden_blocks` — список из `code`, `preview_text`, `detail_text`, `publication` (активность и даты), `place` (раздел и сортировка). Название скрыть нельзя. При редактировании сервер сохраняет исходные значения скрытых блоков, игнорируя их в POST; у новой записи действуют обычные defaults. Это настройка интерфейса: программное API по-прежнему может менять эти поля. Настройки доступны и без JavaScript. Неизвестные поля/блоки и неверные типы отклоняются до записи.

### Колонки, фильтры и сортировка списка

`workspace.listing` и defaults владельца `_workspace.listing` допускают:

* `columns`: упорядоченный список `author`, `created_at`, `updated_at`, `views`, `section`. Дополнительные поля с `in_list` продолжают выводиться отдельно; авторы загружаются пакетом.
* `filters`: список доступных дополнительных фильтров `author`, `created_at`, `views`. Поиск, статус и иерархический раздел остаются базовыми фильтрами.
* `sort`: `{field, direction}`. Разрешены только `sort`, `id`, `name`, `created_at`, `updated_at`, `view_count`, `active_from`; направление — `asc` или `desc`. ID обеспечивает стабильный порядок при совпадении выбранного значения. Произвольные SQL-поля/выражения и EAV-сортировка не принимаются.

GET списка понимает `order`, `direction`, `author` (положительный ID), `created_from`, `created_to` (календарные ISO-даты включительно), `min_views` (неотрицательное целое). Отключённые фильтры игнорируются, неверная сортировка заменяется настройками коллекции. Фильтры и выбранная сортировка сохраняются в поиске, ссылках фильтров, пагинации и возврате из редактора. Дополнительная форма работает обычным GET; фрагменты списка возвращают её актуальное состояние.

По умолчанию сохраняется прежний порядок `sort ASC, id ASC`, колонки раздела и обновления. Новости задают автора, создание, просмотры и раздел, все дополнительные фильтры и `id DESC`.

### Детальные права на содержимое

`CollectionFormDTO::actionPermissions` задаёт карту `create`, `edit`, `publish`, `delete`, `sections` → ключ права. `null` сохраняет настройку, `[]` возвращает наследование. Настройка хранится в `settings.content_actions` и доступна в форме коллекции. Для действия одновременно нужны базовый доступ C8 и выбранное право с областью ID коллекции. Незаданные действия наследуют базовое право: существующие редакторы сохраняют прежние возможности. `collections.manage` по-прежнему даёт полный доступ. Объявление владельца не перезаписывает эту пользовательскую политику.

Зарегистрированы права `collections.items.create`, `.edit`, `.publish`, `.delete` и `collections.sections.manage` без автоматической выдачи ролям. Их можно выбрать в настройках действий или использовать права другого модуля. Само назначение детального права не заменяет базовый доступ к коллекции; проверка создания/редактирования также защищает контексты и загрузки.

Публикация требуется для изменения активности, дат и переноса активной записи. Изменение текста уже активной записи остаётся правом `edit`. Создатель без публикации создаёт неактивные записи. В его форме нет контролов публикации; неизменяемые даты сохраняются с исходными секундами. Пользовательский API проверяет полную форму и patch одинаково, под текущими блокировками записи и коллекции. Переданный флаг или частичный запрос не обходят права. Доверенный API модулей сохраняет прежний контракт.

Разделы требуют `sections`; активация/деактивация и перенос активного раздела дополнительно требуют `publish`. Переименование и создание неактивных разделов доступны без него. Удаление ветки вместе с записями требует `delete`; удаление с переносом записей — `edit` и `publish`. Форма и API используют одинаковые проверки, недоступные действия скрываются из списка и вкладок.

### Массовые действия

`CollectionBulkApiInterface` — пользовательский API атомарных операций. `preview(collectionId, ids, action, targetSectionId)` возвращает `CollectionBulkPreviewDTO`: отсортированные ID и названия, ревизию, целевой раздел и последствия для связей. `execute(collectionId, ids, action, revision, targetSectionId)` требует эту актуальную ревизию и возвращает число обработанных записей. Допускается от 1 до 100 разных положительных целочисленных ID одной коллекции.

Действия: `publish` включает записи сразу и очищает обе даты публикации; `hide` выключает, сохраняя даты; `move` меняет только раздел (`null` — корень); `delete` удаляет записи и вызывает обычную очистку связей, файлов и данных владельца. Публикация/скрытие требуют `edit` и `publish`, перенос — `edit` и дополнительно `publish` для активных записей; удаление требует `delete`. Проверки прав каждой записи и обычные правила одиночного сохранения выполняются повторно.

Коллекция, определения полей, дерево разделов, выбранные записи/значения и входящие связи читаются под текущими блокировками. Ревизия покрывает действие, состав, содержимое, структуру, политику доступа и последствия удаления. Обычный рост счётчика просмотров выбранной записи не требует нового подтверждения. Изменение действия, раздела, состава или содержимого требует заново проверить выборку. Внутренние циклы между удаляемыми записями не блокируют пакет; внешние restrict/defaults блокируют весь пакет, optional clear показываются при подтверждении.

Пакет выполняется в одной внешней транзакции. Ошибка данных, прав, конфликта кодов или обязательного обработчика откатывает предыдущие записи и связанные изменения. Частичного успеха нет. Производные обработчики и физическая уборка остаются после внешнего commit по контракту C6; их ошибки не отменяют уже зафиксированную транзакцию.

Админка предлагает флажки строк текущей страницы, действие и раздел назначения, затем отдельное подтверждение. Формы работают обычным POST без JavaScript, используют CSRF и безопасный `back` исходного списка. Маркер полной формы расположен после всех внешних флажков; усечение не может незаметно превратить пакет в меньшую выборку. После успеха показывается точное число обработанных записей; ошибки конфликта кодов и изменившейся выборки объясняют причину отказа. Пустая, повторная, слишком большая или чужая выборка отклоняется целиком. Настройки списка сворачиваются нативным `details`, чтобы дополнительные фильтры не вытесняли записи на узком экране.

### Живая транслитерация кода

В формах записей, разделов и обычных коллекций код связан с названием по умолчанию. При вводе названия поле обновляется через серверный `Str::slug` — тот же алгоритм, который используется при автоматическом сохранении записи. Кнопка с цепочкой снимает связь и открывает ручной ввод; повторное включение пересчитывает значение. Кнопка обновления внутри поля однократно формирует код, не меняя режим связи. На широком экране цепочка находится между полями, на узком — рядом с подписью кода. При запросе обновление заменяется небольшим прелоадером без изменения высоты формы. Защищённый код коллекции владельца остаётся неизменяемым.

Открытие существующей формы не меняет сохранённый код. Выбранный ручной режим и код сохраняются при ошибках и вспомогательных отправках формы. Без JavaScript остаётся обычное редактируемое поле. Изменение названия при включённой связи меняет код, а значит и адрес материала; уникальность по-прежнему проверяется при сохранении.

Общий компонент `@admin/components/ui/slug-field.twig` отправляет POST с названием и CSRF-токеном: `/admin/collections/slug` требует управления структурой, `/admin/collections/{id}/slug` — доступа к содержимому этой коллекции. Ответ `{slug}` не сохраняет данные и не резервирует уникальный код; результат ограничен 240 символами. Запросы выполняются после короткой паузы ввода, предыдущие отменяются; поздние ответы не меняют ручной ввод и сброшенную форму. Отправка ждёт актуального результата, сохраняя исходную кнопку действия. Ошибка генерации позволяет повторить запрос либо снять связь и ввести значение вручную.
