libinkk / modular
Enterprise-grade Laravel modular architecture package with automatic module discovery, code generators, CRUD scaffolding, repository pattern, service layer, DTO/action workflow, and zero-configuration project scaling.
Package info
pkg:composer/libinkk/modular
Requires
- php: ^8.1
- illuminate/support: ^10.0|^11.0|^12.0|^13.0
Requires (Dev)
- orchestra/testbench: ^8.0|^9.0|^10.0|^11.0
- phpunit/phpunit: ^10.0|^11.0|^12.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
libinkk/modular
Enterprise-grade Laravel modular architecture. Zero manual registration.
Build large Laravel apps as business modules under Modules/. The package discovers modules, registers providers, loads routes, migrations, views, lang, and config, scaffolds layered code, and lets you enable, disable, rename, or delete features safely.
composer require libinkk/modular php artisan modular:install php artisan modular:make Catalog php artisan modular:crud Catalog Product --api
| Package | libinkk/modular |
| License | MIT |
| PHP | ^8.1 (tested through 8.6) |
| Laravel | 10 / 11 / 12 / 13 |
| Developer | Libin K K |
| libinkk1999@gmail.com | |
| Website | www.libinkk.in |
| Docs | DOCUMENTATION.md / libinkk.in |
Table of contents
- Why this package?
- Features
- Requirements
- Installation (step by step)
- Full tutorial: Blog Post API
- Full tutorial: Catalog Product feature
- Feature walkthroughs
- Module structure
- Architecture
- Artisan commands
- Configuration
- Benchmarks
- Testing
- CI
- Best practices
- Troubleshooting
- FAQ
- Roadmap
- License
Why this package?
Growing Laravel apps often end up with:
- Flat, mixed folders under
app/ - Manual provider / route / migration registration
- Fat controllers with business logic
- No clean way to turn a feature off
- Slow onboarding because every project invents its own structure
libinkk/modular enforces one opinionated module layout and automates discovery so you spend time on business rules, not boilerplate.
| Pain | Solution |
|---|---|
Messy app/ |
One folder per business domain under Modules/ |
| Manual providers | Auto-discovered and registered |
| Manual routes / migrations / views | Loaded from each module automatically |
| Fat controllers | Generators push Request → DTO → Action → Service → Repository |
| No feature switch | modular:enable / modular:disable |
| Unclear deps | module.json dependencies + modular:doctor |
| Slow scaffolding | modular:make + modular:crud |
| Boot scan cost | Module cache (prefer_cache) |
Features
- Modular architecture under
Modules/ - Automatic discovery of enabled modules
- Automatic service provider registration
- Auto-load
Routes/web.php+Routes/api.php - Auto-load migrations, views, translations, config
- Repository pattern with interface binding
- Service layer, DTO, Action generators
- Events, listeners, jobs, policies, notifications, middleware
- Full CRUD scaffold (including
--api) - Smart constructor DI wiring (
--inject/--no-inject) - Enable / disable / rename / delete modules
- Module list, info, status, doctor
- Module dependency checks
- Production module cache + auto-refresh
- PHPUnit suite + GitHub Actions matrix (PHP 8.1 to 8.6)
Requirements
| Requirement | Version |
|---|---|
| PHP | ^8.1 (CI covers 8.1 to 8.6) |
| Laravel / Illuminate | ^10 / ^11 / ^12 / ^13 |
| Composer | 2.x |
Laravel 13 typically needs PHP
^8.3. Match your app PHP version accordingly. PHP 8.6.0 is the current latest stable (php.net release notes).
Installation (step by step)
Step 1: Require the package
composer require libinkk/modular
Step 2: Run install
php artisan modular:install
What this does:
- Creates the
Modules/directory - Publishes
config/modular.php - Generates the module cache file
- Adds
"Modules\\": "Modules/"to your appcomposer.jsonautomatically - Runs
composer dump-autoload
Optional flags:
php artisan modular:install --no-composer # do not edit composer.json php artisan modular:install --no-dump # edit composer.json, skip dump-autoload php artisan modular:install --force # overwrite published config
Step 3: Create your first module
php artisan modular:make User
Step 4: Verify health
php artisan modular:list php artisan modular:status php artisan modular:doctor
You are ready to generate code inside Modules/User/.
Full tutorial: Blog Post API
This tutorial builds a complete Blog module with Post CRUD API.
Goal
- Create
Modules/Blog - Scaffold Post API CRUD
- Migrate and verify module health
- Know where to put business logic
Step 1: Install (if not done)
composer require libinkk/modular php artisan modular:install
Step 2: Create the Blog module
php artisan modular:make Blog
You now have:
Modules/Blog/
├── Providers/BlogServiceProvider.php
├── Routes/web.php
├── Routes/api.php
├── Config/
├── Database/
├── Views/
├── Lang/
├── Tests/
└── module.json
Step 3: Generate Post CRUD (API mode)
php artisan modular:crud Blog Post --api
Equivalent styles:
php artisan modular:crud Post --module=Blog --api php artisan modular:crud Post -m=Blog --api
Step 4: What was created
Inside Modules/Blog/ you get:
| Artifact | Path example |
|---|---|
| Model | Models/Post.php |
| Migration | Database/Migrations/*_create_posts_table.php |
| Factory / Seeder | Database/Factories, Database/Seeders |
| Repository + interface | Repositories/, Interfaces/ |
| Service | Services/PostService.php |
| Controller | Controllers/PostController.php |
| Form requests | Requests/StorePostRequest.php, UpdatePostRequest.php |
| DTO | DTO/PostData.php |
| Actions | Actions/CreatePost.php, UpdatePost.php, DeletePost.php |
| API resource | Resources/PostResource.php |
| Policy | Policies/PostPolicy.php |
| Routes | Routes/api.php (api resource registered) |
| Tests | Tests/PostCrudTest.php |
Step 5: Run migrations
php artisan migrate
Module migrations are discovered automatically. No manual path registration.
Step 6: Check module status
php artisan modular:list php artisan modular:info Blog php artisan modular:doctor
Step 7: Write business rules
Open:
Modules/Blog/Services/PostService.phpModules/Blog/Actions/CreatePost.php
Keep the controller thin. Put rules in Service / Action layers.
Step 8: Hit the API
After your app is running, Post routes from Modules/Blog/Routes/api.php are available (prefix depends on the generated route file). Customize validation in Form Requests, then ship.
Full tutorial: Catalog Product feature
Realistic walkthrough for a Catalog module.
Step A: Create Catalog
php artisan modular:make Catalog
Step B: Scaffold Product CRUD for API
php artisan modular:crud Catalog Product --api
Step C: Understand the generated request flow
- HTTP request hits
ProductController@store StoreProductRequestvalidates input- Data becomes a DTO (
ProductData) - An Action (
CreateProduct) runs the use case ProductServiceapplies business rulesProductRepositorysaves via Eloquent- API Resource formats the JSON response
You can change any layer without rewriting the whole feature.
Step D: Add a nested admin controller
php artisan modular:controller Catalog API/Admin/ProductController
Result:
Modules/Catalog/Controllers/API/Admin/ProductController.php
Namespaces are generated for you.
Step E: Add only what you need next
php artisan modular:service Catalog PricingService php artisan modular:action Catalog ApplyDiscount php artisan modular:dto Catalog DiscountData php artisan modular:job Catalog SyncProductStockJob php artisan modular:test Catalog ProductPricingTest
Step F: Emergency disable / re-enable
php artisan modular:disable Catalog
# fix code, deploy, then:
php artisan modular:enable Catalog
php artisan modular:list
When disabled, Catalog providers, routes, and related discovery are skipped. Files stay on disk.
Feature walkthroughs
Each feature below is explained step by step.
1. Automatic module discovery
What it does: On boot, the package scans Modules/, reads each module.json, skips disabled modules, and registers the rest.
Steps to see it:
- Create two modules:
php artisan modular:make Orders php artisan modular:make Payments
- List them:
php artisan modular:list
- Disable one and list again:
php artisan modular:disable Payments php artisan modular:list
- Confirm with doctor:
php artisan modular:doctor
No edits to bootstrap/providers.php or config/app.php are required for module providers.
2. Automatic routes, migrations, views, lang, config
Steps:
- Create a module:
php artisan modular:make Store
- Add or use generated routes in:
Modules/Store/Routes/web.phpModules/Store/Routes/api.php
- Add a migration:
php artisan modular:migration Store create_items_table php artisan migrate
- Use views and translations:
return view('store::index'); __('store::messages.module');
- Module config lives under
Modules/Store/Config/and loads with the module.
3. Create a module with options
php artisan modular:make ApiOnly --api # api routes only php artisan modular:make WebOnly --web # web routes only php artisan modular:make Bare --empty # folders + module.json only php artisan modular:make Mini --minimal # Controllers, Routes, Provider
Steps:
- Pick the option that matches your feature shape.
- Run
modular:make. - Inspect
Modules/{Name}/andmodule.json. - Generate only the classes you need next.
4. Single generators (controller, model, service, ...)
Example: add a controller + model + request
php artisan modular:controller User ProfileController php artisan modular:model User Profile --migration php artisan modular:request User UpdateProfileRequest
Command styles (same result):
# Style 1: module first php artisan modular:controller User UserController # Style 2: --module flag php artisan modular:controller API/UserController --module=User # Style 3: short -m flag php artisan modular:controller API/UserController -m=User
Nested folders:
php artisan modular:controller User API/Admin/UserController
# → Modules/User/Controllers/API/Admin/UserController.php
5. Repository pattern (auto-bound)
Steps:
- Ensure the module exists:
php artisan modular:make Shop
- Generate a repository:
php artisan modular:repository Shop ItemRepository
- What you get:
Repositories/ItemRepository.phpInterfaces/ItemRepositoryInterface.php- Provider binding in
ShopServiceProvider - Matching
ItemServicecreated or smart-merged with DI - Matching controller wiring when
ItemControlleralready exists
- Type-hint the interface in your code:
public function __construct( private ItemRepositoryInterface $items ) {}
6. Auto dependency injection
Naming convention:
ProductService↔ProductControllerProductRepository↔ProductService
Steps:
- Create a controller without wiring:
php artisan modular:controller Shop ProductController --no-inject
- Create a service and wire it:
php artisan modular:service Shop ProductService --inject
-
Open
ProductControllerand confirm constructor injection was added. -
Prompt mode (asks yes/no):
php artisan modular:service Shop OrderService
- Skip wiring entirely:
php artisan modular:service Shop QuoteService --no-inject
Smart merge adds a use import and a promoted constructor property when missing. It does not wipe custom methods.
7. Full CRUD generator
Steps:
- Create module:
php artisan modular:make Inventory
- Generate CRUD:
php artisan modular:crud Inventory Item --api
- Migrate:
php artisan migrate
- Customize:
- Validation → Form Requests
- Business rules → Service / Actions
- Persistence → Repository
- Response shape → API Resource
8. Enable and disable modules
Steps:
- Disable a feature without deleting code:
php artisan modular:disable Payment
-
Confirm
module.jsonhas"enabled": false. -
Confirm routes/providers from that module no longer load.
-
Re-enable when ready:
php artisan modular:enable Payment
When to use:
- Emergency stop in production
- WIP features kept in repo but off
- Staging-only experimental modules
- Safer maintenance windows
9. Rename a module
Steps:
- Rename and update references:
php artisan modular:rename User Customer
- If the target name already exists:
php artisan modular:rename User Customer --force
- Verify:
php artisan modular:list php artisan modular:info Customer
Folder names, class names, namespaces, view namespaces, and related references are updated. Stats are logged in module.json.
10. Delete a module
php artisan modular:delete User php artisan modular:delete User --force
Prefer disable when you might need the code again.
11. Module dependencies
Steps:
- Edit
Modules/Orders/module.json:
{
"name": "Orders",
"description": "Order management",
"version": "1.0.0",
"enabled": true,
"dependencies": ["Users", "Products"]
}
-
Ensure dependency modules exist and are available.
-
Run:
php artisan modular:doctor
Missing dependencies are reported so features do not fail silently.
12. Module cache (production)
Steps:
- Build cache:
php artisan modular:cache
- List from cache:
php artisan modular:list --cached
- Clear when needed:
php artisan modular:clear
- Keep config tuned for production:
'prefer_cache' => true, 'auto_refresh_cache' => true,
auto_refresh_cache refreshes after make / enable / disable / rename / delete.
13. Info, status, doctor
php artisan modular:info Blog php artisan modular:status php artisan modular:doctor
Use these in local setup and CI smoke checks.
14. Database helpers (migration, factory, seeder)
php artisan modular:migration Shop create_coupons_table php artisan modular:factory Shop CouponFactory php artisan modular:seeder Shop CouponSeeder php artisan migrate
15. Supporting generators
php artisan modular:event Shop OrderPlaced php artisan modular:listener Shop SendOrderMail php artisan modular:job Shop SyncOrderJob php artisan modular:notification Shop OrderReady php artisan modular:policy Shop OrderPolicy php artisan modular:middleware Shop EnsureShopAdmin php artisan modular:dto Shop OrderData php artisan modular:action Shop PlaceOrder php artisan modular:enum Shop OrderStatus php artisan modular:rule Shop ValidSku php artisan modular:trait Shop HasSku php artisan modular:helper Shop OrderHelper php artisan modular:command Shop SyncOrdersCommand php artisan modular:resource Shop OrderResource php artisan modular:test Shop OrderFlowTest php artisan modular:view Shop admin/dashboard php artisan modular:lang Shop validation php artisan modular:config Shop settings php artisan modular:route Shop
Generate only what your feature needs. Stay consistent with the layered flow.
Module structure
Modules/
└── User/
├── Controllers/
├── Requests/
├── Models/
├── Services/
├── Repositories/
├── Interfaces/
├── Actions/
├── DTO/
├── Traits/
├── Enums/
├── Policies/
├── Rules/
├── Events/
├── Listeners/
├── Jobs/
├── Notifications/
├── Resources/
├── Helpers/
├── Console/
├── Database/
│ ├── Migrations/
│ ├── Seeders/
│ └── Factories/
├── Config/
├── Routes/
│ ├── api.php
│ └── web.php
├── Views/
├── Lang/
├── Tests/
├── Providers/
│ └── UserServiceProvider.php
└── module.json
module.json
{
"name": "User",
"description": "User Management Module",
"version": "1.0.0",
"enabled": true,
"dependencies": []
}
How assets are used
| Asset | Location | Usage |
|---|---|---|
| Routes | Modules/*/Routes/{web,api}.php |
Auto-loaded |
| Migrations | Modules/*/Database/Migrations |
php artisan migrate |
| Views | Modules/User/Views |
view('user::dashboard') |
| Lang | Modules/User/Lang |
__('user::messages.success') |
| Provider | Modules/User/Providers/... |
Auto-registered |
| Config | Modules/User/Config |
Loaded with the module |
Architecture
Recommended request flow:
Controller → Request → DTO → Action → Service → Repository → Model → Database
| Layer | Responsibility |
|---|---|
| Controller | HTTP only: accept input, call next layer, return response |
| Request | Validation / authorization input |
| DTO | Typed data between layers |
| Action | One use case (CreateUser, UpdateProduct) |
| Service | Business rules and orchestration |
| Repository | Persistence behind an interface |
| Model | Eloquent entity |
Thin controller example:
public function store(StoreUserRequest $request, CreateUser $action) { $user = $action->handle(UserData::fromRequest($request)); return new UserResource($user); }
Name modules after business domains (Orders, Billing), not framework layers (Controllers).
Artisan commands
Setup and health
| Command | Purpose |
|---|---|
modular:install |
Create Modules/, publish config, cache |
modular:list |
List modules |
modular:info {name} |
Module details |
modular:status |
Package / modules status overview |
modular:doctor |
Check PSR-4, providers, routes, cache, dependencies |
Lifecycle
| Command | Purpose |
|---|---|
modular:make {name} |
Create module |
modular:enable {name} |
Enable module |
modular:disable {name} |
Disable module (files kept) |
modular:rename {from} {to} |
Rename + rewrite namespaces/refs |
modular:delete {name} |
Delete module (confirm / --force) |
modular:cache |
Build module cache |
modular:clear |
Clear module cache |
Generators
| Command | Example |
|---|---|
| CRUD | php artisan modular:crud User Product |
| CRUD API | php artisan modular:crud User Product --api |
| Controller | php artisan modular:controller User UserController |
| Model | php artisan modular:model User User |
| Model + migration | php artisan modular:model User User --migration |
| Request | php artisan modular:request User StoreUserRequest |
| Service | php artisan modular:service User UserService |
| Repository | php artisan modular:repository User UserRepository |
| Resource | php artisan modular:resource User UserResource |
| Event | php artisan modular:event User UserCreated |
| Listener | php artisan modular:listener User SendWelcomeEmail |
| Job | php artisan modular:job User SyncUserJob |
| Notification | php artisan modular:notification User WelcomeNotification |
| Policy | php artisan modular:policy User UserPolicy |
| Middleware | php artisan modular:middleware User AdminMiddleware |
| DTO | php artisan modular:dto User UserData |
| Action | php artisan modular:action User CreateUser |
| Enum | php artisan modular:enum User UserStatus |
| Rule | php artisan modular:rule User PhoneNumberRule |
| Test | php artisan modular:test User UserTest |
| Migration | php artisan modular:migration User create_users_table |
| Factory | php artisan modular:factory User UserFactory |
| Seeder | php artisan modular:seeder User UserSeeder |
| Route | php artisan modular:route User |
| Config | php artisan modular:config User |
| Lang | php artisan modular:lang User |
| View | php artisan modular:view User dashboard |
| Trait | php artisan modular:trait User HasProfile |
| Helper | php artisan modular:helper User |
| Console | php artisan modular:console User SyncUsersCommand |
Configuration
Publish (also done by modular:install):
php artisan vendor:publish --tag=modular-config
config/modular.php:
return [ 'modules_path' => base_path('Modules'), 'cache_file' => base_path('bootstrap/cache/modular_modules.php'), // Use cache on boot when the file exists 'prefer_cache' => true, // Refresh cache after make / enable / disable / rename / delete 'auto_refresh_cache' => true, ];
Production tip: keep prefer_cache on and run php artisan modular:cache in deploy scripts (or rely on auto_refresh_cache after lifecycle commands).
Benchmarks
Local micro-benchmarks on PHP 8.5.4 (Linux), measuring ModuleRepository::all() discovery for scaffolded modules (average of many iterations). Numbers are indicative. Your disk / OS will vary.
Module discovery: scan vs cache
| Modules | Scan (avg) | Cache (avg) | Speedup |
|---|---|---|---|
| 10 | ~0.41 ms | ~0.06 ms | ~6.4× |
| 25 | ~0.87 ms | ~0.14 ms | ~6.1× |
| 50 | ~1.71 ms | ~0.25 ms | ~6.7× |
| 100 | ~3.63 ms | ~0.53 ms | ~6.9× |
Takeaway: With many modules, enabling cache (modular:cache + prefer_cache) keeps boot discovery roughly 6 to 7× faster than scanning every module.json.
Scaffolding throughput
| Operation | Result |
|---|---|
| Scaffold 1 module (full template) | ~0.6 ms |
| Scaffold 50 modules | ~25 ms total |
Test suite
| Metric | Result |
|---|---|
| PHPUnit | 43 tests / 425 assertions |
| Runtime (local) | ~1.1 s |
composer install vendor/bin/phpunit
Testing
composer install vendor/bin/phpunit # or composer test
Coverage areas:
- Module create / CRUD / generators
- Enable / disable / rename / delete / cache / doctor
- Auto-registration of enabled vs disabled modules
- Constructor DI wiring / smart merge
- High-level end-to-end workflows +
ModuleRepositoryunit tests
CI
GitHub Actions workflow: .github/workflows/tests.yml
- Triggers: push, pull request, manual dispatch
- Matrix: PHP 8.1 / 8.2 / 8.3 / 8.4 / 8.5 / 8.6
- Uses
shivammathur/setup-php - Runs
composer update+vendor/bin/phpunit
Best practices
- One business domain per module (
Orders, notHttpStuff). - Keep controllers thin. Push rules into Actions / Services.
- Type-hint repository interfaces, not concrete classes.
- Declare dependencies in
module.jsonfor cross-module needs. - Disable instead of deleting when a feature is temporarily unsafe.
- Cache modules in production. Refresh after deploy / lifecycle changes.
- Run
modular:doctorin CI or before release. - Pick one command syntax style and stick to it in the team.
- Migrate domains gradually from a legacy
app/intoModules/. - Commit generated structure. Customize business logic in Services/Actions.
- Use valid PHP identifiers for module and class names. Path traversal / absolute paths are rejected.
Troubleshooting
| Problem | Fix |
|---|---|
Class not found under Modules\ |
Run php artisan modular:install (or add PSR-4 "Modules\\": "Modules/" and composer dump-autoload) |
| Module routes / provider missing | Check module.json → "enabled": true, then modular:list / modular:doctor |
| Disabled module still loads | Clear opcache / restart workers; rebuild cache: modular:clear && modular:cache |
| Doctor fails on dependencies | Create or enable listed dependency modules |
| Rename conflict | Use --force only if overwriting the target is intentional |
| Cache stale after manual file edits | php artisan modular:clear then modular:cache |
| Generators fail "module not found" | Create the module first with modular:make |
| Make/rename fails on odd names | Use a PHP identifier like Orders (no ../, spaces, or /) |
FAQ
Does install edit my composer.json?
Yes. By default it adds "Modules\\": "Modules/" under autoload.psr-4 and runs composer dump-autoload. Use --no-composer to skip.
Do I register providers in bootstrap/providers.php?
No for module providers. Discovery handles enabled modules.
Can I use only some layers (no repository)?
Yes. Generators are optional. Use what fits your team.
Is this only for APIs?
No. Web routes, views, and lang are first-class. Use --api when you want API-oriented CRUD stubs.
PHP 8.6 supported?
Yes. Constraint is ^8.1, and CI includes 8.6 (stable as of 19 Nov 2026).
Roadmap
- Deeper architecture analyzer / dependency graph
- OpenAPI generation from module routes
- Multi-tenant module scoping helpers
- AI-assisted scaffold refinements
Ideas welcome via issues / contact on libinkk.in.
License
MIT © Libin K K
Email: libinkk1999@gmail.com
Website: www.libinkk.in
Install once. Generate modules. Focus on business logic.
For extra deep-dive notes, see DOCUMENTATION.md.
