ray/compiler

Added

• Accept phar:// script directories — realpath() cannot resolve stream URIs, so validation falls back to is_dir()/is_readable(); AOT scripts can now boot from inside a phar archive [#144]

Added

• Accept phar:// script directories — realpath() cannot resolve stream URIs, so validation falls back to is_dir()/is_readable(); AOT scripts can now boot from inside a phar archive [#144]

1.15.0

Eager singleton warm-up for coroutine runtimes

Compiler now writes singletons.json alongside the compiled scripts, and CompiledInjector::warmup() instantiates every listed singleton eagerly:

$injector = new CompiledInjector($scriptDir);
$injector->warmup(); // call once at worker startup

In coroutine runtimes (Swoole, OpenSwoole), lazy singleton initialization can race when construction yields, producing duplicate instances. Calling warmup() before concurrent request handling removes that window. Standard PHP-FPM workers process one request at a time, so no warm-up is required there. [#137] [#140]

Compile-time rejection of injection-point singletons

A singleton whose construction needs a caller-supplied injection point is a first-consumer-wins binding — under coroutines, which consumer wins is nondeterministic. compile() now rejects such bindings with SingletonRequiresInjectionPoint (the message is the dependency index). Use prototype scope instead. [#140]

Generated scripts also emit $ip ?? throw new InjectionPointNotAvailable, so resolving an injection-point binding without a consumer context fails with a dedicated exception instead of a bare TypeError.

Other changes

• Reject an unsafe dependency index instead of encoding it; escape the index and export serialized values in generated code [#139]
• Generated scripts no longer carry // prototype / // singleton scope comments [#140]
• Fix the singleton PostConstruct lifecycle: the injector caches itself, and a failed setter/setContext() rolls back the provisional cache entry instead of leaving a half-initialized singleton [#138]

Upgrade notes

• If your module binds an injection-point-dependent provider as a singleton, compile() now fails — change the binding to prototype scope.
• Recompile your scripts with 1.15.0 before calling warmup(); it throws SingletonsFileNotFound when singletons.json is missing.

Added

• Add CompiledInjector::warmup() — eagerly instantiates every singleton listed in the compiler-generated singletons.json, closing the lazy-initialization race window in coroutine runtimes (Swoole, OpenSwoole); call once at worker start. Not needed under PHP-FPM [#137] [#140]
• Add SingletonRequiresInjectionPoint exception — compile() rejects singletons whose construction needs a caller-supplied injection point (first-consumer-wins bindings); use prototype scope instead [#140]
• Add InjectionPointNotAvailable exception — resolving an injection-point binding without a consumer context fails with a dedicated exception instead of a bare TypeError [#140]
• Add SingletonsFileNotFound exception — warmup() fails loudly when the singleton metadata is missing (recompile) [#140]

Changed

• Reject an unsafe dependency index instead of encoding it; escape the index and export serialized values in generated code [#139]
• Generated scripts no longer carry // prototype / // singleton scope comments; the $singletons write line already expresses the scope [#140]

Fixed

• Align the singleton PostConstruct lifecycle with Ray.Di: the injector caches itself, and a failed setter/setContext() rolls back the provisional cache entry instead of leaving a half-initialized singleton behind [#138]

Changed

• Skip file_exists() guard on the hot path in prototype()/singleton() — an OPcache-cached require performs no filesystem access, so the guard was the only stat() syscall left [#134]
• prototype()/singleton() now require the script directly without try/catch; a missing compiled script is a build invariant violation that surfaces as PHP 8's native catchable Error [#134]
• Deprecate ScriptFileNotFound exception (kept for BC) [#134]
• Remove redundant realpath() call in CompiledInjector::getInstance() [#134]
• Resolve #[ScriptDir] to __DIR__ instead of baking the compile-time absolute path [#136]

Added

• Add performance documentation (docs/performance.md) covering OPcache prerequisites and benchmarking methodology [#134]
• Add self-validating DI benchmark under demo/benchmark/ [#134]

Fixed

• Add --memory-limit=256M to phpstan in composer scripts

Changed

• Skip file_exists() guard on the hot path in prototype()/singleton() — an OPcache-cached require performs no filesystem access, so the guard was the only stat() syscall left [#134]
• prototype()/singleton() now require the script directly without try/catch; a missing compiled script is a build invariant violation that surfaces as PHP 8's native catchable Error [#134]
• Deprecate ScriptFileNotFound exception (kept for BC) [#134]
• Remove redundant realpath() call in CompiledInjector::getInstance() [#134]
• Resolve #[ScriptDir] to __DIR__ instead of baking the compile-time absolute path [#136]

Added

• Add performance documentation (docs/performance.md) covering OPcache prerequisites and benchmarking methodology [#134]
• Add self-validating DI benchmark under demo/benchmark/ [#134]

Fixed

• Add --memory-limit=256M to phpstan in composer scripts

Fixed

• Fix typo in variable and directory name in DependencySaver (qualifer → qualifier) #131

Thanks

• @apple-x-co

Fixed

• Fix typo in variable and directory name in DependencySaver (qualifer → qualifier) [#131]

Changed

• Require PHP 8.2+ (drop PHP 7.x support) [#129]
• Remove deprecated Doctrine annotations

Added

• Add demo for Ray.Compiler usage [#130]

Removed

• Remove unused exception classes

Changed

• Require PHP 8.2+ (drop PHP 7.x support) [#129]
• Remove deprecated Doctrine annotations

Added

• Add demo for Ray.Compiler usage [#130]

Removed

• Remove unused exception classes

Fixed

• Additional array type handling improvements (#128)

New Contributors

• @apple-x-co made their first contribution in #128

Full Changelog: 1.12.2...1.12.3

Fixed

• Additional array type handling improvements [#128]
• Add missing EOL at end of test files

Fixed

• Fix array handling in CompileVisitor to serialize arrays instead of using var_export() [#125]
• Fix fatal error when arrays contain objects (e.g., [new Object(), 'method'])

Full Changelog: 1.12.1...1.12.2

Fixed

• Fix array handling in CompileVisitor to serialize arrays instead of using var_export() [#125]
• Fix fatal error when arrays contain objects (e.g., [new Object(), 'method'])

Fixed

• Remove incorrect @deprecated annotation from DiCompileModule

Links

• Full Changelog

Fixed

• Remove incorrect @deprecated annotation from DiCompileModule

Changed

• Use override() in Compiler and remove BuiltinModule from CompilerModule
• Use override() instead of install() for CompilerModule [#116]
• Move Code4Dependency to src-deprecated and exclude from Psalm

Added

• Introduce Code4Dependency class and incorporate into DependencyCode
• Add Symfony PHP 8.3 polyfill and Override attributes
• Add PHP 8.5 support to CI
• Add LLM documentation for Ray.Compiler [#118]

Fixed

• Remove duplicated class [#116]
• Fix PHP 7.2 compatibility in CompilerModuleOverrideTest
• Use domain types from Types.php and fix PHPStan type errors

Full Changelog: 1.11.0...1.12.0

Changed

• Use override() in Compiler and remove BuiltinModule from CompilerModule
• Use override() instead of install() for CompilerModule [#116]
• Move Code4Dependency to src-deprecated and exclude from Psalm

Added

• Introduce Code4Dependency class and incorporate into DependencyCode
• Add Symfony PHP 8.3 polyfill and Override attributes
• Add PHP 8.5 support to CI
• Add LLM documentation for Ray.Compiler [#118]

Fixed

• Remove duplicated class [#116]
• Fix PHP 7.2 compatibility in CompilerModuleOverrideTest
• Use domain types from Types.php and fix PHPStan type errors

What's Changed

• Update PHP versions in CI workflow and update QA tools latest by @koriym in #114
• CompileVisitor using the visitor pattern and CompiledInjector by @koriym in #115

The dependencies of nikic/PHP-Parser have been removed, and the entire system has been rewritten using a fast compiler based on the Visitor pattern.

The on-demand compilation has been removed, and a compile injector has been added that only uses simple, clean, compiled code.

Basic Usage

Pre-compile your dependencies:

use Ray\Compiler\Compiler;

$compiler = new Compiler();
// Compile Ray.Di bindings to PHP files
$compiler->compile(
    $module,    // AbstractModule: Your application's module
    $scriptDir  // string: Directory path where compiled PHP files will be generated
);

Use the compiled injector:

use Ray\Compiler\CompiledInjector;

$injector = new CompiledInjector($scriptDir);
$instance = $injector->getInstance(YourInterface::class);

Note: The on-demand compiler will be deprecated.

Full Changelog: 1.10.6...1.11.0

Previous releases (prior to 1.11.0) are not documented in this changelog.