API Reference

Overview

This API reference provides detailed documentation for Forge Kernel internals, including performance optimizations, traits, helper functions, services, and architectural components. This documentation is intended for developers who need to understand or extend the kernel.

Performance Optimizations

Forge Kernel includes several performance optimizations to minimize reflection overhead and improve runtime performance.

Class Maps

Class maps cache the location of classes to avoid repeated file system scans and reflection operations. Maps are generated during development and cached in production.

AppCommandSetup

Caches command class locations to avoid scanning the commands directory on every request.

• Cache File: storage/framework/cache/app_command_class_map.php
• Scans: app/Commands
• Rebuilds: Automatically on file changes in development

ServiceDiscoverSetup

Caches service class locations for automatic service discovery.

• Cache File: storage/framework/cache/class-map.php
• Scans: Repositories, Middlewares, Services, Events directories
• Production: Uses cached map, skips scanning

MiddlewareLoader

Caches middleware class locations and their registration attributes.

• Cache File: storage/framework/cache/middleware-map.php
• Scans: app/Middlewares, engine/Core/Http/Middlewares, module middlewares

HelperDiscoverSetup

Caches helper file locations for automatic inclusion.

• Cache File: storage/framework/cache/helper-map.php
• Scans: app/helpers, module helper directories

Autoloader Optimizations

The PSR-4 autoloader includes file existence caching to avoid repeated file system checks.

• Web (APCu): Uses APCu for file existence caching with 1-hour TTL
• CLI (Memory): Uses in-memory array cache (max 8,000 entries)
• Namespace Mapping: Maps app, forge, modules namespaces

Cache Proxy Generation

Methods annotated with #[Cache] are wrapped with runtime-generated proxy classes.

• Proxy Classes: Generated once per class, cached in temp directory
• Performance: Avoids reflection on every method call
• Reuse: Proxies are reused across requests

Lazy Module Loading

Modules are loaded on-demand when their classes are first requested, reducing initial bootstrap time.

• Trigger: Container automatically loads modules when App\Modules\* classes are resolved
• Benefit: Only loaded modules consume memory and processing time

Traits

Forge Kernel provides numerous traits organized by category for common functionality.

Core Traits

Located in engine/Traits/

CLI Traits

Located in engine/CLI/Traits/

Cache Traits

Located in engine/Core/Cache/Traits/

Helper Functions

Global helper functions available throughout the application. Defined in engine/Core/Support/helpers.php.

$dbHost = env('DB_HOST', 'localhost');
$debug = env('APP_DEBUG', false);

// Get
$data = cache('user:123');

// Set
cache('user:123', $userData, 3600);

$timezone = config('app.timezone', 'UTC');

$host = request_host(); // Returns: example.com:8080

$street = data_get($user, 'address.street');
$value = data_get($array, 'nested.key', 'default');

echo e($userInput); // Escapes HTML

echo raw($htmlContent); // No escaping

$token = csrf_token();

echo csrf_meta(); // <meta name="csrf-token" content="...">

echo window_csrf_token();

echo csrf_input(); // <input type="hidden" name="_token" value="...">

$result = tap($value, function($v) {
    // Do something with $v
});

echo component('Button', 'class', ['label' => 'Click']);
echo component('module:Button', 'class', [], true);

layout('main');
layout('module:layout', true);

echo section('content');

echo form_open('/submit', 'POST', ['class' => 'form']);

echo form_close(); // </form>

dd($var1, $var2); // Dumps and exits

Helper Classes

Static helper classes providing common utilities. Located in engine/Core/Helpers/.

Strings

String manipulation utilities.

Url

URL generation utilities.

UUID

ID generation utilities (UUID, NanoID, ULID).

UUID::generate('uuid', ['version' => 4]);
UUID::generate('nanoid', ['size' => 21]);
UUID::generate('ulid');

Hash

Password hashing utilities.

Other Helper Classes

Dependency Injection Container

The Container class provides dependency injection and service management. Located in engine/Core/DI/Container.php.

Singleton Pattern

The container is a singleton, accessed via Container::getInstance().

$container = Container::getInstance();

Service Registration

$container->register(MyService::class);

$container->bind(LoggerInterface::class, FileLogger::class, true);

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

Service Resolution

$service = $container->make(MyService::class);

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

Service Tags

Tag services for grouped retrieval.

$container->tag('middleware', [
    AuthMiddleware::class,
    CsrfMiddleware::class,
]);

$middlewares = $container->tagged('middleware');

Instance Management

Manually set or override service instances.

$container->setInstance(MyService::class, $customInstance);

Automatic Module Loading

When resolving App\Modules\* classes, the container automatically loads the corresponding module if not already loaded.

// Module is automatically loaded when this class is resolved
$service = $container->make(\App\Modules\ForgeAuth\Services\AuthService::class);

Cache Proxy Wrapping

Services with methods annotated with #[Cache] are automatically wrapped with cache proxy classes for performance.

Contracts & Interfaces

Interfaces and contracts available in the kernel. Located in engine/Core/Contracts/.

Core Services

Core services available in the kernel. Located in engine/Core/Services/.

Autoloader

The Autoloader class implements PSR-4 autoloading with performance optimizations. Located in engine/Core/Autoloader.php.

PSR-4 Autoloading

Implements the PSR-4 autoloading standard for automatic class loading.

Namespace Mapping

Maps namespaces to base directories:

• app → BASE_PATH/app
• forge → BASE_PATH/engine
• modules → BASE_PATH/modules

File Existence Caching

Caches file existence checks to avoid repeated file system operations:

• Web (APCu): Uses APCu for file existence caching with 1-hour TTL
• CLI (Memory): Uses in-memory array cache with maximum 8,000 entries
• Performance: Significantly reduces file system I/O

Path Registration

Register additional namespace paths programmatically.

Autoloader::addPath('MyNamespace', '/path/to/classes');

Bootstrap Process

The bootstrap process initializes the kernel. Setup classes are located in engine/Core/Bootstrap/.

Bootstrap

Main bootstrap orchestrator that coordinates all setup classes.

Setup Classes

Cache System

The cache system provides method-level caching with automatic proxy generation.

Cache Drivers

Multiple cache drivers are available:

• File: File-based caching (default)
• Memory: In-memory caching for single request
• SQLite: SQLite database caching

Cache Manager

The CacheManager provides cache operations with tag support.

$cache = Container::getInstance()->make(CacheManager::class);
$cache->set('key', $value, 3600);
$value = $cache->get('key');

// Tagged cache
$cache->tags(['users', 'profile'])->set('user:123', $user);
$cache->clearTag('users');

Cache Attributes

Methods can be annotated with #[Cache] for automatic caching.

use Forge\Core\Cache\Attributes\Cache;

class UserService
{
    #[Cache(ttl: 3600)]
    public function getUser(int $id): User
    {
        // Expensive operation
        return $this->repository->find($id);
    }
}

Cache Interceptor

The CacheInterceptor intercepts method calls and handles cache lookup/storage.

Proxy Generation

The ProxyGenerator creates runtime proxy classes for services with cached methods.

• Proxies are generated once per class and cached in the temp directory
• Proxies extend the original class and implement ProxyMarkerInterface
• Method calls are intercepted and routed through the cache interceptor
• Avoids reflection overhead on every method call