comphp/runtime

Bootstrap, lifecycle, module, service provider, event, and executive support for PHP applications.

0.3.1 2026-05-17 05:32 UTC

Requires

• php: ^8.5
• php-di/php-di: ^7.1
• psr/log: ^3.0
• symfony/dotenv: ^8.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.95
• phpunit/phpunit: ^13.1

MIT

README

CommonPHP Runtime is the bootstrap/runtime foundation for CommonPHP applications. It provides the small layer that starts an application, creates the runtime container, runs an executive, emits lifecycle events, and returns or exits with an integer status code.

The package handles kernel execution, initialization context, dotenv loading, two-phase container creation, modules, service providers, events, drivers, logging access, path resolution, runtime context, and runtime error handling.

What It Is Not

CommonPHP Runtime is not an HTTP framework, router, ORM, config system, filesystem abstraction, session library, cache library, security system, or advanced logging system. It is the boot ROM, not the whole operating system.

See package boundaries for what belongs here and what belongs in separate CommonPHP packages.

Features

• Abstract Kernel for application boot and execution.
• ExecutiveInterface for web, console, worker, or custom runtime modes.
• Dotenv loading with APP_ENV and APP_DEBUG support.
• PHP-DI bootstrap and execution containers with a layered wrapper.
• Optional InitializationContext for replacing runtime collaborators before boot.
• Container attributes, compilation, proxy, and definition-cache options through ContainerOptions.
• Container configuration through kernel, module, explicit service providers, and execution configurators.
• Object-based lifecycle and runtime error events.
• PSR-3 logger binding with NullLogger fallback.
• Immutable AppContext snapshot for services.
• Root/path resolution through PathResolverInterface.
• Lightweight module registration model.
• Isolated lazy driver container plus single-driver and driver-pool traits.

Requirements

• PHP ^8.5
• php-di/php-di:^7.1
• symfony/dotenv:^8.0
• psr/log:^3.0

No additional PHP extensions are declared by this package.

Installation

composer require comphp/runtime

If this package has not been published yet, this command represents the intended Packagist install command once published.

Quick Start

<?php

declare(strict_types=1);

namespace App;

use CommonPHP\Runtime\Contracts\ExecutiveInterface;
use CommonPHP\Runtime\Support\ExitStatus;
use CommonPHP\Runtime\Kernel;

final class AppKernel extends Kernel
{
}

final class ConsoleExecutive implements ExecutiveInterface
{
    public function execute(): int
    {
        echo "Hello from CommonPHP Runtime\n";

        return ExitStatus::SUCCESS;
    }
}

$kernel = new AppKernel();
$kernel
    ->setRoot(dirname(__DIR__))
    ->setEnvironment('dev')
    ->setDebugging(true)
    ->setExecutive(ConsoleExecutive::class);

exit($kernel->execute());

Use execute() when you want an exit status back. Use run() when the kernel should call exit() for you.

Core Concepts

Kernel

The kernel is the main runtime object. It loads environment state, resolves paths, creates the PHP-DI container, imports modules, configures service providers, emits events, runs the executive, and handles shutdown.

Initialization Context

Initialization context lets advanced callers provide runtime collaborators such as a path resolver, module manager, environment loader, container factory, lifecycle handler, event emitter, logger class, container options, and initial environment state.

Executives

Executives are runtime modes. A web executive, console executive, worker executive, or test executive can all implement the same ExecutiveInterface.

Modules

Modules are lightweight registration objects imported before the container is built.

Service Providers

Service providers add definitions to the PHP-DI ContainerBuilder.

Lifecycle

Lifecycle describes startup and shutdown ordering for kernels, executives, modules, service providers, and lifecycle events.

Events

Events are object-based and subscribed to by class name, with optional priorities.

Drivers

Drivers are subsystem-owned implementation objects created lazily by an isolated driver container.

Logging

Logging uses PSR-3. If no logger is configured, the runtime binds Psr\Log\NullLogger.

AppContext

AppContext is a readonly snapshot of start time, environment, debug flag, and root path.

Path Resolution

Path resolution joins root-relative paths. It is not a filesystem abstraction.

Error Handling

Error handling converts executive failures into runtime error events, logs failures when a logger is available, and returns ExitStatus::EXCEPTION.

Documentation

Start with the documentation index.

Key pages:

• Getting started
• Architecture
• Package boundaries
• Kernel
• Initialization context
• Container
• Lifecycle
• Testing and QA

Examples

Examples live in docs/examples:

• Basic runtime
• Custom executive
• Module service provider
• Events
• Drivers
• Logging
• Error handling

Testing and Code Style

If dependencies are installed:

vendor/bin/phpunit -c phpunit.xml.dist
vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.dist.php --dry-run --diff

The current composer.json also includes test, cs:check, and lint scripts. See testing and QA and development dependencies.

Versioning

CommonPHP Runtime is intended to follow semantic versioning. Public interfaces, method names, and observable lifecycle behavior should be treated as compatibility-sensitive.

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

License

CommonPHP Runtime is released under the MIT license declared in composer.json.