Merge pull request #299 from koriym/feature/psalm-domain-types

Enhance type safety with Psalm domain types and fix static analysis errors

Author: koriym

.github/workflows/demo-php8.yml renamed to .github/workflows/demo.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
@@ -22,10 +22,10 @@ jobs:
 
       - name: Get composer cache directory
         id: composer-cache
-        run: echo "::set-output name=dir::$(composer config cache-files-dir)"
+        run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
 
       - name: Cache dependencies
-        uses: actions/cache@v2
+        uses: actions/cache@v4
         with:
           path: ${{ steps.composer-cache.outputs.dir }}
           key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
@@ -35,4 +35,4 @@ jobs:
         run: composer install --no-interaction --no-progress --prefer-dist
 
       - name: Run Demo
-        run: php demo-php8/run.php
+        run: php demo/run.php

.github/workflows/update-copyright-years-in-license-file.yml

@@ -9,7 +9,7 @@ jobs:
   run:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
       - uses: FantasticFiasco/action-update-license-year@v2

CLAUDE.md

@@ -0,0 +1,87 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Ray.Di is a dependency injection and AOP (Aspect-Oriented Programming) framework for PHP inspired by Google Guice. It provides annotations-based dependency injection with support for AOP interceptors.
+
+## Core Architecture
+
+### Key Components
+- **AbstractModule**: Base class for defining dependency bindings. Modules are composed using `install()` and can be overridden using `override()`
+- **Injector**: Main entry point that manages the DI container and creates instances. Auto-registers generated proxy classes and handles untargeted bindings
+- **Bind**: Fluent API for creating bindings (`.to()`, `.toProvider()`, `.toInstance()`, `.in()`)
+- **Container**: Internal storage for all bindings and dependencies
+- **Annotations**: Located in `src/di/Di/` - includes `@Inject`, `@Named`, `@Assisted`, etc.
+
+### Directory Structure
+- `src/di/`: Core DI framework code
+- `src-deprecated/`: Legacy code maintained for compatibility  
+- `tests/di/`: Unit tests with extensive fake classes for testing
+- `demo/` and `demo-php8/`: Examples showing framework usage
+- Compiled proxy classes are cached in configurable temp directories
+
+## Development Commands
+
+### Testing
+```bash
+composer test              # Run PHPUnit tests
+composer coverage          # Generate test coverage with Xdebug
+composer pcov              # Generate coverage with PCOV (faster)
+```
+
+### Code Quality
+```bash
+composer cs                # Run PHP_CodeSniffer
+composer cs-fix            # Auto-fix coding standards
+composer sa                # Static analysis (Psalm + PHPStan)
+composer clean             # Clear analysis caches
+```
+
+### Build Pipeline
+```bash
+composer build             # Full build: cs + sa + pcov + metrics
+composer tests             # Quick check: cs + sa + test
+```
+
+### Analysis Tools
+```bash
+composer phpmd             # PHP Mess Detector
+composer metrics           # Generate code metrics
+composer baseline          # Update static analysis baselines
+```
+
+## Testing Strategy
+
+- Tests use extensive fake classes in `tests/di/Fake/` to simulate real-world scenarios
+- Supports both PHP 7.2+ and PHP 8+ with separate test suites
+- Cache files are automatically cleaned between test runs
+- AOP proxy generation is tested with temporary directories
+
+## Framework Patterns
+
+### Module Definition
+```php
+class MyModule extends AbstractModule
+{
+    protected function configure(): void
+    {
+        $this->bind(Interface::class)->to(Implementation::class);
+        $this->bind(Service::class)->toProvider(ServiceProvider::class);
+    }
+}
+```
+
+### Injection Usage
+```php
+$injector = new Injector(new MyModule());
+$instance = $injector->getInstance(Interface::class);
+```
+
+## Important Notes
+
+- Ray.Di generates proxy classes for AOP which are cached in temp directories
+- The framework supports both constructor and setter injection
+- All bindings are resolved at runtime with automatic proxy weaving for aspects
+- Multi-binding support allows collecting multiple implementations of the same interface

demo/01a-linked-binding.php

@@ -21,12 +21,9 @@ interface MovieListerInterface
 
 class MovieLister implements MovieListerInterface
 {
-    public $finder;
-
-    public function __construct(FinderInterface $finder)
-    {
-        $this->finder = $finder;
-    }
+    public function __construct(
+        public FinderInterface $finder
+    ){}
 }
 
 class FinderModule extends AbstractModule

demo/01b-linked-binding-setter-injection.php

@@ -22,11 +22,9 @@ interface MovieListerInterface
 
 class MovieLister implements MovieListerInterface
 {
-    public $finder;
+    public FinderInterface $finder;
 
-    /**
-     * @Inject
-     */
+    #[Inject]
     public function setFinder(FinderInterface $finder)
     {
         $this->finder = $finder;

demo/02-provider-binding.php

@@ -39,12 +39,9 @@ interface MovieListerInterface
 
 class MovieLister implements MovieListerInterface
 {
-    /** @var Finder */
-    public $finder;
-
-    public function __construct(FinderInterface $finder)
-    {
-        $this->finder = $finder;
+    public function __construct(
+        public FinderInterface $finder
+    ){
     }
 }
 

demo/02a-named-by-qualifier.php

@@ -16,32 +16,21 @@ class LegacyFinder implements FinderInterface
 {
 }
 
-class ModernFinder implements FinderInterface
-{
-}
-
 interface MovieListerInterface
 {
 }
 
 class MovieLister implements MovieListerInterface
 {
-    public $finder;
+    public FinderInterface $finder;
 
-    /**
-     * @Legacy
-     */
-    public function __construct(FinderInterface $finder)
+    public function __construct(#[Legacy] FinderInterface $finder)
     {
         $this->finder = $finder;
     }
 }
 
-/**
- * @Annotation
- * @Target("METHOD")
- * @Qualifier
- */
+#[Attribute(Attribute::TARGET_PARAMETER), Qualifier]
 class Legacy
 {
 }

demo/02b-named-by-named.php

@@ -26,15 +26,9 @@ interface MovieListerInterface
 
 class MovieLister implements MovieListerInterface
 {
-    public $finder;
-
-    /**
-     * @Named("legacy")
-     */
-    public function __construct(FinderInterface $finder)
-    {
-        $this->finder = $finder;
-    }
+    public function __construct(
+        #[Named('legacy')] public FinderInterface $finder
+    ){}
 }
 
 class FinderModule extends AbstractModule

demo/03-injection-point.php

@@ -19,23 +19,22 @@ interface MovieListerInterface
 
 class Finder implements FinderInterface
 {
-    private $className;
+    private string $className;
 
-    public function __construct($className)
+    public function __construct(string $className)
     {
         $this->className = $className;
     }
 
-    public function find()
+    public function find(): string
     {
         return sprintf('search for [%s]', $this->className);
     }
 }
 
 class MovieLister implements MovieListerInterface
 {
-    /** @var Finder */
-    public $finder;
+    public FinderInterface $finder;
 
     public function __construct(FinderInterface $finder)
     {
@@ -45,12 +44,10 @@ public function __construct(FinderInterface $finder)
 
 class FinderProvider implements ProviderInterface
 {
-    private $ip;
-
-    public function __construct(InjectionPointInterface $ip)
-    {
-        $this->ip = $ip;
-    }
+    public function __construct(
+        public InjectionPointInterface $ip
+    )
+    {}
 
     /**
      * {@inheritdoc}

demo/05b-constructor-binding-setter-injection.php

@@ -27,7 +27,7 @@ class Finder implements FinderInterface
 
 class MovieLister implements MovieListerInterface
 {
-    public $finder;
+    public FinderInterface $finder;
 
     /**
      * Setter Injection with no Inject annotation