Устранение неполадок и FAQ¶

Когда директория Flex ведёт себя неправильно, причина почти всегда в одном из нескольких обычных подозреваемых: директория, которую так и не включили, блок разрешений, который так и не объявили, стратегия хранения, которая не может хранить медиафайлы, или кэш, который нужно очистить. Эта страница — справочник «симптом — причина — исправление». Найдите заголовок, совпадающий с тем, что вы видите, и пройдите проверки по порядку.

Моя директория не появляется в боковой панели Admin Next¶

Зарегистрированная, но невидимая директория — обычно одна из этих:

1. Плагин Flex Objects отключён. Проверьте в Admin Next в разделе Plugins, что Flex Objects включён. Без него ничего не рендерится.
2. Директория не включена. Файл схемы, лежащий в user/blueprints/flex-objects/, не активен, пока вы его не включите. Перейдите в Plugins > Flex Objects и добавьте схему в поле directories. Это дописывает путь к схеме в конфигурацию плагина; без этого тип никогда не регистрируется.
3. У текущего пользователя нет разрешения на вывод списка. Автоматическая боковая панель показывает только те директории, которые текущей учётной записи разрешено выводить списком. Не-супер-учётной записи нужно api.<type>.list (см. симптом про разрешения ниже). Если вы тестируете под редактором, у него пункт отсутствует, а у суперадминистратора есть — причина именно в этом.
4. Директория отказалась от боковой панели. В схеме можно задать admin.menu.list.hidden_in_admin_next: true, чтобы не попадать в автоматическую боковую панель (например, когда плагин предоставляет собственную навигацию). Если этот флаг задан, директория намеренно скрыта.
5. Кэш устарел. После включения директории или правки её схемы запустите bin/grav clear, чтобы зарегистрированные типы пересобрались.

REST API возвращает 403 для моей пользовательской директории¶

Это самая частая проблема поддержки Flex начиная с flex-objects 1.4.3, и всё работает как задумано.

Исправление безопасности в 1.4.3 (GHSA-23vq-365v-qcmh) ввело отказ по умолчанию: директория, схема которой не определяет блок config.admin.permissions, закрыта для всех, кроме суперадминистраторов, по REST API. Если у вашей пользовательской директории разрешения не объявлены, до неё могут добраться только суперадминистраторы, а все остальные получают 403.

Исправление — объявить разрешения в схеме. Объявите оба префикса: admin.<type> (устаревший, для классических учётных записей) и api.<type> (для Admin Next и REST API), а затем предоставьте действующему пользователю нужные действия.

config:
  admin:
    permissions:
      admin.contacts:
        type: crud
        label: 'Contacts'
      api.contacts:
        type: crud
        label: 'Contacts (API)'

Flex использует действия list, create, read, update и delete. Чтобы редактор мог просматривать и открывать записи, не меняя их, предоставьте api.contacts.list и api.contacts.read. Добавьте create, update и delete по мере необходимости для роли.

Полную структуру блока разрешений см. в разделе Права доступа справочника по схемам, а о том, как токены и разрешения проверяются для каждого эндпоинта, — в документации API Flex Objects.

Загрузка медиафайлов не работает, или у моих объектов нет медиафайлов¶

Не каждая стратегия хранения поддерживает медиафайлы для отдельных объектов. Стратегия хранения задаётся в config.data.storage:

Если поле медиафайла или файла не принимает загрузки либо у ваших объектов будто бы никогда нет медиафайлов, вы почти наверняка на SimpleStorage. Переключите директорию на FolderStorage, чтобы у каждого объекта была своя папка:

config:
  data:
    storage:
      class: 'Grav\Framework\Flex\Storage\FolderStorage'
      options:
        folder: 'user-data://contacts'

Мои данные устарели, или правки не отображаются¶

Flex использует индекс для быстрого вывода списков и поиска, и этот индекс кэшируется. Когда то, что вы видите, отстаёт от файлов на диске, запустите:

bin/grav clear

Две вещи, которые стоит знать:

• Кэширование индекса. Индекс коллекции строится один раз и кэшируется. Если вы правите файлы объектов напрямую на диске (а не через Admin Next или API), индекс не заметит этого, пока не будет очищен кэш или не изменятся исходные файлы на диске.
• Оговорка про сохранение в одну секунду. Flex частично определяет изменения по времени модификации файла, которое имеет разрешение в одну секунду. Два сохранения одного и того же объекта в одну секунду могут выглядеть для индекса одинаково, поэтому второе изменение может не зарегистрироваться до следующего сохранения или очистки кэша. Если вы скриптом делаете быстрые последовательные записи в один объект, разнесите их по времени или очищайте кэш между ними.

Объекты исчезли или не сохраняются после правки схемы¶

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

• Сохраняйте старые объекты загружаемыми и сохраняемыми. Если вы переименовываете или удаляете поля, помните, что существующие файлы всё ещё содержат старые ключи. Пока объект можно загрузить и сохранить, эти значения сохраняются при записи, даже если они больше не показываются в форме. Избегайте изменений, которые делают ранее корректные данные нечитаемыми.
• Повреждённые файлы пропускаются. Когда Flex строит индекс, файл, который он не может разобрать (недопустимый YAML/JSON/Markdown, оборванная запись, неверное расширение для настроенного форматтера), пропускается, а не обрывает всю коллекцию. Поэтому один плохой файл заставляет один объект «исчезнуть» из списка, пока остальные загружаются нормально. Проверьте исчезнувший файл на синтаксическую ошибку и убедитесь, что его формат соответствует настроенному форматтеру директории (Json, Yaml, Markdown, Serialize, Ini или Csv).

Колонки списка пустые¶

Вид списка Admin Next рендерит колонки, названные в config.admin.list.fields. Пустые колонки почти всегда означают несовпадение имён:

• Каждое поле из списка должно существовать в form.fields. У ключа в admin.list.fields, который не определён в форме, нет значения для рендеринга, поэтому колонка остаётся пустой. Проверьте опечатки и поля, которые вы удалили из формы, но оставили в конфигурации списка.
• Вложенным значениям нужен путь через точку. Если значение лежит внутри вложенного поля (например, группы адреса), ссылайтесь на него полным путём через точку, вроде address.city, а не просто city.

config:
  admin:
    list:
      fields:
        name:
          link: edit
        email: true
        address.city: true

Изменения схемы не вступают в силу¶

Если правки схемы будто бы игнорируются, проверьте две вещи:

1. Очистите кэш. Схемы компилируются и кэшируются. Запускайте bin/grav clear после любой правки схемы.
2. Убедитесь в расположении файла. Схема пользовательской директории лежит в user/blueprints/flex-objects/<type>.yaml. Если тип поставляется плагином или темой, его схема лежит внутри этого пакета, и копия, положенная в другое место, — не тот файл, который загружается. Убедитесь, что вы правите файл, действительно зарегистрированный в конфигурации директорий плагина.

Перенос типа Flex из 1.7 в 2.0¶

Если вы переносите директорию Flex из Grav 1.7, большая часть схемы переносится без изменений. Работа состоит в удалении конфигурации, нацеленной на старую классическую админку (Vue), и добавлении префиксов разрешений, которые требует новый стек. Пройдите по этому контрольному списку:

• Удалите конфигурацию админки, специфичную для классики. Классическая админка на Vue была удалена в flex-objects 1.4.2. Удалите любую конфигурацию, которая имела смысл только там: пользовательские блоки router и redirects, привязанные к старой админке, подсказки списка VueTable и любой пользовательский вид preview. Вместо этого Admin Next строит интерфейс списка и редактирования по config.admin (list.fields, list.options, edit, export).
• Добавьте префиксы разрешений api.<type>. Это шаг, который забывают. Схема 1.7 обычно объявляла только разрешения admin.<type>. При отказе по умолчанию (1.4.3+) не-супер-пользователям нужен ещё и префикс api.<type>, иначе REST API и Admin Next будут возвращать 403. Объявите оба префикса и предоставьте редакторам нужные действия.
• Проверьте путь хранения. Убедитесь, что config.data.storage всё ещё указывает на нужное место и что стратегия соответствует вашим потребностям (используйте FolderStorage, если у типа есть медиафайлы). Потоки вроде user-data:// должны разрешаться туда, где реально лежат ваши записи.
• Повторно проверьте медиафайлы. Если у типа есть поля медиафайлов или файлов, после переноса загрузите и удалите файл через Admin Next, чтобы убедиться, что папка хранения доступна для записи и медиафайлы для отдельных объектов работают от начала до конца.
• Очистите кэш и перепроверьте обе стороны. Запустите bin/grav clear, затем убедитесь, что директория появляется в боковой панели Admin Next, выводит свои объекты и отвечает через REST API и для суперадминистратора, и для обычной учётной записи редактора.