README

A runtime context and scoped path component for the super-kernel framework.

This package provides a small and stable public contract for detecting the current runtime environment, locating the runtime root path, and navigating paths safely within that root boundary.

Features
Why This Package Exists
Installation
Requirements
Quick Start
Public API
Runtime Modes
Usage Examples
Path Safety Rules
Feature Matrix
Architecture Overview
Testing
License

Features

Automatically detects the current runtime environment
Supports Composer script runtime, Phar runtime, and CLI entry runtime
Resolves the runtime root path automatically
Provides a scoped path object for constrained path navigation
Prevents escaping above the runtime root boundary
Exposes a minimal and stable public contract
Keeps runtime detection strategies internal
Uses one public exception contract for all package-level failures

Why This Package Exists

Runtime-dependent path handling is easy to get wrong when the same framework may run in multiple forms:

through Composer
through a Phar package
through a direct CLI entry script

This package centralizes that responsibility.

Instead of scattering environment detection and path normalization logic across different components, consumers can rely on a single runtime context object and a single scoped path model.

Installation

composer require super-kernel/runtime-context

Requirements

PHP ~8.4.0

Quick Start

<?php

declare(strict_types=1);

use SuperKernel\RuntimeContext\RuntimeContext;
use SuperKernel\RuntimeContext\Contract\RuntimeContextInterface;

$context = RuntimeContext::getContext();

if ($context->mode() === RuntimeContextInterface::MODE_PHAR) {
    echo 'Running in phar mode.' . PHP_EOL;
}

echo $context->rootPath() . PHP_EOL;
echo $context->entryPath() . PHP_EOL;

Public API

`RuntimeContext::getContext()`

Returns the current runtime context instance.

`RuntimeContextInterface`

Provides:

current runtime mode
runtime root path
runtime entry path
root scoped path
path resolution from runtime root

`ScopedPathInterface`

Provides:

absolute path
relative path from runtime root
root state detection
downward navigation
upward navigation
relative path resolution within runtime boundary

`RuntimeContextExceptionInterface`

A single public exception contract for all package-level failures.

Runtime Modes

The runtime mode is returned by RuntimeContextInterface::mode().

Available constants:

RuntimeContextInterface::MODE_COMPOSER
RuntimeContextInterface::MODE_PHAR
RuntimeContextInterface::MODE_CLI

Usage Examples

Get the Current Runtime Context

<?php

declare(strict_types=1);

use SuperKernel\RuntimeContext\RuntimeContext;

$context = RuntimeContext::getContext();

echo $context->mode() . PHP_EOL;
echo $context->rootPath() . PHP_EOL;
echo $context->entryPath() . PHP_EOL;

Determine the Runtime Mode

<?php

declare(strict_types=1);

use SuperKernel\RuntimeContext\RuntimeContext;
use SuperKernel\RuntimeContext\Contract\RuntimeContextInterface;

$context = RuntimeContext::getContext();

if ($context->mode() === RuntimeContextInterface::MODE_COMPOSER) {
    echo 'Composer runtime' . PHP_EOL;
}

if ($context->mode() === RuntimeContextInterface::MODE_PHAR) {
    echo 'Phar runtime' . PHP_EOL;
}

if ($context->mode() === RuntimeContextInterface::MODE_CLI) {
    echo 'CLI runtime' . PHP_EOL;
}

Access the Runtime Root Path

<?php

declare(strict_types=1);

use SuperKernel\RuntimeContext\RuntimeContext;

$root = RuntimeContext::getContext()->root();

echo $root->absolute() . PHP_EOL;
echo $root->relative() . PHP_EOL; // "."
var_dump($root->isRoot());        // true

Resolve a Path from the Runtime Root

<?php

declare(strict_types=1);

use SuperKernel\RuntimeContext\RuntimeContext;

$context = RuntimeContext::getContext();
$config = $context->path('config/packages');

echo $config->absolute() . PHP_EOL;
echo $config->relative() . PHP_EOL;

Navigate Downward

<?php

declare(strict_types=1);

use SuperKernel\RuntimeContext\RuntimeContext;

$root = RuntimeContext::getContext()->root();
$src = $root->enter('vendor', 'package-name', 'src');

echo $src->absolute() . PHP_EOL;

Navigate Upward

<?php

declare(strict_types=1);

use SuperKernel\RuntimeContext\RuntimeContext;

$root = RuntimeContext::getContext()->root();
$path = $root->enter('var', 'cache', 'runtime');

$parent = $path->parent();
$top = $path->parent(3);

echo $parent->absolute() . PHP_EOL;
echo $top->absolute() . PHP_EOL;

Resolve Relative Paths Safely

<?php

declare(strict_types=1);

use SuperKernel\RuntimeContext\RuntimeContext;

$root = RuntimeContext::getContext()->root();
$path = $root->enter('vendor', 'package-name', 'src');
$bin = $path->resolve('../../../bin');

echo $bin->absolute() . PHP_EOL;

Handle Runtime Context Exceptions

<?php

declare(strict_types=1);

use SuperKernel\RuntimeContext\RuntimeContext;
use SuperKernel\RuntimeContext\Contract\RuntimeContextExceptionInterface;

try {
    $path = RuntimeContext::getContext()->root()->resolve('../../../../etc');
} catch (RuntimeContextExceptionInterface $exception) {
    echo $exception->getMessage() . PHP_EOL;
}

Path Safety Rules

This package applies strict path constraints.

Allowed

resolving relative paths inside the runtime root
navigating downward with enter()
navigating upward with parent() as long as the root boundary is not crossed
resolving . and .. through resolve() within the runtime root

Rejected

absolute paths passed to resolve()
empty path segments
. passed to enter()
.. passed to enter()
multi-segment input passed to enter()
any operation that escapes above the runtime root

Feature Matrix

Capability	Public Contract	Notes
Detect current runtime	`RuntimeContext::getContext()`	Single public entry point
Read runtime mode	`RuntimeContextInterface::mode()`	Uses public mode constants
Read root path	`RuntimeContextInterface::rootPath()`	Absolute path
Read entry path	`RuntimeContextInterface::entryPath()`	Absolute path
Get root scoped path	`RuntimeContextInterface::root()`	Relative path is `.`
Resolve root-relative path	`RuntimeContextInterface::path()`	Throws on invalid or out-of-bound path
Navigate downward	`ScopedPathInterface::enter()`	Accepts only single valid segments
Navigate upward	`ScopedPathInterface::parent()`	Throws if root boundary is crossed
Resolve relative path	`ScopedPathInterface::resolve()`	Supports `.` and `..` within boundary
Catch all package errors	`RuntimeContextExceptionInterface`	Single public exception contract

Architecture Overview

The following diagram shows the public surface and the internal detection structure.

graph TD
    A[RuntimeContext::getContext()] --> B[RuntimeContextInterface]
    B --> C[ScopedPathInterface]
    A --> D[Internal Runtime Detection]
    D --> E[Composer Script Detector]
    D --> F[Phar Detector]
    D --> G[CLI Entry Detector]
    C --> H[Path Normalization]
    C --> I[Boundary Protection]

Design Intent

Keep the public contract small
Keep runtime detection internal
Keep path navigation explicit and constrained
Keep boundary violations exceptional, not optional

Testing

Run the PHPUnit test suite directly:

php vendor/bin/phpunit --configuration=phpunit.xml.dist

If you explicitly want to execute PHPUnit through Composer:

composer run-script phpunit

License

This project is licensed under the MIT License.

See the LICENSE file for full license text.

super-kernel / runtime-context

Maintainers

Package info

Statistics

Security