README

Modular Laravel Starter Kit is an advanced, API-first starter package for Laravel. It focuses on modularity and clean architecture, aiming to make API development fast, sustainable, and scalable with minimal manual intervention.

🚀 Introduction

This kit is ideal for teams and developers who want a clean, well-structured codebase with clearly separated logic, using modern patterns such as repositories, DTOs, actions, and automatic relationship mapping.

🎯 Goals

• ✅ Automatic generation of complete API modules
• ✅ Minimal manual configuration
• ✅ Scalable and maintainable code
• ✅ Clear separation of concerns through modules
• ✅ No web UI or Blade support – API only

🔧 Features

• Modular structure: Each module is self-contained under app/Modules
• Powerful CLI Generator: Create complete modules via php artisan make:module
• Dynamic field handling: Fillables, casts, and relationships auto-handled
• Flexible flags:
  • --exceptions: Generate exception classes
  • --observers: Generate observer stubs
  • --policies: Generate policy stubs
• Auto-discovery: Routes, migrations, factories, observers, and policies
• Repository pattern: Interface-to-implementation binding out-of-the-box
• Fully configurable: config/modules.php for structure and behaviors

✅ Supported Field Types

🔄 Automatic Relationship Sync

You can use the SyncRelations::execute() helper to automatically sync both belongsToMany and belongsTo relationships using your DTO:

SyncRelations::execute($model, [
    'tags' => $dto->tags,         // BelongsToMany
    'brand' => $dto->brand_id,    // BelongsTo
]);

• For BelongsToMany, it performs $relation->sync(array)
• For BelongsTo, it sets the foreign key and saves the model if changed.

⚙️ Usage

1. Generate a New Module

php artisan make:module Product \
  --model="name:string,price:float,stock:int,is_active:bool,category_id:int" \
  --relations="category:belongsTo:Category,reviews:hasMany:Review" \
  --exceptions \
  --observers \
  --policies

2. Flags

3. Structure

app/Modules/Example/
├── Models/
├── Repositories/
├── Interfaces/
├── Http/
│   ├── Controllers/
│   ├── Actions/
│   ├── Requests/
│   ├── Resources/
│   └── DTOs/
├── Exceptions/
├── Observers/
├── Policies/
├── routes/
│   └── api.php
└── database/
    ├── migrations/
    └── factories/

4. Auto-Registration

Observers and Policies are auto-registered if files exist.

5. Validation for Foreign Keys

If a field ends in _id, the generated FormRequest will contain:

'user_id' => ['required', 'integer', 'exists:users,id'],

🧩 Planned Features

• Event and Listener support
• Notification scaffolding
• Relationship sync logic from DTO
• Sanctum authentication integration
• Exception handling stubs per action
• Resource, DTO, Request,Action,Controller
• Feature test generation
• Migration and Factory generators
• Interactive CLI wizard (make:module step-by-step)

✅ Requirements

• Laravel 9.x+
• PHP 8.0+

💡 Notes

• API-only – no Blade views or web routes.
• Ideal for headless frontends (React, Vue, etc.)

🤝 Contribution

• Issues and feature requests welcome.
• Pull Requests encouraged.

🐳 Docker Support

This starter kit includes full support for Docker. You can spin up the app, database, and web server with a single command.

✅ Getting Started

1. Build and start containers:

   docker compose up -d --build

2. Stop containers:

   docker compose down

3. Access Laravel container (for running artisan/test/composer):

   docker exec -it app_module bash

4. Run migrations:

   docker exec -it app_module php artisan migrate

5. Run tests:

   docker exec -it app_module php artisan test

6. MySQL connection (host machine):

• Host: 127.0.0.1
• Port: 3306
• User: homestead
• Password: secret
• Database: homestead