Расширение кода

JournalPHP расширяется стандартными средствами Laravel и новым кодом по соглашениям проекта.

Обзор

Новая функциональность добавляется сервис-провайдерами, событиями, middleware и классами по тем же соглашениям, что и существующий код: Actions, репозитории с интерфейсами, сервисы со сменными драйверами. Соглашения описаны в разделе Архитектура проекта.

Сервис-провайдеры

Провайдеры приложения зарегистрированы в config/app.php → providers:

Провайдер	Назначение
`AppServiceProvider`	Общая инициализация, включая `FORCE_HTTPS`
`AuthServiceProvider`	Политики авторизации
`EventServiceProvider`	События, слушатели, провайдеры Socialite
`RouteServiceProvider`	Загрузка маршрутов и лимиты запросов
`BroadcastServiceProvider`	Каналы WebSocket-вещания
`RepositoryServiceProvider`	Автоматическая регистрация репозиториев
`MetaBuilderServiceProvider`	SEO-билдеры страниц
`MailServiceProvider`	SMTP из настроек админ-панели
`MediaServiceProvider`	Привязка хранилища файлов через `UploaderManager`
`AiServiceProvider`	Привязка AI-сервиса через `AiManager`
`ImageModerationServiceProvider`	Привязка модерации изображений через `ImageModerationManager`
`ScoutConfigServiceProvider`	Поисковый движок из настроек админ-панели
`HorizonServiceProvider`, `LogViewerServiceProvider`	Доступ к Horizon и Log Viewer
`SlowQueryServiceProvider`	Логирование SQL-запросов дольше 700 мс

Свои привязки добавляйте в AppServiceProvider::register() или в отдельный провайдер, зарегистрированный в config/app.php:

php

$this->app->bind(MyServiceInterface::class, MyService::class);

Actions

Бизнес-операции оформляются как Action-классы с методом execute():

php

namespace App\Actions\MyFeature;

class DoSomethingAction
{
    public function __construct(
        protected DoSomethingRepositoryInterface $repository,
    ) {}

    public function execute(User $user, array $data): Result
    {
        // бизнес-логика
    }
}

Зависимости внедряются через конструктор, Action — через параметр метода контроллера:

php

public function store(MyRequest $request, DoSomethingAction $action): RedirectResponse
{
    $action->execute($request->user(), $request->validated());

    return back();
}

Репозитории

Создайте интерфейс в подкаталоге Interfaces/ и реализацию рядом с ним:

app/Repositories/MyFeature/
├── Interfaces/
│   └── GetSomethingRepositoryInterface.php
└── GetSomethingRepository.php

RepositoryServiceProvider зарегистрирует привязку автоматически, если имя реализации совпадает с именем интерфейса без суффикса Interface.

Новая настройка в админ-панели

Репозиторий: в app/Repositories/Config/MyFeature/ создайте репозиторий чтения настройки из таблицы config. Значение по умолчанию верните из репозитория или добавьте в ConfigSeeder.
Контроллер: app/Http/Controllers/Admin/MyFeatureSettingsController.php с методами edit и update. Сохраняйте значение через Config::updateOrCreate('myFeature', $value) — модель сама сбросит кэш.

Маршруты: в routes/admin.php:

php

$route->get('/settings/my-feature', [MyFeatureSettingsController::class, 'edit'])->name('settings.my-feature.edit');
$route->put('/settings/my-feature', [MyFeatureSettingsController::class, 'update'])->name('settings.my-feature.update');

Раздел: в config/admin_sections.php добавьте ключ, совпадающий с путём после /admin-panel/:
php
```
'settings/my-feature' => 'Моя настройка',
```
Страница: Inertia-страница в resources/js/Admin/Pages/Settings/MyFeature/Edit.vue.
Меню: пункт в resources/js/Admin/Layout/AppSidebar.vue с тем же путём.

WARNING

Путь, для которого нет ключа в config/admin_sections.php, доступен любому администратору. Добавляйте ключ для каждого нового раздела.

Вход через новый OAuth-провайдер

Установите пакет провайдера из SocialiteProviders.
Добавьте его обработчик в SocialiteWasCalled в EventServiceProvider::$listen.
Добавьте redirect провайдера в config/services.php → oauth.
Добавьте поля Client ID и Client Secret в AuthSettingsController, репозиторий настройки в app/Repositories/Config/Auth/ и форму в resources/js/Admin/Pages/Settings/Auth/Edit.vue.
Добавьте провайдер в список публичных провайдеров в GetSharedInertiaConfigRepository, чтобы кнопка появилась в окне входа.

Новое хранилище файлов

Добавьте значение и название в App\Enums\UploaderDriver.
Создайте класс в app/Services/Uploader/Drivers/, унаследовав AbstractUploader.
Добавьте метод create{Name}Driver() в UploaderManager.
Добавьте поля учётных данных в MediaSettingsController и resources/js/Admin/Pages/Settings/Media/Edit.vue.

Новый поисковый движок

Добавьте значение в App\Enums\SearchDriver и перевод названия в resources/lang/*/enums.php.
Реализуйте драйвер в app/Services/Search/Drivers/ с интерфейсами SearchDriverInterface и SearchIndexManagementInterface, а также провайдеры поиска постов и пользователей в app/Services/Search/Providers/.
Зарегистрируйте драйвер методом create{Name}Driver() в SearchManager.
Передайте ключи в конфигурацию Scout в ScoutConfigServiceProvider.
Добавьте поля в UpdateSearchSettingsRequest, UpdateSearchSettingsAction и resources/js/Admin/Pages/Settings/Search/Edit.vue.

Новый сервис GIF

Добавьте значение и название в App\Enums\GifDriver.
Создайте класс в app/Services/Gif/Drivers/, унаследовав AbstractGifService, и реализуйте методы endpoint(), params(), results() и next().
Добавьте метод create{Name}Driver() в GifManager.
Добавьте ветку с ключами сервиса в match в Admin/GifSettingsController и секцию с полями в resources/js/Admin/Pages/Settings/Gifs/Edit.vue.

Драйвер возвращает результаты в формате {results, next}.

Новый AI-провайдер

Добавьте значение в App\Enums\AiProvider вместе с названием, моделью и адресом API по умолчанию.
Добавьте метод create{Name}Driver() в AiManager. Если провайдер совместим с OpenAI Chat Completions API, метод возвращает OpenAiCompatibleService. Иначе создайте драйвер в app/Services/Ai/Drivers/, унаследовав AbstractAiService и реализовав request().

Провайдер появится в списке в Админ-панель → AI → Настройки автоматически.

Новый драйвер модерации изображений

Добавьте значение и название в App\Enums\ImageModerationDriver.
Создайте класс в app/Services/Moderation/Image/Drivers/, унаследовав AbstractImageModerationService и реализовав moderateBatch().
Добавьте метод create{Name}Driver() в ImageModerationManager.
Добавьте поля настроек в ImageModerationSettingsController и resources/js/Admin/Pages/AiIntegrations/ImageModerationSettings/Edit.vue.

Новый платёжный провайдер

Добавьте значение в App\Enums\PaymentProviderDriver и перевод названия в resources/lang/*/enums.php.
Реализуйте App\Services\Payments\Contracts\PaymentProviderInterface и клиент API в app/Services/Payments/Providers/{Name}/.
Добавьте метод create{Name}Driver() в PaymentManager.
Добавьте код провайдера в правило in:yookassa,tbank в SubscriptionPaymentProviderController и SubscriptionPaymentController, поля ключей — в SubscriptionPaymentProviderController и форму настроек.
Если провайдер присылает уведомления о платежах, добавьте обработчик в App\Http\Controllers\Payments\PaymentWebhookController.

Новый язык

Переводы находятся в resources/lang/:

Файлы	Что содержат
`resources/lang/ru.json`, `resources/lang/en.json`	Строки интерфейса сайта
`resources/lang/ru/.php`, `resources/lang/en/.php`	Серверные тексты: авторизация, валидация, письма, ошибки (`errors.php`), сообщения (`messages.php`), подписи значений перечислений (`enums.php`), мета-теги

JSON-файлы подключаются через laravel-vue-i18n. Добавляя строку, вносите её во все языки с одинаковым ключом.

Чтобы добавить язык:

Создайте resources/lang/{code}.json со строками интерфейса.
Создайте каталог resources/lang/{code}/ и переведите файлы из resources/lang/en/.
Подключите локаль Moment.js в resources/js/app.js по примеру moment/dist/locale/ru.
Добавьте код языка в правило валидации in:en,ru в app/Http/Controllers/Admin/GeneralSettingsController.php, в список языков на странице общих настроек (resources/js/Admin/Pages/Settings/General/Edit.vue) и в список допустимых локалей в app/Http/Middleware/SetLocaleFromConfig.php.

Команды, события, middleware

bash

php artisan make:command MyCommand
php artisan make:event SomethingHappened
php artisan make:listener HandleSomething --event=SomethingHappened
php artisan make:middleware MyMiddleware

Команды из app/Console/Commands/ загружаются автоматически; расписание — в app/Console/Kernel.php.
Слушатели регистрируются в EventServiceProvider::$listen.
Middleware регистрируются в app/Http/Kernel.php — глобально, в группе или как псевдоним.
Наблюдатели моделей подключаются атрибутом #[ObservedBy] на модели.

Локальные пакеты

Код можно вынести в пакет и подключить через path-репозиторий Composer:

json

{
    "repositories": [
        { "type": "path", "url": "./packages/my-package" }
    ]
}

Сервис-провайдер пакета регистрируется автоматически через extra.laravel.providers в его composer.json или вручную в config/app.php.

Форк

Обновления из основного репозитория забираются в форк командами:

bash

git remote add upstream https://github.com/ADamCarraway/journalphp.git
git fetch upstream
git merge upstream/master

Расширение кода ​

Обзор ​

Сервис-провайдеры ​

Actions ​

Репозитории ​

Новая настройка в админ-панели ​

Вход через новый OAuth-провайдер ​

Новое хранилище файлов ​

Новый поисковый движок ​

Новый сервис GIF ​

Новый AI-провайдер ​

Новый драйвер модерации изображений ​

Новый платёжный провайдер ​

Новый язык ​

Команды, события, middleware ​

Локальные пакеты ​

Форк ​