Download the PHP package alizharb/laravel-modular without Composer

Laravel Modular 🚀

Laravel Modular is a professional, framework-agnostic modular system engineered for Laravel 11/12/13. It empowers you to build scalable, strictly typed, and decoupled applications with zero configuration overhead.

We override 29+ native Artisan commands to provide a seamless "first-class" modular experience, feeling exactly like standard Laravel but better.

✨ Features

• 🏗️ Native Experience: 29+ Artisan commands (make:model, make:controller, etc.) fully support --module.
• ⚡ Zero Config Autoloading: Intelligent composer-merge-plugin integration for isolated module dependencies.
• 🚦 Topological Sorting: Strict dependency graph resolution ensures base modules always boot before their dependents.
• 🚀 Performance First: Built-in discovery caching (modular:cache) for near-zero overhead in production.
• 🔄 Dynamic Activation: Enable or disable modules on the fly via module:enable and module:disable.
• 🔍 Auto-Discovery: Automatic registration of Artisan commands, Policies, and Event Listeners within modules.
• 🔌 Decoupled Architecture: Strictly typed ModuleRegistry and traits for maximum stability.
• 🧭 Production Diagnostics: modular:doctor, modular:status, modular:debug, modular:graph, and modular:why make module state transparent.
• 🧠 Laravel Boost Ready: Ships package guidelines and a dedicated Boost skill for AI-assisted modular development.
• 🧩 Migration Friendly: Includes modular:import-nwidart to preview and migrate nwidart-style modules.
• ✅ Laravel 11, 12 & 13 Ready: Optimized for PHP 8.2+ and the latest framework features.
• 🎨 Asset Management: Seamless Vite integration via modular_vite() and asset linking.

🌍 Ecosystem

Enhance your modular application with our official packages:

• Laravel Hooks: specific modular hook system support.
• Filament Integration: Seamless Filament admin panel integration in modules.
• Livewire Integration: First-class Livewire component support in modules.
• Laravel Themer: Advanced theme management system.

🚀 Installation

Install the package via Composer:

Preview the installer without writing files:

Run the installation command to automatically configure your application:

Note: This will automatically install and configure wikimedia/composer-merge-plugin to handle your module dependencies.

Manual Setup

If you prefer to configure things manually, follow these steps:

1. Composer Autoloading Add the following to your root composer.json to ensure module namespaces are autoloaded:

2. Vite Configuration To enable hot-reloading for module assets, create a vite.modular.js file in your root and update vite.config.js:

📖 Usage

Creating a Module

Generate a fully structured module in seconds:

Generating Resources

Every standard Laravel make: command acts as a modular command when you pass the --module flag:

Modular Database

Run migrations and seeders specifically for your modules:

Module Management & Utilities

Blade Directives

Use our dedicated Blade directives to conditionally render UI based on module availability:

🏎️ Performance Optimization

For maximum production performance, we recommend the following:

1. Optimized PSR-4: Ensure "Modules\\": "modules/" is in your root composer.json. modular:install handles this for you.
2. Dependency Syncing: Use php artisan modular:sync to merge module dependencies into your root composer.json and disable the merge-plugin.
3. Discovery Caching: Always run php artisan modular:cache in your deployment pipeline.
4. Cache Refreshing: Use php artisan modular:refresh when deployments reuse build artifacts or cache directories.
5. Health Checks: Run php artisan modular:doctor --json in CI or deployment validation.

modular:cache stores module metadata, statuses, discovered resources, manifest hashes, dependency hashes, provider lists, and a cache timestamp. modular:doctor warns when cached module manifests no longer match disk.

Middleware & Config

Define middleware in your module.json:

Access config case-insensitively:

Module Manifest

Every module is described by module.json. In v1.2.0, manifests are validated by modular:doctor and exposed through JSON diagnostics.

Use requires for dependency ordering, conflicts for modules that cannot be enabled together, and provides for capabilities a module exposes to the application.

Lifecycle Events

Laravel Modular dispatches lifecycle events for integrations, dashboards, logs, and automation:

• ModuleEnabling
• ModuleEnabled
• ModuleDisabling
• ModuleDisabled
• ModularCached
• ModularRefreshed

🧠 Laravel Boost Support

Laravel Modular ships first-class Laravel Boost resources:

• resources/boost/guidelines/core.blade.php
• resources/boost/skills/laravel-modular-development/SKILL.md

After installing Laravel Boost in an application, run:

If Laravel Modular was installed after Boost, rediscover package resources:

Boost-aware agents will learn to use native make:* --module commands, respect module boundaries, validate module.json, and run the right diagnostics.

🛠️ Helpers & Assets

Global Helpers

Access module information globally with strictly typed helpers:

Asset Management

Link your module assets to public/modules for easy serving:

Use the helper to generate asset URLs in your Blade views:

⚙️ Configuration

Publish the configuration file for advanced customization:

You can customize:

• Paths: Move modules to packages/ or any custom directory.
• Composer: Set default fields (vendor, author, license) for generated composer.json files.
• Activator: Swap the default module activator for your own implementation.

🧪 Testing

We strictly enforce testing. Use the provided test suite to verify your modules:

For module-level testing:

🌍 Ecosystem

Extend your modular architecture with our official ecosystem packages:

⚡ JavaScript & Vite Integration

We provide first-class support for modern frontend tooling:

• NPM Workspaces: Run php artisan modular:npm to configure workspaces, allowing each module to manage its own package.json dependencies efficiently.
• Vite Integration: Use the modular_vite('ModuleName') helper to load module-specific assets with full Hot Module Replacement (HMR) support.
• Asset Publishing: Easily publish public assets to the main application with php artisan modular:link.

🔄 Migrating From nwidart/laravel-modules

Laravel Modular v1.2.0 includes a dry-run importer for teams evaluating a move from nwidart/laravel-modules:

The importer is intentionally safe: preview first, import deliberately, then run:

Read the full guide: Migration From nwidart.

📚 Documentation

• Installation
• Commands
• Architecture
• Deployment
• Performance
• CI
• Laravel Boost
• Command Parity
• Comparison
• Roadmap
• v1.2.0 Release Notes

For a copy-ready release note, see RELEASE_NOTES_1.2.0.md.

💖 Sponsors

We would like to extend our thanks to the following sponsors for funding Laravel Modular development. If you are interested in becoming a sponsor, please visit the Laravel Modular GitHub Sponsors page.

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING for details.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

🌟 Acknowledgments

• Laravel: For creating the most elegant PHP framework.
• Spatie: For setting the standard on Laravel package development.

🔒 Security

If you discover any security-related issues, please email Ali Harb at [email protected].

Please see SECURITY for the full security policy.

📄 License

The MIT License (MIT). Please see License File for more information.

Made with ❤️ by Ali Harb