README

Manifest-driven runtime для модулей в Laravel 12/13.

ewk/laravel-modules помогает Laravel-приложению находить модули в настроенных директориях, валидировать module.json, сортировать модули по зависимостям и загружать enabled-модули через предсказуемый loader pipeline.

Пакет покрывает runtime loading, feature values, production registry cache, lifecycle-команды (make:module, modules:install, modules:update, modules:remove, modules:enable, modules:disable, modules:list, modules:optimize, modules:optimize-clear) и module-aware генераторы: native make:* --module для 22 артефактов плюс архитектурные make:use-case/action/query/dto/vo (см. docs/cli.md). Опциональный MoonShine admin-UI управляет модулями из админки (docs/moonshine.md); установка/обновление через zip-upload в UI остаётся roadmap.

Quick Start

composer require ewk/laravel-modules
php artisan vendor:publish --tag=modules-config
php artisan make:module blog

Проверка production cache:

php artisan modules:optimize

Требования

Компонент	Версия
PHP	8.3+
Laravel	12 / 13
Optional admin bridge	MoonShine 4
Optional routes bridge	Inertia 2

Возможности

Manifest-first modules: immutable metadata и feature schema живут в module.json; mutable state и feature values - в state.json.
Dependency-aware registry: meta.dependencies сортируются и проверяются через Composer SemVer constraints.
Loader pipeline: 15 convention-based loaders загружают config, providers, migrations, routes, commands, policies, middleware и другие runtime paths.
Runtime feature API: FeatureRepositoryInterface читает актуальные settings.values из state.json.
Production cache: modules:optimize кеширует discovery в bootstrap/cache/modules.php, но не кеширует state и values.
Lifecycle toolkit: scaffold, install, update, remove, enable и disable работают через UseCase-классы с backup/rollback boundaries.
Opt-in диагностическое логирование: off by default; включается через MODULES_LOGGING=true и пишет structured discovery/cache/pipeline/lifecycle события на выбранный канал хоста для field-diagnostics (docs/logging.md).
Optional bridges: MoonShine и Inertia активируются только при наличии соответствующих пакетов.

Минимальный модуль

php artisan make:module blog

Команда создаёт структуру модуля, module.json, ServiceProvider stub и приватный state.json.

Минимальный module.json после scaffold:

{
  "schema_version": 1,
  "meta": {
    "name": "blog",
    "display_name": "Blog",
    "kind": "module",
    "group": "content",
    "version": "1.0.0"
  },
  "settings": {
    "schema": {}
  }
}

schema_version, meta.name, meta.kind и meta.version — обязательные; meta.group — необязательное (kebab-case группа для отображения в modules:list). Полный контракт — в docs/manifest.md.

storage/app/private/modules/blog/state.json:

{
  "enabled": true,
  "installed_at": "2026-05-23T14:12:00+00:00",
  "updated_at": "2026-05-23T14:12:00+00:00",
  "source": {
    "kind": "local",
    "installed_version": "1.0.0"
  },
  "settings": {
    "values": {}
  }
}

Feature Usage

Добавьте feature schema и values, как описано в docs/feature-toggles.md, затем читайте их через scoped repository:

<?php

declare(strict_types=1);

use Ewk\LaravelModules\Contracts\FeatureRepositoryInterface;

final readonly class PostController
{
    public function __construct(
        private FeatureRepositoryInterface $features,
    ) {
    }

    public function index(): void
    {
        $commentsEnabled = $this->features->getBool('blog', 'enable_comments');
    }
}

Документация

Раздел	Описание
Getting Started	Установка и первая проверка
Module Structure	Поддерживаемые runtime-пути
Manifest	Контракт `module.json`
Configuration	Конфиг и routing options
MoonShine	Опциональный admin-UI управления модулями
Architecture	Registry, cache, loaders, lifecycle
Loaders	Справочник лоадеров и написание своего
Feature Toggles	Runtime settings API
Logging	Opt-in диагностический слой и каталог событий
Octane	Octane worker contract и reload-операционка
CLI	Реализованные Artisan-команды
AI Skills	Поставляемые Agent Skills и `modules:ai-install`
Contributing	Quality gates и PR rules

License

MIT

ewk / laravel-modules

Maintainers

Package info

Statistics

Security