Add globals provider component

Author: SerafimArts

Writerside/boson.tree

@@ -55,6 +55,7 @@
         <toc-element topic="cpu-info.md" />
         <toc-element topic="weak-types.md" />
         <toc-element topic="static-files.md" />
+        <toc-element topic="globals-provider.md" />
     </toc-element>
     <toc-element toc-title="Integrations">
         <toc-element topic="symfony-adapter.md"

Writerside/topics/components/globals-provider.md

@@ -0,0 +1,163 @@
+# PHP Globals Provider
+
+<show-structure for="chapter" depth="2"/>
+
+The component provides the ability to manage global PHP variables and 
+obtain their state depending on WebView requests.
+
+## Installation
+
+<tldr>
+    <p>
+        Via <a href="https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies">Composer</a>:
+    </p>
+    <p>
+        <code lang="bash">composer require boson-php/globals-provider</code>
+    </p>
+</tldr>
+
+**Requirements:**
+
+* `PHP ^8.4`
+
+## Usage
+
+The component provides several implementations of 
+`ServerGlobalsProviderInterface` for managing PHP `$_SERVER` superglobals:
+
+### DefaultServerGlobalsProvider
+
+The default provider that handles basic request-aware parameters:
+
+```php
+use Boson\Component\GlobalsProvider\DefaultServerGlobalsProvider;
+use Boson\Component\Http\Request;
+
+$provider = new DefaultServerGlobalsProvider();
+
+$globals = $provider->getServerGlobals(new Request(
+    method: 'POST',
+    url: 'https://example.com/path?query=value',
+    headers: ['Host' => 'example.com']
+));
+
+//
+// Expected output:
+//
+// array:9 [
+//   "REQUEST_TIME_FLOAT" => 1749130915.4316
+//   "REQUEST_TIME" => 1749130915
+//   "REQUEST_METHOD" => "POST"
+//   "QUERY_STRING" => "query=value"
+//   "PATH_INFO" => "/path"
+//   "REMOTE_ADDR" => "example.com"
+//   "REMOTE_PORT" => 80
+//   "REQUEST_URI" => "/path?query=value"
+//   "HTTP_HOST" => "example.com"
+// ]
+//
+```
+
+This provider automatically sets request-dependent variables:
+- Request time parameters (`REQUEST_TIME`, `REQUEST_TIME_FLOAT`)
+- Request information (`REQUEST_METHOD`, `REQUEST_URI`, `HTTP_HOST`, etc.)
+- Request headers (converted to uppercase with `HTTP_` prefix)
+
+#### PSR-20 Clock
+
+The `DefaultServerGlobalsProvider` supports custom time handling 
+through PSR-20 Clock interface:
+
+```php
+use Boson\Component\GlobalsProvider\DefaultServerGlobalsProvider;
+use Psr\Clock\ClockInterface;
+
+class CustomClock implements ClockInterface
+{
+    public function now(): \DateTimeImmutable
+    {
+        return new \DateTimeImmutable('2024-01-01 12:00:00');
+    }
+}
+
+$provider = new DefaultServerGlobalsProvider(
+    clock: new CustomClock(),
+);
+```
+
+The PSR-20 Clock component is used to generate the `REQUEST_TIME` 
+and `REQUEST_TIME_FLOAT` parameters.
+
+```php
+[ 
+    "REQUEST_TIME_FLOAT" => 1749130915.4316,
+    "REQUEST_TIME" => 1749130915,
+    // ...
+]
+```
+
+This allows for consistent time-based testing and custom time 
+handling in your application.
+
+### StaticServerGlobalsProvider
+
+Provides constant server parameters that are independent of the request:
+
+```php
+use Boson\Component\GlobalsProvider\StaticServerGlobalsProvider;
+
+// With default superglobal $_SERVER values
+$provider = new StaticServerGlobalsProvider();
+
+// Or with custom values
+$provider = new StaticServerGlobalsProvider([
+    'DOCUMENT_ROOT' => '/custom/root',
+    'SERVER_NAME' => 'example.com',
+    'SERVER_PORT' => '8080',
+    'SERVER_SOFTWARE' => 'Custom Server'
+]);
+```
+
+The provider ensures:
+- Valid document root (from `SCRIPT_FILENAME` or `DOCUMENT_ROOT`)
+- Default server name (`SERVER_NAME`)
+- Default server port (`SERVER_PORT`)
+- Default server software (`SERVER_SOFTWARE`)
+- etc...
+
+### CompoundServerGlobalsProvider
+
+Combines multiple providers into a single one:
+
+```php
+use Boson\Component\GlobalsProvider\CompoundServerGlobalsProvider;
+use Boson\Component\GlobalsProvider\DefaultServerGlobalsProvider;
+use Boson\Component\GlobalsProvider\StaticServerGlobalsProvider;
+
+$providers = [
+    // PHP default $_SERVER superglobals provider
+    new StaticServerGlobalsProvider(),
+    // Request-aware $_SERVER superglobals provider
+    new DefaultServerGlobalsProvider(),
+    // Custom superglobals provider
+    new StaticServerGlobalsProvider([
+        'SERVER_SOFTWARE' => 'Custom Server'
+    ]),
+];
+
+$provider = new CompoundServerGlobalsProvider($providers);
+```
+
+The compound provider merges results from all providers in the order they 
+are provided. Later providers can override values from earlier ones.
+
+### EmptyServerGlobalsProvider
+
+A simple provider that returns an empty array of server globals:
+
+```php
+use Boson\Component\GlobalsProvider\EmptyServerGlobalsProvider;
+
+$provider = new EmptyServerGlobalsProvider();
+$globals = $provider->getServerGlobals($request); // Returns []
+```