README

Part of the Jardis Business Platform — Enterprise-grade PHP components for Domain-Driven Design

Runtime class versioning via namespace injection. Load different implementations of the same class by version label — without changing call sites. Configure fallback chains so a missing version silently degrades to the previous one. Register proxy instances for hot-swapping at test or runtime. Deploy new logic versions without breaking existing code.

Features

SubDirectory Resolution — injects a version label into the namespace to locate versioned class implementations
Proxy Cache — pre-register object instances via LoadClassFromProxy that are returned directly, bypassing class loading
Fallback Chains — define ordered fallback sequences in ClassVersionConfig so resolution degrades gracefully across versions
Version Groups + Aliases — map multiple labels to one canonical version key
Tracing Decorator — wrap any resolver in TracingClassVersion to record every resolution for debugging
Zero-coupling — works with any PSR-4 autoloader, no framework dependency required

Installation

composer require jardissupport/classversion

Quick Start

use JardisSupport\ClassVersion\Data\ClassVersionConfig;
use JardisSupport\ClassVersion\Reader\LoadClassFromSubDirectory;
use JardisSupport\ClassVersion\ClassVersion;

// Map version labels to canonical subdirectory names
$config = new ClassVersionConfig(
    version: ['V2' => ['v2', '2.0'], 'V1' => ['v1', '1.0']],
);

$resolver = new ClassVersion(
    $config,
    new LoadClassFromSubDirectory($config),
);

// Resolves App\Service\V2\Calculator (namespace injection)
$className = $resolver(App\Service\Calculator::class, 'v2');

$instance = new $className();

Advanced Usage

use JardisSupport\ClassVersion\Data\ClassVersionConfig;
use JardisSupport\ClassVersion\Reader\LoadClassFromSubDirectory;
use JardisSupport\ClassVersion\Reader\LoadClassFromProxy;
use JardisSupport\ClassVersion\ClassVersion;
use JardisSupport\ClassVersion\TracingClassVersion;

// Fallback chain: if V2 namespace is missing, try V1 before the base class
$config = new ClassVersionConfig(
    version: ['V2' => ['v2', '2.0'], 'V1' => ['v1', '1.0']],
    fallbacks: ['V2' => ['V1']],
);

// Proxy cache: return a pre-built instance for a specific class + version
$proxy = new LoadClassFromProxy($config);
$proxy->addProxy(App\Service\Calculator::class, new MyTestCalculator(), 'v2');

$resolver = new ClassVersion(
    $config,
    new LoadClassFromSubDirectory($config),
    $proxy,
);

// Wrap with tracing decorator to record all resolutions
$tracing = new TracingClassVersion($resolver);

// Returns the pre-registered proxy instance directly
$result = $tracing(App\Service\Calculator::class, 'v2');

// Resolves App\Service\V2\Formatter — falls back to V1 if the V2 namespace is absent
$className = $tracing(App\Service\Formatter::class, 'v2');
$instance = new $className();

// Inspect the resolution log
foreach ($tracing->getTrace() as $entry) {
    echo $entry['requested'] . ' [' . ($entry['version'] ?? 'default') . ']'
        . ' → ' . $entry['type'] . PHP_EOL;
}

$tracing->clearTrace();

Documentation

Full documentation, guides, and API reference:

docs.jardis.io/support/classversion

License

This package is licensed under the PolyForm Shield License 1.0.0. Free for all use except building competing frameworks or developer tooling.

Jardis · Documentation · Headgent

jardissupport / classversion

Maintainers

Package info

Statistics

Security