Skip to content

CHANGES-V3.md

Latest commit

 

History

History
120 lines (90 loc) · 4.65 KB

CHANGES-V3.md

File metadata and controls

120 lines (90 loc) · 4.65 KB

Version 3.0 Architecture Changes

Overview

Version 3.0 introduces a plugin-based architecture for module auto-discovery. The monolithic ModularServiceProvider has been refactored into a collection of focused, composable Plugin classes. This improves extensibility, testability, and separation of concerns.

Breaking Changes

Requirements

  • PHP 8.3+ (was 8.0+)
  • Laravel 11+ (dropped Laravel 9/10 support)

Removed Features

Removed Replacement
ModularEventServiceProvider EventsPlugin (auto-registered)
AutoDiscoveryHelper FinderFactory
ModuleRegistry::getCachePath() Cache::path()
make:livewire --module Install internachi/modular-livewire
Breadcrumbs integration Load manually in service provider

Cache Changes

Before After
bootstrap/cache/modules.php bootstrap/cache/app-modules.php
Module paths only All plugin discovery data

Plugin Architecture

Core Classes

PluginRegistry       → Registration point for plugins
PluginHandler        → Orchestrates plugin lifecycle
PluginDataRepository → Manages discovery data (cached or fresh)
Cache                → File I/O for unified cache
FinderFactory        → Creates FinderCollection instances
ModuleFileInfo       → Decorator with module() and fullyQualifiedClassName()

Plugin Base Class

abstract class Plugin
{
    abstract public function discover(FinderFactory $finders): iterable;
    abstract public function handle(Collection $data);
}

PHP 8 Attributes

Attribute Behavior
#[AfterResolving(Service::class)] Defer until service resolved
#[OnBoot] Execute during booting() hook
(none) Explicit call via PluginHandler::handle()

Built-in Plugins

Plugin Trigger Responsibility
ModulesPlugin Eager Discover composer.json, create ModuleConfig
RoutesPlugin !routesAreCached() Load route files
ViewPlugin AfterResolving(ViewFactory) Register view namespaces
BladePlugin AfterResolving(BladeCompiler) Register Blade components
TranslatorPlugin AfterResolving(Translator) Register translations
EventsPlugin AfterResolving(Dispatcher) Discover event listeners
MigratorPlugin AfterResolving(Migrator) Register migration paths
GatePlugin AfterResolving(Gate) Register model policies
ArtisanPlugin Artisan::starting() Register commands

Boot Flow

ModularServiceProvider::register()
    ├─ Register singletons
    ├─ PluginRegistry::add(built-in plugins)
    └─ $app->booting(PluginHandler::boot)
            └─ For each plugin:
                    └─ Plugin::boot(handler, app)
                            └─ Read attributes, schedule execution

Extensibility

Register custom plugins in a service provider:

public function register(): void
{
    PluginRegistry::register(MyPlugin::class);
}

Custom plugins:

  • Must extend InterNACHI\Modular\Plugins\Plugin
  • Are automatically integrated into caching
  • Can use lifecycle attributes

Laravel Integration

Modular 3.0 integrates with Laravel's optimize commands via the optimizes() method:

  • php artisan optimize → runs modules:cache
  • php artisan optimize:clear → runs modules:clear

Migration Checklist

  1. Upgrade PHP to 8.3+ and Laravel to 11+
  2. Run php artisan modules:clear
  3. Run composer update internachi/modular
  4. If using Livewire: composer require internachi/modular-livewire
  5. Update any AutoDiscoveryHelper references to FinderFactory
  6. Remove any ModularEventServiceProvider references