nWidart/laravel-modules

This system is a modular architecture package for Laravel and Lumen applications, enabling the creation, management, and lifecycle control of isolated software modules. It provides a comprehensive suite of console commands for scaffolding components like controllers, models, and Inertia pages, while handling module activation, dependency resolution, and asset publishing. The system integrates with modern build tools like Vite and supports granular configuration for code generation, ensuring modules can be developed and deployed as distinct, self-contained units within the host application.

21 changes.

The project underwent a comprehensive overhaul to support Laravel 13 and PHP 8.3, replacing legacy code with modern conventions such as Vite, anonymous migrations, and strict typing. This period introduced Lumen compatibility, a new module manifest system, and a complete rewrite of stubs and console commands to align with current framework standards. Additionally, a robust test suite was established to ensure the stability of these extensive architectural changes.

22 changes.

This period focused on extending framework compatibility by adding specific support for Laravel Vapor and Lumen, alongside a comprehensive expansion of console commands for generating and managing module artifacts. The work introduced robust scaffolding for Inertia.js, Vite asset aggregation, and file-based module activation, significantly enhancing the developer experience for creating and maintaining modular applications.

The Module facade now exposes a static \prohibitDestructiveCommands\ method that allows users to prevent the execution of potentially dangerous database operations (\module:migrate-fresh\, \module:migrate-refresh\, and \module:migrate-reset\). When this method is called with \true\, it delegates to the underlying migration commands to enforce the prohibition, providing a centralized control point for database safety within the module system.

src/Facades · high confidence

A new ModuleEvent constant class has been introduced to define standard event names for module lifecycle operations, including boot, register, enabling/disabling, creating/deleting, and usage states. This provides a centralized, consistent set of string identifiers for these events across the application.

src/Constants · high confidence

New stub files have been added to the \src/Commands/stubs/inertia\ directory to support scaffolding Inertia.js applications with React, Vue 3, and Svelte. These stubs include entry-point configurations (\app-\.stub\) that initialize the Inertia app and resolve page components from both the main application and module directories, as well as template stubs for pages (\page-\.stub\) and components (\component-\*.stub\) tailored to each framework's syntax.

src/Commands/stubs/inertia · high confidence

The AI assistant now includes dedicated support for the nWidart/laravel-modules package. A new core guideline file (.ai/laravel-modules/core.blade.php) provides an overview of the modular architecture, while a specific skill (.ai/laravel-modules/1/skill/laravel-modules-development/SKILL.blade.php) offers detailed instructions for creating modules, generating components (controllers, models, migrations, etc.), managing module lifecycles, and handling Inertia.js integration within modules. This enables the assistant to guide users through module-based development patterns and artisan commands.

.ai · high confidence

Introduces standard development configuration files including .editorconfig for consistent coding styles, .gitattributes to exclude development artifacts from packaged releases, and .php-cs-fixer.dist.php to enforce PSR-12 compliance. Additionally, adds pint.json for Laravel preset formatting, phpunit.xml.dist for test execution, and .travis.yml for continuous integration, while updating .gitignore to exclude build and cache artifacts.

(repo-wide) · high confidence

A new FileActivator class has been added to manage module activation states by reading and writing status data to a JSON file. This implementation persists module enable/disable actions to disk, allowing the system to track which modules are active across requests without relying on in-memory state or a database.

src/Activators · high confidence

This change introduces Laravel-specific implementations for module handling, including a new \LaravelFileRepository\ and \Module\ class that extend the base module functionality. The \Module\ class now includes logic to detect Laravel Vapor environments via the \modules.vapor\_maintenance\_mode\ config setting, ensuring that cached service paths are written to a writable location compatible with Vapor's constraints. Additionally, provider and alias registration methods are implemented to leverage Laravel's native \ProviderRepository\ and \AliasLoader\ for proper integration.

src/Laravel · high confidence

Users running Lumen can now use the module system with Lumen-specific implementations. The diff introduces \src/Lumen/LumenFileRepository.php\ and \src/Lumen/Module.php\. \LumenFileRepository\ extends the base \FileRepository\ to provide Lumen-specific module creation. \Module\ extends the base \Module\ class to override \getCachedServicesPath\ (customizing the service cache file name to include the snake-cased module name) and \registerProviders\ (iterating through providers to register them with the Lumen application container), while \registerAliases\ is implemented as a no-op, reflecting Lumen's lack of alias support.

src/Lumen · high confidence

The package now supports Lumen 5.5.x alongside Laravel, introducing a dedicated \LumenModulesServiceProvider\ that registers a \LumenFileRepository\ and configures stub paths. Module service providers are no longer loaded via the legacy bootstrap process; instead, a new \ModuleManifest\ class builds a manifest of enabled modules and their providers, which is then loaded by the \ModulesServiceProvider\ using Laravel's \ProviderRepository\. This change also includes a \@module()\ Blade directive for status checks, a \module()\ helper function, and Vite integration via a \module\_vite()\ helper and a publishable \vite-module-loader.js\ script.

src · high confidence

The \src/Commands/Publish\ directory now contains five new console commands that allow users to publish specific module resources individually: \module:publish\ for general assets, \module:publish-config\ for configuration files (with dynamic service provider resolution), \module:publish-migration\ for database migrations, \module:publish-translation\ for language files, and \module:publish-inertia\ for frontend app.js stubs (supporting Vue, React, and Svelte). These commands provide granular control over which module components are copied to the application, replacing or supplementing broader publishing mechanisms.

src/Commands/Publish · high confidence

Added NameParser and SchemaParser classes to the Nwidart\\Modules\\Support\\Migrations namespace. NameParser analyzes migration file names to determine the schema action (create, delete, add, drop) and target table. SchemaParser converts schema definition strings into structured arrays and generates the corresponding Laravel migration code, including support for foreign key constraints via relationship keys.

src/Support/Migrations · high confidence

The \src/Commands/Make\ directory now contains a comprehensive suite of new console commands for scaffolding module components. Users can generate Actions, Casts, Enums, Exceptions, Helpers, Interfaces, Listeners, Observers, Repositories, and Service Providers using dedicated commands (e.g., \module:make-action\, \module:make-enum\). The suite also includes commands for Inertia integration (\module:make-inertia-component\, \module:make-inertia-page\) with support for Vue, React, and Svelte, as well as enhanced generation for Controllers, Models, and Resources with additional flags like \--invokable\, \--api\, and \--all\. A new \module:make-replacement\ command allows for creating custom stub replacement keys.

src/Commands/Make · high confidence

A new \scripts/vite-module-loader.js\ script has been added to the project. This utility reads the \modules\_statuses.json\ file to identify enabled modules and dynamically imports their individual \vite.config.js\ files to aggregate their configured asset paths. This enables the build system to automatically discover and include assets from specific, enabled Vite modules.

scripts · high confidence

This change introduces three new classes in the Nwidart\\Modules\\Support namespace to enhance module generation and configuration handling. ModuleServiceProvider provides an abstract base for module service providers, centralizing the registration of commands, schedules, translations, config, and views, while also adding a check to skip config merging when the configuration is cached. Stub offers a reusable mechanism for loading and rendering stub files with placeholder replacements, falling back to default stubs if overrides are not found. ReplacementKeyCommand serves as an abstract base for commands that handle key replacement logic during module generation.

src/Support · high confidence

Two new traits are introduced in src/Traits: PathNamespace provides methods to generate and clean module namespaces and paths (e.g., studly\_path, path\_namespace, module\_namespace, clean\_path, app\_path), and CanClearModulesCache adds a clearCache method that resets the modules cache via resetModules. Existing traits are updated: MigrationLoaderTrait’s loadMigrationFiles and getMigrationGeneratorPath now have explicit string type hints and their docblocks are removed, and ModuleCommandTrait’s getModuleName now uses the app() helper instead of the Laravel container to resolve the modules service, with its docblock removed.

src/Traits · high confidence

The ConsoleServiceProvider now registers commands by merging a new, expanded list of default commands with any custom commands defined in the \modules.commands\ configuration file, allowing users to override or extend the command set. The provider also removes the deprecated \defer\ property and switches to using fully qualified class names (e.g., \Commands\\Make\\ControllerMakeCommand::class\) instead of string concatenation for command registration. Additionally, the ContractsServiceProvider updates the \RepositoryInterface\ binding to explicitly use \LaravelFileRepository\, aligning with the preparation for a database implementation.

src/Providers · high confidence

The stubs in src/Commands/stubs have been completely rewritten to align with modern Laravel standards (5.5+ through 8+). Key changes include: replacing the legacy \fire()\ method with \handle()\ in console commands and updating \$name\ to \$signature\; switching controllers to extend \App\\Http\\Controllers\\Controller\ and adding full CRUD methods; updating models to use the \HasFactory\ trait and factories to extend \Illuminate\\Database\\Eloquent\\Factories\\Factory\; modernizing service providers to use \register()\ and \provides()\ with return types, and updating the route service provider to use \map()\ and \boot()\ instead of \before()\ and \map()\ with Router injection; adding support for Vite via \vite.stub\ and \package.stub\ (replacing Laravel Mix); introducing new stubs for invokable actions/helpers, enums, casts, scopes, and Inertia controllers; and updating the \composer.stub\ to include \autoload-dev\ and \extra.laravel\ for auto-discovery.

src/Commands/stubs · high confidence

The database management commands (migrate, migrate-fresh, migrate-refresh, migrate-reset, migrate-rollback, migrate-status, and seed) have been moved into a new \Database\ subdirectory and refactored to extend \BaseCommand\ instead of Laravel's base \Command\. This change introduces a \direction\ option (defaulting to 'asc' for migrate, 'desc' for reset/rollback) to control migration ordering, adds a \subpath\ option to \migrate\ and \migrate-rollback\ for targeting specific migration directories, and implements the \ConfirmableCommand\ interface on \migrate-fresh\ and \migrate-reset\ to enforce confirmation steps. Additionally, \migrate-fresh\ now explicitly handles root-level migrations after wiping the database, and \migrate-rollback\ now accepts a \subpath\ argument to limit rollbacks to specific module migration files.

src/Commands/Database · high confidence

The generated route stubs for new modules now apply authentication middleware by default. The API route stub (api.stub) uses the 'auth:sanctum' middleware with a 'v1' prefix, while the web route stub (web.stub) applies 'auth' and 'verified' middleware. This ensures that newly generated module routes are protected out of the box, aligning with the project's security posture for modules.

src/Commands/stubs/routes · high confidence

The FileGenerator class now includes a \withFileOverwrite\ method that allows generated files to overwrite existing ones. Previously, the generator would silently skip files that already existed; with this change, users can explicitly enable overwriting during file generation. Additionally, the \FileAlreadyExistException\ has been moved to the \Nwidart\\Modules\\Exceptions\ namespace, and type hints have been added to the \FileGenerator\ and \ModuleGenerator\ classes for better code clarity and static analysis support.

src/Generators · high confidence

The module configuration has been significantly overhauled to align with modern Laravel conventions and improve customization. The default module namespace path has changed from 'modules' to 'Modules', and the 'app\_folder' setting now defaults to 'app/'. The stub system is expanded to support separate web and API route files, Vite configuration, and new asset stubs (JS/Sass), while replacing the old 'module.json' stub with a dynamic generation approach. The generator configuration now uses a granular, nested structure for each component type (e.g., models, controllers, events), allowing users to explicitly define paths and enable/disable generation for specific folders like Actions, Casts, or Jobs, which were previously fixed or absent.

config · high confidence

The migration stubs in src/Commands/stubs/migration have been refactored to generate anonymous classes instead of named classes, aligning with modern Laravel conventions. Additionally, the 'create' and 'drop' stubs now use the $table-\>id() method for primary keys instead of $table-\>increments('id'), and the 'drop' stub uses Schema::dropIfExists() for safer table removal. All stubs also include the Schema facade import, use void return types for up/down methods, and follow PSR-2 formatting standards.

src/Commands/stubs/migration · high confidence

The Migrator class has been updated to allow specifying a sub-path for module-specific migration files, enabling more granular organization of migration scripts. It now accepts an explicit database connection via a new setDatabase method, ensuring that migration operations target the correct database instance rather than relying on defaults. Additionally, the migration path resolution logic has been refactored to read from a configurable 'migration' path setting, allowing users to customize where migrations are stored. The class also includes improvements to handle anonymous migration files by checking file existence before instantiation, and uses modern PHP syntax and type hints throughout.

src/Migrations · high confidence

The module management console commands have been refactored to extend a new BaseCommand class, standardizing their structure and output. Existing commands (enable, disable, update, use, delete, install, list) now use a unified task-based display format and, in the case of ListCommand, display module priority instead of order. Additionally, several new action commands have been introduced: CheckLangCommand to identify missing language files and keys across modules, DumpCommand to run optimized autoloaders, ModelPruneCommand to prune models by module with interactive selection, ModelShowCommand to display Eloquent model information with interactive search, and ListCommandsCommand to list all commands within a module grouped by directory.

src/Commands/Actions · high confidence

The module repository interface has been significantly expanded to support new capabilities and stricter typing. New methods have been added for configuration access (config), file system interaction (getFiles), module lifecycle management (boot, register), asset path resolution (assetPath), and module deletion (delete). The interface also introduces specific checks for module activation status via isEnabled and isDisabled, replacing the previous generic status queries. Several existing methods have been renamed for clarity: enabled and disabled are now allEnabled and allDisabled, and return types have been added to methods like scan, toCollection, and count to improve type safety and IDE support.

src/Contracts · high confidence

The library now includes dedicated exception classes to provide clearer error reporting for specific failure scenarios. A new \InvalidActivatorClass\ exception is thrown when the activator configuration is missing or outdated, offering a static helper to guide users toward running the vendor publish command. Additionally, \InvalidAssetPath\ is introduced to catch cases where a module name is missing from an asset path, while \FileAlreadyExistException\ and \InvalidJsonException\ are added to handle file and JSON validation errors respectively. The existing \ModuleNotFoundException\ has also been simplified.

src/Exceptions · high confidence

The publisher classes in src/Publishing now use strict PHP types for properties and return values, removing legacy docblock-only type hints. AssetPublisher and LangPublisher have switched from reading paths via the repository to using the new GenerateConfigReader, while MigrationPublisher now accepts a Migrator instance to determine source paths, decoupling it from the generic repository config for migration-specific logic.

src/Publishing · high confidence

The command infrastructure has been modernized: \SetupCommand\ now uses the \handle()\ method with integer return codes and Laravel's \components\ API for output, replacing the legacy \fire()\ method and direct \info()\/\error()\ calls. A new \BaseCommand\ abstract class introduces a \--all\ (\-a\) option, integrates \ConfirmableTrait\ and \Prohibitable\ for production safety, and implements \multisearch\ prompts for module selection. New commands include \module:composer-update\ to fix PSR-4 autoload paths in module \composer.json\ files, and \module:v6:migrate\ to convert v5 module statuses to v6. The \UpdatePhpunitCoverage\ command now uses configurable paths for the app folder and module statuses file. Additionally, the deprecated \PublishMigrationCommand\ has been removed.

src/Commands · high confidence

The configuration system for module generation paths has been updated to use a new \GeneratorPath\ class and \GenerateConfigReader\. This change allows generator settings to be defined as structured arrays containing \path\, \generate\, and optional \namespace\ keys, rather than simple strings or booleans. When a namespace is not explicitly provided, it is automatically derived from the path relative to the application folder, ensuring consistent namespace generation for newly created module components.

src/Support/Config · high confidence

The module installation and update workflows have been refactored to improve type safety and performance. The Installer class now uses strict PHP 8+ typed properties and interfaces (RepositoryInterface), and simplifies its git installation logic by replacing a switch statement with direct conditional checks. The Updater class has been significantly enhanced: it now installs both require and require-dev packages in single Composer calls instead of one-by-one, supports silencing Composer output via configuration, and automatically merges module scripts into the main project's composer.json file.

src/Process · high confidence

The generated module service provider stub has been refactored to extend \ModuleServiceProvider\ instead of the base Laravel \ServiceProvider\. This change removes the manual implementation of config, view, and translation registration methods, as well as the deprecated \defer\ property, relying on the parent class to handle these registrations. The new stub also introduces properties for the module name and includes pre-configured arrays for registering event and route service providers, streamlining the boilerplate for new modules.

src/Commands/stubs/scaffold · high confidence

The generated view stubs have been refactored from the legacy @extends/@section/@yield syntax to Laravel's modern component-based layout system (\<x-...\>). The index stub now wraps content in a component tag, and the master stub has been updated to use {{ $slot }} for content injection, includes a CSRF token meta tag, adds standard SEO meta tags, integrates the Figtree font via BunnyCDN, and prepares placeholders for Vite asset compilation (currently commented out).

src/Commands/stubs/views · high confidence

Added snapshot tests for FileActivator JSON output; Added test coverage for module action commands; Added test stubs for feature and unit tests; Added test stubs for the Recipe module; Added tests for FileActivator module status management; Added tests for PathNamespace trait methods; Added tests for module:make commands; Added tests for the module update-phpunit-coverage command; Added unit tests for module contracts, facades, and support utilities; Initial test suite for module management and commands.

The package has been upgraded to require PHP 8.3 and Laravel 13, dropping support for older versions. This change removes legacy dependencies such as \pingpong/generators\, \pingpong/support\, and \laravelcollective/html\, while introducing new dev tools including \laravel/pint\, \phpstan/phpstan\, and \spatie/phpunit-snapshot-assertions\. The minimum PHPUnit version is now 12, and the \wikimedia/composer-merge-plugin\ is added as a runtime dependency to support external configuration merging.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 68.

• Code Health 96
• Architecture 95
• Maturity 49
• Readiness 77
• Security 98

• 300 commits — 244 feature/other, 56 fixes

• (repo) — 95 commits
• src/Commands — 56 commits
• tests/Commands — 46 commits
• (root) — 15 commits
• src/Support — 13 commits
• config/config.php — 12 commits
• src/LaravelModulesServiceProvider.php — 11 commits
• src/Generators — 7 commits
• src/ModuleManifest.php — 7 commits
• src/helpers.php — 6 commits
• .github/workflows — 4 commits
• src/Contracts — 4 commits
• src/Module.php — 4 commits
• src/FileRepository.php — 3 commits
• tests/ModuleHelperTest.php — 3 commits
• .ai/laravel-modules — 2 commits
• .github/FUNDING.yml — 2 commits
• src/Activators — 2 commits
• .github/ISSUE_TEMPLATE — 1 commit
• scripts/vite-module-loader.js — 1 commit

• fix: Fix Module translation loading missing namespace
• fix: Fix migration path configuration key
• fix: Fix namespace import and update schedule parameter type
• fix: Fixes #1972 modules:make generate double separator
• fix: Merge pull request #1932 from rupeshstha/fix/fix-interface
• fix: Merge pull request #1978 from elemes1/1867-fix-vite-module-windows-os
• fix: Merge pull request #1981 from nWidart/fix-paths-for-publishing
• fix: Merge pull request #2059 from nWidart/hot-fixes-for-mismatch-variables
• fix: Merge pull request #2135 from itshichabk/fix-enable-module-command-log
• fix: Potential fix for pull request finding
• fix: Revert "Merge pull request #1898 from solomon-ochepa/optiomize-file-repository"
• fix: Revert "Merge pull request #1920 from alissn/RegisterLangFiles"
• fix: Revert "Revert "Merge pull request #1920 from alissn/RegisterLangFiles""
• fix: [bug] Fix issue with omitted config.php key name
• fix: [bug] Update $module property typecasting to mixed
• fix: [fix] Comment out the factory method
• fix: [fix] bug fix after search and select items
• fix: [fix] change method name
• fix: [fix] deprecate discover command and delete tests
• fix: [fix] fix auto-discover of translations file
• …and 280 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

nWidart/laravel-modules was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.