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.

Table of Contents

• Features
• Why This Package Exists
• Installation
• Requirements
• Quick Start
• Public API
• Runtime Modes
• Usage Examples
  • Get the Current Runtime Context
  • Determine the Runtime Mode
  • Access the Runtime Root Path
  • Resolve a Path from the Runtime Root
  • Navigate Downward
  • Navigate Upward
  • Resolve Relative Paths Safely
  • Handle Runtime Context Exceptions
• 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

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.