Ray.Compiler - DI Compiler for Ray.Di
========================================

Ray.Compiler is a dependency injection compiler for Ray.Di that pre-compiles DI bindings into executable PHP code. It transforms Ray.Di's complex dependency resolution into simple PHP scripts, replacing the full-featured Ray.Di Injector with a minimal CompiledInjector that does nothing but execute pre-compiled code.

Installation
------------
composer require ray/compiler

Prerequisites
-------------
Understanding Ray.Compiler requires understanding Ray.Di (the dependency injection framework being compiled).

Ray.Di Complete Documentation (for LLMs):
https://ray-di.github.io/llms-full.txt

This document explains Ray.Di's module system, dependency resolution, scope management, and AOP—all concepts that Ray.Compiler transforms into executable PHP code.

Two-Phase Architecture
----------------------
- Compile-time: Uses Ray.Di's full dependency resolution (reflection, binding analysis, AOP weaving)
- Runtime: Minimal CompiledInjector simply executes pre-generated scripts—no reflection, no binding resolution, no dependency graph traversal

Basic Usage
-----------
Pre-compile your dependencies:

```php
use Ray\Compiler\Compiler;

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

Use the compiled injector:

```php
use Ray\Compiler\CompiledInjector;

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

Core Components
---------------

1. Compiler (src/Compiler.php): Entry point that compiles Ray.Di modules into Scripts
   - Acquires file lock for thread safety during compilation
   - Uses CompileVisitor to traverse and convert dependencies to PHP code
   - Saves compiled scripts to target directory

2. CompiledInjector (src/CompiledInjector.php): Minimal injector that executes pre-compiled code
   - Does NOT perform dependency resolution - all resolution happens at compile-time
   - Does NOT use reflection - all necessary metadata embedded in compiled scripts
   - getInstance() simply constructs file path and executes script via require
   - Manages singleton instances in $singletons array

3. Scope Functions (src-function/):
   - singleton(): Returns cached instance or requires script file (singleton scope)
   - prototype(): Always requires script file for new instance (prototype scope)

Key Concepts
------------

Dependency Index Format:
Dependencies are identified as "Interface-BindingName" (e.g., "FooInterface-", "BarInterface-named"). This index is used for:
- Script file naming (with backslashes replaced by underscores)
- Singleton storage keys
- Dependency lookups

Scope Handling:
- Singleton: Instance created once, cached in $singletons[$dependencyIndex]
- Prototype: New instance created on each getInstance() call
- Scope determined during compilation and embedded in generated scripts

Version Control
---------------
Compiled DI code is considered an environment-specific build artifact and should NOT be committed to version control.

Add the compile directory to your .gitignore:
/tmp/di/

PHP Version Support
-------------------
Requires PHP 7.2+ or 8.0+

Full Documentation
------------------
For complete documentation including architecture details, development commands, and Docker integration, see:
https://ray-di.github.io/Ray.Compiler/llms-full.txt