Пролог

Руководство по обновлению MoonShine 2.x → 3.0

Скринкасты

Обновление пакета

1. Обновление composer.json

Измените версию пакета в вашем composer.json:

{
    "require": {
        "moonshine/moonshine": "^3.0"
    }
}
{
    "require": {
        "moonshine/moonshine": "^3.0"
    }
}

2. Создание резервных копий

Перед обновлением необходимо сделать резервные копии следующих файлов:

mv config/moonshine.php config/moonshine_old.php
mv app/Providers/MoonShineServiceProvider.php app/Providers/MoonShineServiceProvider_old.php
mv app/MoonShine/Pages/Dashboard.php app/MoonShine/Pages/Dashboard_old.php
mv config/moonshine.php config/moonshine_old.php
mv app/Providers/MoonShineServiceProvider.php app/Providers/MoonShineServiceProvider_old.php
mv app/MoonShine/Pages/Dashboard.php app/MoonShine/Pages/Dashboard_old.php

Эти файлы понадобятся для переноса конфигурации и настроек, смотрите раздел Список изменений.

3. Обновление конфигурации приложения

Если у вас Laravel < 11, то в конфигурации config/app.php необходимо найти и удалить App\Providers\MoonShineServiceProvider::class

После выполнения команды moonshine:install сервис-провайдер будет добавлен автоматически.

4. Запуск обновления

composer update
composer update

Первоначальная настройка

1. Установка новой версии

Выполните команду:

php artisan moonshine:install
php artisan moonshine:install

Эта команда создаст:

  • Новый сервис-провайдер
  • Обновленную конфигурацию
  • Новый Layout
  • Новый Dashboard

2. Миграция настроек

  1. Перенесите параметры из старого конфига (moonshine_old.php) в новый, смотрите документацию по конфигурации
  2. В новой версии изменилась структура меню:
  • Откройте app/MoonShine/Layouts/MoonShineLayout.php
  • Скопируйте старое меню из MoonShineServiceProvider_old.php в метод menu
  • У иконок удалите префикс heroicons.outline.
  • Обновите все экземпляры ресурсов на строковые классы:
// Было
MenuItem::make('Settings', new SettingResource(), 'heroicons.outline.adjustments-vertical')
 
// Стало
MenuItem::make('Settings', SettingResource::class, 'adjustments-vertical')
// Было
MenuItem::make('Settings', new SettingResource(), 'heroicons.outline.adjustments-vertical')
 
// Стало
MenuItem::make('Settings', SettingResource::class, 'adjustments-vertical')

3. Регистрация ресурсов и страниц

В новом MoonShineServiceProvider.php необходимо зарегистрировать все ресурсы и страницы:

$core->resources([
    MoonShineUserResource::class,
    MoonShineUserRoleResource::class,
    // Добавьте все ваши ресурсы
]);
 
$core->pages([
    ...$config->getPages(),
    SettingPage::class,
]);
$core->resources([
    MoonShineUserResource::class,
    MoonShineUserRoleResource::class,
    // Добавьте все ваши ресурсы
]);
 
$core->pages([
    ...$config->getPages(),
    SettingPage::class,
]);

Команды для генерации списков:

Для импорта пространств имен:

find app/MoonShine/Resources -type f | sed "s/app/use App/" | sed "s|/|\\\|g" | sed "s/.php/;/" | sort
find app/MoonShine/Resources -type f | sed "s/app/use App/" | sed "s|/|\\\|g" | sed "s/.php/;/" | sort

Для списка ресурсов:

find app/MoonShine/Resources -type f -exec basename {} \; | sed "s/.php/::class,/" | sort
find app/MoonShine/Resources -type f -exec basename {} \; | sed "s/.php/::class,/" | sort

4. Обновление Dashboard

  • Перенесите нужные компоненты из Dashboard_old.php в новый Dashboard.php
  • Учтите изменения из раздела Список изменений

5. Удаление старых файлов

После успешной миграции удалите:

# Старый Layout (если существует)
rm app/MoonShine/MoonShineLayout.php
 
# Бэкапы файлов от 2.x
rm config/moonshine_old.php
rm app/Providers/MoonShineServiceProvider_old.php
rm app/MoonShine/Pages/Dashboard_old.php
# Старый Layout (если существует)
rm app/MoonShine/MoonShineLayout.php
 
# Бэкапы файлов от 2.x
rm config/moonshine_old.php
rm app/Providers/MoonShineServiceProvider_old.php
rm app/MoonShine/Pages/Dashboard_old.php

Список изменений

Пространства имен

Основные изменения

MoonShine\Resources\ → MoonShine\Laravel\Resources\
MoonShine\Fields\Relationships\ → MoonShine\Laravel\Fields\Relationships\
MoonShine\Fields\Slug → MoonShine\Laravel\Fields\Slug
MoonShine\Fields\ → MoonShine\UI\Fields\
MoonShine\Decorations\Block → MoonShine\UI\Components\Layout\Box
MoonShine\Decorations\ → MoonShine\UI\Components\Layout\*
    (некоторые на MoonShine\UI\Components\, проверьте вручную)
MoonShine\Enums\ → MoonShine\Support\Enums\
MoonShine\Pages\ → MoonShine\Laravel\Pages\
MoonShine\Models\ → MoonShine\Laravel\Models\
MoonShine\QueryTags\ → MoonShine\Laravel\QueryTags\
MoonShine\Attributes\ → MoonShine\Support\Attributes\
MoonShine\Components\ → MoonShine\UI\Components\
MoonShine\Metrics\ → MoonShine\UI\Components\Metrics\Wrapped\
MoonShine\ActionButtons\ → MoonShine\UI\Components\
MoonShine\Http\Responses\ → MoonShine\Laravel\Http\Responses\
MoonShine\Http\Controllers\ → MoonShine\Laravel\Http\Controllers\
MoonShine\MoonShineAuth → MoonShine\Laravel\MoonShineAuth
MoonShine\Resources\ → MoonShine\Laravel\Resources\
MoonShine\Fields\Relationships\ → MoonShine\Laravel\Fields\Relationships\
MoonShine\Fields\Slug → MoonShine\Laravel\Fields\Slug
MoonShine\Fields\ → MoonShine\UI\Fields\
MoonShine\Decorations\Block → MoonShine\UI\Components\Layout\Box
MoonShine\Decorations\ → MoonShine\UI\Components\Layout\*
    (некоторые на MoonShine\UI\Components\, проверьте вручную)
MoonShine\Enums\ → MoonShine\Support\Enums\
MoonShine\Pages\ → MoonShine\Laravel\Pages\
MoonShine\Models\ → MoonShine\Laravel\Models\
MoonShine\QueryTags\ → MoonShine\Laravel\QueryTags\
MoonShine\Attributes\ → MoonShine\Support\Attributes\
MoonShine\Components\ → MoonShine\UI\Components\
MoonShine\Metrics\ → MoonShine\UI\Components\Metrics\Wrapped\
MoonShine\ActionButtons\ → MoonShine\UI\Components\
MoonShine\Http\Responses\ → MoonShine\Laravel\Http\Responses\
MoonShine\Http\Controllers\ → MoonShine\Laravel\Http\Controllers\
MoonShine\MoonShineAuth → MoonShine\Laravel\MoonShineAuth

Дополнительные пакеты

При необходимости установите и обновите пространства имен для:

  1. Import/Export:
  • MoonShine\Laravel\Handlers\ExportHandler
  • MoonShine\Laravel\Handlers\ImportHandler
  1. Apexcharts:
  • MoonShine\UI\Components\Metrics\Wrapped\DonutChartMetric
  • MoonShine\UI\Components\Metrics\Wrapped\LineChartMetric
  1. Ace Editor:
  • MoonShine\Fields\Code
  1. EasyMDE:
  • MoonShine\Fields\Markdown
  1. TinyMce:
  • MoonShine\Fields\TinyMce

Методы

Основные изменения

  1. Создание экземпляров ресурсов и страниц:
// Было
new NameResource()
 
// Стало
// Рекомендуется через DI
// или:
app(NameResource::class)
// Было
new NameResource()
 
// Стало
// Рекомендуется через DI
// или:
app(NameResource::class)
  1. Сигнатуры методов:
// Было
public function components(): array
public function title(): string
public function breadcrumbs(): string
public function rules(Model $item): array
protected function afterUpdated(Model $user): Model
public function detailButtons(): array
public function modifyListComponent(MoonShineRenderable|TableBuilder $table): MoonShineRenderable
$field->getData()
detailPageUrl
MoonShineAuth::guard()
getActiveActions()
 
// Стало
protected function components(): iterable
public function getTitle(): string
public function getBreadcrumbs(): string
protected function rules($item): array
protected function afterUpdated($user): Model
public function detailButtons(): ListOf
public function modifyListComponent(ComponentContract $table): ComponentContract
$field->getData()->getOriginal()
getDetailPageUrl
MoonShineAuth::getGuard()
activeActions()
// Было
public function components(): array
public function title(): string
public function breadcrumbs(): string
public function rules(Model $item): array
protected function afterUpdated(Model $user): Model
public function detailButtons(): array
public function modifyListComponent(MoonShineRenderable|TableBuilder $table): MoonShineRenderable
$field->getData()
detailPageUrl
MoonShineAuth::guard()
getActiveActions()
 
// Стало
protected function components(): iterable
public function getTitle(): string
public function getBreadcrumbs(): string
protected function rules($item): array
protected function afterUpdated($user): Model
public function detailButtons(): ListOf
public function modifyListComponent(ComponentContract $table): ComponentContract
$field->getData()->getOriginal()
getDetailPageUrl
MoonShineAuth::getGuard()
activeActions()
  1. Изменения в методах полей:
// Было
public function fields(): array
 
// Стало
protected function indexFields(): iterable // допускает только поля
protected function detailFields(): iterable
protected function formFields(): iterable
// Было
public function fields(): array
 
// Стало
protected function indexFields(): iterable // допускает только поля
protected function detailFields(): iterable
protected function formFields(): iterable
  1. Атрибуты таблиц:
// Новый формат
TableBuilder::make()
    ->tdAttributes(fn(mixed $data, int $row, TableBuilder $table): array =>
        $row === 3 ? ['class' => 'bgc-yellow'] : []
    )
    ->tdAttributes(fn(mixed $data, int $row, int $cell, TableBuilder $table): array =>
        $cell === 3 ? ['align' => 'right'] : []
    )
// Новый формат
TableBuilder::make()
    ->tdAttributes(fn(mixed $data, int $row, TableBuilder $table): array =>
        $row === 3 ? ['class' => 'bgc-yellow'] : []
    )
    ->tdAttributes(fn(mixed $data, int $row, int $cell, TableBuilder $table): array =>
        $cell === 3 ? ['align' => 'right'] : []
    )
  1. Изменения в других методах:
  • Хелпер to_page → toPage
  • Вместо метода columnSpan у компонентов использовать метод компонента Column: Column::make([...])->columnSpan(..)
  • Вместо expansion('url') нужно использовать метод suffix('url')

Удаленные методы

  1. Методы отображения полей:
  • hideOnIndex, showOnIndex
  • hideOnForm, showOnForm
  • hideOnCreate, showOnCreate
  • hideOnUpdate, showOnUpdate
  • hideOnDetail, showOnDetail
  • hideOnAll
  • hideOnExport, showOnExport
  • useOnImport (используйте пакет import-export)

В разделе Routes можно найти альтернативные методы

  1. Хелперы:
  • form
  • table
  • actionBtn

Переменные

Основные изменения

  1. Иконки:
  • Удалите префиксы heroicons.outline и heroicons.solid
  • Теперь эти иконки доступны по умолчанию
  1. Меню:
// Было
MenuItem::make('Settings', new SettingResource(), 'heroicons.outline.adjustments-vertical')
 
// Стало
MenuItem::make('Settings', SettingResource::class, 'adjustments-vertical')
// Было
MenuItem::make('Settings', new SettingResource(), 'heroicons.outline.adjustments-vertical')
 
// Стало
MenuItem::make('Settings', SettingResource::class, 'adjustments-vertical')
  1. Асинхронные события:
// Было
->async(asyncUrl: ..., asyncEvents: ...)
'table-updated-{name}'
 
// Стало
->async(url: ..., events: ...)
AlpineJs::event(JsEvent::TABLE_UPDATED, {name})
// Было
->async(asyncUrl: ..., asyncEvents: ...)
'table-updated-{name}'
 
// Стало
->async(url: ..., events: ...)
AlpineJs::event(JsEvent::TABLE_UPDATED, {name})
  1. Направление сортировки:
// Было
protected string $sortDirection = 'ASC';
 
// Стало
protected SortDirection $sortDirection = SortDirection::ASC;
// Было
protected string $sortDirection = 'ASC';
 
// Стало
protected SortDirection $sortDirection = SortDirection::ASC;
  1. Assets:
// Было
$assets // строки
 
// Стало
$assets // принимает AssetElementContract, такие как Css, InlineCss, Js, InlineJs
Для управления используется [AssetManager](/docs/3.x/appearance/assets).
// Было
$assets // строки
 
// Стало
$assets // принимает AssetElementContract, такие как Css, InlineCss, Js, InlineJs
Для управления используется [AssetManager](/docs/3.x/appearance/assets).

Удаленные переменные

  • protected bool $isAsync = true; (теперь включено по умолчанию)