AdminYard — минимальная админка на PHP для легаси-проектов
Что такое AdminYard?
AdminYard — это библиотека для создания админок на PHP, которую я недавно написал с нуля. Зачем, спросите вы, если вокруг и так полно админок? Я искал библиотеку, которая бы встроилась в существующий легаси-проект и не притащила с собой кучу новых тяжелых зависимостей вроде фреймворков, шаблонизаторов и ORM. Ничего подходящего не нашел: мне попадались либо библиотеки из экосистемы фреймворков, либо мутные платные скрипты.
Я много работал с бандлом для Symfony EasyAdmin, еще начиная с первой версии. Из него позаимствовал общий подход и идею описания конфигурации. Также реализовал в своей библиотеке те фичи, которых мне не хватало в EasyAdmin и для которых приходилось придумывать костыли.
В этой статье я расскажу об основных возможностях AdminYard и приведу упрощенные примеры конфигурации. Если не охота читать, можете сразу попробовать демо-сайт или посмотреть исходный код на гитхабе.
Страница списка сущностей Comment с фильтром и инлайн-редактированием поля Name
Фичи AdminYard
CRUD-операции. Для начала работы в конфиге AdminYard описываются те таблицы и поля из базы данных, с которыми будет вестись работа в админке. После этого для каждой описанной сущности появляются 4 экрана:
list — cписок всех сущностей,
show — просмотр одной сущности,
new — форма создания,
edit — форма редактирования.
Отображение каждого поля на этих экранах настраивается независимо. Для определенных сущностей ненужные экраны можно отключить. Ячейки в таблице списка сущностей можно сделать редактируемыми прямо в списке сущностей, без перехода к форме редактирования (in-place edit).
Формы создания и редактирования сущностей создаются автоматически на основе конфига. К полям на формах создания и редактирования можно указать правила валидации.
Форма редактирования с отображением ошибки валидации
Связи между сущностями и виртуальные поля. Если в вашем проекте связь многие-к-одному сделана стандартным образом, через хранение parent_id в дочерней сущности, то такая связь указывается в конфиге AdminYard и работает из коробки. В колонке таблицы со списком сущностей вместо значения parent_id отображается ссылка на саму родительскую сущность, а при создании или редактировании дочерней сущности родительская сущность выбирается из списка.
Поддержки связи многие-ко-многим нет, но есть точки расширения для её реализации в вашем коде. Я сделал так, потому что в отличие от стандартного поля parent_id для связи многие-к-одному, связь многие-ко-многим хранится в отдельной таблице. Для изменения записей в ней нет стандартных интерфейсных подходов, интерфейс часто определяется бизнес-логикой. Рассмотрим пример связи многие-ко-многим: посты и теги в блоге. В интерфейсе удобно редактировать эту связь как дополнительное поле со списком тегов на форме редактирования поста. Такие поля описываются в конфиге как виртуальные поля. Чтобы они заработали, требуется написать обработчики событий, которые и будут сохранять содержимое виртуальных полей в другие таблицы.
Поле со списком тегов на форме редактирования поста — виртуальное, на самом деле это связь многие-ко-многим
Фильтры для списков сущностей. Это то, чего мне не хватало в EasyAdmin. Между полями фильтра и полями сущностей не всегда есть прямое соответствие. Например, в фильтре может присутствовать общий поиск по нескольким текстовым колонкам или, наоборот, два поля для выбора интервала времени при фильтрации по одной колонке. Чтобы задавать такое соответствие, потребуется написать фрагмент SQL-запроса.
Выбранный фильтр сохраняется в отдельном хранилище, например, в сессии. Это удобно, чтобы на какой-то странице админки не приходилось каждый раз выбирать одни и те же условия.
Контроль доступа на уровне строк. AdminYard позволяет указать условия в SQL-запросах для ограничения доступа к некоторым строкам на чтение и на запись. Вот как выглядит искусственный пример, в котором к записям с id от 31 до 35 ограничен доступ на запись, а к записям с id от 40 до 41 ограничен доступ на чтение.
Обычно управление доступом делается в зависимости от роли текущего пользователя и от состояния сущности. В примере с блогом рядовой модератор может одобрять или отклонять только новые комментарии, а администратор может менять статусы любых комментариев. Это можно сделать с помощью контроля доступа на уровне строк.
Шаблоны и их переопределение. Шаблоны в AdminYard — это обычные php-файлы. В комплекте есть шаблоны по умолчанию, и их можно переопределить независимо для каждой сущности. Например, в блоге форму редактирования поста надо существенно доработать: сверстать по красивому макету, добавить автосохранение в localStorage, подключить продвинутый редактор вместо стандартной textarea. А форма редактирования пользователей может остаться стандартной, так как её используют редко. Всё это делается с помощью переопределения встроенных шаблонов.
Защита от CSRF во всех формах. Мелочь, а приятно.
Чего нет в AdminYard
То, чем проект не является и что он не делает, описывает его не хуже, а может даже и лучше, чем список фич.
Нет авторизации. Она должна быть внешняя: пользователь и права должны проверяться до того, как управление будет передано в AdminYard. Если требуются разные привилегии пользователей в зависимости от ролей, они должны программироваться через конфиг. Он динамический и может содержать разные действия, поля и даже сущности в зависимости от ролей пользователя.
Нет внешних шаблонизаторов. В обычных шаблонах в php-файлах важно не забывать экранировать вывод, чтобы не допустить XSS-уязвимости.
Нет современного фронтенда. В библиотеке используется только серверный рендеринг (веб 1.0). Как показывает практика, этого более чем достаточно в непубличных интерфейсах админок.
Нет управления ассетами. Переопределяйте шаблон layout.php и указывайте в нем правильные пути к существующим ассетам.
Нет совместного редактирования. Такие продвинутые фичи уже за скоупом проекта. Если два человека отправят одну и ту же форму, сохранится только последняя версия.
Нет ORM. Вам самим нужно заниматься миграциями, создавать индексы, чтобы не тормозила фильтрация и сортировка, и в некоторых случаях писать фрагменты SQL.
Пример конфигурации
Это раздел для тех, кому интересно посмотреть на программный интерфейс библиотеки.
В простейшем случае в index.php надо поместить следующий код:
setSession(new Session());
$response = $adminPanel->handleRequest($request);
$response->send();Конфиг представляет собой php-код в объектном стиле. Вот базовый пример:
addField(new FieldConfig(
name: 'id', // Название колонки в таблице БД
type: new DbColumnFieldType(FieldConfig::DATA_TYPE_INT, true), // Тип - числовой первичный ключ
// Колонка включена только на экранах list и show.
// На формах создания и редактирования, очевидно, нельзя редактировать ID сущности.
useOnActions: [FieldConfig::ACTION_LIST, FieldConfig::ACTION_SHOW]
))
->addField(new FieldConfig(
name: 'title',
// Тип колонки - строка. Закомментировано, так как это значение по умолчанию, его можно опустить
// type: new DbColumnFieldType(FieldConfig::DATA_TYPE_STRING),
// Если поле появляется на экранах new или edit, ему надо указать контрол на форме
control: 'input', // Обычный инпут
validators: [new Length(max: 80)], // Валидировать максимальную длину поля
sortable: true, // Разрешить сортировку по этому полю на экране list
actionOnClick: 'edit' // Сделать ячейку на экране list кликабельной и ведущей на экран edit
))
->addField(new FieldConfig(
name: 'text',
control: 'textarea', // Textarea для текста поста
// Все экраны за исключением list, так как текст будет распирать таблицу
useOnActions: [FieldConfig::ACTION_SHOW, FieldConfig::ACTION_EDIT, FieldConfig::ACTION_NEW]
))
->addField(new FieldConfig(
name: 'created_at',
type: new DbColumnFieldType(FieldConfig::DATA_TYPE_TIMESTAMP), // Тип колонки в БД - timestamp
control: 'datetime', // HTML5-контрол выбора даты и времени
sortable: true
))
->addField(new FieldConfig(
name: 'comments',
// Специальный конфиг для связи один-ко-многим. Описывает "виртуальную" колонку, которой нет в БД.
// Она появится на экранах list и show в виде ссылки на список комментариев с примененным фильтром
// с подставленным текущим постом.
type: new LinkedByFieldType(
$commentConfig,
'CASE WHEN COUNT(*) > 0 THEN COUNT(*) ELSE NULL END', // Текст для ссылки
'post_id'
),
sortable: true
))
// Здесь определяется фильтр на экране list
->addFilter(new Filter(
'search', // Фильтр содержит поле поиска
'Fulltext Search', // Название поля поиска
'search_input', // Контрол
'title LIKE %1$s OR text LIKE %1$s', // шаблон условия для WHERE
// Функция для преобразования входного значения в параметр для PDO
// В этом случае пустая строка в поле поиска не приведет к фильтрации,
// а непустая строка будет искаться как подстрока (LIKE '%...%')
fn(string $value) => $value !== '' ? '%' . $value . '%' : null
))
;
// Fields and filters configuration for "Comment"
$commentConfig
->addField(new FieldConfig(
name: 'id',
type: new DbColumnFieldType(FieldConfig::DATA_TYPE_INT, true), // Primary key
useOnActions: [] // Скрыть ID со всехе экранов
))
->addField($postIdField = new FieldConfig(
name: 'post_id',
type: new DbColumnFieldType(FieldConfig::DATA_TYPE_INT),
control: 'autocomplete', // Контрол - автодополнение
validators: [new NotBlank()], // Валидатор для запрета пустых значений поля
sortable: true,
// Специальный конфиг для связи многие-к-одному. В колонке будет отображаться ссылка на пост
// на экранах list и show. Результат "CONCAT('#', id, ' ', title)" будет использован как текст ссылки.
linkToEntity: new LinkTo($postEntity, "CONCAT('#', id, ' ', title)"),
// Отключить на экране edit, при редактировании комментария его нельзя перенести к другому посту
useOnActions: [FieldConfig::ACTION_LIST, FieldConfig::ACTION_SHOW, FieldConfig::ACTION_NEW]
))
->addField(new FieldConfig(
name: 'name',
control: 'input',
validators: [new NotBlank(), new Length(max: 50)],
inlineEdit: true, // Разрешить "инлайн-редактирование" поля прямо на экране list
))
->addField(new FieldConfig(
name: 'email',
control: 'email_input', // Контрол
validators: [new Length(max: 80)],
inlineEdit: true,
))
// ...
->addField(new FieldConfig(
name: 'status_code',
// defaultValue используется при добавлении в БД, если поле отсутствует на экране new
type: new DbColumnFieldType(FieldConfig::DATA_TYPE_STRING, defaultValue: 'new'),
control: 'radio', // Radio-кнопки для выбора статуса
options: ['new' => 'Pending', 'approved' => 'Approved', 'rejected' => 'Rejected'],
inlineEdit: true,
// Отключить на экране new
useOnActions: [FieldConfig::ACTION_LIST, FieldConfig::ACTION_SHOW, FieldConfig::ACTION_EDIT]
))
// ...
->addFilter(new FilterLinkTo(
$postIdField, // Специальный фильтр по полю, содержащему связь многие-к-одному
'Post',
))
->addFilter(new Filter(
'created_from', // name контрола в форме фильтров
'Created after',
'date',
'created_at >= %1$s', // Показать комментарии, созданные после указанной даты, created_at - поле коммента
))
->addFilter(new Filter(
'created_to', // name контрола в форме фильтров
'Created before',
'date',
'created_at < %1$s', // Показать комментарии, созданные после указанной даты, created_at - поле коммента
))
->addFilter(new Filter(
'statuses',
'Status',
'checkbox_array', // Несколько чекбоксов можно отметить одновременно для отображения сразу нескольких статусов
'status_code IN (%1$s)', // Filter comments by status
options: ['new' => 'Pending', 'approved' => 'Approved', 'rejected' => 'Rejected'] // Коды и названия чекбоксов
));
// Искусственный пример управления доступом
$postEntity->setReadAccessControl(
new LogicalExpression('read_access_control', 40, 'id != %1$s AND id != 1 + %1$s')
);
$postEntity->setWriteAccessControl(
new LogicalExpression('write_access_control', [31, 32, 33, 34, 35], 'id NOT IN (%s)'),
);
// Более полезный пример управления доступом
$postEntity->
setReadAccessControl(
isGranted('ROLE_ADMIN')
? null // админам нет ограничений
// а не-админы могут просматривать только свои посты или опубликованные чужие
: new LogicalExpression('expression1', getUserId(), 'published = 1 OR user_id = %s')
)
->setWriteAccessControl(
isGranted('ROLE_ADMIN')
? null // админам нет ограничений
// а не-админы могут редактировать только свои посты
: new LogicalExpression('expression2', getUserId())
)
return $adminConfig
->addEntity($postEntity)
->addEntity($commentConfig)
;Более продвинутые возможности, например, редактирование виртуальных полей через обработчики событий, описаны в README на гитхабе.
Системные требования
AdminYard работает в PHP версии 8.2 и выше. Для работы нужна реляционная база данных: MySQL, PostgreSQL или SQLite.
Кому подойдет?
В первую очередь тем, кому надо добавить или переделать админку в существующем легаси-проекте. AdminYard позволяет не тратить время на создание и обработку типовых форм, а сразу сфокусироваться на бизнес-логике приложения.
Новые проекты, особенно объемом больше одного человеко-месяца, я бы не стал делать на AdminYard с нуля. Вам всё равно понадобится какой-нибудь фреймворк и библиотеки, лучше взять готовую админку, интегрирующуюся с ними.
Впечатления от разработки
Я взялся за разработку AdminYard, во многом надеясь на помощь нейросетей. Конечно, я бы и сам мог написать весь код с нуля, но у меня бы ушло слишком много времени на рутину и не осталось бы энтузиазма для размышлений над действительно интересными и творческими моментами. Да и самого времени, как всегда, не хватает.
Сначала я попросил ChatGPT предложить пример описания конфигурации админки на PHP в объектном стиле. Отредактировал и доработал этот пример. Затем попросил создать классы для описания конфигурации, сервисы, фикстуры демо-приложения. Первый результат, который хоть как-то выводил настоящее содержимое базы данных, появился достаточно быстро. Это придало мне уверенности в том, что я смогу за разумное время довести проект до состояния, в котором его можно применять в существующих проектах.
По ходу разработки меняется характер работы: программист переходит от крупных мазков и постоянного создания новых классов к работе над деталями, доработкам и рефакторингу. Здесь уже ChatGPT не помогает, так как сформулировать задачу для него слишком сложно из-за отсутствия контекста. Мне на помощь пришла нейросеть Codeium. Я установил ее как плагин к PhpStorm и использовал подсказки с автодополнением кода. Конечно, они не снимают необходимость понимать, что происходит в коде, но определенную помощь тоже оказывают.
Планы на будущее
Особых планов нет. Но если вы сделаете пулл-реквест с какой-нибудь полезной фичей, я при необходимости причешу код и смержу.
