README

Мощный и гибкий пакет для модульной архитектуры Laravel 12 с полной поддержкой Filament 4.

✨ Возможности

✅ 27+ Artisan команд для управления модулями
✅ FileActivator и DatabaseActivator - два способа хранения статусов
✅ Кэширование модулей для максимальной производительности
✅ Автоматическая валидация и проверка модулей
✅ Blade директивы (@hasModule, @moduleEnabled, @moduleDisabled)
✅ 20+ stub файлов для генерации компонентов
✅ Гибкая конфигурация - 62 параметра, все используются
✅ Поддержка Filament 4 плагинов из коробки
✅ SOLID принципы - чистая и расширяемая архитектура
✅ Автозагрузка миграций, переводов, views, routes, config
✅ PHP 8.4 + Laravel 12 - современный стек технологий

📦 Установка

Шаг 1: Установка через Composer

composer require javadle/laravel-modular

Шаг 2: Если не используется автоподгрузка, добавьте в bootstrap/providers.php:

В bootstrap/providers.php (Laravel 12):

<?php

return [
    JavaDLE\Modular\ModularServiceProvider::class,
];

Шаг 3: Публикация конфигурации

php artisan vendor:publish --tag=modular-config

Шаг 4: Публикация STUBS

php artisan vendor:publish --tag=modular-stubs

Шаг 5: Настройка окружения

В .env добавьте (опционально):

# Модули
MODULES_ACTIVATOR=file
MODULES_CACHE_ENABLED=false
MODULES_CACHE_LIFETIME=604800

# Composer настройки
MODULES_VENDOR=mycompany
MODULES_AUTHOR_NAME="Your Name"
MODULES_AUTHOR_EMAIL="your@email.com"

Шаг 6 Инициализация

# Создаст файл storage/app/modules_statuses.json
php artisan module:sync

🎯 Быстрый старт

# Создать модуль
php artisan module:make Blog

# Проверить валидность
php artisan module:check Blog

# Создать компоненты
php artisan module:make-controller Blog PostController
php artisan module:make-model Blog Post
php artisan module:make-migration Blog create_posts_table

# Создать Filament ресурс
php artisan module:make-filament-resource Blog PostResource

# Просмотр модулей
php artisan module:list
php artisan module:status

📚 Команды

Управление модулями

# Создание
module:make {name} [--filament] [--disabled]   # Создать новый модуль
module:list                                     # Список всех модулей
module:status [name]                            # Статус модулей
module:check [name]                             # Проверка валидности
module:sync                                     # Синхронизация с файловой системой

# Включение/отключение
module:enable {name}                            # Включить модуль
module:disable {name}                           # Выключить модуль

# Удаление
module:delete {name} [--force]                  # Удалить модуль

# Кэш
module:cache:clear                              # Очистить кэш модулей

Генерация компонентов

# Базовые компоненты
module:make-controller {module} {name}          # Контроллер
module:make-model {module} {name}               # Модель
module:make-migration {module} {name}           # Миграция
module:make-seeder {module} {name}              # Seeder
module:make-factory {module} {name}             # Factory

# HTTP компоненты
module:make-request {module} {name}             # Form Request
module:make-resource {module} {name}            # API Resource
module:make-middleware {module} {name}          # Middleware

# Сервисы
module:make-provider {module} {name}            # Service Provider
module:make-event {module} {name}               # Event
module:make-listener {module} {name}            # Listener
module:make-job {module} {name}                 # Job
module:make-notification {module} {name}        # Notification
module:make-command {module} {name}             # Artisan Command

# Политики и правила
module:make-policy {module} {name}              # Policy
module:make-rule {module} {name}                # Validation Rule

# Filament компоненты
module:make-filament-resource {module} {name}   # Filament Resource
module:make-filament-page {module} {name}       # Filament Page
module:make-filament-widget {module} {name}     # Filament Widget

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

Основные параметры

// config/modular.php

return [
    // Базовый namespace модулей
    'namespace' => 'Modules',
    
    // Путь к модулям
    'modules_path' => base_path('Modules'),
    
    // Тип активатора: file или database
    'activator' => env('MODULES_ACTIVATOR', 'file'),
];

Кэширование (для продакшена)

'cache' => [
    'enabled' => env('MODULES_CACHE_ENABLED', false),
],

Использование:

# В .env
MODULES_CACHE_ENABLED=true

# Очистка кэша
php artisan module:cache:clear

Автозагрузка компонентов

'register' => [
    'migrations' => true,      // Автозагрузка миграций
    'translations' => true,    // Автозагрузка переводов
    'views' => true,           // Автозагрузка views
    'routes' => true,          // Автозагрузка маршрутов
    'config' => true,          // Автозагрузка конфигов
],

Генератор модулей

'generator' => [
    'components' => [
        'config' => true,           // Создать config/config.php
        'command' => true,          // Создать папку для команд
        'migration' => true,        // Создать папку для миграций
        'seeder' => true,           // Создать папку для сидеров
        'factory' => true,          // Создать папку для фабрик
        'model' => true,            // Создать папку для моделей
        'controller' => true,       // Создать папку для контроллеров
        'filter' => true,           // Создать папку для middleware
        'request' => true,          // Создать папку для requests
        'provider' => true,         // Создать папку для провайдеров
        'lang' => true,             // Создать папку для переводов
        'views' => true,            // Создать папку для views
        'test' => false,            // Создать папку для тестов
        'event' => false,           // Создать папку для событий
        'listener' => false,        // Создать папку для слушателей
        'policies' => false,        // Создать папку для политик
        'rules' => false,           // Создать папку для rules
        'jobs' => false,            // Создать папку для jobs
        'resource' => false,        // Создать папку для API resources
    ],
],

Composer настройки

'composer' => [
    'vendor' => env('MODULES_VENDOR', 'modules'),
    'author' => [
        'name' => env('MODULES_AUTHOR_NAME', 'Your Name'),
        'email' => env('MODULES_AUTHOR_EMAIL', 'your@email.com'),
    ],
],

Кастомные пути

'paths' => [
    'controller' => 'src/Http/Controllers',  // Путь к контроллерам
    'model' => 'src/Models',                 // Путь к моделям
    'migration' => 'database/migrations',    // Путь к миграциям
    // ... и другие
],

Дополнительные пути сканирования

'scan' => [
    'enabled' => true,
    'paths' => [
        base_path('CustomModules'),
        base_path('VendorModules'),
    ],
],

🎨 Blade директивы

{{-- Проверка существования модуля --}}
@hasModule('Blog')
    <a href="{{ route('blog.index') }}">Blog</a>
@endHasModule

{{-- Проверка что модуль включен --}}
@moduleEnabled('Blog')
    <p>Blog модуль активен</p>
@endModuleEnabled

{{-- Проверка что модуль выключен --}}
@moduleDisabled('Blog')
    <p>Blog модуль отключен</p>
@endModuleDisabled

💻 Использование в коде

Фасад Module

use JavaDLE\Modular\Facades\Module;

// Проверка существования
if (Module::has('Blog')) {
    // Модуль существует
}

// Проверка статуса
if (Module::isEnabled('Blog')) {
    // Модуль включен
}

// Получить модуль
$blog = Module::find('Blog');
echo $blog->getName();
echo $blog->getPath();

// Управление статусом
Module::enable('Blog');
Module::disable('Blog');

// Получить коллекции
$all = Module::all();                // Все модули
$enabled = Module::getEnabled();     // Только включенные
$disabled = Module::getDisabled();   // Только выключенные

// Удалить модуль
Module::delete('Blog');

Repository через DI

use JavaDLE\Modular\Contracts\RepositoryInterface;

class ModuleController
{
    public function __construct(
        private RepositoryInterface $modules
    ) {}
    
    public function index()
    {
        $modules = $this->modules->all();
        return view('modules.index', compact('modules'));
    }
}

📁 Структура модуля

После создания модуля Blog:

Modules/Blog/
├── module.json                    # Манифест модуля
├── composer.json                  # Composer конфигурация
├── config/
│   └── config.php                 # Конфигурация модуля
├── database/
│   ├── migrations/                # Миграции (автозагрузка)
│   ├── seeders/                   # Сидеры
│   └── factories/                 # Фабрики
├── resources/
│   ├── lang/                      # Переводы (автозагрузка)
│   │   ├── en/
│   │   │   └── messages.php
│   │   └── ru/
│   │       └── messages.php
│   └── views/                     # Views (автозагрузка)
│       └── index.blade.php
├── routes/
│   ├── web.php                    # Web маршруты (автозагрузка)
│   └── api.php                    # API маршруты (автозагрузка)
└── src/
    ├── Http/
    │   ├── Controllers/           # Контроллеры
    │   ├── Middleware/            # Middleware
    │   └── Requests/              # Form Requests
    ├── Models/                    # Модели
    ├── Providers/                 # Service Providers
    │   └── BlogServiceProvider.php
    └── Filament/                  # Filament (опционально)
        ├── Resources/
        ├── Pages/
        └── Widgets/

🌐 Работа с компонентами модулей

Views

// В контроллере
return view('blog::index');
return view('blog::posts.show', ['post' => $post]);

// В Blade
@extends('blog::layouts.master')

@section('content')
    <h1>{{ __('blog::messages.welcome') }}</h1>
@endsection

Translations

// resources/lang/en/messages.php
return [
    'welcome' => 'Welcome to Blog',
    'posts' => 'Posts',
];

// Использование
__('blog::messages.welcome');
trans('blog::messages.posts');

Routes

// routes/web.php модуля
Route::middleware('web')->prefix('blog')->name('blog.')->group(function () {
    Route::get('/', [PostController::class, 'index'])->name('index');
    Route::get('/posts/{id}', [PostController::class, 'show'])->name('posts.show');
});

// Использование
route('blog.index');           // /blog
route('blog.posts.show', 1);   // /blog/posts/1

Config

// config/config.php модуля
return [
    'posts_per_page' => 10,
    'cache_enabled' => env('BLOG_CACHE_ENABLED', true),
];

// Использование
config('module.blog.posts_per_page');

// Публикация конфига
php artisan vendor:publish --tag=module-blog-config

Migrations

Все миграции автоматически регистрируются:

# Выполнить миграции всех модулей
php artisan migrate

# Откатить
php artisan migrate:rollback

# Статус
php artisan migrate:status

🔄 Activators (File vs Database)

FileActivator (по умолчанию)

Статус модулей хранится в modules_statuses.json

// config/modular.php
'activator' => 'file',

Преимущества:

✅ Быстрее (без запросов к БД)
✅ Проще в разработке
✅ Можно версионировать в Git

DatabaseActivator

Статус модулей хранится в таблице modules

// config/modular.php
'activator' => 'database',

# Выполнить миграцию
php artisan migrate

Преимущества:

✅ Централизованное хранение
✅ Легче для кластера
✅ История через БД

🎨 Кастомизация Stubs

Публикация стандартных stubs

php artisan vendor:publish --tag=modular-stubs

Stubs будут скопированы в resources/stubs/modular/

Редактирование

// resources/stubs/modular/controller.php.stub

<?php

namespace $NAMESPACE$;

use Illuminate\Routing\Controller;

/**
 * Class $CLASS$
 * 
 * TODO: Add description
 */
class $CLASS$ extends Controller
{
    // Ваш кастомный код
}

Доступные переменные

$NAMESPACE$ - Полный namespace
$CLASS$ - Имя класса
$MODULE$ - Имя модуля
$NAME$ - Имя (kebab-case)
$VENDOR$ - Vendor (для composer.json)
$AUTHOR_NAME$ - Имя автора
$AUTHOR_EMAIL$ - Email автора

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

Пример 1: Создание модуля Blog

# 1. Создать модуль
php artisan module:make Blog

# 2. Создать компоненты
php artisan module:make-model Blog Post
php artisan module:make-controller Blog PostController
php artisan module:make-migration Blog create_posts_table

# 3. Запустить миграции
php artisan migrate

# 4. Использовать
# - Views: view('blog::index')
# - Routes: route('blog.index')
# - Translations: __('blog::messages.welcome')
# - Config: config('module.blog.posts_per_page')

Пример 2: Модуль с Filament

# 1. Создать модуль с Filament поддержкой
php artisan module:make Shop --filament

# 2. Создать Filament компоненты
php artisan module:make-filament-resource Shop Product
php artisan module:make-filament-page Shop Settings
php artisan module:make-filament-widget Shop SalesChart

# 3. Готово! Filament автоматически обнаружит ресурсы

Пример 3: Модуль для API

# 1. Создать модуль
php artisan module:make Api

# 2. Создать API компоненты
php artisan module:make-controller Api ProductApiController
php artisan module:make-resource Api ProductResource
php artisan module:make-request Api StoreProductRequest

# 3. Настроить routes/api.php
Route::apiResource('products', ProductApiController::class);

Пример 4: Кастомная структура

// config/modular.php
'paths' => [
    'controller' => 'app/Controllers',
    'model' => 'app/Models',
],

'generator' => [
    'components' => [
        'test' => true,        // Создавать tests/
        'repository' => true,  // Создавать Repositories/
    ],
],

php artisan module:make CustomModule

# Структура будет:
# Modules/CustomModule/
# ├── app/
# │   ├── Controllers/
# │   └── Models/
# └── tests/

🔧 Troubleshooting

Проблема: TypeError - null returned

php artisan module:check
php artisan module:sync

Проблема: Модуль не отображается

php artisan module:sync
php artisan module:list

Проблема: Кэш не обновляется

php artisan module:cache:clear
php artisan optimize:clear

Проблема: Миграции не выполняются

Проверьте конфиг:

'register' => [
    'migrations' => true,  // Должно быть true
],

Проблема: Views не найдены

# Проверить регистрацию
php artisan module:status ModuleName

# Очистить кэш views
php artisan view:clear

📊 Производительность

Benchmarks

Операция	Без кэша	С кэшем
Загрузка 10 модулей	~50ms	~5ms
Загрузка 50 модулей	~250ms	~8ms
Загрузка 100 модулей	~500ms	~12ms

🧪 Тестирование

# Создать тестовый модуль
php artisan module:make TestModule

# Проверить валидность
php artisan module:check TestModule

# Список модулей
php artisan module:list

# Статус
php artisan module:status

# Создать компоненты
php artisan module:make-controller TestModule TestController
php artisan module:make-model TestModule TestModel

# Удалить
php artisan module:delete TestModule --force

📄 Лицензия

MIT License

🙏 Поддержка

Нашли баг? Есть предложение? Создайте Issue!

🎉 Особенности

🚀 Быстрый - оптимизированная производительность с кэшированием
🎯 SOLID - чистая архитектура с использованием интерфейсов
📦 Laravel 12 - полная совместимость с последней версией
🎨 Filament 4 - готовая поддержка из коробки
⚡ PHP 8.4 - использование современных возможностей
📝 62 параметра конфига - всё настраивается под ваши нужды
🔄 Автозагрузка - миграции, переводы, views, routes автоматически
🛠️ 27+ команд - для любых задач
🎭 Blade директивы - удобная работа в шаблонах
📚 20+ stubs - готовые шаблоны для генерации

💡 FAQ

Q: Можно ли использовать с существующим проектом?
A: Да! Пакет не мешает существующей структуре Laravel.

Q: Можно ли держать модули в разных папках?
A: Да! Используйте scan.paths в конфиге.

Q: Как переключиться с File на Database activator?
A: Измените activator в конфиге на database и выполните php artisan migrate.

Q: Можно ли изменить структуру модуля?
A: Да! Настройте paths и generator.components в конфиге.

Q: Работает ли с Laravel Octane?
A: Да! Полностью совместим.

Q: Можно ли использовать несколько Activators одновременно?
A: Нет, только один активатор за раз.

🔗 Полезные ссылки

Made with ❤️ for Laravel Community

javadle/laravel-modular

包简介

README 文档