Getting Started

Minimal Steps to Begin

Installation

composer require nasirkhan/module-manager

Verify Installation
```
php artisan module:status
```
This lists all available modules and their status (enabled/disabled).
First Use Case: Enable a Module
```
php artisan module:enable Post
```
This enables the Post module, making its routes, migrations, and services available.

Where to Look First

Module Status: Run php artisan module:status to see all modules and their versions.
Dependencies: Check dependencies with php artisan module:dependencies Post.

Migration Tracking: Ensure migrations are up-to-date with:

php artisan module:track-migrations Post --force
php artisan module:detect-updates Post
php artisan migrate

First Practical Workflow

Build a New Module (if needed):
```
php artisan module:build Blog
```
This scaffolds a new module in Modules/Blog/ with all standard directories.
Publish Module Assets (for customization):
```
php artisan module:publish Blog
```
This copies the module to Modules/ for local modifications.

Enable and Test:

php artisan module:enable Blog
php artisan migrate

Implementation Patterns

Core Workflows

1. Module Lifecycle Management

Enable/Disable Modules:

php artisan module:enable Post
php artisan module:disable Category

Remove a Module (carefully!):
```
php artisan module:remove Tag
```

2. Dependency Management

Check if dependencies are satisfied:
```
php artisan module:dependencies Post
```

Programmatically:

$service = app(\Nasirkhan\ModuleManager\Services\ModuleVersion::class);
if (!$service->dependenciesSatisfied('Post')) {
    // Handle missing dependencies
}

3. Migration Handling

Track migrations after updates:

php artisan module:track-migrations Post --force

Detect new migrations:
```
php artisan module:detect-updates Post
```

Check for pending migrations:

php artisan module:check-migrations Post

Integration Tips

1. Service Provider Integration

Modules auto-register their service providers via module.json priority.
Override provider logic in published modules (e.g., Modules/Post/Providers/AppServiceProvider.php).

2. Route Handling

Module routes are loaded in priority order (higher priority in module.json loads first).

Publish routes for customization:

php artisan vendor:publish --tag=post-routes

3. Testing

Generate test classes:

php artisan module:make-test Post UserModelTest --unit

Test module dependencies before enabling:

$this->assertTrue($service->dependenciesSatisfied('Post'));

4. Configuration

Publish config files:

php artisan vendor:publish --tag=post-config

Override in config/module-manager.php or module-specific config files.

Advanced Patterns

1. Dynamic Module Loading

Use the ModuleVersion service to load modules conditionally:

$modules = $service->getModulesByPriority();
foreach ($modules as $module) {
    if ($service->isEnabled($module)) {
        // Load module-specific logic
    }
}

2. Migration Versioning

Track migration states per module version:

$tracker = app(\Nasirkhan\ModuleManager\Services\MigrationTracker::class);
$tracker->trackModuleMigrations('Post', '1.0.0');
$newMigrations = $tracker->getNewMigrationsSinceLastCheck('Post');

3. Asset Publishing

Publish all module assets at once:

php artisan vendor:publish --tag=post-migrations --tag=post-views --tag=post-config --tag=post-lang

4. Custom Commands

Extend module commands by publishing and overriding:
```
php artisan module:publish Post
```
Then modify Modules/Post/Console/Kernel.php.

Gotchas and Tips

Pitfalls

1. Namespace Conflicts

After publishing, namespaces are rewritten. Run:

composer dump-autoload
php artisan config:clear

If using IDE autocompletion, restart it or clear caches.

2. Migration State Issues

If migrations aren’t detected after a composer update:

php artisan module:track-migrations --force
php artisan module:detect-updates
php artisan vendor:publish --tag={module}-migrations
php artisan migrate:fresh

3. Dependency Loops

Circular dependencies (e.g., A requires B, B requires A) will fail silently. Use:
```
php artisan module:dependencies A
```
to debug.

4. Priority Collisions

Modules with the same priority in module.json may load in an undefined order. Explicitly set priorities (e.g., 10 for core, 5 for UI).

5. Published Module Overrides

Changes to published modules (Modules/{module}/) are not synced back to vendor. To update:
```
composer update nasirkhan/module-manager
php artisan module:publish {module} --force
```

Debugging Tips

1. Module Not Showing in Status?

Clear caches:

composer dump-autoload
php artisan cache:clear
php artisan config:clear

Check module.json for typos in name or alias.

2. Routes Not Loading?

Verify priority in module.json and check for conflicts.

Publish routes:

php artisan vendor:publish --tag={module}-routes

3. Service Provider Issues

If a module’s provider fails silently, check:
- The priority in module.json.
- The register() and boot() methods in Modules/{module}/Providers/{Provider}.php.
Temporarily disable other modules to isolate the issue:
```
php artisan module:disable AllBut Post
```

4. Migration Errors

Use --step to debug:
```
php artisan migrate --step --pretend
```
Check module:check-migrations for unpublished migrations.

Configuration Quirks

1. `module.json` Validation

The name and alias fields are case-sensitive. Ensure consistency:

"name": "Post",       // Must match directory name
"alias": "post"       // Used in URLs/routes

2. Default Enabled State

Modules are disabled by default unless explicitly enabled. Use:
```
php artisan module:enable Post
```
To enable all modules at once:
```
php artisan module:enable All
```

3. Composer Autoload

After publishing, run:
```
composer dump-autoload
```
If using Laravel Mix/Vite, rebuild assets:
```
npm run dev
```

Extension Points

1. Custom Module Build Templates

Override the default module scaffold by publishing and modifying:
```
php artisan module:publish --tag=module-scaffold
```
Edit vendor/nasirkhan/module-manager/stubs/module/ to change templates.

2. Hooks for Module Events

Listen for module events (e.g., ModuleEnabled, ModuleDisabled) by publishing and extending:
```
php artisan module:publish Post
```
Then add listeners in Modules/Post/Providers/EventServiceProvider.php.

3. Custom Commands

Add module-specific commands by publishing and extending:
```
php artisan module:publish Post
```
Then create Modules/Post/Console/Commands/ with your logic.

4. Migration Hooks

Extend migration logic by publishing and overriding:
```
php artisan vendor:publish --tag=post-migrations
```
Then modify Modules/Post/database/migrations/.

Performance Tips

1. Disable Unused Modules

Reduce overhead by disabling unused modules:
```
php artisan module:disable UnusedModule
```

Module Manager Laravel Package