Первые шаги

Конфигурация

Введение

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

Способы конфигурации

MoonShine можно настроить двумя способами:

  1. Через файл конфигурации config/moonshine.php
  2. Через MoonShineServiceProvider с использованием класса MoonShineConfigurator

Конфигурация через файл moonshine.php

Файл config/moonshine.php содержит все доступные настройки MoonShine. Вы можете изменять эти настройки напрямую в файле.

Пример содержимого файла moonshine.php:

return [
    'title' => env('MOONSHINE_TITLE', 'MoonShine'),
    'logo' => '/assets/logo.png',
    'logo_small' => '/assets/logo-small.svg',
    'use_migrations' => true,
    'use_notifications' => true,
    'use_database_notifications' => true,
    'use_profile' => true,
    'domain' => env('MOONSHINE_DOMAIN'),
    'prefix' => 'admin',
    'middleware' => [
        // ...
    ],
    'auth' => [
        'enabled' => true,
        'guard' => 'moonshine',
        'middleware' => Authenticate::class,
        // ...
    ],
    'layout' => \MoonShine\Laravel\Layouts\AppLayout::class,
    'locale' => 'en',
    'locales' => ['en', 'ru'],
 
    // ...
];

Частичная конфигурация

Альтернативно, вы можете оставить в файле moonshine.php только те параметры, которые отличаются от значений по умолчанию. Это делает конфигурацию более чистой и легкой для понимания.

Пример оптимизированного содержимого файла moonshine.php:

return [
    'title' => 'My MoonShine Application',
    'use_migrations' => true,
    'use_notifications' => true,
    'use_database_notifications' => true,
];

use_migrations, use_notifications, use_database_notifications должны присутствовать всегда либо в moonshine.php, либо в MoonShineServiceProvider. Все остальные параметры, не указанные в файле, будут использовать значения по умолчанию.

Конфигурация через MoonShineServiceProvider

Альтернативный способ настройки - MoonShineServiceProvider. Этот метод предоставляет более программный подход к конфигурации.

Пример конфигурации в MoonShineServiceProvider:

 namespaces
use Illuminate\Support\ServiceProvider;
use MoonShine\Contracts\Core\DependencyInjection\CoreContract;
use MoonShine\Laravel\DependencyInjection\MoonShine;
use MoonShine\Laravel\DependencyInjection\MoonShineConfigurator;
use MoonShine\Laravel\DependencyInjection\ConfiguratorContract;
 
class MoonShineServiceProvider extends ServiceProvider
{
    /**
     * @param  MoonShine  $core
     * @param  MoonShineConfigurator  $config
     *
     */
    public function boot(
        CoreContract $core,
        ConfiguratorContract $config,
    ): void
    {
        $config
            ->title('My Application')
            ->logo('/assets/logo.png')
            ->logo('/assets/logo_small.png', true)
            ->useMigrations()
            ->useNotifications()
            ->useDatabaseNotifications()
            ->useProfile()
            ->dir('app/MoonShine', 'App\MoonShine')
            ->prefixes('admin', 'page', 'resource')
            ->homeRoute('moonshine.index')
            ->notFoundException(MoonShineNotFoundException::class)
            ->middleware([
                // ...
            ])
            ->disk('public')
            ->cacheDriver('redis')
            ->authEnable()
            ->guard('moonshine')
            ->authMiddleware(Authenticate::class)
            ->authPipelines([])
            ->authorizationRules(
                function(ResourceContract $ctx, mixed $user, Ability $ability, mixed $data): bool {
                    return true;
                }
            )
            ->layout(\App\MoonShine\Layouts\CustomLayout::class)
            ->locale('ru')
            ->locales(['en', 'ru']);
 
        // ...
    }
}

Конфигурация через MoonShineServiceProvider имеет приоритет над настройками в файле moonshine.php. При использовании этого метода вы можете полностью удалить файл moonshine.php из вашего проекта.

Некоторые методы MoonShineConfigurator не имеют прямых аналогов в файле moonshine.php и наоборот. Это связано с различиями в подходах к конфигурации через файл и через код.

Основные настройки

Независимо от выбранного способа конфигурации, вы можете настроить следующие основные параметры:

Опции

  • use_migrations - использовать публикацию миграций системы по умолчанию (moonshine_users, moonshine_user_roles),
  • use_notifications - использовать систему уведомлений,
  • use_database_notifications - использовать систему уведомлений Laravel на основе драйвера базы данных,
  • dir - директория для MoonShine (по умолчанию app/MoonShine). Директория используется для генерации файлов через artisan команды, в целом MoonShine не привязан к структуре,
  • namespace - namespace для классов созданных через artisan команды (по умолчанию App\MoonShine).
'dir' => 'app/MoonShine',
'namespace' => 'App\MoonShine',
 
'use_migrations' => true,
'use_notifications' => true,
'use_database_notifications' => true,
$config
    ->dir(dir: 'app/MoonShine', namespace: 'App\MoonShine')
    ->useMigrations()
    ->useNotifications()
    ->useDatabaseNotifications();

Заголовок

Мета заголовок на страницах (<title>My Application</title>).

'title' => 'My Application',
$config->title('My Application');
'logo' => '/assets/logo.png',
'logo_small' => '/assets/logo-small.png',
$config
    ->logo('/assets/logo.png')
    ->logo('/assets/logo-small.png', small: true);

Middleware

Вы можете переопределить или дополнить список middleware в системе.

'middleware' => [
    'web',
    'auth',
    // ...
],
$config
    ->middleware(['web', 'auth'])
    ->addMiddleware('custom-middleware')
    ->exceptMiddleware(['auth']);

Маршрутизация

Установка префиксов

'prefix' => 'admin',
'page_prefix' => 'page',
'resource_prefix' => 'resource',
$config->prefixes('admin', 'page', 'resource');

Вы можете оставить resource_prefix пустым и URL ресурсов будет иметь вид /admin/{resourceUri}/{pageUri}, но вы можете создать конфликт с роутами пакетов.

Установка домена

'domain' => 'admin.example.com',
$config->domain('admin.example.com');

404

Вы можете заменить Exception на собственный.

'not_found_exception' => MoonShineNotFoundException::class,
$config->notFoundException(MoonShineNotFoundException::class);

Аутентификация

Установка guard

'auth' => [
    'guard' => 'admin',
    // ...
],
$config->guard('admin');

Отключение встроенной аутентификации

'auth' => [
    'enabled' => false,
    // ...
],
$config->authDisable();

Изменение модели

'auth' => [
    // ...
    'model' => User::class,
    // ...
],

Указывается при инициализации приложения, поэтому указывается исключительно через файл конфигурации.

Middleware для проверки наличия сессии

'auth' => [
    // ...
    'middleware' => Authenticate::class,
    // ...
],
$config->authMiddleware(Authenticate::class);

Pipelines

'auth' => [
    // ...
    'pipelines' => [
        TwoFactor::class
    ],
    // ...
],
$config->authPipelines([TwoFactor::class]);

Поля пользователя

Если вы просто заменили модель на свою auth.model, то скорее всего вы столкнетесь с проблемой несоответствия наименования полей. Чтобы настроить соответствие, воспользуйтесь настройкой userField().

'user_fields' => [
    'username' => 'email',
    'password' => 'password',
    'name' => 'name',
    'avatar' => 'avatar',
],
$config->userField('username', 'username');

Локализация

Язык по умолчанию

'locale' => 'en',
$config->locale('en');

Установка доступных языков

'locales' => ['en', 'ru'],
$config->locales(['en', 'ru']);

Подробнее смотрите в разделе локализация.

Хранилище

Storage

'disk' => 'public',
'disk_options' => [],
$config->disk('public', options: []);

Cache

'cache' => 'file',
$config->cacheDriver('redis');

Layout

Шаблон используемый по умолчанию.

'layout' => \App\MoonShine\Layouts\CustomLayout::class,
$config->layout(\App\MoonShine\Layouts\CustomLayout::class);

Формы

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

'forms' => [
    'login' => LoginForm::class,
    'filters' => FiltersForm::class,
],
$config->set('forms.login', MyLoginForm::class);

Страницы

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

'pages' => [
    'dashboard' => Dashboard::class,
    'profile' => ProfilePage::class,
    'login' => LoginPage::class,
    'error' => ErrorPage::class,
],
$config->changePage(LoginPage::class, MyLoginPage::class);

Главная страница

Вы можете указать какой роут или урл является главной страницей панели. Используется при редиректе после успешной аутентификации, ссылке на логотипе и 404 странице.

'home_route' => 'moonshine.index',
// or url string
'home_url' => '/admin/page/some-page',
$config->homeRoute('moonshine.index');
// or url string
$config->homeUrl('/admin/page/some-page');

Получение страниц и форм

MoonShine предоставляет удобные методы для получения страниц и форм в вашем приложении.

Получение страниц

Метод getPage позволяет получить экземпляр страницы по её имени или использовать страницу по умолчанию.

getPage(
    string $name,
    string $default,
    mixed ...$parameters,
)

Параметры:

  • $name - имя страницы в конфиге,
  • $default - класс страницы по умолчанию, если не найдена в конфиге,
  • $parameters - дополнительные параметры для конструктора страницы.

Пример использования:

// Helper
 
$customPage = moonshineConfig()->getPage('custom');
// DI
 
use MoonShine\Contracts\Core\DependencyInjection\ConfiguratorContract;
use MoonShine\Laravel\DependencyInjection\MoonShineConfigurator;
 
/**
 * @param  MoonShineConfigurator  $configurator
 */
public function index(ConfiguratorContract $config)
{
  $customPage = $config->getPage('custom');
}

Получение форм

Метод getForm позволяет получить экземпляр формы по её имени или использовать форму по умолчанию.

getForm(
    string $name,
    string $default,
    mixed ...$parameters,
)

Параметры:

  • $name - имя формы в конфиге,
  • $default - класс формы по умолчанию,
  • $parameters - дополнительные параметры для конструктора формы.

Пример использования:

// Helper
 
$form = moonshineConfig()->getForm('login');
// DI
 
use MoonShine\Contracts\Core\DependencyInjection\ConfiguratorContract;
use MoonShine\Laravel\DependencyInjection\MoonShineConfigurator;
 
/**
 * @param  MoonShineConfigurator  $configurator
 */
public function index(ConfiguratorContract $config)
{
  $form = $config->getForm('login');
}

Объявление страниц и форм в конфигурации

Вы можете настроить соответствие между именами и классами страниц и форм в файле moonshine.php.

return [
    // Другие настройки...
 
    'pages' => [
        'dashboard' => \App\MoonShine\Pages\DashboardPage::class,
        'custom' => \App\MoonShine\Pages\CustomPage::class,
    ],
 
    'forms' => [
        'login' => \App\MoonShine\Forms\LoginForm::class,
        'custom' => \App\MoonShine\Forms\CustomForm::class,
    ],
];

Это позволит вам легко получать нужные страницы и формы по их именам, используя методы getPage и getForm.

Выбор метода конфигурации

При выборе метода конфигурации важно учитывать следующее:

  1. Приоритет: Конфигурация через MoonShineServiceProvider имеет приоритет над настройками в файле moonshine.php.

  2. Гибкость:

    • Полная конфигурация через moonshine.php дает четкий обзор всех настроек,
    • Частичная конфигурация через moonshine.php позволяет легко видеть, какие параметры были изменены,
    • Конфигурация через MoonShineServiceProvider предоставляет максимальную гибкость и возможность использовать логику при настройке.

  3. Простота поддержки:

    • Использование файла moonshine.php может быть проще для быстрых изменений и понимания общей структуры настроек,
    • MoonShineServiceProvider позволяет централизованно управлять настройками в одном месте в коде.

  4. Интеграция с кодом:

    • Конфигурация через MoonShineServiceProvider лучше интегрируется с остальным кодом приложения и позволяет использовать зависимости и сервисы Laravel.

Выберите метод, который лучше всего соответствует вашему стилю разработки и требованиям проекта. Вы также можете комбинировать эти подходы, например, используя файл moonshine.php для базовых настроек и MoonShineServiceProvider для более сложной конфигурации.