Getting Started

Minimal Steps to Begin

Installation:
```
composer require nwidart/laravel-modules
```
The package auto-registers its service provider and aliases.

Publish Configuration (Optional but recommended):

php artisan vendor:publish --provider="Nwidart\Modules\LaravelModulesServiceProvider"

Enable Autoloading: Add to composer.json:

"extra": {
    "merge-plugin": {
        "include": ["Modules/*/composer.json"]
    }
}

Run:

composer dump-autoload

Create Your First Module:
```
php artisan module:make Blog
```
This generates a module skeleton in Modules/Blog/ with:
- ModuleServiceProvider
- routes/web.php/routes/api.php
- Http/Controllers/ (empty by default)
- Database/Migrations/
- Resources/views/
Enable the Module:
```
php artisan module:enable Blog
```
Verify: Check php artisan module:list to confirm the module is enabled.

First Use Case: Adding a Model + Migration

Generate a Model:
```
php artisan module:make-model Blog/Post -m
```
This creates:
- Database/Models/Post.php
- Database/Migrations/[timestamp]_create_posts_table.php
Run Migrations:
```
php artisan migrate
```

Define Routes (in Modules/Blog/routes/web.php):

Route::resource('posts', 'PostsController');

Generate a Controller (if not auto-generated):

php artisan module:make-controller Blog/PostsController --resource

Where to Look First

Documentation: laravelmodules.com/docs
Artisan Commands: Run php artisan and filter by module: prefix.
Module Structure: Modules/[ModuleName]/ follows Laravel conventions but is isolated.
Configuration: Published at config/modules.php (customize paths, namespaces, etc.).

Implementation Patterns

Core Workflows

1. Modular Development Cycle

Create a Module:
```
php artisan module:make [name] [--namespace="Module\\Namespace"]
```
Example: php artisan module:make Admin --namespace="App\\Modules\\Admin"

Generate Assets: Use Laravel’s generators with module-specific flags:

php artisan module:make-model Admin/User -m
php artisan module:make-controller Admin/UsersController --resource --api
php artisan module:make-migration create_users_table --module=Admin

Seed Data:

php artisan module:seed Admin --class=AdminDatabaseSeeder

Compile Assets: Modules support Laravel Mix/Vite. Add a vite.config.js or webpack.mix.js to the module root and use:
```
php artisan module:build Admin
```

2. Route Management

Default: Modules use a RouteServiceProvider (auto-generated at Modules/[Module]/RouteServiceProvider.php).
Custom Routes: Define in Modules/[Module]/routes/web.php or routes/api.php.
Load Routes: Automatically loaded when the module is enabled.

3. Service Providers

Each module has a ModuleServiceProvider (e.g., Modules/Blog/ModuleServiceProvider.php).

public function boot()
{
    $this->registerTranslations();
    $this->registerConfig();
    $this->registerViews();
    $this->registerRoutes();
    $this->registerPolicies();
}

4. Views and Assets

Views: Store in Modules/[Module]/Resources/views/.

Assets: Use Laravel Mix/Vite. Configure in vite.config.js (module root):

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/css/app.css', 'resources/js/app.js'],
            refresh: true,
        }),
    ],
});

Publish Assets: Run php artisan module:build [module].

5. Database and Migrations

Migrations: Store in Modules/[Module]/Database/Migrations/.
Seeders: Store in Modules/[Module]/Database/Seeders/.
Run Migrations:
```
php artisan migrate --module=Blog
```

Seed Data:

php artisan db:seed --class=BlogDatabaseSeeder

6. Testing

Test Isolation: Use --module flag in phpunit.xml:
```
<env name="MODULES" value="Blog,Admin"/>
```

Test Helpers: Use module() helper to load a module in tests:

use Nwidart\Modules\Facades\Module;

Module::load('Blog');

Integration Tips

1. Dependency Management

Module Dependencies: Define in Modules/[Module]/module.json:
```
{
    "require": ["Auth", "Database"]
}
```
Auto-Load Dependencies: Run php artisan module:enable [module] to load dependencies.

2. Configuration

Module-Specific Config: Publish config files to config/modules.php:

'paths' => [
    'modules' => base_path('Modules'),
],
'namespace' => 'Modules',

Override Config: Use config_path('modules.php') to customize paths/namespaces.

3. Middleware

Module-Specific Middleware: Register in ModuleServiceProvider:

public function boot()
{
    $this->app['router']->middleware('web', \App\Http\Middleware\CheckBlogAuth::class);
}

Global Middleware: Define in app/Http/Kernel.php under $moduleMiddleware.

4. Events and Listeners

Generate Event/Listener:

php artisan module:make-event Blog/PostCreated
php artisan module:make-listener Blog/HandlePostCreated --event=Blog/PostCreated

Register in ModuleServiceProvider:

public function boot()
{
    $this->app->make('Blog\Events\PostCreated')->listen(function ($event) {
        // Handle event
    });
}

5. API Resources

Generate Resource:

php artisan module:make-resource Blog/PostResource

Use in Controllers:
```
return new PostResource(Post::all());
```

6. Commands

Generate Module Command:

php artisan module:make-command Blog/GenerateSitemap

Register in ModuleServiceProvider:

protected $commands = [
    \Modules\Blog\Commands\GenerateSitemap::class,
];

7. File Activator (Database Storage)

Enable Database Storage:
```
php artisan module:v6:migrate
```

Custom Activator: Extend \Nwidart\Modules\Activators\DatabaseActivator:

use Nwidart\Modules\Activators\DatabaseActivator;

class CustomActivator extends DatabaseActivator
{
    protected $table = 'module_statuses';
}

Register in config/modules.php:

'activator' => \App\Activators\CustomActivator::class,

Gotchas and Tips

Pitfalls

1. Autoloading Issues

Symptom: Class not found errors for module classes.
Cause: Missing composer dump-autoload or incorrect merge-plugin config.

Fix:

Ensure composer.json has:

"extra": {
    "merge-plugin": {
        "include": ["Modules/*/composer.json"]
    }
}

Run composer dump-autoload.

2. Route Conflicts

Symptom: Routes from different modules conflict (e.g., /posts in both Blog and Admin).