AdminYard — минимальная админка на PHP для легаси-проектов

Что такое AdminYard?

AdminYard — это библиотека для создания админок на PHP, которую я недавно написал с нуля. Зачем, спросите вы, если вокруг и так полно админок? Я искал библиотеку, которая бы встроилась в существующий легаси-проект и не притащила с собой кучу новых тяжелых зависимостей вроде фреймворков, шаблонизаторов и ORM. Ничего подходящего не нашел: мне попадались либо библиотеки из экосистемы фреймворков, либо мутные платные скрипты.

Я много работал с бандлом для Symfony EasyAdmin, еще начиная с первой версии. Из него позаимствовал общий подход и идею описания конфигурации. Также реализовал в своей библиотеке те фичи, которых мне не хватало в EasyAdmin и для которых приходилось придумывать костыли.

В этой статье я расскажу об основных возможностях AdminYard и приведу упрощенные примеры конфигурации. Если не охота читать, можете сразу попробовать демо-сайт или посмотреть исходный код на гитхабе.

Фичи 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 надо поместить следующий код:

<?php  use S2\AdminYard\DefaultAdminFactory; use Symfony\Component\HttpFoundation\Request; use Symfony\Component\HttpFoundation\Session\Session;  // Динамический конфиг, рассмотрим чуть ниже $adminConfig = require 'admin_config.php';  // Типовой код инициализации сервисов AdminYard // Вместо фабрики можно определить сервисы в каком-нибудь DI контейнере $pdo = new PDO('mysql:host=localhost;dbname=adminyard', 'username', 'passwd'); $adminPanel = DefaultAdminFactory::createAdminPanel($adminConfig, $pdo, require 'translations/en.php', 'en');  // Нужен компонент Symfony HTTP Foundation $request = Request::createFromGlobals(); $request->setSession(new Session()); $response = $adminPanel->handleRequest($request); $response->send();

Конфиг представляет собой php-код в объектном стиле. Вот базовый пример:

<?php  use S2\AdminYard\Config\AdminConfig; use S2\AdminYard\Config\DbColumnFieldType; use S2\AdminYard\Config\EntityConfig; use S2\AdminYard\Config\FieldConfig; use S2\AdminYard\Config\Filter; use S2\AdminYard\Config\FilterLinkTo; use S2\AdminYard\Config\LinkTo; use S2\AdminYard\Database\PdoDataProvider; use S2\AdminYard\Event\AfterSaveEvent; use S2\AdminYard\Event\BeforeDeleteEvent; use S2\AdminYard\Event\BeforeSaveEvent; use S2\AdminYard\Validator\NotBlank; use S2\AdminYard\Validator\Length;  $adminConfig = new AdminConfig();  $commentConfig = new EntityConfig(     'Comment', // Название сущности в интерфейсе и УРЛах     'comments' // Название таблицы в БД );  $postEntity = (new EntityConfig('Post', 'posts'))     ->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', // Контрол <input type="search">         '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', // Контрол <input type="email">         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 и использовал подсказки с автодополнением кода. Конечно, они не снимают необходимость понимать, что происходит в коде, но определенную помощь тоже оказывают.

Планы на будущее

Особых планов нет. Но если вы сделаете пулл-реквест с какой-нибудь полезной фичей, я при необходимости причешу код и смержу.

Ссылки

• попробовать админку на демо-сайте,

• посмотреть исходный код на гитхабе.