README

northrook/kernel provides the Northrook process runtime. Kernel lifecycle, container compilation, and request handling remain separate concerns.

Kernel

Kernel implements the non-HTTP KernelInterface. It registers the process Context, owns the compiled container, and advances through:

Boot → Compile → Initializing → Runtime → Shutdown → Terminated

boot() is idempotent while the kernel is booted and not terminated. It throws when KernelContext::Terminated is set; call reset() before booting again. Reading $kernel->container boots lazily when the container is not yet compiled, and does not invoke boot() again after that. run() boots, calls the protected execute() hook, and returns its exit status. The default hook returns 0.

Applications extend Kernel to configure the compiler and process execution:

<?php

namespace App;

use Northrook\Container\CompilerInterface;
use Northrook\Kernel;

final class AppKernel extends Kernel
{
    protected function configureCompiler(CompilerInterface $compiler): void
    {
        $compiler->parameters->assign([
            'app.name' => 'Example',
        ]);
    }

    protected function execute(): int
    {
        return 0;
    }
}

The compiler scans src by default. Kernel seeds app.env, app.debug, app.root_directory, and app.var_directory.

Compiled containers are stored under {var}/container with separate environment and debug-mode names. A missing or invalid dump is compiled and persisted. Debug mode also fingerprints scanned source modification times. The container var directory must currently be inside the application root.

reset() clears retained service instances and transient context, then restores KernelContext::Runtime. It does not discard the compiled container. Terminated kernels must be reset before another boot() or run().

The Kernel provides protocol-neutral event dispatch. #[OnEvent] methods are discovered during container compilation. Listener metadata is stored in the compiled container, while listener instances and their dependencies are resolved lazily. Higher priority values run first.

The base lifecycle dispatches KernelReady during Initializing, KernelRunning during Runtime, KernelShutdown during Shutdown, and KernelTerminated during Terminated. KernelFailed reports execution failures before shutdown. KernelTerminated still fires after shutdown on failure paths. Boot and compile events are intentionally absent because container-backed listeners do not exist yet.

HTTP applications implement HttpKernelInterface. Request handling, HTTP events, routing, middleware, and response output do not belong to the base Kernel.

Entry point

The executing script requires the bootstrap and returns the entry callable. When RUNTIME_ENTRY is unset, the bootstrap re-requires $_SERVER['SCRIPT_FILENAME']. The nested include only loads Composer autoload; the outer execution must return the callable.

<?php

use Northrook\KernelInterface;
use Northrook\RuntimeOptions;

require_once dirname(__DIR__) . '/vendor/runtime.php';

return static function (RuntimeOptions $options): KernelInterface {
    return AppKernel::initialize($options)->boot();
};

The entry callable receives typed runtime dependencies and returns an application object. Point RUNTIME_ENTRY at a separate script when the front controller should not return the callable itself.

The runtime supports these callable parameters:

RuntimeOptions
RuntimeInterface or Runtime
array $argv under CLI
string $rootDirectory, $rootDir, or $projectDir
parameters with default values

Process configuration

RUNTIME_ENTRY selects the callable script. Resolution uses $_SERVER['RUNTIME_ENTRY'], $_ENV['RUNTIME_ENTRY'], then $_SERVER['SCRIPT_FILENAME'].

RUNTIME_OPTIONS accepts an array or JSON object. Supported options are app_env, app_debug, root_dir, source_dir, and var_dir. Server values take precedence over environment values and generated defaults. source_dir defaults to src for container class discovery.

Composer only runs scripts declared by the root package. Register the generator in the application's composer.json. Optional configuration belongs under extra.runtime:

{
  "scripts": {
    "post-install-cmd": "@php vendor/northrook/kernel/bin/post-install.php",
    "post-update-cmd": "@php vendor/northrook/kernel/bin/post-install.php"
  },
  "extra": {
    "runtime": {
      "class": "App\\Runtime",
      "project_dir": "app",
      "app_env": "production",
      "autoload_template": "config/runtime.template"
    }
  }
}

Set extra.runtime to false to disable generation.

northrook / kernel

Maintainers

Package info

Statistics

Security

README

Kernel

Entry point

Process configuration