Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk

Blog / Arsitektur / Strategi Multi-Module Laravel:...
Arsitektur

Strategi Multi-Module Laravel: Membangun Aplikasi Besar Tanpa Membuat Kode Berantakan

AD

Admin HijrahKreativa

Penulis

19 Oct 2026
12 min read
11 views

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.

Overview

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,
  • modul penjualan langsung mengubah tabel milik modul gudang,
  • mengubah satu fitur memicu bug di fitur lain yang tidak terduga,
  • developer baru butuh berminggu-minggu untuk memahami alur data.

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:

  • memahami tiga strategi modularisasi dan memilih yang tepat,
  • membangun modul berbasis folder dengan service provider sendiri (tanpa paket),
  • alternatif dengan nwidart/laravel-modules,
  • pola komunikasi antar modul: kontrak, event, dan ID (bukan relasi Eloquent lintas modul),
  • test arsitektur yang gagal bila batas modul dilanggar.

Prerequisites

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.

Step-by-step Tutorial

Langkah 1: Tentukan Batas Modul dari Bisnis, Bukan dari Teknis

Kesalahan umum adalah membagi berdasarkan lapisan teknis (Controllers, Models, Services). Bagilah berdasarkan kapabilitas bisnis: sekumpulan data dan aturan yang berubah bersama.

Cara cepat menemukannya:

  1. Daftar semua tabel.
  2. Kelompokkan tabel yang selalu diubah bersama dalam satu transaksi.
  3. Beri nama kelompok dengan istilah bisnis yang dipakai klien.
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.

Langkah 2: Pilih Strategi Modularisasi

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.

Langkah 3: Struktur Folder Modul

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

Langkah 4: Service Provider per Modul

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();
    }
}

Langkah 5: Kontrak Publik Antar Modul

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.

Langkah 6: Modul Sales Memakai Kontrak

// 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:

  • Sales menyimpan product_id sebagai referensi ID, bukan relasi belongsTo(Product::class) lintas modul. Snapshot nama dan harga disimpan di item pesanan.
  • Sales tidak mengurangi stok sendiri; ia meminta modul Inventory melalui kontraknya.

Foreign key di database antar tabel milik modul berbeda masih boleh dipertahankan untuk integritas data. Yang dihindari adalah ketergantungan kode (model Eloquent) lintas modul.

Langkah 7: Komunikasi Asinkron dengan Event

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
{
    // ...
}

Langkah 8: Tegakkan Batas dengan Test Arsitektur

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.

Langkah 9: Alternatif dengan nwidart/laravel-modules

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.

Langkah 10: Migrasi Bertahap dari Struktur Lama

Jangan memindahkan seluruh aplikasi sekaligus. Urutan yang aman:

  1. Tetapkan batas di atas kertas: tabel milik modul apa.

  2. Buat modul paling mandiri dulu (biasanya Catalog atau Customer).

  3. 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 {}
    
  4. Ganti pemakaian lintas modul dengan kontrak, satu per satu.

  5. Aktifkan test arsitektur untuk modul tersebut. Gunakan ->ignoring() sementara untuk pelanggaran lama yang belum diperbaiki, lalu kurangi daftarnya setiap sprint.

  6. Ulangi untuk modul berikutnya.

Troubleshooting

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

Best Practices

Keamanan

  • Setiap modul mendaftarkan Policy dan middleware otorisasinya sendiri; jangan mengandalkan modul lain untuk memeriksa izin.
  • Kontrak publik hanya mengembalikan data yang memang boleh diketahui modul lain (DTO), bukan model lengkap dengan kolom sensitif.
  • Event yang masuk queue hanya membawa ID dan data primitif, bukan objek berisi data pribadi.

Performa

  • Sediakan method batch di kontrak (findMany) agar modul pemanggil tidak menyebabkan N+1 lintas modul.
  • Cache di dalam implementasi kontrak bila data jarang berubah.
  • Gunakan listener ShouldQueue untuk efek samping yang tidak perlu terjadi dalam request yang sama.

Maintainability

  • Batas modul mengikuti kapabilitas bisnis, dan setiap tabel punya satu pemilik.
  • Bagian publik modul kecil dan eksplisit: Contracts, Data, Events.
  • Komunikasi lintas modul melalui kontrak (sinkron) atau event (asinkron), tidak melalui model Eloquent.
  • Test arsitektur wajib berjalan di CI.
  • Tulis README.md singkat di setiap modul: tanggung jawab, tabel yang dimiliki, kontrak publik, dan event yang dikirim/didengar.
  • Mulai dari modular monolith. Modul dengan batas yang sudah teruji jauh lebih mudah dipecah menjadi layanan terpisah di masa depan, jika memang dibutuhkan.

Related Articles

Last Tested

Komponen Versi
Laravel 13.x
PHP 8.4
MySQL 8.4 LTS
Pest 4.x
nwidart/laravel-modules 13.x
Tanggal 19 Oktober 2026

Bagikan artikel:

Artikel lainnya