MoonShine 2.0. Что нового?22.11.2023 09:31

ActionButtons

Те, кто уже давно используют 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'),

FormBuilder

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

TableBuilder

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

Fields

Как бы там ни было, но поля — это основа 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'),
        ];
    })

Async

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

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

UpdateOnPreview

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

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

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

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

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/link

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

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

Json

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

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()

Resource

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

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

2. С публикацией всех страниц ресурса, которые вы сможете кастомизировать по-своему.

3. Полностью пустой ресурс для нетривиальных задач.

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

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

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

Basic

Fragments

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

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

Generics

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

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

Будет полезно для тех, кто пишет пакеты для 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]);
        }
    );
}

Handlers

Удобные классы для реализации логики в 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 за её пределами.

    @moonShineAssets
head>

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

x-data="sortable"

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

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

Toasts improvements

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

Stubs для всего

Да кстати, мы интегрировали 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

План на 3.0

• Интеграция Laravel Echo, наконец-таки вебсокеты

• Multi tenancy

• Бесконечная вложенность в меню

• Асинхронное удаление полей и записей

• Новые шаблоны и темы

• 2FA

• Вложенные ресурсы

Заключение

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

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

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