Strategi Multi-Module Laravel: Membangun Aplikasi Besar Tanpa Membuat Kode Berantakan
Admin HijrahKreativa
Penulis
Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk
Admin HijrahKreativa
Penulis
Dari folder app/ yang berisi 200 model menjadi modular monolith dengan batas yang jelas: struktur modul, service provider per modul, komunikasi antar modul, dan penegakan batas dengan test arsitektur.
Struktur bawaan Laravel (app/Models, app/Http/Controllers, app/Services) sangat baik untuk aplikasi kecil sampai menengah. Masalah muncul ketika aplikasi tumbuh menjadi ERP mini, POS dengan gudang, atau SaaS dengan belasan fitur:
app/Models berisi 150 file, dan tidak jelas mana milik fitur apa,Solusinya bukan langsung microservices, tetapi modular monolith: satu aplikasi, satu deploy, tetapi kode dibagi menjadi modul dengan batas yang jelas dan dijaga secara otomatis.
Hasil akhir artikel ini:
nwidart/laravel-modules,| Komponen | Versi |
|---|---|
| PHP | 8.3+ (disarankan 8.4) |
| Laravel | 13.x |
| Composer | 2.x |
| Testing | Pest 4 (dengan plugin arsitektur bawaan) |
| Opsional | nwidart/laravel-modules ^13.0, deptrac/deptrac |
Studi kasus: aplikasi toko dengan empat modul: Catalog (produk, kategori), Inventory (stok, gudang), Sales (pesanan, pembayaran), dan Customer.
Kesalahan umum adalah membagi berdasarkan lapisan teknis (Controllers, Models, Services). Bagilah berdasarkan kapabilitas bisnis: sekumpulan data dan aturan yang berubah bersama.
Cara cepat menemukannya:
| Modul | Memiliki tabel | Tanggung jawab |
|---|---|---|
| Catalog | products, categories, category_product | Informasi produk dan harga jual |
| Inventory | stocks, stock_movements, warehouses | Jumlah stok per gudang, mutasi |
| Sales | orders, order_items, payments | Proses pesanan dan pembayaran |
| Customer | customers, addresses | Data pelanggan |
| Shared | — | Kode teknis umum: helper uang, base class, trait |
Aturan kepemilikan: setiap tabel dimiliki tepat satu modul. Modul lain tidak boleh menulis langsung ke tabel tersebut.
| Strategi | Cara | Kelebihan | Kekurangan |
|---|---|---|---|
A. Folder modul di app/ atau modules/ |
Namespace per modul + service provider sendiri | Tanpa dependensi, kontrol penuh | Perlu menulis sedikit kode bootstrap |
B. nwidart/laravel-modules |
Paket dengan generator Artisan per modul | Cepat, konvensi siap pakai | Terikat pada konvensi dan versi paket |
| C. Paket Composer lokal | Setiap modul paket di packages/ dengan composer.json |
Batas paling tegas, bisa dipakai ulang | Overhead tertinggi |
Untuk sebagian besar tim, Strategi A adalah titik awal terbaik. Langkah 3–8 membahasnya, lalu Langkah 9 menunjukkan Strategi B.
modules/
├── Catalog/
│ ├── Contracts/
│ │ └── CatalogApi.php ← satu-satunya pintu yang boleh dipakai modul lain
│ ├── Data/
│ │ └── ProductSummary.php ← DTO publik
│ ├── Database/
│ │ ├── Factories/
│ │ └── Migrations/
│ ├── Events/
│ │ └── ProductPriceChanged.php ← event publik
│ ├── Http/
│ │ ├── Controllers/
│ │ ├── Requests/
│ │ └── Resources/
│ ├── Models/ ← internal
│ ├── Services/ ← internal
│ ├── routes/api.php
│ ├── CatalogServiceProvider.php
│ └── Tests/
├── Inventory/
├── Sales/
├── Customer/
└── Shared/
Bagian publik setiap modul hanya: Contracts, Data, dan Events. Sisanya internal.
Daftarkan autoload di composer.json:
{
"autoload": {
"psr-4": {
"App\\": "app/",
"Modules\\": "modules/",
"Database\\Factories\\": "database/factories/",
"Database\\Seeders\\": "database/seeders/"
}
}
}
composer dump-autoload
Setiap modul mendaftarkan sendiri route, migration, view, binding, dan listener-nya.
// modules/Catalog/CatalogServiceProvider.php
namespace Modules\Catalog;
use Illuminate\Support\Facades\Route;
use Illuminate\Support\ServiceProvider;
use Modules\Catalog\Contracts\CatalogApi;
use Modules\Catalog\Services\CatalogApiService;
class CatalogServiceProvider extends ServiceProvider
{
public function register(): void
{
$this->app->bind(CatalogApi::class, CatalogApiService::class);
$this->mergeConfigFrom(__DIR__.'/config.php', 'catalog');
}
public function boot(): void
{
$this->loadMigrationsFrom(__DIR__.'/Database/Migrations');
$this->loadViewsFrom(__DIR__.'/resources/views', 'catalog');
$this->loadTranslationsFrom(__DIR__.'/lang', 'catalog');
Route::middleware('api')
->prefix('api/v1/catalog')
->name('catalog.')
->group(__DIR__.'/routes/api.php');
}
}
Daftarkan provider di bootstrap/providers.php:
return [
App\Providers\AppServiceProvider::class,
Modules\Shared\SharedServiceProvider::class,
Modules\Catalog\CatalogServiceProvider::class,
Modules\Inventory\InventoryServiceProvider::class,
Modules\Customer\CustomerServiceProvider::class,
Modules\Sales\SalesServiceProvider::class,
];
Migration modul ikut dijalankan oleh php artisan migrate biasa. Untuk membuat migration langsung di folder modul:
php artisan make:migration create_products_table --path=modules/Catalog/Database/Migrations
Factory di dalam modul perlu memberi tahu Laravel lokasinya:
// modules/Catalog/Models/Product.php
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Modules\Catalog\Database\Factories\ProductFactory;
class Product extends Model
{
use HasFactory;
protected static function newFactory(): ProductFactory
{
return ProductFactory::new();
}
}
Modul Sales perlu harga dan nama produk saat membuat pesanan. Jangan mengimpor Modules\Catalog\Models\Product dari Sales. Sediakan kontrak:
// modules/Catalog/Data/ProductSummary.php
namespace Modules\Catalog\Data;
final readonly class ProductSummary
{
public function __construct(
public int $id,
public string $sku,
public string $name,
public int $price,
public bool $isActive,
) {}
}
// modules/Catalog/Contracts/CatalogApi.php
namespace Modules\Catalog\Contracts;
use Modules\Catalog\Data\ProductSummary;
interface CatalogApi
{
public function find(int $productId): ?ProductSummary;
/** @param list<int> $ids @return array<int, ProductSummary> keyed by id */
public function findMany(array $ids): array;
}
// modules/Catalog/Services/CatalogApiService.php
namespace Modules\Catalog\Services;
use Modules\Catalog\Contracts\CatalogApi;
use Modules\Catalog\Data\ProductSummary;
use Modules\Catalog\Models\Product;
final class CatalogApiService implements CatalogApi
{
public function find(int $productId): ?ProductSummary
{
return $this->findMany([$productId])[$productId] ?? null;
}
public function findMany(array $ids): array
{
return Product::query()
->whereKey($ids)
->get(['id', 'sku', 'name', 'price', 'is_active'])
->mapWithKeys(fn (Product $p) => [$p->id => new ProductSummary(
$p->id, $p->sku, $p->name, $p->price, $p->is_active,
)])
->all();
}
}
Karena kontrak ini adalah API publik modul, ia mendapat perlakuan yang sama seperti API HTTP: perubahan yang tidak kompatibel harus dibicarakan dengan pemilik modul lain.
// modules/Sales/Services/PlaceOrder.php
namespace Modules\Sales\Services;
use Illuminate\Support\Facades\DB;
use Modules\Catalog\Contracts\CatalogApi;
use Modules\Inventory\Contracts\InventoryApi;
use Modules\Sales\Events\OrderPlaced;
use Modules\Sales\Models\Order;
final class PlaceOrder
{
public function __construct(
private readonly CatalogApi $catalog,
private readonly InventoryApi $inventory,
) {}
/** @param list<array{product_id:int, quantity:int}> $lines */
public function handle(int $customerId, array $lines): Order
{
$products = $this->catalog->findMany(array_column($lines, 'product_id'));
return DB::transaction(function () use ($customerId, $lines, $products) {
$order = Order::create(['customer_id' => $customerId, 'status' => 'pending', 'total' => 0]);
$total = 0;
foreach ($lines as $line) {
$product = $products[$line['product_id']]
?? throw new \DomainException('Produk tidak ditemukan.');
if (! $product->isActive) {
throw new \DomainException("Produk {$product->name} tidak aktif.");
}
$this->inventory->reserve($product->id, $line['quantity'], reference: "order:{$order->id}");
$order->items()->create([
'product_id' => $product->id, // hanya ID, tanpa relasi Eloquent lintas modul
'product_name' => $product->name,
'unit_price' => $product->price,
'quantity' => $line['quantity'],
'line_total' => $product->price * $line['quantity'],
]);
$total += $product->price * $line['quantity'];
}
$order->update(['total' => $total]);
OrderPlaced::dispatch($order->id, $customerId, $total);
return $order;
});
}
}
Perhatikan:
product_id sebagai referensi ID, bukan relasi belongsTo(Product::class) lintas modul. Snapshot nama dan harga disimpan di item pesanan.Foreign key di database antar tabel milik modul berbeda masih boleh dipertahankan untuk integritas data. Yang dihindari adalah ketergantungan kode (model Eloquent) lintas modul.
Untuk efek samping yang tidak harus terjadi dalam transaksi yang sama (kirim email, tambah poin loyalitas, perbarui statistik), gunakan event. Pengirim tidak perlu tahu siapa yang mendengarkan.
// modules/Sales/Events/OrderPlaced.php
namespace Modules\Sales\Events;
use Illuminate\Foundation\Events\Dispatchable;
final class OrderPlaced
{
use Dispatchable;
public function __construct(
public readonly int $orderId,
public readonly int $customerId,
public readonly int $total,
) {}
}
Event hanya membawa data primitif dan ID, bukan model, sehingga aman diserialisasi ke queue dan tidak membocorkan model internal.
// modules/Customer/Listeners/AwardLoyaltyPoints.php
namespace Modules\Customer\Listeners;
use Illuminate\Contracts\Queue\ShouldQueue;
use Modules\Sales\Events\OrderPlaced;
final class AwardLoyaltyPoints implements ShouldQueue
{
public function handle(OrderPlaced $event): void
{
// tambahkan poin ke pelanggan $event->customerId
}
}
// modules/Customer/CustomerServiceProvider.php
use Illuminate\Support\Facades\Event;
public function boot(): void
{
Event::listen(\Modules\Sales\Events\OrderPlaced::class, \Modules\Customer\Listeners\AwardLoyaltyPoints::class);
}
Karena event dikirim di dalam transaksi, listener queue sebaiknya hanya berjalan setelah transaksi berhasil di-commit. Tambahkan pada listener:
final class AwardLoyaltyPoints implements ShouldQueue, \Illuminate\Contracts\Events\ShouldHandleEventsAfterCommit
{
// ...
}
Batas yang tidak diuji akan dilanggar dalam hitungan minggu. Pest menyediakan architecture testing:
// tests/Arch/ModuleBoundariesTest.php
$modules = ['Catalog', 'Inventory', 'Sales', 'Customer'];
foreach ($modules as $module) {
$others = array_values(array_diff($modules, [$module]));
foreach ($others as $other) {
arch("{$module} tidak menyentuh internal {$other}")
->expect("Modules\\{$module}")
->not->toUse([
"Modules\\{$other}\\Models",
"Modules\\{$other}\\Services",
"Modules\\{$other}\\Http",
"Modules\\{$other}\\Database",
]);
}
}
arch('Shared tidak bergantung pada modul bisnis')
->expect('Modules\Shared')
->not->toUse(['Modules\Catalog', 'Modules\Inventory', 'Modules\Sales', 'Modules\Customer']);
foreach ($modules as $module) {
arch("DTO publik {$module} bersifat readonly")
->expect("Modules\\{$module}\\Data")
->toBeReadonly();
}
arch('tidak ada dd atau dump yang tertinggal')
->expect(['dd', 'dump', 'ray'])
->not->toBeUsed();
php artisan test tests/Arch
FAIL Tests\Arch\ModuleBoundariesTest
⨯ Sales tidak menyentuh internal Catalog
Expecting 'Modules\Sales' not to use 'Modules\Catalog\Models'.
at modules/Sales/Http/Controllers/OrderController.php:9
Jalankan test ini di CI pada setiap pull request. Alternatif untuk proyek yang lebih besar adalah deptrac, yang memvisualisasikan dan memvalidasi ketergantungan antar lapisan atau modul.
Jika tim lebih suka konvensi siap pakai dan generator Artisan per modul:
composer require nwidart/laravel-modules
php artisan vendor:publish --provider="Nwidart\Modules\LaravelModulesServiceProvider"
Aktifkan autoload modul lewat merge plugin di composer.json:
"extra": {
"laravel": { "dont-discover": [] },
"merge-plugin": {
"include": ["Modules/*/composer.json"]
}
}
composer dump-autoload
php artisan module:make Catalog Inventory Sales Customer
php artisan module:make-model Product Catalog -m
php artisan module:make-controller ProductController Catalog --api
php artisan module:list
Paket ini membuat struktur folder, service provider, route, dan composer.json per modul. Prinsip di Langkah 5–8 (kontrak publik, event, test arsitektur) tetap berlaku; paket hanya membantu struktur, bukan menjaga batas.
Pastikan versi paket sesuai versi Laravel (misalnya ^13.0 untuk Laravel 13), dan baca catatan upgrade setiap kali Laravel naik versi mayor.
Jangan memindahkan seluruh aplikasi sekaligus. Urutan yang aman:
Tetapkan batas di atas kertas: tabel milik modul apa.
Buat modul paling mandiri dulu (biasanya Catalog atau Customer).
Pindahkan model, controller, dan service ke modul. Sementara, biarkan class lama sebagai alias agar kode lama tetap berjalan:
// app/Models/Product.php (sementara)
namespace App\Models;
/** @deprecated gunakan Modules\Catalog\Models\Product melalui CatalogApi */
class Product extends \Modules\Catalog\Models\Product {}
Ganti pemakaian lintas modul dengan kontrak, satu per satu.
Aktifkan test arsitektur untuk modul tersebut. Gunakan ->ignoring() sementara untuk pelanggaran lama yang belum diperbaiki, lalu kurangi daftarnya setiap sprint.
Ulangi untuk modul berikutnya.
| Error / Gejala | Penyebab | Solusi |
|---|---|---|
Class "Modules\Catalog\..." not found |
Autoload PSR-4 belum ditambahkan atau belum di-dump | Tambahkan "Modules\\": "modules/", jalankan composer dump-autoload |
Route modul tidak muncul di route:list |
Provider modul belum didaftarkan, atau route di-cache | Daftarkan di bootstrap/providers.php, jalankan php artisan route:clear |
| Migration modul tidak dijalankan | loadMigrationsFrom() tidak dipanggil atau path salah |
Periksa path di service provider |
Unable to locate factory for [Modules\...\Product] |
Factory di luar namespace bawaan | Tambahkan method newFactory() di model |
| View modul tidak ditemukan | Namespace view tidak didaftarkan | loadViewsFrom(..., 'catalog') lalu panggil view('catalog::products.index') |
| Circular dependency antar modul | Modul A memakai kontrak B dan B memakai kontrak A | Jadikan salah satu arah sebagai event, atau pindahkan konsep bersama ke modul baru |
| Listener queue berjalan sebelum data tersimpan | Event dikirim di dalam transaksi | Gunakan ShouldHandleEventsAfterCommit atau DB::afterCommit() |
| Modul tidak ter-autoload dengan nwidart | Merge plugin tidak aktif atau diblokir Composer | Izinkan plugin: composer config allow-plugins.wikimedia/composer-merge-plugin true |
Keamanan
Performa
findMany) agar modul pemanggil tidak menyebabkan N+1 lintas modul.ShouldQueue untuk efek samping yang tidak perlu terjadi dalam request yang sama.Maintainability
Contracts, Data, Events.README.md singkat di setiap modul: tanggung jawab, tabel yang dimiliki, kontrak publik, dan event yang dikirim/didengar.| Komponen | Versi |
|---|---|
| Laravel | 13.x |
| PHP | 8.4 |
| MySQL | 8.4 LTS |
| Pest | 4.x |
| nwidart/laravel-modules | 13.x |
| Tanggal | 19 Oktober 2026 |
Sebelumnya
Soft Delete, Audit Trail, dan Activity Log: Cara Melacak Perubahan Data Aplikasi
Berikutnya
Membangun Laravel Starter Kit yang Reusable untuk Berbagai Jenis Aplikasi Bisnis
Dokumen ini menjelaskan prosedur konfigurasi autentikasi SSH Key antara server Ubuntu dan GitHub untuk memungkinkan server melakukan operasi Git, seperti clone, pull, dan fetch tanpa menggunakan username dan password akun GitHub.
Peta jalan arsitektur dari satu server hingga banyak server: tahapan pertumbuhan dan sinyal kapan naik tahap, prinsip yang sebaiknya diterapkan sejak awal (stateless, asinkron, data ber-tenant), read replica, pengelolaan data yang terus tumbuh, degradasi yang anggun saat layanan bermasalah, feature...
Menyiapkan lingkungan uji yang jujur, mengukur satu endpoint dengan ApacheBench, mensimulasikan perilaku pengguna sungguhan dengan k6 (skenario, threshold, autentikasi token), menelusuri penyebab request lambat dengan Telescope, memantau server selama pengujian, serta menulis laporan hasil dan angga...
Bagaimana Octane membuat Laravel lebih cepat dengan mem-boot aplikasi sekali dan menyimpannya di memori, apa yang sebenarnya dipercepat (dan yang tidak), risiko kebocoran state antar-request yang wajib dipahami, cara memeriksa kode agar aman untuk Octane, pemasangan dengan FrankenPHP di production,...
03 Nov 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
19 Oct 2026
HijrahKreativa
Kami balas secepatnya
Masuk dulu untuk chat dengan tim kami. Riwayat chat Anda tersimpan di akun.
Masuk