From 55450f75da327a32d3082f7a7326a62418503224 Mon Sep 17 00:00:00 2001
From: Christian Sciberras <christian@yumpu.com>
Date: Sat, 23 Apr 2022 22:48:52 +0200
Subject: [PATCH] Initial commit

---
 .gitignore                   |  2 ++
 README.md                    | 25 +++++++++++++++++++++++++
 composer.json                | 22 ++++++++++++++++++++++
 src/.phpstorm.meta.php       |  6 ++++++
 src/Castable.php             | 12 ++++++++++++
 src/NotCastableException.php | 10 ++++++++++
 src/functions.php            | 35 +++++++++++++++++++++++++++++++++++
 7 files changed, 112 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 README.md
 create mode 100644 composer.json
 create mode 100644 src/.phpstorm.meta.php
 create mode 100644 src/Castable.php
 create mode 100644 src/NotCastableException.php
 create mode 100644 src/functions.php

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..d1502b0
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,2 @@
+vendor/
+composer.lock
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..943ee58
--- /dev/null
+++ b/README.md
@@ -0,0 +1,25 @@
+# PHP Castable
+
+Basic groundwork for type-casting in PHP.
+
+## Features / Functionality
+
+- Works with simple types and objects
+- `cast($value, $type)` function that converts a value to a target type.
+- `Castable` interface, exposes function called whenever cast() is called on objects implementing this interface.
+- Error handling - all errors routed to `NotCastableException`
+- Fixes type-hinting for PhpStorm
+- PHP 5.6+ (but seriously, stop using PHP 5 :))
+
+While `cast()` is just a regular PHP function, it would be the equivalent to type-casting operators in other languages (e.g. `val as Type`, `(Type)val`, `val.to(Type)`, `CAST(val, TYPE)`...).
+
+## Behaviour
+
+1. If the value to be type-casted is not an object, PHP's `settype()` is used.
+2. If, instead, it is an object that implements `Castable` interface, `castTo()` is called and its value returned.
+3. Otherwise, if the object is the same or a subclass of the desired type, then it is returned unchanged.
+
+## Motivation
+
+In many cases, having specific `castToX()` methods in your classes is enough and the behaviour typically works adequately.
+However, sometimes this becomes too much or a more dynamic solution is needed. In this case, this package helps to avoid writing the boilerplate code.
\ No newline at end of file
diff --git a/composer.json b/composer.json
new file mode 100644
index 0000000..868ec64
--- /dev/null
+++ b/composer.json
@@ -0,0 +1,22 @@
+{
+  "name": "uuf6429/php-castable",
+  "description": "Type casting functionality for PHP",
+  "type": "library",
+  "authors": [
+    {
+      "name": "Christian Sciberras",
+      "email": "christian@sciberras.me"
+    }
+  ],
+  "autoload": {
+    "psr-4": {
+      "uuf6429\\Castable\\": "src/"
+    },
+    "files": [
+      "src/functions.php"
+    ]
+  },
+  "require": {
+    "php": "^5.6 || ^7 || ^8"
+  }
+}
diff --git a/src/.phpstorm.meta.php b/src/.phpstorm.meta.php
new file mode 100644
index 0000000..43bb50e
--- /dev/null
+++ b/src/.phpstorm.meta.php
@@ -0,0 +1,6 @@
+<?php
+
+namespace PHPSTORM_META {
+    override(\uuf6429\Castable\cast(1), map(['' => '@']));
+    override(\uuf6429\Castable\Castable::castTo(0), map(['' => '@']));
+}
diff --git a/src/Castable.php b/src/Castable.php
new file mode 100644
index 0000000..1d474b8
--- /dev/null
+++ b/src/Castable.php
@@ -0,0 +1,12 @@
+<?php
+
+namespace uuf6429\Castable;
+
+interface Castable
+{
+    /**
+     * @param string $type
+     * @return mixed
+     */
+    public function castTo($type);
+}
diff --git a/src/NotCastableException.php b/src/NotCastableException.php
new file mode 100644
index 0000000..872c378
--- /dev/null
+++ b/src/NotCastableException.php
@@ -0,0 +1,10 @@
+<?php
+
+namespace uuf6429\Castable;
+
+use RuntimeException;
+
+class NotCastableException extends RuntimeException
+{
+
+}
diff --git a/src/functions.php b/src/functions.php
new file mode 100644
index 0000000..6f61310
--- /dev/null
+++ b/src/functions.php
@@ -0,0 +1,35 @@
+<?php
+
+use uuf6429\Castable\Castable;
+use uuf6429\Castable\NotCastableException;
+
+function cast($value, $type)
+{
+    if (!is_object($value)) {
+        if (settype($value, $type)) {
+            return $value;
+        }
+        throw new NotCastableException(
+            sprintf('Value of type %s cannot be cast to %s', gettype($value), $type)
+        );
+    }
+
+    if ($value instanceof Castable) {
+        try {
+            return $value->castTo($type);
+        } catch (Exception $exception) {
+        } catch (Throwable $exception) {
+        }
+        throw new NotCastableException(
+            sprintf('Castable object could not be cast to %s', $type), 0, $exception
+        );
+    }
+
+    if (!is_a($value, $type)) {
+        throw new NotCastableException(
+            sprintf('Object of class %s is not compatible with class %s', get_class($value), $type)
+        );
+    }
+
+    return $value;
+}