Getting Started

Minimal Steps

Installation
```
composer require internachi/modular
```
- No manual configuration required; Laravel auto-discovers the package.
Publish Config (Optional but Recommended)
```
php artisan vendor:publish --tag=modular-config
```
- Customize the default module namespace (e.g., InterNACHI instead of Modules\).
Create Your First Module
```
php artisan make:module users
```
- This scaffolds a module in app-modules/users/ with standard Laravel conventions.
Update Composer
```
composer update modules/users
```
- Registers the module as a Composer path repository.
Sync Project Configs (Optional)
```
php artisan modules:sync
```
- Updates phpunit.xml and PhpStorm configs to recognize modules.

First Use Case: Creating a Module-Specific Model

php artisan make:model User --module=users

Generates a model in app-modules/users/src/Models/User.php.
Automatically registers migrations, factories, and policies under the module namespace.

Implementation Patterns

1. Module-Specific Artisan Commands

Generate a Controller in a Module
```
php artisan make:controller UserController --module=users
```
- Outputs to app-modules/users/src/Http/Controllers/UserController.php.
Run Module-Specific Seeders
```
php artisan db:seed --module=users
```
- Executes app-modules/users/src/Database/Seeders/DatabaseSeeder.

Cache/Clear Module Discovery

php artisan modules:cache   # Optimize auto-discovery
php artisan modules:clear   # Reset cache

2. Leveraging Laravel Conventions

Auto-Discovery:
- Commands: Register via app-modules/{module}/src/Console/Kernel.php.
- Migrations: Run via php artisan migrate (no extra steps).
- Factories: Use factory(Modules\Users\Models\User::class).
- Policies: Auto-discovered for models.
- Blade Components: Namespace support (e.g., <x-users::profile />).
- Translations: Access via __('users::messages.welcome').

Example: Blade Component Place a component at:

app-modules/users/src/View/Components/Profile.php

Use in Blade:

<x-users::profile user="{{ $user }}" />

3. Integration Workflows

A. Adding a Module to an Existing Project

Create the module:
```
php artisan make:module payments
```

Generate resources (e.g., models, migrations):

php artisan make:model Payment --module=payments
php artisan make:migration create_payments_table --module=payments

Route::prefix('payments')->group(function () {
    Route::get('/', 'PaymentController@index');
});

B. Sharing Modules Across Projects

Publish the module as a Composer package:

composer config repositories.my-modules path ./app-modules
composer require my-modules/payments

Reuse the module in other projects by referencing it in their composer.json.

4. Customizing Module Structure

Publish the app-modules.php config:

php artisan vendor:publish --tag=modular-stubs

Modify stubs to change:

Default file paths (e.g., src/ → app/).
Namespace prefixes (e.g., Modules\ → App\Modules\).

Example stub placeholder:

// app-modules.php
'stubs' => [
    'module' => [
        'path' => __DIR__.'/stubs/module',
        'namespace' => 'App\\Modules',
    ],
],

Gotchas and Tips

Pitfalls

Namespace Collisions
- Avoid naming modules with reserved Laravel names (e.g., Auth, Cache).
- Fix: Use a custom namespace (e.g., InterNACHI\Auth).
Composer Path Repository Issues
- If composer update fails, ensure app-modules/ exists and is writable.
- Fix: Manually add to composer.json:
```
"repositories": {
    "my-modules": { "type": "path", "url": "./app-modules" }
}
```
PhpStorm Not Recognizing Modules
- Run php artisan modules:sync to update IDE configs.
- Manual Fix: Add app-modules/ to PhpStorm’s "Project Root" settings.
Blade Component Auto-Discovery Fails
- Ensure components are in src/View/Components/ or resources/components/.
- Fix: Verify the component namespace matches the module name (e.g., <x-users::profile />).
Migration Path Issues on Windows
- Use forward slashes (/) in paths or enable composer.config.json:
```
{
    "config": {
        "platform-check": false
    }
}
```

Debugging Tips

Check Loaded Modules
```
php artisan modules:list
```
- Lists all discovered modules and their paths.

Clear Caches

php artisan modules:clear
php artisan config:clear
php artisan view:clear

Verify Auto-Discovery
- Check vendor/internachi/modular/src/ModuleServiceProvider.php for registered tags.
- Ensure config/app.php includes:
```
'providers' => [
    Internachi\Modular\ModuleServiceProvider::class,
],
```
Debug Composer Paths
- Run composer show -a to verify module repositories are registered.

Extension Points

Custom Module Stubs
- Override default scaffolding by publishing stubs:
```
php artisan vendor:publish --tag=modular-stubs
```
- Modify files in config/stubs/module/.

Add Module-Specific Service Providers

public function register()
{
    $this->app->register(\Modules\Users\Providers\AuthServiceProvider::class);
}

Dynamic Module Loading

Use the Modules facade to check if a module is loaded:

if (\Internachi\Modular\Facades\Modules::has('users')) {
    // Module is active
}

Post-Install Hooks

Add scripts to composer.json to auto-run modules:sync:

"scripts": {
    "post-autoload-dump": [
        "@php artisan modules:sync"
    ]
}

Pro Tips

Use --module for All make: Commands
- Ensures consistency in namespace and file structure:
```
php artisan make:policy UserPolicy --module=users
```

Leverage Module-Specific Routes

Prefix routes in app-modules/{module}/routes/web.php:

Route::prefix('admin/users')->group(function () {
    // Module-specific routes
});

Isolate Dependencies
- Add module-specific dependencies to app-modules/{module}/composer.json:
```
{
    "require": {
        "spatie/laravel-permission": "^5.0"
    }
}
```
- Run composer update in the module directory.
Test Modules in Isolation
- Use the --module flag with phpunit:
```
php artisan test --module=users
```
- Tests run against the module’s namespace (e.g., Modules\Users\Tests).

Modular Laravel Package