initial commit

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) sji <sji@sj-i.dev>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,83 @@
+# Typist
+
+Typist is a PHP library enforcing types of local variables.  
+It internally uses references to typed properties introduced in PHP 7.4.
+
+## Installation
+
+```
+composer require sj-i/typist
+```
+
+## Supported Versions
+
+- PHP 7.4 or later
+
+# Usage
+## Basic Usage
+
+```
+use Typist\Typist;
+
+// type enforcements are valid during the lifetime of this `$_`
+$_ = [
+    Typist::int($typed_int, 1),
+    Typist::string($typed_string, 'str'),
+    Typist::bool($typed_bool, false),
+    Typist::float($typed_float, 0.1),
+    Typist::class(\DateTimeInterface::class, $typed_object, new \DateTime()),
+];
+
+assert($typed_int === 1);
+assert($typed_string === 'str');
+assert($typed_bool === false);
+assert($typed_float === 0.1);
+assert($typed_object instanceof \DateTime);
+
+// modifications with valid types are OK
+$typed_int = 2;
+$typed_string = 'trs';
+$typed_bool = true;
+$typed_float = -0.1;
+$typed_object = new DateTimeImmutable();
+
+// any statements below raises TypeError
+$typed_int = 'a';
+$typed_string = 1;
+$typed_bool = 'a';
+$typed_float = 'a';
+$typed_object = 'a';
+```
+
+## Nullable Types
+
+```
+use Typist\Typist;
+
+$_ = [
+    Typist::nullable()::int($typed_int1, 1),
+    Typist::nullable()::int($typed_int2, null),
+    Typist::nullable()::string($typed_string1, 'str'),
+    Typist::nullable()::string($typed_string2, null),
+    Typist::nullable()::bool($typed_bool1, false),
+    Typist::nullable()::bool($typed_bool2, null),
+    Typist::nullable()::float($typed_float1, 0.1),
+    Typist::nullable()::float($typed_float2, null),
+    Typist::nullable()::class(\DateTimeInterface::class, $typed_object1, new \DateTime()),
+    Typist::nullable()::class(\DateTimeInterface::class, $typed_object2, null),
+];
+```
+
+or if you use PHP8, `()` can be omitted.
+
+```
+use Typist\Typist;
+
+$_ = [
+    Typist::nullable::int($typed_int2, null),
+    Typist::nullable::string($typed_string2, null),
+    Typist::nullable::bool($typed_bool2, null),
+    Typist::nullable::float($typed_float2, null),
+    Typist::nullable::class(\DateTimeInterface::class, $typed_object2, null),
+];
+```

composer.json

@@ -0,0 +1,34 @@
+{
+  "name": "sj-i/typist",
+  "description": "Enforcing types of local variables",
+  "type": "library",
+  "keywords": [
+    "type-safety"
+  ],
+  "minimum-stability": "stable",
+  "license": "MIT",
+  "authors": [
+    {
+      "name": "sji",
+      "homepage": "https://twitter.com/sji_ch"
+    }
+  ],
+  "require": {
+    "php": "^7.4 || ^8.0"
+  },
+  "require-dev": {
+    "phpunit/phpunit": "^8.0 || ^9.0",
+    "vimeo/psalm": "^3.12",
+    "squizlabs/php_codesniffer": "^3.5"
+  },
+  "autoload": {
+    "psr-4": {
+      "Typist\\": "src/Typist"
+    }
+  },
+  "autoload-dev": {
+    "psr-4": {
+      "Typist\\": "tests/Typist"
+    }
+  }
+}

phpcs.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0"?>
+<ruleset name="Typist">
+    <arg name="extensions" value="php" />
+    <rule ref="PSR12" />
+</ruleset>

psalm.xml

@@ -0,0 +1,15 @@
+<?xml version="1.0"?>
+<psalm
+        errorLevel="1"
+        resolveFromConfigFile="true"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xmlns="https://getpsalm.org/schema/config"
+        xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
+>
+    <projectFiles>
+        <directory name="src"/>
+        <ignoreFiles>
+            <directory name="vendor"/>
+        </ignoreFiles>
+    </projectFiles>
+</psalm>

src/Typist/BoolEnforcer.php

@@ -0,0 +1,27 @@
+<?php
+
+/**
+ * This file is part of the sj-i/typist package.
+ *
+ * (c) sji <sji@sj-i.dev>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Typist;
+
+final class BoolEnforcer
+{
+    private bool $value;
+
+    /**
+     * @internal
+     */
+    public function __construct(bool &$value)
+    {
+        $this->value = &$value;
+    }
+}

src/Typist/ClassEnforcer.php

@@ -0,0 +1,67 @@
+<?php
+
+/**
+ * This file is part of the sj-i/typist package.
+ *
+ * (c) sji <sji@sj-i.dev>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Typist;
+
+use ReflectionClass;
+
+/**
+ * @template T
+ */
+final class ClassEnforcer
+{
+    /** @var class-string[] */
+    private static array $registered_classes = [];
+
+    private GeneratedClassEnforcerInterface $enforcer;
+
+    /**
+     * @internal
+     * @param class-string<T> $passed_class_name
+     * @param T $value
+     * @throws \ReflectionException
+     */
+    public function __construct(string $passed_class_name, &$value)
+    {
+        $class = new ReflectionClass($passed_class_name);
+
+        $namespace = $class->getNamespaceName();
+        $class_name = $class->getShortName();
+        $fully_qualified_class_name = ($namespace === '' ? '\\' : $namespace) . $class_name;
+
+        $enforcer_name = $class_name . 'Enforcer';
+        $enforcer_namespace = rtrim(implode('\\', [__NAMESPACE__ , $namespace]), '\\');
+        $enforcer_interface_name = GeneratedClassEnforcerInterface::class;
+
+        if (!isset(self::$registered_classes[$fully_qualified_class_name])) {
+            $code = <<<TEMPLATE
+            declare(strict_types=1);
+            namespace {$enforcer_namespace};
+            class {$enforcer_name} implements \\{$enforcer_interface_name}
+            {
+                private {$fully_qualified_class_name} \$value;
+                public function __construct({$fully_qualified_class_name} &\$value)
+                {
+                    \$this->value = &\$value;
+                }
+            }
+            TEMPLATE;
+            eval($code);
+            self::$registered_classes[$fully_qualified_class_name] = true;
+        }
+
+        /** @var class-string<GeneratedClassEnforcerInterface> $enforcer_fqn */
+        $enforcer_fqn = implode('\\', [$enforcer_namespace, $enforcer_name]);
+        $this->enforcer = new $enforcer_fqn($value);
+    }
+}

src/Typist/FloatEnforcer.php

@@ -0,0 +1,27 @@
+<?php
+
+/**
+ * This file is part of the sj-i/typist package.
+ *
+ * (c) sji <sji@sj-i.dev>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Typist;
+
+final class FloatEnforcer
+{
+    private float $value;
+
+    /**
+     * @internal
+     */
+    public function __construct(float &$value)
+    {
+        $this->value = &$value;
+    }
+}

src/Typist/GeneratedClassEnforcerInterface.php

@@ -0,0 +1,21 @@
+<?php
+
+/**
+ * This file is part of the sj-i/typist package.
+ *
+ * (c) sji <sji@sj-i.dev>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Typist;
+
+/**
+ * @internal
+ */
+interface GeneratedClassEnforcerInterface
+{
+}

src/Typist/IntEnforcer.php

@@ -0,0 +1,27 @@
+<?php
+
+/**
+ * This file is part of the sj-i/typist package.
+ *
+ * (c) sji <sji@sj-i.dev>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Typist;
+
+final class IntEnforcer
+{
+    private int $value;
+
+    /**
+     * @internal
+     */
+    public function __construct(int &$value)
+    {
+        $this->value = &$value;
+    }
+}

src/Typist/NullableBoolEnforcer.php

@@ -0,0 +1,27 @@
+<?php
+
+/**
+ * This file is part of the sj-i/typist package.
+ *
+ * (c) sji <sji@sj-i.dev>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Typist;
+
+final class NullableBoolEnforcer
+{
+    private ?bool $value;
+
+    /**
+     * @internal
+     */
+    public function __construct(?bool &$value)
+    {
+        $this->value = &$value;
+    }
+}