MoonShine 2.0. Что нового?

Последние полгода наше комьюнити CutCode работает над новой версией нашей open-source админ-панели MoonShine. И вот недавно состоялся релиз MoonShine 2. Давайте пройдемся по всем значимым изменениям! Конечно, в одной статье я не смогу осветить все нововведения, но попробую сделать это по-максимуму. Ну а также расскажу о ближайших планах на MoonShine 3.

Laravel >= 10.20

PHP >= 8.1

Если смотреть на MoonShine 2 чисто визуально, то отличий не так и много. Да, у нас немного изменились некоторые поля и компоненты, появилось верхнее меню, но все это мелочь по сравнению с изменениями под капотом - там мы переписали 90% кода. В MoonShine 2 полностью новое ядро, которое дает невероятное количество дополнительных возможностей для разработчиков.

Ресурсы уже не будут прежними. Теперь базовый ресурс вообще ничего не знает о Eloquent моделях и может работать с любым другим хранилищем.

Мы реализовали ресурс для моделей и называется он ModelResource. Те, кто использовал MoonShine 1, даже не увидят разницы в подходе. Но здесь нужно обратить внимание на то, что ресурс теперь изолирован и вы можете написать реализацию своего хранилища: будь то данные из внешнего api или парсинг лог файлов. Тут уже вы ограничиваетесь только своей фантазией.

Новый постоянный житель MoonShine. Теперь страницы это основа MoonShine. Да у нас уже были кастомные страницы (которых к слову теперь нет), но текущие страницы не имеют границ и могут работать даже без ресурса. Ответственность у страниц это отображение компонентов, которых может быть сколько угодно - они могут быть компонентами MoonShine, либо просто blade компонентами или даже livewire! В итоге можно сказать, что ресурс это бокс с общей логикой для набора страниц. Но и опять-таки страницы могут существовать и без ресурса. Профиль пользователя это просто MoonShine-страница, которую можно заменить на свою, тоже самое касается и дашборда (главной страницы)

public function components(): array { return [ FormBuilder::make()->fields([ Block::make([ Grid::make([ Column::make([ Heading::make('Text'), ID::make(), Hidden::make('Hidden'), ])->columnSpan(6), Column::make([ Heading::make('Textarea'), Textarea::make('Textarea'), TinyMce::make('TinyMce'), ])->columnSpan(6), ]), LineBreak::make(), ]), ])->submit('Submit', ['class' => 'btn-lg btn-primary']), ]; }

Как я уже говорил ранее, для вашего удобства мы уже написали ресурс для моделей - ведь все-таки мы используем Laravel, и я думаю в 99% случаев ресурсы будут на основе моделей. Также к ресурсу мы добавили готовые страницы:

для листинга записей (IndexPage),
добавления/редактирования(FormPage) ,
детальная(DetailPage).

Чтобы вам удобно было располагать и наполнять компоненты на этих страницах, мы добавили подход с использованием слоев (Layers). В итоге страницы выглядят следующим образом:

public function components(): array { return array_merge( $this->topLayer(), $this->mainLayer(), $this->bottomLayer(), ); }

Теперь, для того чтобы добавить компоненты сверху, достаточно переопределить метод topLayer.

public function topLayer(): array { return [ Flex::make([ Heading::make('Title') ]) ->customAttributes(['class' => 'mb-4']) ->justifyAlign('end') ]; }

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

Компоненты теперь сердце MoonShine. Всё что вы видите в MoonShine сделано компонентами. Вы можете их добавлять, перемещать, добавлять свои. За счет компонентов мы получили полноценный конструктор, и теперь процесс работы с админ-панелью напоминает сборку кубиков конструктора LEGO - очень увлекательный процесс! Ну и само собой, появилось много новых компонентов и декораций из коробки, о которых вы узнаете в документации.

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

final class MoonShineLayout implements MoonShineLayoutContract { public static function build(): LayoutBuilder { return LayoutBuilder::make([ Sidebar::make([ Menu::make()->customAttributes(['class' => 'mt-2']), ]), LayoutBlock::make([ Flash::make(), Header::make(), Content::make(), Footer::make()->copyright(fn (): string => <<<'HTML' © 2021-2023 Made with ❤️ by <a href="https://cutcode.dev" class="font-semibold text-primary hover:text-secondary" target="_blank" > CutCode a> HTML)->menu([ 'https://moonshine.cutcode.dev' => 'Documentation', ]), ])->customAttributes(['class' => 'layout-page']), ]); } }

Те, кто уже давно используют MoonShine, помнят, что у нас для кнопок в таблице были ItemAction, для массовых действий BulkAction, а в форме FormAction, а на детальной странице DetailAction, ах да еще общие Action для главной страницы сверху. Чуть сам не запутался пока писал) Но все это в прошлом! Встречайте - теперь кнопками правит ActionButton и эти красавцы умеют гораздо больше, чем толпа предыдущих сущностей вместе взятых.

ActionButton::make('Create', $resource->route('crud.create'));

Нужно вызвать модалку по клику, с любым содержимым или подтверждением действий? Не проблема, для этого есть метод - inModal или withConfirm.

ActionButton::make('Create', $resource->route('crud.create')) ->inModal(fn() => 'Create', FormBuilder::make()),

Хотите открыть offcanvas - пожалуйста, воспользуйтесь методом inOffCanvas.

ActionButton::make('Filtes', '#') ->secondary() ->icon('heroicons.outline.adjustments-horizontal') ->inOffCanvas( fn (): array|string|null => __('moonshine::ui.filters'), fn (): FormBuilder => new FiltersForm() )

Кнопка может переходить на любой урл, а также можно получить асинхронно контент или загрузить блейд фрагмент (об этом немного позже), а самое важное что рендерятся они где угодно в MoonShine и есть хелперы для вызова в блейд.

actionBtn('Create', route('example.url')) ->inModal(fn() => 'Create', async: true),

Думаю есть те кто будет ругать js в php классе, но такая возможность присутствует и стоит о ней сказать

ActionButton::make('Create', $resource->route('crud.create')) ->onClick(fn() => 'alert()', 'prevent'),

Прежде чем мы поговорим о новых возможностях полей, стоит заметить, что изменена их концепция. В MoonShine 1 поля были привязаны к ресурсу и их тяжело было применять за его пределами. Теперь поля можно рендерить отдельно где угодно, но есть и места где им самое место - и это конечно же форма! С приходом MoonShine 2 мы рады представить FormBuilder, c помощью которого вы можете легко наполнить форму полями и декорациями, указать какой тип данных будет у полей (TypeCasts, подробнее в документации), а также использовать Precognition или асинхронное сохранение.

Еще одно важное место для хранения полей - TableBuilder. Теперь создать таблицу в MoonShine или за её пределами - не проблема. Наполняем её любыми данными и указываем тип данных с помощью TypeCasts. Как и с формами, поддерживается асинхронный режим. Появился инструмент для управления атрибутами ячеек и строк, теперь добавлять им классы, стили, да всё что угодно - можно через ComponentAttributeBag.

Как бы там ни было, но поля - это основа MoonShine, без них точно никуда. И они всюду. Давайте разберем, что появилось нового! Для начала еще раз повторюсь, что поля ничего не знают о моделях (за исключением полей отношений, тут уж никуда без моделей) и могут наполняться любыми данными, даже за пределами MoonShine. Также появились новые поля, о которых можно почитать подробнее в документации.

Помните фильтры? Ну так вот - их больше не существует и теперь поля могут быть фильтрами, а логику фильтрации вы сможете менять “на лету”.

Теперь можно получать доступ к вложенным элементам через точку (‘user.email’):

Preview::make('Email', 'user.email');

Также логику можно выносить в отдельные Apply-классы, и регистрировать в системе. О Apply классах и MoonShineRegister подробнее смотрите в документации.

Поле Enum прокачали и добавили возможность указывать заголовок и цвет бейджа прямо в Enum, достаточно просто использовать методы getColor/toString.

enum ColorEnum: string { case Red = "R"; case Black = "B"; case White = "W"; public function getColor(): string { return match ($this->value) { "R" => 'purple', "B" => 'gray', "W" => 'green' }; } public function toString(): string { return match ($this->value) { "R" => 'Purple', "B" => 'Gray', "W" => 'Green' }; } }

BelongsToMany теперь работает со всеми типами полей для pivot значений.

BelongsToMany::make('Categories', 'categories', resource: new CategoryResource()) ->fields(function () { return [ Date::make('Created at')->format('d.m.Y'), ]; })

Select можно указать url и получать опции селекта асинхронно, достаточно только соблюдать структуру ответа, которую мы укажем в документации.

Select::make('Select') ->async(route('async-search')) ->searchable(),

Отобразить поля теперь можно в таблице в виде элемента формы и асинхронно сохранять при изменении.

Text::make('Title') ->updateOnPreview(fn ($item) => $this->route('resource.update-column', $item->getKey()))

Мы улучшили интерфейс полей и добавили больше возможностей кастомизации без создания отдельного класса. Вот как это работает:

Text::make('Thumbnail') // Добавили дополнительные скрипты и стили для поля ->addAssets(['custom.js', 'custom.css']) // В форме до элемента отобразили превью с картинкой ->beforeRender(function (Text $field) { return $field->preview(); }) // Изменили превью, вместо текста отображаем изображение ->changePreview(function ($value) { return view('moonshine::ui.image', [ 'value' => $value ? Storage::url($value) : null, ]); }) // Изменили логику сохранения, где мы не просто сохраняем текст а загружаем изображение по указанному урл ->onApply(function (Article $item, string $value) { $path = 'thumbnail.jpg'; if ($value && $value !== $path) { Storage::put($path, file_get_contents($value)); $item->thumbnail = $path; } return $item; }),

Добавить ссылку к полю или обернуть его в badge теперь можно для всех текстовых полей

Email::make('Title') ->badge('purple') ->link(fn($value) => "mailto:$value", 'Go to'),

Поле прокачали по-полной, принимает любые типы полей и даже может работать как отношение, отображая форму или таблицу прямо в основной форме

Json::make('Comments') ->asRelation(new CommentResource()) ->fields([ ID::make(), BelongsTo::make('Article') ->setColumn('article_id') ->searchable(), BelongsTo::make('User') ->setColumn('user_id'), Text::make('Text')->required(), Image::make('Files') ->multiple() ->removable() ->disk('public') ->dir('comments'), ]) ->creatable() ->removable()

Еще раз напомню, что в MoonShine 2 ресурс теперь может работать и не на основе моделей. Но все-таки ресурс с моделями у нас прямо в коробке. И он очень похож на тот, который мы использовали в первой версии. Но также появились и новые подходы, а именно:

Раздельный подход, где у нас под каждый тип полей (для главной, формы, детальной страницы) свои отдельные методы.
С публикацией всех страниц ресурса, которые вы сможете кастомизировать по-своему.
Полностью пустой ресурс для нетривиальных задач.

Иконку можно менять прямо в ресурсе через атрибут

#[Icon('heroicons.users')] class ArticleResource extends ModelResource

Был прокачан поиск по ресурсу и по json, доступ к отношениям и многое другое (смотрим документацию).

Появилась новая декорация Fragment, которая дает возможность использовать blade fragments, отмечать блоки на странице и подгружать их асинхронно.

Fragment::make([ TableBuilder::make(items: $this->getResource()->paginate()) ->fields($this->getResource()->getIndexFields()) ->buttons([ ...$this->getResource()->getIndexButtons(), ]), ])->withName('crud-table'),

Мы стараемся улучшать интерфейс и внедрили аннотации с дженериками для нашего с вами удобства.

Будет полезно для тех, кто пишет пакеты для MoonShine. Теперь можно регистрировать собственные правила валидации и все они будут применяться в ресурсе.

public function boot(): void { MoonShine::defineAuthorization( static function (ResourceContract $resource, Model $user, string $ability, Model $item): bool { $hasUserPermissions = in_array( HasMoonShinePermissions::class, class_uses_recursive($user), true ); if (! $hasUserPermissions) { return true; } if (! $user->moonshineUserPermission) { return true; } return isset($user->moonshineUserPermission->permissions[$resource::class][$ability]); } ); }

Удобные классы для реализации логики в MoonShine.

class ExportHandler extends Handler { public function handle(): Response { // Logic } }

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

return LayoutBuilder::make([ TopBar::make([ Menu::make()->top(), ]), // ... ]);

Кастомизация темы и цветовой схемы. Фон, кнопки и другие элементы запросто можно перекрасить.

protected function theme(): array { return [ 'colors' => [ 'body' => '#fff' ] ]; }

Директива с ассетами MoonShine, чтобы можно было использовать возможности MoonShine за её пределами.

<head> @moonShineAssets </head>

Sortable прямо в коробке и уже интегрированы в поля Json/Image/File

x-data="sortable"

Helpers для тех кому нравятся хелперы

moonshine() moonshineRegister() to_page() moonshineRequest() moonshineAssets() moonshineMenu() moonshineLayout() form() table() actionBtn() // ...

Toasts можно вызвать в js.

Да кстати, мы интегрировали Laravel Prompts во все консольные команды. Понять структуру кастомных полей или компонентов для разработчиков теперь будет куда проще. Да и установка MoonShine теперь сводится к одной команде.

php artisan moonshine:field php artisan moonshine:component php artisan moonshine:apply php artisan moonshine:controller php artisan moonshine:layout php artisan moonshine:page

Проект разрастается и переехал на новый домен - https://moonshine-laravel.com

Интеграция Laravel Echo, наконец-таки вебсокеты
Multi tenancy
Бесконечная вложенность в меню
Асинхронное удаление полей и записей
Новые шаблоны и темы
2FA
Вложенные ресурсы

Обновление получилось очень большим и трудозатратным. И я рассказал только о самых больших изменениях. Подробнее можно посмотреть в обзорном видео:

Работая по MoonShine v.2 мы реализовали много пожеланий участников нашего комьюнити, а некоторые разработчики втягиваются в разработку, реализовывая свои же предложения. Всех Laravel-разработчиков приглашаю присоединиться - использовать MoonShine2 в своих проектах и участвовать в open source разработке.

Данил Щуцкий, автор проекта CutCode.

Новые требования

Новый подход

Ресурсы

Страницы

Слои

Поля

Компоненты

LayoutBuilder

ActionButtons

FormBuilder

TableBuilder

Fields

Async

UpdateOnPreview

beforeRender/afterRender/changePreview/addAssets/onApply/onBeforeApple/onAfterApple/onAfterDelete

Badge/link

Json

Resource

Basic

Fragments

Generics

Произвольные правила авторизации

Handlers

Красота и сахар

Toasts improvements

Stubs для всего

Новый домен

План на 3.0

Заключение