Laravel Api Module Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation:

   composer require rpvirtual/laravel-api-module
   

   Laravel’s Package Discovery will auto-register the service provider. If not, manually add it to config/app.php.

2. Publish Configuration (Optional):

   php artisan vendor:publish --provider="Rpvirtual\LaravelApiModule\LaravelApiModuleServiceProvider" --tag="config"
   

   This generates config/moduleapi.php for customization (e.g., default namespace, storage paths).

3. Generate Your First Module:

   php artisan moduleapi:make User
   

   This creates a skeleton module in app/Modules/User/ with:

   • Http/Controllers/ (API controllers)
   • Database/Migrations/ (module-specific migrations)
   • Providers/ (module service provider)
   • Resources/ (translations, configs)
   • Routes/api.php (module routes)

4. Register the Module: Add the module’s provider to config/app.php under providers:

   Rpvirtual\LaravelApiModule\Modules\User\Providers\UserModuleServiceProvider::class,
   

   Or use the moduleapi:register command:

   php artisan moduleapi:register User
   

5. Run Migrations:

   php artisan migrate
   

   The module’s migrations will execute alongside your app’s.

6. Test the API: The module auto-registers routes under /api/user/.... Test with:

   php artisan route:list | grep user
   

Implementation Patterns

Core Workflows

1. Module Creation & Structure

• Naming Conventions: Use PascalCase for module names (e.g., User, Product).
• Directory Layout:

  app/Modules/{ModuleName}/
  ├── Http/
  │   ├── Controllers/          # API controllers (e.g., UserController)
  │   ├── Middleware/           # Module-specific middleware
  │   └── Resources/            # Request/Response transformers
  ├── Database/
  │   └── Migrations/           # Module migrations
  ├── Providers/
  │   └── {ModuleName}ModuleServiceProvider.php  # Registers routes, configs, etc.
  ├── Resources/
  │   ├── lang/                 # Translations
  │   ├── views/                # (Optional) If extending to include views later
  │   └── configs/              # Module-specific configs
  └── Routes/
      └── api.php               # Module routes
  

• Auto-Discovery: The package scans app/Modules/ for valid modules on boot.

2. Routing

• Module Routes: Define routes in {Module}/Routes/api.php:

  Route::prefix('users')->group(function () {
      Route::get('/', [UserController::class, 'index']);
      Route::post('/', [UserController::class, 'store']);
  });
  

• Route Prefix: Override the default /api prefix in config/moduleapi.php:

  'route_prefix' => 'v1',
  

• API Versioning: Use Laravel’s built-in versioning or integrate with spatie/laravel-api for versioned modules.

3. Controllers & Logic

• Base Controller: Extend Rpvirtual\LaravelApiModule\Http\Controllers\ApiController for shared logic (e.g., API responses, auth).

  namespace App\Modules\User\Http\Controllers;
  
  use Rpvirtual\LaravelApiModule\Http\Controllers\ApiController;
  
  class UserController extends ApiController
  {
      public function index()
      {
          return $this->successResponse(User::all());
      }
  }
  

• Request Validation: Use Laravel’s FormRequest in {Module}/Http/Controllers/:

  use App\Modules\User\Http\Requests\StoreUserRequest;
  
  public function store(StoreUserRequest $request)
  {
      // Validated data: $request->validated()
  }
  

4. Database & Migrations

• Module-Specific Migrations: Place migrations in {Module}/Database/Migrations/.
• Shared Database: Use Laravel’s Schema::create() or create:module command:

  php artisan make:migration create_users_table --module=user
  

• Seeders: Add module seeders to {Module}/Database/Seeders/ and register them in the module provider.

5. Service Providers

• Module Provider: Register routes, configs, and bindings in {Module}/Providers/{Module}ModuleServiceProvider.php:

  public function register()
  {
      $this->registerRoutes();
      $this->registerConfigs();
      $this->registerBindings();
  }
  
  protected function registerRoutes()
  {
      Route::module('user', function () {
          require __DIR__.'/../../Routes/api.php';
      });
  }
  

6. Configuration & Translations

• Module Configs: Publish and extend configs:

  php artisan vendor:publish --tag="moduleapi-config" --module=user
  

• Translations: Add language files to {Module}/Resources/lang/ and load them in the provider:

  public function boot()
  {
      $this->loadTranslationsFrom(__DIR__.'/../../Resources/lang', 'user');
  }
  

7. Middleware

• Module Middleware: Create middleware in {Module}/Http/Middleware/ and register it in the module provider:

  protected function registerMiddleware()
  {
      $this->app['router']->moduleMiddleware('user', function ($router) {
          $router->aliasMiddleware('user.auth', \App\Modules\User\Http\Middleware\Authenticate::class);
      });
  }
  

• Route-Specific Middleware: Apply in {Module}/Routes/api.php:

  Route::middleware(['user.auth'])->group(function () {
      // Protected routes
  });
  

8. Testing

• Module Isolation: Test modules in isolation using Laravel’s testing helpers:

  public function test_user_module()
  {
      $response = $this->getJson('/api/users');
      $response->assertStatus(200);
  }
  

• Mocking: Use ModuleTestCase (if provided) or extend PHPUnit\Framework\TestCase with module-specific setup.

Integration Tips

1. API Documentation:

   • Integrate with Laravel API Docs or Swagger by extending the module’s routes/api.php to include OpenAPI annotations.
   • Example:

     Route::get('/users', [UserController::class, 'index'])
          ->middleware('auth:api')
          ->name('users.index')
          ->middleware('swagger.document');
     

2. Authentication:

   • Use Laravel Sanctum, Passport, or custom token auth. Apply middleware in the module’s routes:

     Route::middleware('auth:api')->group(function () {
         // Authenticated routes
     });
     

3. Event Handling:

   • Dispatch module-specific events in controllers and listen in the module provider:

     // In UserController
     event(new UserCreated($user));
     
     // In UserModuleServiceProvider
     public function boot()
     {
         event(new UserCreated());
     }
     

4. Caching:

   • Cache module responses using Laravel’s cache middleware or ApiController helpers:

     return $this->cachedResponse(60, function () {
         return User::all();
     });
     

5. Rate Limiting:

   • Apply rate limiting at the module level in app/Http/Kernel.php:

     'api' => [
         \App\Modules\User\Http\Middleware\LimitRequests::class,
         // Other middleware
     ],
     

6. Logging:

   • Use Laravel’s logging with module-specific channels. Configure in config/moduleapi.php:

     'log_channel' => 'user',
     

   • Then define the channel in config/logging.php.

7. Queues & Jobs:

   • Dispatch jobs from module controllers and process them in module-specific queues:

     // In UserController
     dispatch(new SendUserWelcomeEmail($user))->onQueue('user-queue');
     

   • Configure queues in config/moduleapi.php:

     'queue_connection' => 'user-connection',
     

8. API Resources:

   • Use Laravel’s ApiResource for consistent JSON responses. Place resources in {Module}/Http/Resources/:

     namespace App\Modules\User\Http\Resources;
     
     use Illuminate\Http\Resources\Json\JsonResource;
     
     class UserResource extends JsonResource
     {
         public function toArray($request)
         {
             return [
                 'id' => $this->id,
                 'name' => $this->name,
             ];
         }
     }
     

   • Transform responses in controllers:

     return UserResource::collection(User::all());
     

Gotchas and Tips