API Reference

Core Engine API

Essential classes that power the Forge Engine framework. These core components handle application initialization, service discovery, class loading, and the overall application lifecycle.

Engine

The main application engine that bootstraps and runs the framework. The Engine class is responsible for initializing the application, loading modules, and handling the request-response cycle.

Constructor & Properties

__construct(Container $container)

Initialize the engine with a dependency injection container.

$container = new Container();
$engine = new Engine($container);

$container: Container

The dependency injection container instance.

Core Methods

run(): void

Starts the application and handles the incoming request.

$engine = new Engine($container);
$engine->run();

getContainer(): Container

Returns the dependency injection container instance.

$container = $engine->getContainer();
$service = $container->get(MyService::class);

loadModules(): void

Load and initialize all registered modules.

$engine->loadModules();

Bootstrap

Handles application initialization and service registration. The Bootstrap class is responsible for setting up essential services, loading configuration, and preparing the application for execution.

Static Methods

boot(Container $container): void

Bootstraps the application with essential services.

$container = new Container();
Bootstrap::boot($container);

loadServices(Container $container): void

Load and register core services in the container.

Bootstrap::loadServices($container);

loadConfiguration(): void

Load application configuration from config files.

Bootstrap::loadConfiguration();

Autoloader

Manages class loading and namespace registration. The Autoloader handles automatic loading of classes using PSR-4 autoloading standards and provides namespace mapping capabilities.

Static Methods

register(): void

Register the autoloader with PHP's spl_autoload system.

Autoloader::register();

addNamespace(string $namespace, string $path): void

Add a namespace to directory mapping.

Autoloader::addNamespace('App\\Controllers', 'app/controllers');
Autoloader::addNamespace('App\\Models', 'app/models');

loadClass(string $class): bool

Attempt to load a specific class.

$loaded = Autoloader::loadClass('App\\Controllers\\UserController');

Loader

Loads modules and their dependencies. The Loader class is responsible for discovering, loading, and initializing modules within the application.

Core Methods

loadModule(string $modulePath): void

Load a specific module from its path.

$loader = new Loader();
$loader->loadModule('modules/ForgeAuth');

getLoadedModules(): array

Get all currently loaded modules.

$modules = $loader->getLoadedModules();
foreach ($modules as $module) {
    echo $module->getName() . "\n";
}

ServiceDiscoverSetup

Discovers and registers services and event listeners. This class handles automatic service discovery, dependency injection setup, and event listener registration throughout the application.

Core Methods

discoverServices(): void

Discover and register all available services.

$discover = new ServiceDiscoverSetup();
$discover->discoverServices();

registerEventListeners(): void

Register all event listeners found in the application.

$discover->registerEventListeners();

Container

The dependency injection container for managing services and dependencies. Provides service registration, resolution, and lifecycle management for the entire application.

Service Registration

bind(string $abstract, string|callable $concrete = null): void

Bind a service to the container.

$container->bind(UserService::class);
$container->bind(PaymentInterface::class, StripePayment::class);
$container->bind('config', fn() => new Config());

singleton(string $abstract, string|callable $concrete = null): void

Bind a singleton service to the container.

$container->singleton(CacheManager::class);
$container->singleton('logger', LoggerService::class);

Service Resolution

get(string $abstract): mixed

Resolve a service from the container.

$userService = $container->get(UserService::class);
$logger = $container->get('logger');

has(string $abstract): bool

Check if a service is bound in the container.

if ($container->has(UserService::class)) {
    $service = $container->get(UserService::class);
}

Usage Examples

Common patterns and examples for working with the Core Engine classes.

Basic Application Setup

// Initialize autoloader
Autoloader::register();
Autoloader::addNamespace('App\\Controllers', 'app/controllers');
Autoloader::addNamespace('App\\Models', 'app/models');

// Create container and bootstrap
$container = new Container();
Bootstrap::boot($container);

// Create and run engine
$engine = new Engine($container);
$engine->run();

Service Registration Pattern

// Register services in container
$container->singleton(DatabaseConnection::class, function() {
    return new DatabaseConnection([
        'host' => 'localhost',
        'database' => 'myapp',
        'username' => 'root',
        'password' => 'password'
    ]);
});

$container->bind(UserService::class, function($container) {
    return new UserService(
        $container->get(DatabaseConnection::class)
    );
});

// Use registered services
$userService = $container->get(UserService::class);

Module Loading Pattern

$loader = new Loader();

// Load specific modules
$loader->loadModule('modules/ForgeAuth');
$loader->loadModule('modules/ForgeCache');

// Get loaded modules
$modules = $loader->getLoadedModules();
foreach ($modules as $module) {
    echo "Loaded: " . $module->getName() . "\n";
    echo "Version: " . $module->getVersion() . "\n";
}

Best Practices

Recommended patterns and guidelines for working with the Core Engine.

Do's

  • • Always register the autoloader first
  • • Use dependency injection for service management
  • • Follow PSR-4 autoloading standards
  • • Register services as singletons when appropriate
  • • Use interfaces for service contracts
  • • Bootstrap the application before running the engine

Don'ts

  • • Don't create circular dependencies
  • • Don't manually require class files
  • • Don't bypass the container for service creation
  • • Don't register services in the wrong order
  • • Don't ignore namespace conventions
  • • Don't skip error handling in service registration