feat: Improve Superglobals service

system/HTTP/Parameters/InputParameters.php

@@ -0,0 +1,64 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of CodeIgniter 4 framework.
+ *
+ * (c) CodeIgniter Foundation <[email protected]>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace CodeIgniter\HTTP\Parameters;
+
+use CodeIgniter\Exceptions\InvalidArgumentException;
+use CodeIgniter\Exceptions\RuntimeException;
+
+/**
+ * @template TKey of string
+ * @template TValue of scalar|array<(int|string), mixed>
+ *
+ * @extends Parameters<TKey, TValue>
+ *
+ * @see \CodeIgniter\HTTP\Parameters\InputParametersTest
+ */
+class InputParameters extends Parameters
+{
+    public function override(array $parameters = []): void
+    {
+        $this->parameters = [];
+
+        foreach ($parameters as $key => $value) {
+            $this->set($key, $value);
+        }
+    }
+
+    public function get(string $key, mixed $default = null): mixed
+    {
+        if ($default !== null && ! is_scalar($default)) {
+            throw new InvalidArgumentException(sprintf('The default value for the InputParameters must be a scalar type, "%s" given.', gettype($default)));
+        }
+
+        // TODO: We need to check that the default value is set. Let's check the unique string
+        $tempDefault = bin2hex(random_bytes(8));
+
+        $value = parent::get($key, $tempDefault);
+
+        if ($value !== null && $value !== $tempDefault && ! is_scalar($value)) {
+            throw new RuntimeException(sprintf('The value of the key "%s" InputParameters does not contain a scalar value, "%s" given.', $key, gettype($value)));
+        }
+
+        return $value === $tempDefault ? $default : $value;
+    }
+
+    public function set(string $key, mixed $value): void
+    {
+        if (! is_scalar($value) && ! is_array($value)) {
+            throw new InvalidArgumentException(sprintf('The value for the InputParameters must be a scalar type, "%s" given.', gettype($value)));
+        }
+
+        $this->parameters[$key] = $value;
+    }
+}

system/HTTP/Parameters/Parameters.php

@@ -0,0 +1,89 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of CodeIgniter 4 framework.
+ *
+ * (c) CodeIgniter Foundation <[email protected]>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace CodeIgniter\HTTP\Parameters;
+
+use ArrayIterator;
+use CodeIgniter\Exceptions\RuntimeException;
+
+/**
+ * @template TKey of string
+ * @template TValue
+ *
+ * @implements ParametersInterface<TKey, TValue>
+ *
+ * @see \CodeIgniter\HTTP\Parameters\ParametersTest
+ */
+class Parameters implements ParametersInterface
+{
+    /**
+     * @param array<TKey, TValue> $parameters
+     */
+    public function __construct(
+        protected array $parameters = [],
+    ) {
+    }
+
+    public function override(array $parameters = []): void
+    {
+        $this->parameters = $parameters;
+    }
+
+    public function has(string $key): bool
+    {
+        return array_key_exists($key, $this->parameters);
+    }
+
+    public function get(string $key, mixed $default = null): mixed
+    {
+        return array_key_exists($key, $this->parameters) ? $this->parameters[$key] : $default;
+    }
+
+    public function set(string $key, mixed $value): void
+    {
+        $this->parameters[$key] = $value;
+    }
+
+    public function remove(string $key): void
+    {
+        unset($this->parameters[$key]);
+    }
+
+    public function all(?string $key = null): array
+    {
+        if ($key === null) {
+            return $this->parameters;
+        }
+
+        if (! isset($this->parameters[$key]) || ! is_array($this->parameters[$key])) {
+            throw new RuntimeException(sprintf('The key "%s" value for Parameters is not an array or was not found.', $key));
+        }
+
+        return $this->parameters[$key];
+    }
+
+    public function keys(): array
+    {
+        return array_keys($this->parameters);
+    }
+
+    public function getIterator(): ArrayIterator
+    {
+        return new ArrayIterator($this->parameters);
+    }
+
+    public function count(): int
+    {
+        return count($this->parameters);
+    }
+}

system/HTTP/Parameters/ParametersInterface.php

@@ -0,0 +1,67 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of CodeIgniter 4 framework.
+ *
+ * (c) CodeIgniter Foundation <[email protected]>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace CodeIgniter\HTTP\Parameters;
+
+use Countable;
+use IteratorAggregate;
+
+/**
+ * @template TKey of string
+ * @template TValue
+ *
+ * @extends IteratorAggregate<TKey, TValue>
+ */
+interface ParametersInterface extends IteratorAggregate, Countable
+{
+    /**
+     * @param array<TKey, TValue> $parameters
+     */
+    public function __construct(array $parameters = []);
+
+    /**
+     * @param array<TKey, TValue> $parameters
+     */
+    public function override(array $parameters = []): void;
+
+    /**
+     * @param TKey $key
+     */
+    public function has(string $key): bool;
+
+    /**
+     * @param TKey   $key
+     * @param TValue $default
+     *
+     * @return TValue|null
+     */
+    public function get(string $key, mixed $default = null): mixed;
+
+    /**
+     * @param TKey   $key
+     * @param TValue $value
+     */
+    public function set(string $key, mixed $value): void;
+
+    /**
+     * @param TKey $key
+     *
+     * @return array<TKey, TValue>
+     */
+    public function all(?string $key = null): array;
+
+    /**
+     * @return list<TKey>
+     */
+    public function keys(): array;
+}

system/HTTP/Parameters/ServerParameters.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of CodeIgniter 4 framework.
+ *
+ * (c) CodeIgniter Foundation <[email protected]>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace CodeIgniter\HTTP\Parameters;
+
+/**
+ * @template TKey of string
+ * @template TValue
+ *
+ * @extends Parameters<TKey, TValue>
+ */
+class ServerParameters extends Parameters
+{
+}

tests/system/HTTP/Parameters/InputParametersTest.php

@@ -0,0 +1,107 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of CodeIgniter 4 framework.
+ *
+ * (c) CodeIgniter Foundation <[email protected]>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace CodeIgniter\HTTP\Parameters;
+
+use CodeIgniter\Exceptions\InvalidArgumentException;
+use CodeIgniter\Test\CIUnitTestCase;
+use PHPUnit\Framework\Attributes\Group;
+use stdClass;
+
+/**
+ * @internal
+ */
+#[Group('Others')]
+final class InputParametersTest extends CIUnitTestCase
+{
+    /**
+     * @var array<string, mixed>
+     */
+    private array $original = [
+        'title'        => '',
+        'toolbar'      => '1',
+        'path'         => 'public/index.php',
+        'current_time' => 1741522635.661474,
+        'debug'        => true,
+        'pages'        => 15,
+        'filters'      => [
+            0 => 'name',
+            1 => 'sum',
+        ],
+        'sort' => [
+            'date' => 'ASC',
+            'age'  => 'DESC',
+        ],
+    ];
+
+    public function testGetNonScalarValues(): void
+    {
+        $parameters = new InputParameters($this->original);
+
+        $this->assertNull($parameters->get('undefined_or_null', null));
+
+        $this->expectException(InvalidArgumentException::class);
+
+        $parameters->get('undefined_throw', new stdClass()); // @phpstan-ignore argument.type
+    }
+
+    public function testAttemptSetNullValues(): void
+    {
+        $parameters = new InputParameters($this->original);
+
+        $this->expectException(InvalidArgumentException::class);
+
+        $parameters->set('nullable', null); // @phpstan-ignore argument.type
+    }
+
+    public function testAttemptSetNonScalarValues(): void
+    {
+        $parameters = new InputParameters($this->original);
+
+        $this->expectException(InvalidArgumentException::class);
+
+        $parameters->set('nullable', new stdClass()); // @phpstan-ignore argument.type
+    }
+
+    public function testUpdateAndSetNewValues(): void
+    {
+        /**
+         * @var array<string, mixed>
+         */
+        $expected = [
+            'title'        => 'CodeIgniter',
+            'toolbar'      => '0',
+            'path'         => '',
+            'current_time' => 1741522888.661434,
+            'debug'        => false,
+            'pages'        => 10,
+            'filters'      => [
+                0 => 'sum',
+                1 => 'name',
+            ],
+            'sort' => [
+                'age'  => 'ASC',
+                'date' => 'DESC',
+            ],
+            'slug' => 'Ben-i-need-help',
+        ];
+
+        $parameters = new InputParameters($this->original);
+
+        foreach (array_keys($expected) as $key) {
+            $parameters->set($key, $expected[$key]);
+        }
+
+        $this->assertSame($expected, $parameters->all());
+    }
+}