├── .github
    └── workflows
    │   └── ci.yml
├── .gitignore
├── README.md
├── composer.json
├── global
    ├── autoloader.php
    ├── bool-array.php
    ├── double-array.php
    ├── float-array.php
    ├── functions.php
    ├── int-array.php
    └── string-array.php
├── phpunit.xml
├── psalm.xml
├── src
    ├── AbstractTypedArray.php
    ├── BoolArray.php
    ├── FloatArray.php
    ├── IntArray.php
    ├── ObjectTypedArray.php
    └── StringArray.php
└── tests
    └── BasicTest.php


/.github/workflows/ci.yml:
--------------------------------------------------------------------------------
 1 | name: CI
 2 | 
 3 | on: [push]
 4 | 
 5 | jobs:
 6 |   phpunit:
 7 |     name: PHP ${{ matrix.php-versions }} Test on ${{ matrix.operating-system }}
 8 |     runs-on: ${{ matrix.operating-system }}
 9 |     strategy:
10 |       matrix:
11 |         operating-system: ['ubuntu-latest']
12 |         php-versions: ['8.3', '8.4']
13 | 
14 |     steps:
15 |       - name: Checkout
16 |         uses: actions/checkout@v4
17 | 
18 |       - name: Setup PHP
19 |         uses: shivammathur/setup-php@v2
20 |         with:
21 |           php-version: ${{ matrix.php-versions }}
22 |           extensions: mbstring, intl, sodium
23 |           ini-values: error_reporting=-1, display_errors=On
24 |           coverage: none
25 | 
26 |       - name: Install Composer dependencies
27 |         uses: "ramsey/composer-install@v2"
28 | 
29 |       - name: PHPUnit tests
30 |         run: vendor/bin/phpunit
31 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | /.idea
2 | /vendor
3 | /composer.lock
4 | /composer.phar
5 | /.phpunit.cache
6 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # Strictly Typed Arrays in PHP 8
  2 | 
  3 | [![Build Status](https://github.com/paragonie/typed-arrays/actions/workflows/ci.yml/badge.svg)](https://github.com/paragonie/typed-arrays/actions)
  4 | [![Latest Stable Version](https://poser.pugx.org/paragonie/typed-arrays/v/stable)](https://packagist.org/packages/paragonie/typed-arrays)
  5 | [![Latest Unstable Version](https://poser.pugx.org/paragonie/typed-arrays/v/unstable)](https://packagist.org/packages/paragonie/typed-arrays)
  6 | [![License](https://poser.pugx.org/paragonie/typed-arrays/license)](https://packagist.org/packages/paragonie/typed-arrays)
  7 | [![Downloads](https://img.shields.io/packagist/dt/paragonie/typed-arrays.svg)](https://packagist.org/packages/paragonie/typed-arrays)
  8 | 
  9 | **Requires PHP 8.3**. This is best described through example:
 10 | 
 11 | ```php
 12 | <?php
 13 | require_once 'vendor/autoload.php';
 14 | 
 15 | class Foo
 16 | {
 17 |     public function __construct(
 18 |         public readonly string⟦⟧ $foo,
 19 |         public readonly int⟦⟧ $bar
 20 |     ) {}
 21 | }
 22 | 
 23 | $x = new Foo(
 24 |     string⟦⟧('apple', 'bee'),
 25 |     int⟦⟧(4, 5, 120000),
 26 | );
 27 | var_dump($x->foo, $x->bar);
 28 | var_dump($x->foo[1]);
 29 | ```
 30 | 
 31 | This should output the following:
 32 | 
 33 | ```
 34 | object(string⟦⟧)#5 (2) {
 35 |   [0]=>
 36 |   string(5) "apple"
 37 |   [1]=>
 38 |   string(3) "bee"
 39 | }
 40 | object(int⟦⟧)#6 (3) {
 41 |   [0]=>
 42 |   int(4)
 43 |   [1]=>
 44 |   int(5)
 45 |   [2]=>
 46 |   int(120000)
 47 | }
 48 | string(3) "bee"
 49 | ```
 50 | 
 51 | If you try to pass an incorrect type, you'll get a `TypeError`:
 52 | 
 53 | ```php
 54 | <?php
 55 | declare(strict_types=1);
 56 | require_once 'vendor/autoload.php';
 57 | 
 58 | class Foo
 59 | {
 60 |     public function __construct(
 61 |         public readonly string⟦⟧ $foo
 62 |     ) {}
 63 | }
 64 | 
 65 | $x = new Foo(
 66 |     string⟦⟧('apple', 'bee', 25)
 67 | );
 68 | var_dump($x->foo, $x->bar);
 69 | ```
 70 | 
 71 | Should produce:
 72 | 
 73 | ```terminal
 74 | Fatal error: Uncaught TypeError: string⟦⟧(): Argument #3 must be of type string, int given
 75 | ```
 76 | 
 77 | ## What Is This Package Doing?
 78 | 
 79 | We are using Unicode characters (`⟦` and `⟧`) to create a class that implements `ArrayAccess`.
 80 | All arguments to these types are then strictly typed.
 81 | 
 82 | In effect, we have turned a class into a typed array that your IDE will not complain about.
 83 | 
 84 | ## Does It Support Multi-Level Types? e.g. `string⟦⟧⟦⟧`
 85 | 
 86 | You betcha.
 87 | 
 88 | ```php
 89 | <?php
 90 | declare(strict_types=1);
 91 | require_once 'vendor/autoload.php';
 92 | 
 93 | class Bar
 94 | {
 95 |     public function __construct(
 96 |         public readonly string⟦⟧⟦⟧ $double,
 97 |     ) {}
 98 | }
 99 | 
100 | $test = new Bar(string⟦⟧⟦⟧(
101 |     string⟦⟧('test'),
102 |     string⟦⟧('example'),
103 | ));
104 | var_dump($test->double);
105 | ```
106 | 
107 | This will produce:
108 | 
109 | ```terminal
110 | object(string⟦⟧⟦⟧)#7 (2) {
111 |   [0]=>
112 |   object(string⟦⟧)#5 (1) {
113 |     [0]=>
114 |     string(4) "test"
115 |   }
116 |   [1]=>
117 |   object(string⟦⟧)#6 (1) {
118 |     [0]=>
119 |     string(7) "example"
120 |   }
121 | }
122 | ```
123 | 
124 | ## Does This Support Arrays of Classes?
125 | 
126 | Of course!
127 | 
128 | ```php
129 | <?php
130 | declare(strict_types=1);
131 | require_once 'vendor/autoload.php';
132 | 
133 | class Foo {}
134 | 
135 | class Bar
136 | {
137 |     public function __construct(
138 |         public readonly Foo⟦⟧ $example
139 |     ) {}
140 | }
141 | 
142 | $test = new Bar(new Foo⟦⟧(new Foo));
143 | var_dump($test);
144 | ```
145 | 
146 | Output:
147 | 
148 | ```terminal
149 | object(Bar)#2 (1) {
150 |   ["example"]=>
151 |   object(Foo⟦⟧)#5 (1) {
152 |     [0]=>
153 |     object(Foo)#6 (0) {
154 |     }
155 |   }
156 | }
157 | ```
158 | 
159 | ### How Does This Create Types for My Classes?
160 | 
161 | See: [the autoloader](global/autoloader.php).
162 | 
163 | 


--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "paragonie/typed-arrays",
 3 |   "description": "Strictly typed scalar arrays for PHP 8.3 and newer",
 4 |   "keywords": [
 5 |     "typed arrays",
 6 |     "strict typing",
 7 |     "scalar types"
 8 |   ],
 9 |   "license": "ISC",
10 |   "authors": [
11 |     {
12 |       "name": "Paragon Initiative Enterprises, LLC",
13 |       "email": "security@paragonie.com",
14 |       "homepage": "https://paragonie.com"
15 |     }
16 |   ],
17 |   "autoload": {
18 |     "psr-4": {
19 |       "ParagonIE\\TypedArrays\\": "src"
20 |     },
21 |     "files": ["global/autoloader.php"]
22 |   },
23 |   "autoload-dev": {
24 |     "psr-4": {
25 |       "ParagonIE\\TypedArrays\\Tests\\": "tests"
26 |     }
27 |   },
28 |   "require": {
29 |     "php": "^8.3"
30 |   },
31 |   "require-dev": {
32 |     "phpunit/phpunit": "^9",
33 |     "vimeo/psalm": "^4"
34 |   }
35 | }


--------------------------------------------------------------------------------
/global/autoloader.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | declare(strict_types=1);
 3 | 
 4 | use ParagonIE\TypedArrays\ObjectTypedArray;
 5 | 
 6 | // Load all the wrappers for scalar type
 7 | require_once __DIR__ . '/bool-array.php';
 8 | require_once __DIR__ . '/float-array.php';
 9 | require_once __DIR__ . '/int-array.php';
10 | require_once __DIR__ . '/string-array.php';
11 | require_once __DIR__ . '/double-array.php';
12 | require_once __DIR__ . '/functions.php';
13 | 
14 | spl_autoload_register(function (string $class_name) {
15 |     /* Security note: This will not allow escape characters, so the eval() below should be ok. */
16 |     if (!preg_match('#([A-Za-z0-9\\\\]+)(⟦⟧+)$#', $class_name, $m)) {
17 |         // We are only interested in autoloading typed arrays
18 |         return false;
19 |     }
20 |     switch ($m[1]) {
21 |         case 'string':
22 |         case 'int':
23 |         case 'float':
24 |         case 'bool':
25 |             // These wre autoloaded above!
26 |             return false;
27 |         default:
28 |             if (!class_exists($m[1]) && !interface_exists($m[1])) {
29 |                 return false;
30 |             }
31 |     }
32 | 
33 |     // Okay, now let's generate the type container at runtime.
34 |     $depth = mb_str_split($m[2], 2, 'utf-8');
35 |     $composite = $m[1];
36 |     for ($i = 0; $i < count($depth); ++$i) {
37 |         if (!class_exists($composite . '⟦⟧', false)) {
38 |             // Class definition
39 |             $exec = "class {$composite}⟦⟧ extends " . ObjectTypedArray::class .
40 |                 "\n{\n" .
41 |                 "    protected const string OBJECT_TYPE = '{$composite}';\n" .
42 |                 "}\n\n";
43 |             // Function helper
44 |             $exec .= "function {$composite}⟦⟧({$composite} ...\$args): {$composite}⟦⟧\n" .
45 |                 "{\n" .
46 |                 "    return new {$composite}⟦⟧(...\$args);\n" .
47 |                 "}\n\n";
48 |             /* We may want to consider dumping to a file instead of just executing. */
49 |             eval($exec);
50 |         }
51 |         $composite .= '⟦⟧';
52 |     }
53 |     // For performance, you're going to want to use opcache
54 |     return true;
55 | });
56 | 


--------------------------------------------------------------------------------
/global/bool-array.php:
--------------------------------------------------------------------------------
1 | <?php
2 | declare(strict_types=1);
3 | use ParagonIE\TypedArrays\BoolArray;
4 | 
5 | class bool⟦⟧ extends BoolArray
6 | {}
7 | 
8 | 


--------------------------------------------------------------------------------
/global/double-array.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | declare(strict_types=1);
 3 | use ParagonIE\TypedArrays\ObjectTypedArray;
 4 | 
 5 | class bool⟦⟧⟦⟧ extends ObjectTypedArray
 6 | {
 7 |     protected const string OBJECT_TYPE = 'bool⟦⟧';
 8 | }
 9 | 
10 | class float⟦⟧⟦⟧ extends ObjectTypedArray
11 | {
12 |     protected const string OBJECT_TYPE = 'float⟦⟧';
13 | }
14 | 
15 | class int⟦⟧⟦⟧ extends ObjectTypedArray
16 | {
17 |     protected const string OBJECT_TYPE = 'int⟦⟧';
18 | }
19 | 
20 | class string⟦⟧⟦⟧ extends ObjectTypedArray
21 | {
22 |     protected const string OBJECT_TYPE = 'string⟦⟧';
23 | }
24 | 


--------------------------------------------------------------------------------
/global/float-array.php:
--------------------------------------------------------------------------------
1 | <?php
2 | declare(strict_types=1);
3 | use ParagonIE\TypedArrays\FloatArray;
4 | 
5 | class float⟦⟧ extends FloatArray
6 | {}
7 | 


--------------------------------------------------------------------------------
/global/functions.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | declare(strict_types=1);
 3 | 
 4 | function bool⟦⟧(bool ...$args): bool⟦⟧
 5 | {
 6 |     return new bool⟦⟧(...$args);
 7 | }
 8 | 
 9 | 
10 | function float⟦⟧(float ...$args): float⟦⟧
11 | {
12 |     return new float⟦⟧(...$args);
13 | }
14 | 
15 | function int⟦⟧(int ...$args): int⟦⟧
16 | {
17 |     return new int⟦⟧(...$args);
18 | }
19 | 
20 | function string⟦⟧(string ...$args): string⟦⟧
21 | {
22 |     return new string⟦⟧(...$args);
23 | }
24 | 
25 | // Second level deep:
26 | 
27 | function bool⟦⟧⟦⟧(bool⟦⟧ ...$args): bool⟦⟧⟦⟧
28 | {
29 |     return new bool⟦⟧⟦⟧(...$args);
30 | }
31 | 
32 | 
33 | function float⟦⟧⟦⟧(float⟦⟧ ...$args): float⟦⟧⟦⟧
34 | {
35 |     return new float⟦⟧⟦⟧(...$args);
36 | }
37 | 
38 | 
39 | function int⟦⟧⟦⟧(int⟦⟧ ...$args): int⟦⟧⟦⟧
40 | {
41 |     return new int⟦⟧⟦⟧(...$args);
42 | }
43 | 
44 | function string⟦⟧⟦⟧(string⟦⟧ ...$args): string⟦⟧⟦⟧
45 | {
46 |     return new string⟦⟧⟦⟧(...$args);
47 | }
48 | 


--------------------------------------------------------------------------------
/global/int-array.php:
--------------------------------------------------------------------------------
1 | <?php
2 | declare(strict_types=1);
3 | use ParagonIE\TypedArrays\IntArray;
4 | 
5 | class int⟦⟧ extends IntArray
6 | {}
7 | 
8 | 


--------------------------------------------------------------------------------
/global/string-array.php:
--------------------------------------------------------------------------------
1 | <?php
2 | declare(strict_types=1);
3 | use ParagonIE\TypedArrays\StringArray;
4 | 
5 | class string⟦⟧ extends StringArray
6 | {}
7 | 


--------------------------------------------------------------------------------
/phpunit.xml:
--------------------------------------------------------------------------------
 1 | <?xml version="1.0" encoding="UTF-8"?>
 2 | <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 3 |          xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.6/phpunit.xsd"
 4 |          bootstrap="vendor/autoload.php"
 5 |          cacheResultFile=".phpunit.cache/test-results"
 6 |          executionOrder="depends,defects"
 7 |          forceCoversAnnotation="true"
 8 |          beStrictAboutCoversAnnotation="true"
 9 |          beStrictAboutOutputDuringTests="true"
10 |          beStrictAboutTodoAnnotatedTests="true"
11 |          convertDeprecationsToExceptions="true"
12 |          failOnRisky="true"
13 |          failOnWarning="true"
14 |          verbose="true">
15 |     <testsuites>
16 |         <testsuite name="default">
17 |             <directory>tests</directory>
18 |         </testsuite>
19 |     </testsuites>
20 | 
21 |     <coverage cacheDirectory=".phpunit.cache/code-coverage"
22 |               processUncoveredFiles="true">
23 |         <include>
24 |             <directory suffix=".php">src</directory>
25 |         </include>
26 |     </coverage>
27 | </phpunit>
28 | 


--------------------------------------------------------------------------------
/psalm.xml:
--------------------------------------------------------------------------------
 1 | <?xml version="1.0"?>
 2 | <psalm
 3 |     errorLevel="5"
 4 |     resolveFromConfigFile="true"
 5 |     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 6 |     xmlns="https://getpsalm.org/schema/config"
 7 |     xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
 8 | >
 9 |     <projectFiles>
10 |         <directory name="src" />
11 |         <ignoreFiles>
12 |             <directory name="vendor" />
13 |         </ignoreFiles>
14 |     </projectFiles>
15 |     <issueHandlers>
16 |         <InvalidAttribute errorLevel="info" />
17 |     </issueHandlers>
18 | </psalm>
19 | 


--------------------------------------------------------------------------------
/src/AbstractTypedArray.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | declare(strict_types=1);
 3 | namespace ParagonIE\TypedArrays;
 4 | 
 5 | abstract class AbstractTypedArray implements \ArrayAccess
 6 | {
 7 |     protected array $contents = [];
 8 | 
 9 |     protected const string SCALAR_TYPE = 'mixed';
10 | 
11 |     public function __debugInfo(): array
12 |     {
13 |         return $this->contents;
14 |     }
15 | 
16 |     #[\Override]
17 |     public function offsetExists(mixed $offset): bool
18 |     {
19 |         return array_key_exists($offset, $this->contents);
20 |     }
21 | 
22 |     #[\Override]
23 |     public function offsetGet(mixed $offset): mixed
24 |     {
25 |         if (!$this->offsetExists($offset)) {
26 |             throw new \RangeException('Index not found: ' . $offset);
27 |         }
28 |         return $this->contents[$offset];
29 |     }
30 | 
31 |     #[\Override]
32 |     public function offsetSet(mixed $offset, mixed $value): void
33 |     {
34 |         switch (static::SCALAR_TYPE) {
35 |             case 'mixed':
36 |                 break;
37 |             case 'string':
38 |                 if (!is_string($value)) {
39 |                     throw new \TypeError('Only ' . static::SCALAR_TYPE . ' types can be assigned');
40 |                 }
41 |                 break;
42 |             case 'int':
43 |                 if (!is_int($value)) {
44 |                     throw new \TypeError('Only ' . static::SCALAR_TYPE . ' types can be assigned');
45 |                 }
46 |                 break;
47 |             case 'float':
48 |                 if (!is_float($value) && !is_int($value)) {
49 |                     throw new \TypeError('Only ' . static::SCALAR_TYPE . ' types can be assigned');
50 |                 }
51 |                 break;
52 |             case 'bool':
53 |                 if (!is_bool($value)) {
54 |                     throw new \TypeError('Only ' . static::SCALAR_TYPE . ' types can be assigned');
55 |                 }
56 |                 break;
57 |             case 'object':
58 |                 if (!is_object($value)) {
59 |                     throw new \TypeError('Only ' . static::SCALAR_TYPE . ' types can be assigned');
60 |                 }
61 |                 break;
62 |         }
63 |         $this->contents[$offset] = $value;
64 |     }
65 | 
66 |     #[\Override]
67 |     public function offsetUnset(mixed $offset): void
68 |     {
69 |         if (array_key_exists($offset, $this->contents)) {
70 |             unset($this->contents[$offset]);
71 |         }
72 |     }
73 | }
74 | 


--------------------------------------------------------------------------------
/src/BoolArray.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | declare(strict_types=1);
 3 | namespace ParagonIE\TypedArrays;
 4 | 
 5 | class BoolArray extends AbstractTypedArray
 6 | {
 7 |     protected const string SCALAR_TYPE = 'bool';
 8 |     public function __construct(bool ...$arguments)
 9 |     {
10 |         $this->contents = $arguments;
11 |     }
12 | }
13 | 


--------------------------------------------------------------------------------
/src/FloatArray.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | declare(strict_types=1);
 3 | namespace ParagonIE\TypedArrays;
 4 | 
 5 | class FloatArray extends AbstractTypedArray
 6 | {
 7 |     protected const string SCALAR_TYPE = 'float';
 8 | 
 9 |     public function __construct(float ...$arguments)
10 |     {
11 |         $this->contents = $arguments;
12 |     }
13 | }
14 | 


--------------------------------------------------------------------------------
/src/IntArray.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | declare(strict_types=1);
 3 | namespace ParagonIE\TypedArrays;
 4 | 
 5 | class IntArray extends AbstractTypedArray
 6 | {
 7 |     protected const string SCALAR_TYPE = 'int';
 8 | 
 9 |     public function __construct(int ...$arguments)
10 |     {
11 |         $this->contents = $arguments;
12 |     }
13 | }
14 | 


--------------------------------------------------------------------------------
/src/ObjectTypedArray.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | declare(strict_types=1);
 3 | namespace ParagonIE\TypedArrays;
 4 | 
 5 | class ObjectTypedArray extends AbstractTypedArray
 6 | {
 7 |     protected const string OBJECT_TYPE = 'stdClass';
 8 |     protected const string SCALAR_TYPE = 'object';
 9 | 
10 |     public function __construct(object ...$arguments)
11 |     {
12 |         foreach ($arguments as $index => $argument) {
13 |             if (!is_object($argument)) {
14 |                 throw new \TypeError("Argument at index {$index} is not an object");
15 |             }
16 |             $type = static::OBJECT_TYPE;
17 |             if (!$argument instanceof $type) {
18 |                 throw new \TypeError("Argument at index {$index} is the wrong type");
19 |             }
20 |         }
21 |         $this->contents = $arguments;
22 |     }
23 | 
24 |     #[\Override]
25 |     public function offsetSet(mixed $offset, mixed $value): void
26 |     {
27 |         $type = static::OBJECT_TYPE;
28 |         if (!$value instanceof $type) {
29 |             throw new \TypeError("Value is the wrong type");
30 |         }
31 |         $this->contents[$offset] = $value;
32 |     }
33 | }
34 | 


--------------------------------------------------------------------------------
/src/StringArray.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | declare(strict_types=1);
 3 | namespace ParagonIE\TypedArrays;
 4 | 
 5 | class StringArray extends AbstractTypedArray
 6 | {
 7 |     protected const string SCALAR_TYPE = 'string';
 8 | 
 9 |     public function __construct(string ...$arguments)
10 |     {
11 |         $this->contents = $arguments;
12 |     }
13 | }
14 | 


--------------------------------------------------------------------------------
/tests/BasicTest.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | declare(strict_types=1);
 3 | namespace ParagonIE\TypedArrays\Tests;
 4 | 
 5 | use PHPUnit\Framework\TestCase;
 6 | use ParagonIE\TypedArrays\{
 7 |     AbstractTypedArray,
 8 |     BoolArray,
 9 |     FloatArray,
10 |     IntArray,
11 |     StringArray
12 | };
13 | use function bool⟦⟧, float⟦⟧, int⟦⟧, string⟦⟧;
14 | 
15 | /**
16 |  * @covers AbstractTypedArray
17 |  */
18 | class BasicTest extends TestCase
19 | {
20 |     public function testBasic()
21 |     {
22 |         $bools = bool⟦⟧(true, false);
23 |         $ints = int⟦⟧(1, 2, 3);
24 |         $floats = float⟦⟧(1.618, M_E, M_PI);
25 |         $strings = string⟦⟧('a', 'b', 'c');
26 | 
27 |         $this->assertInstanceOf(BoolArray::class, $bools);
28 |         $this->assertInstanceOf(FloatArray::class, $floats);
29 |         $this->assertInstanceOf(IntArray::class, $ints);
30 |         $this->assertInstanceOf(StringArray::class, $strings);
31 | 
32 |         $this->assertIsBool($bools[0]);
33 |         $this->assertIsFloat($floats[0]);
34 |         $this->assertIsInt($ints[0]);
35 |         $this->assertIsString($strings[0]);
36 |     }
37 | }


--------------------------------------------------------------------------------