Rename request-scoped helpers to use 'context' terminology

loks0n · claude · loks0n · commit 23c23c402945 · 2026-04-28T10:30:59.000+01:00
Singletons stay under setResource/getResource (the global container);
per-request values are now setContext (the request container). The
adapters' coroutine-context key and local variable rename to match:

- Http::setRequestResource() -&gt; Http::setContext()
- Adapter\Swoole\Server::REQUEST_CONTAINER_CONTEXT_KEY
    -&gt; Adapter\Swoole\Server::CONTEXT_KEY
- same in Adapter\SwooleCoroutine\Server
- $requestContainer locals -&gt; $context
- internal storage key '__utopia_http_request_container'
    -&gt; '__utopia_http_context'

setContext is protected, so this is internal-only — no application API
break. Subclasses overriding the old name need to rename.

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/src/Http/Adapter/Swoole/Server.php b/src/Http/Adapter/Swoole/Server.php
@@ -12,7 +12,7 @@
 class Server extends Adapter
 {
     protected SwooleServer $server;
-    protected const string REQUEST_CONTAINER_CONTEXT_KEY = '__utopia_http_request_container';
+    protected const string CONTEXT_KEY = '__utopia_http_context';
     protected Container $container;
 
     /**
@@ -28,11 +28,11 @@ public function __construct(string $host, ?string $port = null, array $settings
     public function onRequest(callable $callback): void
     {
         $this->server->on('request', function (SwooleRequest $request, SwooleResponse $response) use ($callback) {
-            $requestContainer = new Container($this->container);
-            $requestContainer->set('swooleRequest', fn() => $request);
-            $requestContainer->set('swooleResponse', fn() => $response);
+            $context = new Container($this->container);
+            $context->set('swooleRequest', fn() => $request);
+            $context->set('swooleResponse', fn() => $response);
 
-            Coroutine::getContext()[self::REQUEST_CONTAINER_CONTEXT_KEY] = $requestContainer;
+            Coroutine::getContext()[self::CONTEXT_KEY] = $context;
 
             \call_user_func($callback, new Request($request), new Response($response));
         });
@@ -41,7 +41,7 @@ public function onRequest(callable $callback): void
     public function getContainer(): Container
     {
         if (Coroutine::getCid() !== -1) {
-            return Coroutine::getContext()[self::REQUEST_CONTAINER_CONTEXT_KEY] ?? $this->container;
+            return Coroutine::getContext()[self::CONTEXT_KEY] ?? $this->container;
         }
 
         return $this->container;
diff --git a/src/Http/Adapter/SwooleCoroutine/Server.php b/src/Http/Adapter/SwooleCoroutine/Server.php
@@ -11,7 +11,7 @@
 
 class Server extends Adapter
 {
-    protected const string REQUEST_CONTAINER_CONTEXT_KEY = '__utopia_http_request_container';
+    protected const string CONTEXT_KEY = '__utopia_http_context';
 
     protected SwooleServer $server;
     protected Container $container;
@@ -36,23 +36,23 @@ public function __construct(
     public function onRequest(callable $callback): void
     {
         $this->server->handle('/', function (SwooleRequest $request, SwooleResponse $response) use ($callback) {
-            $requestContainer = new Container($this->container);
-            $requestContainer->set('swooleRequest', fn() => $request);
-            $requestContainer->set('swooleResponse', fn() => $response);
+            $context = new Container($this->container);
+            $context->set('swooleRequest', fn() => $request);
+            $context->set('swooleResponse', fn() => $response);
 
-            Coroutine::getContext()[self::REQUEST_CONTAINER_CONTEXT_KEY] = $requestContainer;
+            Coroutine::getContext()[self::CONTEXT_KEY] = $context;
 
             try {
                 \call_user_func($callback, new Request($request), new Response($response));
             } finally {
-                unset(Coroutine::getContext()[self::REQUEST_CONTAINER_CONTEXT_KEY]);
+                unset(Coroutine::getContext()[self::CONTEXT_KEY]);
             }
         });
     }
 
     public function getContainer(): Container
     {
-        return Coroutine::getContext()[self::REQUEST_CONTAINER_CONTEXT_KEY] ?? $this->container;
+        return Coroutine::getContext()[self::CONTEXT_KEY] ?? $this->container;
     }
 
     public function getServer(): SwooleServer
diff --git a/src/Http/Http.php b/src/Http/Http.php
@@ -406,11 +406,17 @@ public function setResource(string $name, callable $callback, array $injections
     }
 
     /**
-     * Set a request-scoped resource on the current request's container.
+     * Set a request-scoped value on the current request's context container.
+     *
+     * The framework convention is: `setResource()` registers singletons on
+     * the global container; `setContext()` registers per-request values on
+     * the adapter's request container, which is coroutine-local under the
+     * Swoole adapters. `getResource()` reads from the request container
+     * with parent-fallback to the global one, so either kind resolves.
      *
      * @param list<string> $injections
      */
-    protected function setRequestResource(string $name, callable $callback, array $injections = []): void
+    protected function setContext(string $name, callable $callback, array $injections = []): void
     {
         $this->server->getContainer()->set($name, $callback, $injections);
     }
@@ -674,7 +680,7 @@ public function execute(Route $route, Request $request, Response $response): sta
                 }
             }
         } catch (\Throwable $e) {
-            $this->setRequestResource('error', fn() => $e, []);
+            $this->setContext('error', fn() => $e, []);
 
             foreach ($groups as $group) {
                 foreach (self::$errors as $error) { // Group error hooks
@@ -793,16 +799,16 @@ private function runInternal(Request $request, Response $response): static
             $response->setCompressionSupported($this->compressionSupported);
         }
 
-        $this->setRequestResource('request', fn() => $request);
-        $this->setRequestResource('response', fn() => $response);
+        $this->setContext('request', fn() => $request);
+        $this->setContext('response', fn() => $response);
 
         try {
             foreach (self::$requestHooks as $hook) {
                 $arguments = $this->getArguments($hook, [], []);
                 \call_user_func_array($hook->getAction(), $arguments);
             }
         } catch (\Exception $e) {
-            $this->setRequestResource('error', fn() => $e, []);
+            $this->setContext('error', fn() => $e, []);
 
             foreach (self::$errors as $error) { // Global error hooks
                 if (\in_array('*', $error->getGroups())) {
@@ -832,7 +838,7 @@ private function runInternal(Request $request, Response $response): static
         $route = $this->match($request);
         $groups = ($route instanceof Route) ? $route->getGroups() : [];
 
-        $this->setRequestResource('route', fn() => $route, []);
+        $this->setContext('route', fn() => $route, []);
 
         if (self::REQUEST_METHOD_HEAD === $method) {
             $method = self::REQUEST_METHOD_GET;
@@ -860,7 +866,7 @@ private function runInternal(Request $request, Response $response): static
                 foreach (self::$errors as $error) { // Global error hooks
                     /** @var Hook $error */
                     if (\in_array('*', $error->getGroups())) {
-                        $this->setRequestResource('error', fn() => $e, []);
+                        $this->setContext('error', fn() => $e, []);
                         \call_user_func_array($error->getAction(), $this->getArguments($error, [], $request->getParams()));
                     }
                 }
@@ -878,7 +884,7 @@ private function runInternal(Request $request, Response $response): static
             $route->path($path);
 
             $this->setRoute($route);
-            $this->setRequestResource('route', fn() => $route, []);
+            $this->setContext('route', fn() => $route, []);
         }
         if (null !== $route) {
             return $this->execute($route, $request, $response);
@@ -902,15 +908,15 @@ private function runInternal(Request $request, Response $response): static
             } catch (\Throwable $e) {
                 foreach (self::$errors as $error) { // Global error hooks
                     if (\in_array('*', $error->getGroups())) {
-                        $this->setRequestResource('error', fn() => $e, []);
+                        $this->setContext('error', fn() => $e, []);
                         \call_user_func_array($error->getAction(), $this->getArguments($error, [], $request->getParams()));
                     }
                 }
             }
         } else {
             foreach (self::$errors as $error) { // Global error hooks
                 if (\in_array('*', $error->getGroups())) {
-                    $this->setRequestResource('error', fn() => new Exception('Not Found', 404), []);
+                    $this->setContext('error', fn() => new Exception('Not Found', 404), []);
                     \call_user_func_array($error->getAction(), $this->getArguments($error, [], $request->getParams()));
                 }
             }

Original file line number	Diff line number	Diff line change
`@@ -11,7 +11,7 @@`
`11`	`11`
`12`	`12`	`class Server extends Adapter`
`13`	`13`	`{`
`14`		`- protected const string REQUEST_CONTAINER_CONTEXT_KEY = '__utopia_http_request_container';`
	`14`	`+ protected const string CONTEXT_KEY = '__utopia_http_context';`
`15`	`15`
`16`	`16`	`protected SwooleServer $server;`
`17`	`17`	`protected Container $container;`
`@@ -36,23 +36,23 @@ public function __construct(`
`36`	`36`	`public function onRequest(callable $callback): void`
`37`	`37`	`{`
`38`	`38`	`$this->server->handle('/', function (SwooleRequest $request, SwooleResponse $response) use ($callback) {`
`39`		`- $requestContainer = new Container($this->container);`
`40`		`- $requestContainer->set('swooleRequest', fn() => $request);`
`41`		`- $requestContainer->set('swooleResponse', fn() => $response);`
	`39`	`+ $context = new Container($this->container);`
	`40`	`+ $context->set('swooleRequest', fn() => $request);`
	`41`	`+ $context->set('swooleResponse', fn() => $response);`
`42`	`42`
`43`		`- Coroutine::getContext()[self::REQUEST_CONTAINER_CONTEXT_KEY] = $requestContainer;`
	`43`	`+ Coroutine::getContext()[self::CONTEXT_KEY] = $context;`
`44`	`44`
`45`	`45`	`try {`
`46`	`46`	`\call_user_func($callback, new Request($request), new Response($response));`
`47`	`47`	`} finally {`
`48`		`- unset(Coroutine::getContext()[self::REQUEST_CONTAINER_CONTEXT_KEY]);`
	`48`	`+ unset(Coroutine::getContext()[self::CONTEXT_KEY]);`
`49`	`49`	`}`
`50`	`50`	`});`
`51`	`51`	`}`
`52`	`52`
`53`	`53`	`public function getContainer(): Container`
`54`	`54`	`{`
`55`		`- return Coroutine::getContext()[self::REQUEST_CONTAINER_CONTEXT_KEY] ?? $this->container;`
	`55`	`+ return Coroutine::getContext()[self::CONTEXT_KEY] ?? $this->container;`
`56`	`56`	`}`
`57`	`57`
`58`	`58`	`public function getServer(): SwooleServer`
Original file line number	Diff line number	Diff line change
`@@ -406,11 +406,17 @@ public function setResource(string $name, callable $callback, array $injections`
`406`	`406`	`}`
`407`	`407`
`408`	`408`	`/**`
`409`		`- * Set a request-scoped resource on the current request's container.`
	`409`	`+ * Set a request-scoped value on the current request's context container.`
	`410`	`+ *`
	`411`	+ * The framework convention is: `setResource()` registers singletons on
	`412`	+ * the global container; `setContext()` registers per-request values on
	`413`	`+ * the adapter's request container, which is coroutine-local under the`
	`414`	+ * Swoole adapters. `getResource()` reads from the request container
	`415`	`+ * with parent-fallback to the global one, so either kind resolves.`
`410`	`416`	`*`
`411`	`417`	`* @param list<string> $injections`
`412`	`418`	`*/`
`413`		`- protected function setRequestResource(string $name, callable $callback, array $injections = []): void`
	`419`	`+ protected function setContext(string $name, callable $callback, array $injections = []): void`
`414`	`420`	`{`
`415`	`421`	`$this->server->getContainer()->set($name, $callback, $injections);`
`416`	`422`	`}`
`@@ -674,7 +680,7 @@ public function execute(Route $route, Request $request, Response $response): sta`
`674`	`680`	`}`
`675`	`681`	`}`
`676`	`682`	`} catch (\Throwable $e) {`
`677`		`- $this->setRequestResource('error', fn() => $e, []);`
	`683`	`+ $this->setContext('error', fn() => $e, []);`
`678`	`684`
`679`	`685`	`foreach ($groups as $group) {`
`680`	`686`	`foreach (self::$errors as $error) { // Group error hooks`
`@@ -793,16 +799,16 @@ private function runInternal(Request $request, Response $response): static`
`793`	`799`	`$response->setCompressionSupported($this->compressionSupported);`
`794`	`800`	`}`
`795`	`801`
`796`		`- $this->setRequestResource('request', fn() => $request);`
`797`		`- $this->setRequestResource('response', fn() => $response);`
	`802`	`+ $this->setContext('request', fn() => $request);`
	`803`	`+ $this->setContext('response', fn() => $response);`
`798`	`804`
`799`	`805`	`try {`
`800`	`806`	`foreach (self::$requestHooks as $hook) {`
`801`	`807`	`$arguments = $this->getArguments($hook, [], []);`
`802`	`808`	`\call_user_func_array($hook->getAction(), $arguments);`
`803`	`809`	`}`
`804`	`810`	`} catch (\Exception $e) {`
`805`		`- $this->setRequestResource('error', fn() => $e, []);`
	`811`	`+ $this->setContext('error', fn() => $e, []);`
`806`	`812`
`807`	`813`	`foreach (self::$errors as $error) { // Global error hooks`
`808`	`814`	`if (\in_array('*', $error->getGroups())) {`
`@@ -832,7 +838,7 @@ private function runInternal(Request $request, Response $response): static`
`832`	`838`	`$route = $this->match($request);`
`833`	`839`	`$groups = ($route instanceof Route) ? $route->getGroups() : [];`
`834`	`840`
`835`		`- $this->setRequestResource('route', fn() => $route, []);`
	`841`	`+ $this->setContext('route', fn() => $route, []);`
`836`	`842`
`837`	`843`	`if (self::REQUEST_METHOD_HEAD === $method) {`
`838`	`844`	`$method = self::REQUEST_METHOD_GET;`
`@@ -860,7 +866,7 @@ private function runInternal(Request $request, Response $response): static`
`860`	`866`	`foreach (self::$errors as $error) { // Global error hooks`
`861`	`867`	`/** @var Hook $error */`
`862`	`868`	`if (\in_array('*', $error->getGroups())) {`
`863`		`- $this->setRequestResource('error', fn() => $e, []);`
	`869`	`+ $this->setContext('error', fn() => $e, []);`
`864`	`870`	`\call_user_func_array($error->getAction(), $this->getArguments($error, [], $request->getParams()));`
`865`	`871`	`}`
`866`	`872`	`}`
`@@ -878,7 +884,7 @@ private function runInternal(Request $request, Response $response): static`
`878`	`884`	`$route->path($path);`
`879`	`885`
`880`	`886`	`$this->setRoute($route);`
`881`		`- $this->setRequestResource('route', fn() => $route, []);`
	`887`	`+ $this->setContext('route', fn() => $route, []);`
`882`	`888`	`}`
`883`	`889`	`if (null !== $route) {`
`884`	`890`	`return $this->execute($route, $request, $response);`
`@@ -902,15 +908,15 @@ private function runInternal(Request $request, Response $response): static`
`902`	`908`	`} catch (\Throwable $e) {`
`903`	`909`	`foreach (self::$errors as $error) { // Global error hooks`
`904`	`910`	`if (\in_array('*', $error->getGroups())) {`
`905`		`- $this->setRequestResource('error', fn() => $e, []);`
	`911`	`+ $this->setContext('error', fn() => $e, []);`
`906`	`912`	`\call_user_func_array($error->getAction(), $this->getArguments($error, [], $request->getParams()));`
`907`	`913`	`}`
`908`	`914`	`}`
`909`	`915`	`}`
`910`	`916`	`} else {`
`911`	`917`	`foreach (self::$errors as $error) { // Global error hooks`
`912`	`918`	`if (\in_array('*', $error->getGroups())) {`
`913`		`- $this->setRequestResource('error', fn() => new Exception('Not Found', 404), []);`
	`919`	`+ $this->setContext('error', fn() => new Exception('Not Found', 404), []);`
`914`	`920`	`\call_user_func_array($error->getAction(), $this->getArguments($error, [], $request->getParams()));`
`915`	`921`	`}`
`916`	`922`	`}`