README

Overview

glugox/orchestrator is the runtime module manager for Laravel applications that embrace the Glugox modular ecosystem. The package discovers available modules, registers them with the framework, and gives developers tooling to enable, disable, and monitor every module that powers their application.

Where glugox/module defines the contracts a module must fulfil and glugox/module-generator scaffolds new modules, orchestrator is the piece that connects everything at runtime inside the main Laravel app.

Architecture at a Glance

┌────────────────────┐         ┌────────────────────┐         ┌────────────────────┐
│  Main Laravel App  │────┬──▶ │  glugox/orchestr.  │ ───────▶│    Module Runtime  │
└────────────────────┘    │    └────────────────────┘         │ (Routes, Migrations│
                          │                                   │  Providers, etc.)  │
                          │    ┌────────────────────┐         └────────────────────┘
                          └──▶ │  glugox/module     │ ◀────┐
                               └────────────────────┘      │
                                                           │
                               ┌────────────────────┐      │
                               │ glugox/module-gen. │ ─────┘
                               └────────────────────┘

• Main Laravel App – hosts the modules and exposes the artisan commands and APIs to administrators.
• glugox/orchestrator – discovers, validates, enables, disables, and boots modules.
• glugox/module – provides the base ModuleContract, lifecycle hooks, and helper traits that orchestrator consumes.
• glugox/module-generator – produces modules that follow the conventions required by both orchestrator and glugox/module.

Installation

composer require glugox/orchestrator

Laravel auto-discovers the service provider. If you want explicit control, register it in config/app.php:

'providers' => [
    // ...
    Glugox\Orchestrator\OrchestratorServiceProvider::class,
],

Publish the configuration file to customise module directories and discovery options:

php artisan vendor:publish --provider="Glugox\Orchestrator\OrchestratorServiceProvider"

Configuration

The published config/orchestrator.php file controls how modules are located and managed.

Key settings include:

• paths.modules – directories that should be scanned for modules (defaults to base_path('modules')).
• manifest – file name that stores cached discovery information.
• autoload – toggles whether discovered modules should be automatically registered at boot.

Configuration values are consumed by Support\OrchestratorConfig, keeping discovery behaviour consistent across commands and runtime services.

Module Lifecycle

1. Discovery – Support\ModuleDiscovery scans configured directories and composer metadata for modules. Manifest files speed up repeat scans.
2. Registration – Discovered modules are registered with the Laravel container via OrchestratorServiceProvider.
3. Boot – When a module is enabled, orchestrator resolves its ModuleServiceProvider (defined by glugox/module) and loads routes, migrations, translations, and assets.
4. Management – The lifecycle can be controlled via artisan commands or the Services\ModuleManager API.

Modules generated by glugox/module-generator already implement the contracts from glugox/module, so they are immediately compatible with orchestrator.

Command Reference

• php artisan orchestrator:modules:list – show every discovered module with its current status.
• php artisan orchestrator:modules:enable {module} – enable a module and boot its service provider.
• php artisan orchestrator:modules:disable {module} – disable a module while keeping it installed.
• php artisan orchestrator:modules:reload – flush the manifest cache and rediscover modules.

Commands delegate to Services\ModuleManager and Services\ModuleRegistry, which encapsulate runtime state and synchronisation logic.

Using Orchestrator in Your Application

Bootstrapping Modules During Application Start

The service provider hooks into Laravel's boot sequence. When the application starts, orchestrator:

1. Reads the manifest to determine available modules.
2. Resolves each module's metadata via ModuleRegistry.
3. For enabled modules, registers the corresponding ModuleServiceProvider from the module package.
4. Invokes lifecycle hooks such as bootRoutes, bootMigrations, and bootAssets that are declared by the module through the interfaces in glugox/module.

Because the work is performed in a service provider, modules participate in the Laravel pipeline like any other package, benefiting from deferred service loading, configuration merging, and event listeners.

Coordinating with glugox/module

glugox/module supplies the contracts and base implementations that orchestrator relies on. When a module implements the ModuleContract, orchestrator can:

• Inspect the module identifier, version, and dependencies.
• Resolve the module's custom service provider class.
• Invoke optional capabilities such as route, migration, or asset loading.

If a module declares dependencies, orchestrator ensures they are enabled first, preventing runtime mismatches.

Integrating Modules Generated by glugox/module-generator

glugox/module-generator scaffolds modules that already follow the directory structure and class naming conventions required by orchestrator. Typical workflow:

1. Generate a module:

   php artisan module:make Inventory

2. The generator creates the module skeleton, including the service provider and manifest expected by orchestrator.

3. Run php artisan orchestrator:modules:reload to discover the new module.

4. Enable it with php artisan orchestrator:modules:enable company/inventory and the module becomes part of the application immediately.

Programmatic Usage

use Glugox\Orchestrator\Services\ModuleManager;

$manager = app(ModuleManager::class);

// Retrieve all modules
$modules = $manager->all();

// Enable a module
$manager->enable('company/billing');

// Disable a module
$manager->disable('company/crm');

ModuleManager talks to ModuleRegistry to keep module status in sync with the manifest file, and raises domain-specific exceptions if modules cannot be located or have unmet dependencies.

Project Structure

src/
├── Commands/
│   ├── DisableModuleCommand.php
│   ├── EnableModuleCommand.php
│   ├── ListModulesCommand.php
│   └── ReloadModulesCommand.php
├── Services/
│   ├── ModuleManager.php
│   └── ModuleRegistry.php
├── Support/
│   ├── ModuleDiscovery.php
│   └── OrchestratorConfig.php
└── OrchestratorServiceProvider.php

Roadmap Ideas

• Optional dashboard UI for module management.
• Declarative dependency resolution between modules.
• Remote module registries with signed manifests.
• Lifecycle hooks for pre/post enable and disable events.