From b483030e477026f5813d928540ec845c8ab712be Mon Sep 17 00:00:00 2001
From: roxblnfk <roxblnfk@ya.ru>
Date: Tue, 8 Sep 2026 13:14:57 +0400
Subject: [PATCH] feat: support PHP 8.1 via #[ScopeShared] attribute

Lower the minimum PHP version to 8.1. Since `readonly class` and ReflectionClass::isReadOnly() are 8.2-only, add a #[ScopeShared] attribute that opts a service out of per-scope cloning explicitly, so the same instance is shared across the whole scope tree on any supported version.

State::clone() now shares a service when it is an enum, a readonly class (8.2+), or carries #[ScopeShared].

Refs #4

Assisted-By: Claude Opus 4.8 (1M context)
---
 composer.json                           |  3 +-
 psalm.xml                               |  2 +-
 src/Attribute/ScopeShared.php           | 18 ++++++
 src/Internal/State.php                  |  7 ++-
 tests/Unit/ScopeSharedAttributeTest.php | 78 +++++++++++++++++++++++++
 tests/Unit/Stub/ScopeSharedTag.php      | 21 +++++++
 6 files changed, 126 insertions(+), 3 deletions(-)
 create mode 100644 src/Attribute/ScopeShared.php
 create mode 100644 tests/Unit/ScopeSharedAttributeTest.php
 create mode 100644 tests/Unit/Stub/ScopeSharedTag.php

diff --git a/composer.json b/composer.json
index 24d1a04..7630986 100644
--- a/composer.json
+++ b/composer.json
@@ -24,7 +24,7 @@
         }
     ],
     "require": {
-        "php": ">=8.2",
+        "php": ">=8.1",
         "internal/destroy": "^1.0",
         "psr/container": "1 - 2",
         "yiisoft/injector": "^1.2"
@@ -33,6 +33,7 @@
         "bamarni/composer-bin-plugin": "^1.8",
         "llm/skills": "^1.12",
         "revolt/event-loop": "^1.0",
+        "roxblnfk/unpoly": "^1.8",
         "testo/codecov": "^0.2.1",
         "testo/fiber": "^0.1.3",
         "testo/testo": "^0.10.46"
diff --git a/psalm.xml b/psalm.xml
index a350484..27598b8 100644
--- a/psalm.xml
+++ b/psalm.xml
@@ -5,7 +5,7 @@
        errorLevel="1"
        findUnusedBaselineEntry="false"
        findUnusedCode="false"
-       phpVersion="8.2"
+       phpVersion="8.1"
 >
     <issueHandlers>
         <RedundantConditionGivenDocblockType errorLevel="suppress"/>
diff --git a/src/Attribute/ScopeShared.php b/src/Attribute/ScopeShared.php
new file mode 100644
index 0000000..b8934fb
--- /dev/null
+++ b/src/Attribute/ScopeShared.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Internal\Container\Attribute;
+
+/**
+ * Marks a service to be shared across scopes instead of cloned per-scope.
+ *
+ * By default a scope clones each cached service when a child scope is derived, so every scope owns
+ * its own mutable instance. A class marked with this attribute keeps a single instance shared across
+ * the whole scope tree — use it for services that are safe to share (e.g. stateless or immutable ones)
+ * on any supported PHP version, including where `readonly class` is unavailable.
+ *
+ * The attribute is not inherited: a subclass must be marked explicitly to be treated as shared.
+ */
+#[\Attribute(\Attribute::TARGET_CLASS)]
+final class ScopeShared {}
diff --git a/src/Internal/State.php b/src/Internal/State.php
index 59d5972..4c738bf 100644
--- a/src/Internal/State.php
+++ b/src/Internal/State.php
@@ -4,6 +4,7 @@
 
 namespace Internal\Container\Internal;
 
+use Internal\Container\Attribute\ScopeShared;
 use Internal\Container\Container;
 use Internal\Container\Factoriable;
 use Internal\Container\Inflector;
@@ -172,7 +173,11 @@ public function clone(ObjectContainer $container): self
             }
 
             $reflection = new \ReflectionClass($service);
-            if ($reflection->isReadOnly() || $reflection->isEnum()) {
+            if (
+                $reflection->isEnum()
+                || (PHP_VERSION_ID >= 80200 && $reflection->isReadOnly())
+                || $reflection->getAttributes(ScopeShared::class) !== []
+            ) {
                 $self->cache[$id] = $service;
                 continue;
             }
diff --git a/tests/Unit/ScopeSharedAttributeTest.php b/tests/Unit/ScopeSharedAttributeTest.php
new file mode 100644
index 0000000..5c025af
--- /dev/null
+++ b/tests/Unit/ScopeSharedAttributeTest.php
@@ -0,0 +1,78 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Internal\Container\Tests\Unit;
+
+use Internal\Container\Attribute\ScopeShared;
+use Internal\Container\ObjectContainer;
+use Internal\Container\Tests\Unit\Stub\ContainerScopeService;
+use Internal\Container\Tests\Unit\Stub\ScopeSharedTag;
+use Testo\Assert;
+use Testo\Codecov\Covers;
+use Testo\Test;
+
+/**
+ * {@see ScopeShared} — a service carrying the attribute is shared across scopes instead of cloned.
+ *
+ * A scope clones each cached service so children get their own mutable copy; the attribute opts a class
+ * out of that, keeping one instance across the whole scope tree even when it is a plain mutable class
+ * (neither `readonly` nor an enum).
+ */
+#[Test]
+#[Covers(ObjectContainer::class)]
+final class ScopeSharedAttributeTest
+{
+    public function scopeSharesMarkedServiceWithTheParent(): void
+    {
+        $container = new ObjectContainer();
+        $parent = $container->get(ScopeSharedTag::class);
+
+        $inScope = $container->scope(
+            static fn(ObjectContainer $scoped): ScopeSharedTag => $scoped->get(ScopeSharedTag::class),
+        );
+
+        Assert::same($inScope, $parent);
+    }
+
+    public function mutatingTheSharedServiceInsideAScopeIsVisibleToTheParent(): void
+    {
+        $container = new ObjectContainer();
+        $parent = $container->get(ScopeSharedTag::class);
+
+        $container->scope(static function (ObjectContainer $scoped): void {
+            $scoped->get(ScopeSharedTag::class)->tag = 42;
+        });
+
+        Assert::same($parent->tag, 42);
+    }
+
+    public function nestedScopesShareTheSameMarkedInstance(): void
+    {
+        $container = new ObjectContainer();
+        $parent = $container->get(ScopeSharedTag::class);
+
+        $deepest = $container->scope(
+            static fn(ObjectContainer $l1): ScopeSharedTag => $l1->scope(
+                static fn(ObjectContainer $l2): ScopeSharedTag => $l2->get(ScopeSharedTag::class),
+            ),
+        );
+
+        Assert::same($deepest, $parent);
+    }
+
+    /**
+     * The attribute is the differentiator: an otherwise identical unmarked mutable service is still cloned.
+     */
+    public function unmarkedServiceIsStillClonedPerScope(): void
+    {
+        $container = new ObjectContainer();
+        $parent = $container->get(ContainerScopeService::class);
+
+        $inScope = $container->scope(
+            static fn(ObjectContainer $scoped): ContainerScopeService => $scoped->get(ContainerScopeService::class),
+        );
+
+        Assert::notSame($inScope, $parent);
+    }
+}
diff --git a/tests/Unit/Stub/ScopeSharedTag.php b/tests/Unit/Stub/ScopeSharedTag.php
new file mode 100644
index 0000000..13a176e
--- /dev/null
+++ b/tests/Unit/Stub/ScopeSharedTag.php
@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Internal\Container\Tests\Unit\Stub;
+
+use Internal\Container\Attribute\ScopeShared;
+
+/**
+ * Mutable service marked {@see ScopeShared} — a scope shares it with its parent instead of cloning it.
+ *
+ * Deliberately not `readonly` and not an enum, so a test that observes sharing proves the attribute is
+ * the cause rather than immutability.
+ *
+ * @internal
+ */
+#[ScopeShared]
+final class ScopeSharedTag
+{
+    public int $tag = 7;
+}