Kernel API Reference

Overview

The kernel is a small set of primitives your app builds on: a PSR-4 autoloader, a dependency injection container, a caching layer, helper functions, traits, and the bootstrap that wires everything together. Most capabilities you add — routing, views, databases — wrap these primitives rather than replace them.

Performance Optimizations

The kernel minimizes repeated file-system and reflection work by building a few caches on disk. All of them live under storage/framework/cache/ and are rebuilt automatically when their source changes.

Autoloader class map

The PSR-4 autoloader records resolved classes to avoid repeated file-existence checks across requests. The map is kept in memory and persisted to storage/framework/cache/class_file_map.php. The persistent map is capped at 8,000 entries to keep memory bounded.

Compiled hooks

Module lifecycle hooks are discovered once and compiled to storage/framework/cache/compiled_hooks.php, so the kernel does not re-scan every module on each request.

Module registrations

The list of installed and enabled modules is cached to storage/framework/cache/module_registrations.php, avoiding repeated module discovery.

Cache proxy generation

Methods annotated with #[Cache] are wrapped in runtime-generated proxy classes so the kernel avoids reflection on every call. See the Cache System section below.

Command flush:cache clears these caches; the kernel rebuilds them on the next request.

Traits

The kernel ships a set of reusable traits in kernel/Traits/ (namespace Forge\Traits). Pull them into your classes with the use keyword.

CLI traits

A separate set of traits lives in kernel/CLI/Traits/ (namespace Forge\CLI\Traits) for building console commands:

• CliGenerator — generate command scaffolding
• CommandOptionTrait — parse command options and arguments
• ManagesAssetLinks — link module assets
• OutputHelper — styled console output
• Wizard — interactive question prompts

Helper Functions

The kernel exposes a small set of global helper functions defined in kernel/Core/Support/helpers.php. You do not need to import them; they are available anywhere in your app.

Dependency Injection Container

The Container class (in kernel/Core/DI/Container.php) resolves and manages the services your app depends on. It is a singleton, so you reach it from anywhere.

$container = Container::getInstance();

Registering services

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

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

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

Resolving services

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

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

Service tags

Group services for retrieval together.

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

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

Overriding instances

Replace a resolved service with a concrete instance manually.

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

Other container methods

• has($abstract) — check whether a binding exists
• getAll($ids) — resolve several services at once
• getServiceIds() — list registered service ids
• getServices() — list registered service instances
• setParameter($id, $value) / getParameter($id) — store and read container parameters

The Injectable attribute

Classes you want the container to manage are marked with the single #[Injectable] attribute.

use Forge\Core\DI\Attributes\Injectable;

#[Injectable]
class MyService
{
    public function __construct(
        private CacheManager $cache,
    ) {}
}

Services with #[Cache] methods are wrapped in cache proxies automatically; see the Cache System section.

Contracts & Interfaces

Contracts live in kernel/Core/Contracts/. They define the boundaries capabilities and your own code implement.

The database contracts are implemented by ForgeDatabaseSQL; the view contract by ForgeView.

Core Services

A small set of services ships in the kernel at kernel/Core/Services/. Most are used by the kernel or the package manager rather than called directly from your app.

Autoloader

The kernel's Autoloader (in kernel/Core/Autoloader.php) implements PSR-4 autoloading for your app, the kernel, and installed modules.

Namespace mapping

Namespaces are mapped to base directories:

• app → BASE_PATH/app
• forge → BASE_PATH/kernel
• modules → BASE_PATH/modules

File existence caching

To avoid repeated file-system lookups, the autoloader keeps a class file map in memory and persists it to storage/framework/cache/class_file_map.php between requests. The persistent map is capped at 8,000 entries.

Adding paths

Register additional namespace paths programmatically.

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

Bootstrap Process Internal

The bootstrap boots the kernel on every request. You normally do not call these classes directly; they run automatically when your front controller invokes Kernel::init(). The orchestrator and setup classes live in kernel/Core/Bootstrap/.

Entry point

Calling Kernel::init() delegates to the singleton Bootstrap, which loads the environment, runs each setup class, and guards your .env file from direct HTTP access.

Setup classes

Cache System

The cache system provides method-level caching with automatic proxy generation. Use the cache() helper or resolve CacheManager from the container.

Drivers

Three drivers are available; the default is SQLite.

• SQLite (default): persists to storage/database/cache.sqlite
• File: writes storage/framework/cache/<key>.cache files
• Memory: in-memory, per request only

Choose the driver with the CACHE_DRIVER environment variable.

Reading and writing

Use the cache() helper for single keys, or resolve the cache manager to use tags.

// Single keys
cache('api.weather', $weather, 3600);
$weather = cache('api.weather');

// Tagged cache via the manager
$cache = Container::getInstance()->make(CacheManager::class);
$cache->tags(['users', 'profile'])->set('user:123', $user);
$cache->clearTag('users');

Cache attributes

Annotate a method with #[Cache] for automatic caching; annotate with #[NoCache] to opt a method out.

use Forge\Core\Cache\Attributes\Cache;

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

Proxy generation

Services with cached methods are wrapped in runtime-generated proxies (ProxyGenerator) so the interceptor (CacheInterceptor) manages lookups without reflection on every call.

• Proxies are generated once per class and reused across requests
• They extend the original class and implement ProxyMarkerInterface
• Cached methods resolve through the interceptor