sezer / monolith-modular

v1.0.2 2026-10-12 18:14 UTC

Requires

• php: ^8.3
• illuminate/console: ^13.0
• illuminate/filesystem: ^13.0
• illuminate/support: ^13.0

Requires (Dev)

• orchestra/testbench: ^11.0
• phpunit/phpunit: ^12.0

MIT

• Hussien Attia

Published on Packagist.org on 2026-10-12 18:15 UTC

README

Modular monolith scaffolding and Artisan generators for Laravel.

Author: Hussien Sezer ([e-mail])

Installation

# Path repository (this monorepo)
composer require sezer/monolith-modular

php artisan vendor:publish --tag=modular-config
php artisan vendor:publish --tag=modular-stubs   # optional overrides

Ensure your host composer.json autoloads modules:

"autoload": {
  "psr-4": {
    "Modules\\": "Modules/"
  }
}

Configuration

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

Published as config/modular.php:

Key	Purpose
path	Modules root (base_path('Modules'))
namespace	Root namespace (Modules)
api.version	Active API version for folders + route prefix (v1)
api.prefix / api.middleware	Route group settings
types.api|web|full.directories	Folder trees for make:module (optional dirs are commented out by default)
namespaces.*	Generator relative namespaces

Override version via env: MODULAR_API_VERSION=v1.

Missing folders on generate

make:module only scaffolds directories listed (uncommented) in config.

Any make:module-* generator auto-creates its folder when missing:

php artisan make:module-event Users FireEvent
# → creates Modules/Users/Events/ + FireEvent.php

php artisan make:module-job Users ProcessJob
# → creates Modules/Users/Jobs/ + ProcessJob.php

Uncommenting a directory in config only affects future make:module scaffolds.

Create a module

php artisan make:module {name} {type=api} [--api-version=] [--force]

Arguments

Argument	Required	Description
name	yes	Module name (Orders, blog, order-items → StudlyCase OrderItems)
type	no	Scaffold shape. Default: api

Types

Type	What you get
api	API folders only: Http/Controllers/Api/{Version}, requests/resources under Api version, Routes/api.php. No web views/controllers.
web	Web folders: Http/Controllers/Web, Resources/views, Routes/web.php. No Api/{Version} tree.
full	Both API and web trees + both route files.

Options

Option	Description
--api-version=v2	Override config('modular.api.version') for folder names only (e.g. creates Http/Controllers/Api/V2). Does not change global config. Use --api-version (not --version) because Artisan already owns --version.
--force	Delete and recreate the module if it already exists.

Examples

php artisan make:module Orders api
php artisan make:module Blog web
php artisan make:module Catalog full
php artisan make:module Orders api --api-version=v2
php artisan make:module Orders api --force

Module providers are auto-discovered — no edits to bootstrap/providers.php.

API routes load as {api.prefix}/{api.version}/... (e.g. /api/v1/...).

Creating a module also remembers it (see below).

Remember / use / forget module

So you do not pass the module name on every generator:

php artisan module:remember Orders   # or: module:use Orders
php artisan make:module-model Order
php artisan make:module-controller Order --api --resource
php artisan module:current
php artisan module:forget

Command	Alias	Description
module:remember {module}	module:use	Store the active module in storage/modular/current-module
module:current		Show the remembered module
module:forget		Clear the remembered module

make:module remembers the new module automatically.

How generators resolve {module}

You run	Meaning
make:module-model Orders Order	Explicit module + class (always works)
make:module-model Order	Class only → uses remembered module
make:module-model Order with nothing remembered	Error — remember a module or pass both args

Generators overview

Every generator is:

php artisan make:module-{artifact} {module?} {name?} [options]

Argument	Description
module	Existing module name (Orders). Optional if you ran module:remember.
name	Class / artifact name (Order, StoreOrderRequest). With one argument only, that value is treated as name.

Shared option on most class generators:

Option	Description
--force	Overwrite the file if it already exists.

make:module-model options (-mfs, -a, --api, …)

php artisan make:module-model {module} {name} [-m] [-f] [-s] [-c] [-a] [--api] [--force]

Creates Modules/{Module}/Models/{Name}.php. Shortcuts stack like Laravel’s make:model.

Flag	Long form	What it creates (inside the same module)
-m	--migration	Migration: Database/Migrations/xxxx_create_{table}_table.php
-f	--factory	Factory: Database/Factories/{Name}Factory.php
-s	--seed	Seeder: Database/Seeders/{Name}Seeder.php
-c	--controller	Resource controller via make:module-controller
-a	--all	Same as -m -f -s -c together
	--api	Only with -c / -a: controller goes under Http/Controllers/Api/{Version} (API resource stub)
	--force	Overwrite model if it exists

What -mfs means

php artisan make:module-model Orders Order -mfs

Is shorthand for migration + factory + seeder:

Letter	Creates
m	Modules/Orders/Database/Migrations/..._create_orders_table.php
f	Modules/Orders/Database/Factories/OrderFactory.php
s	Modules/Orders/Database/Seeders/OrderSeeder.php

Plus the model: Modules/Orders/Models/Order.php.

Other model examples

# Model only
php artisan make:module-model Orders Order

# Model + migration
php artisan make:module-model Orders Order -m

# Model + migration + factory + seeder
php artisan make:module-model Orders Order -mfs

# Everything: migration, factory, seeder, resource controller
php artisan make:module-model Orders Order -a

# Same as -a, but controller is API-versioned
php artisan make:module-model Orders Order -a --api
# → Modules/Orders/Http/Controllers/Api/V1/OrderController.php

make:module-controller options (--api, -r, -i, …)

php artisan make:module-controller {module} {name} [--api] [-r|--resource] [-i|--invokable] [--api-version=] [--force]

Flag	Long form	Effect
	--api	Put class under Http/Controllers/Api/{Version}/ (e.g. Api/V1). Without it → Http/Controllers/Web/.
-r	--resource	Generate REST methods. With --api: index/store/show/update/destroy. Without --api: also create + edit.
-i	--invokable	Single __invoke action controller.
	--api-version=v2	Override version folder/namespace for this file only (V2 instead of config default).
	--force	Overwrite if exists.

Order is auto-suffixed to OrderController.

Path / stub matrix

Options	Path	Stub style
(none)	Http/Controllers/Web/OrderController.php	Empty controller
--api	Http/Controllers/Api/V1/OrderController.php	Empty controller
--resource	Http/Controllers/Web/...	Full resource (incl. create/edit)
--api --resource	Http/Controllers/Api/V1/...	API resource (no create/edit)
--invokable	Web or Api (depends on --api)	__invoke only
--api --api-version=v2	Http/Controllers/Api/V2/...	Same stubs, V2 folder

Examples

# Web empty controller
php artisan make:module-controller Orders Order

# API empty controller → Api/V1
php artisan make:module-controller Orders Order --api

# API resource controller (typical JSON API)
php artisan make:module-controller Orders Order --api --resource

# API resource under v2 folders
php artisan make:module-controller Orders Order --api --resource --api-version=v2

# Invokable API action
php artisan make:module-controller Orders PlaceOrder --api --invokable

Other generators with options

make:module-request

php artisan make:module-request Orders StoreOrderRequest [--api] [--api-version=] [--force]

Option	Effect
--api	Http/Requests/Api/{Version}/StoreOrderRequest.php
(none)	Http/Requests/StoreOrderRequest.php
--api-version=v2	Use V2 instead of config version

make:module-resource

php artisan make:module-resource Orders OrderResource [-c|--collection] [--api-version=] [--force]

Option	Effect
(default)	JSON resource under Http/Resources/Api/{Version}/
-c / --collection	Resource collection class
--api-version=v2	Version folder override

make:module-listener

php artisan make:module-listener Orders SendOrderConfirmation [--event=OrderPlaced] [--queued] [--force]

Option	Effect
--event=OrderPlaced	Type-hint / import that event (Modules\{Module}\Events\OrderPlaced if short name)
--queued	Implements ShouldQueue

make:module-test

php artisan make:module-test Orders OrderTest          # Feature → Tests/Feature
php artisan make:module-test Orders OrderServiceTest --unit   # Unit → Tests/Unit

Option	Effect
--unit / -u	Unit test under Tests/Unit (PHPUnit TestCase)
(default)	Feature test under Tests/Feature (Laravel Tests\TestCase)

make:module-migration

php artisan make:module-migration Orders create_orders_table [--create=orders] [--table=orders] [--force]

Option	Effect
--create=orders	Create-table migration stub for that table
--table=orders	Alter-table migration stub
(name create_*_table)	Auto-detects create stub + table name

Full command list

php artisan make:module-model Orders Order -mfs
php artisan make:module-controller Orders Order --api --resource
php artisan make:module-controller Orders OrderController --model=Order --api
php artisan make:module-controller Orders Order --api --api-version=v2
php artisan make:module-request Orders StoreOrderRequest --api
php artisan make:module-resource Orders OrderResource
php artisan make:module-migration Orders create_orders_table
php artisan make:module-factory Orders OrderFactory --model=Order
php artisan make:module-seeder Orders OrderSeeder
php artisan make:module-event Orders OrderPlaced
php artisan make:module-listener Orders SendOrderConfirmation --event=OrderPlaced
php artisan make:module-observer Orders OrderObserver --model=Order
php artisan make:module-job Orders ProcessOrder
php artisan make:module-policy Orders OrderPolicy --model=Order
php artisan make:module-rule Orders ValidOrderStatus
php artisan make:module-middleware Orders EnsureOrderOwner
php artisan make:module-enum Orders OrderStatus
php artisan make:module-action Orders CreateOrderAction
php artisan make:module-provider Orders OrderEventServiceProvider
php artisan make:module-mail Orders OrderShipped
php artisan make:module-notification Orders OrderPaid
php artisan make:module-command Orders SyncOrders
php artisan make:module-exception Orders OrderNotFoundException
php artisan make:module-cast Orders MoneyCast
php artisan make:module-channel Orders OrderChannel
php artisan make:module-trait Orders HasOrders
php artisan make:module-interface Orders OrderRepositoryInterface
php artisan make:module-class Orders Support/OrderCalculator
php artisan make:module-test Orders OrderTest
php artisan make:module-test Orders OrderServiceTest --unit
php artisan make:module-scope Orders ActiveOrderScope

License

MIT