README

A general-purpose modular architecture framework for PHP. Build applications where each module has its own dependency injection container, with carefully controlled sharing through explicit import/export contracts.

💡 Versatile: Works well for CLI tools, data pipelines, background processors, APIs, and complex PHP applications that benefit from clear module boundaries.

✨ Why Modular Framework?

🔒 True Encapsulation: Each module has its own isolated DI container
⚡ PowerModuleSetup: Extend module functionality without breaking encapsulation
🚀 Microservice Ready: Isolated modules can easily become independent services
📋 Explicit Dependencies: Import/export contracts make relationships visible
🧪 Better Testing: Test modules in isolation with their own containers
👥 Team Scalability: Different teams can own different modules
🔌 Plugin-Ready: Third-party modules extend functionality safely

Quick Start

composer require power-modules/framework

use Modular\Framework\App\ModularAppBuilder;

$app = new ModularAppBuilder(__DIR__)
    ->withModules(
        \MyApp\Auth\AuthModule::class,
        \MyApp\Orders\OrdersModule::class,
    )
    ->build();

// Get any exported service
$orderService = $app->get(\MyApp\Orders\OrderService::class);

⚡ PowerModuleSetup Extension System

The framework's most powerful feature - PowerModuleSetup allows extending module functionality without breaking encapsulation:

$app = new ModularAppBuilder(__DIR__)
    ->withModules(UserModule::class, OrderModule::class)
    ->addPowerModuleSetup(new RoutingSetup())    // Adds HTTP routing to modules implementing HasRoutes interface
    ->addPowerModuleSetup(new EventBusSetup())   // Pulls module events and handlers into a central event bus
    ->build();

Available extensions:

power-modules/router - HTTP routing with PSR-15 middleware Coming soon:
- power-modules/events - Event-driven architecture
- power-modules/dependency-graph - Visualize module dependencies
- power-modules/cli - Build CLI applications with modular commands
- power-modules/plugin - Plugin architecture for third-party modules
Your own! - Create custom PowerModuleSetup implementations for your needs

🚀 Microservice Evolution Path

Start with a modular monolith, evolve to microservices naturally:

Today: Modular monolith

class UserModule implements PowerModule, ExportsComponents {
    public static function exports(): array {
        return [
            UserService::class,
        ];
    }
}

class OrderModule implements PowerModule, ImportsComponents {
    public static function imports(): array {
        return [
            ImportItem::create(UserModule::class, UserService::class),
        ];
    }
}

Later: Independent microservices

class UserModule implements PowerModule, HasRoutes {
    public function getRoutes(): array
    {
        return [
            Route::get('/', UserController::class, 'list'),
        ];
    }

    public function register(ConfigurableContainerInterface $container): void
    {
        $container->set(UserController::class, UserController::class)
            ->addArguments([UserService::class]);
    }
}

class OrderModule implements PowerModule, ImportsComponents {
    // Uses User HTTP API instead of direct service import
}

Your modules are designed with clear boundaries. When you're ready to scale, the module structure supports splitting them into separate services.

📚 Documentation

📖 Complete Documentation Hub - Comprehensive guides, examples, and API reference

Quick Links:

Getting Started - Build your first module in 5 minutes
Use Cases - Real-world examples (web APIs, ETL, etc.)
Architecture - Deep dive into framework internals

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

GPL-3.0-or-later - Open source with copyleft protection. See LICENSE for details.

Commercial licenses available for proprietary use and ecosystem development. The PowerModuleSetup pattern and ecosystem architecture are protected innovations.

For commercial licensing inquiries, contact: roundcubez@gmail.com

power-modules / framework

Maintainers

Details