Module System

Overview

The Forge Framework's module system provides a flexible and powerful way to extend your application's functionality. Modules are self-contained packages that can be easily installed, updated, and removed without affecting the core framework or other modules.

One of the key philosophies behind Forge modules is that they don't rely on external dependencies or packages like Composer. This approach keeps modules lightweight, reduces potential conflicts, and simplifies the installation process.

Official Modules

Forge provides several official modules that extend the framework's functionality. Here's a list of the currently available official modules:

The Forge team is continuously working on developing new modules to extend the framework's capabilities. Check the official repository for the latest modules.

Creating Modules

Forge makes it easy to create your own modules using the built-in scaffolding command. This command will generate the basic structure and files needed for a new module.

Using the Module Scaffolding Command

To create a new module, run the following command in your terminal:

php forge.php make:module

This command will guide you through the process of creating a new module by asking for details such as:

• Module name
• Description
• Version
• Author information
• Dependencies (if any)

After completing the prompts, the command will create a new module in the modules/ directory with the appropriate structure. You can then begin developing your module's functionality.

Private Registries

Forge allows you to create and use private module registries. This is useful for organizations that want to maintain their own set of modules or use modules from trusted third-party developers.

Configuring Private Registries

To configure a private registry, you need to edit the config/package_manager.php file in your application:

// config/package_manager.php
return [
    "registry" => [
        [
            "name" => "my-private-registry",
            "url" => "https://github.com/username/my-private-modules",
            "branch" => "main",
            "private" => false,
            "ssh" => false
        ]
    ],
    "cache_ttl" => 3600
];

You can define multiple registries in the configuration file. The framework will search for modules in all configured registries.

Module Development

One of the core philosophies of the Forge Framework is that modules should be lightweight and self-contained. Unlike many other frameworks, Forge modules do not rely on external dependencies or packages like Composer. This approach has several benefits:

• Smaller file sizes and reduced overhead
• Fewer potential conflicts between dependencies
• Simplified installation and update processes
• Better control over the codebase

Module Structure

A typical Forge module has the following structure:

ModuleName/
  ├── ModuleNameModule.php  # Main module class that implements ModuleContract
  ├── forge.json            # Module metadata and configuration
  ├── config/               # Module-specific configuration
  ├── resources/            # Assets, views, and other resources
  └── src/                  # Module source code

Module Main Class

Every module must have a main class that implements the ModuleContract interface. This class is responsible for registering the module's services with the framework's dependency injection container.

namespace MyModule;

use Forge\Core\Contracts\ModuleContract;
use Forge\Core\DependencyInjection\Container;

class MyModuleModule implements ModuleContract
{
    public function register(Container $container): void
    {
        // Register module services
        $container->singleton(MyService::class);
    }

    public function boot(): void
    {
        // Perform any necessary bootstrapping
    }
}

Publishing Modules

If you're developing modules using the Forge repository, you can use the modules.php tool to help with versioning and publishing your modules.

Creating Module Versions

To create a new version of a module, use the following command:

php modules.php create-version module-name@version

For example:

php modules.php create-version my-module@1.0.0

This command will:

• Create a ZIP archive of your module
• Calculate an integrity hash for the archive
• Update the module manifest file
• Commit the changes to the module registry

Publishing to a Registry

After creating a version, you can publish it to your registry with:

php modules.php publish

This will push the changes to the remote repository specified in your registry configuration.

Remember to update the repository URL in the modules-registry to point to your own registry URL if you're maintaining a private registry.