Cast Virtual Field

Author: phpfui

README.md

@@ -7,14 +7,15 @@ Why another PHP ORM? In writing minimal and fast websites, it was determined tha
 
 ## Features
 - **Active Records** A fully type checked object interface and implement basic CRUD functionality.
-- **Active Tables** Full table operations including support for where, having, limits, ordering, grouping, joins and unions.
+- **Active Tables** Full table operations (select, update, insert and delete) including support for where, having, limits, ordering, grouping, joins and unions.
 - **Data Cursors** Cursors implement **iterable** and **Countable** eliminating the need for full arrays read into memory.
 - **Validation** Fully customizable and translatable backend validation.
-- **Virtual Fields** Supports get and set semantics for any custom or calculated field.
+- **Virtual Fields** Supports get and set semantics for any custom or calculated field such as Carbon dates.
 - **Migrations** Simple migrations offer atomic up and down migrations.
 - **Relations** Parent, children, one to one, many to many, and custom relationships.
 - **Transactions** Object based transaction meaning exceptions can not leave an open transacton.
-- **Type Safe** Prevent stupid type errors.
+- **Type Safe** Prevents stupid type errors.
+- **Injection Safe** Uses PDO placeholders and field sanitation to prevent injection attacks.
 - **Raw SQL Query Support** Execute any valid SQL command.
 - **Multiple Database Support** Work with multiple databases simultaneously.
 - **Multi-Vendor Support** Built on PDO with support for MySQL, MariaDB and SQLite.
@@ -115,7 +116,7 @@ Exceptions are generated in the following conditions:
 All of the above exceptions are programmer errors and strictly enforced. Empty queries are not considered errors. SQL may also return [Exceptions](https://www.php.net/manual/en/class.exception.php) if invalid fields are used.
 
 ### Type Conversions
-If you set a field to the wrong type, the library logs an warning then converts the type via the appropriate PHP cast.
+If you set a field to the wrong type, the library logs a warning then converts the type via the appropriate PHP cast.
 
 ## Multiple Database Support
 While this is primarily a single database ORM, you can switch databases at run time. Save the value from `$connectionId = \PHPFUI\ORM::addConnection($pdo);` and then call `\PHPFUI\ORM::useConnection($db);` to switch.  `\PHPFUI\ORM::addConnection` will set the current connection.

Tests/Fixtures/Record/Order.php

@@ -6,5 +6,8 @@ class Order extends \Tests\Fixtures\Record\Definition\Order
 	{
 	protected static array $virtualFields = [
 		'OrderDetailChildren' => [\PHPFUI\ORM\Children::class, \Tests\Fixtures\Table\OrderDetail::class, 'order_detail_id'],
+		'order_date' => [\PHPFUI\ORM\Cast::class, \Carbon\Carbon::class],
+		'paid_date' => [\PHPFUI\ORM\Cast::class, \Carbon\Carbon::class],
+		'shipped_date' => [\PHPFUI\ORM\Cast::class, \Carbon\Carbon::class],
 	];
 	}

Tests/Unit/CastTest.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Tests\Unit;
+
+class CastTest extends \PHPUnit\Framework\TestCase
+	{
+	public function testOrderCast() : void
+		{
+		$order = new \Tests\Fixtures\Record\Order(30);
+		$this->assertTrue($order->loaded());
+		$this->assertEquals(7, $order->order_date->diffInDays($order->shipped_date));
+		$ship_date = $order->shipped_date->addDays(10);
+		$order->shipped_date = $ship_date;
+		$this->assertEquals(17, $order->order_date->diffInDays($order->shipped_date));
+		}
+	}

composer.json

@@ -20,6 +20,7 @@
         "phpfui/phpunit-syntax-coverage": "^1.0",
         "roave/security-advisories": "dev-latest",
         "friendsofphp/php-cs-fixer": "^3.0",
+        "nesbot/carbon": "*",
         "phpstan/phpstan": "^1.8"
     },
     "autoload": {

docs/5. Virtual Fields.md

@@ -5,6 +5,8 @@ You can define virtual fields with get and set semantics for any **\App\Record**
 
 Every **\App\Record** class has a static $virtualFields array defined. The key of the array is the name of the virtual key.  The value for each virtual field is an array of strings. The first string is the virtual field class name. Subsequent parameters are are passed the the **getValue** and **setValue** methods.
 
+Note that virtual fields are created each time they are accessed and not stored or cached in the \PHPFUI\ORM\Record object.  This means you can not change the virtual field on the Record object itself. You can only assign it to the Record object, which will store the value represented by the virtual field in the object, but not the virtual field itself.
+
 The **VirtualField** class has two properties that will always be defined for use by the derived class:
 * $currentRecord is the current record that the virtual field should be based on.
 * $fieldName the field name that the VirtualField object was created from.  This is the key of the $virtualFields array in the Record class.
@@ -125,3 +127,20 @@ foreach ($suppliers as $supplier)
   echo $supplier->company . "\n";
   }
 ```
+
+## Cast Virtual Field
+Often you want to use PHP class instead of a native scalar type (string, int, float, bool) to make your life easier. The Carbon class is an excellent example of a widely used package.  It would be nice to get and set Carbon objects instead of strings formatted to the MySQL date format.
+
+Use \PHPFUI\ORM\Cast virtual field to accommplish this. The Cast virtual field works with a wide variety of packages, as its only requirements are to implement **__toString** and a construct from a value.
+### Usage
+```php
+class Invoice extends \Tests\App\Record\Definition\Order
+	{
+	protected static array $virtualFields = [
+  	'due_date' => [\PHPFUI\ORM\Cast::class, \Carbon\Carbon::class],
+		'invoice_date' => [\PHPFUI\ORM\Cast::class, \Carbon\Carbon::class],
+	];
+	}
+$invoice = new Invoice(20);
+echo 'Lead Weeks: ' . $invoice->invoice_date->diffInWeeks($invoice->due_date);
+```

src/PHPFUI/ORM/Cast.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace PHPFUI\ORM;
+
+class Cast extends \PHPFUI\ORM\VirtualField
+	{
+	public function getValue(array $parameters) : mixed
+		{
+		$class = \array_shift($parameters);
+
+		return new $class($this->currentRecord[$this->fieldName]);
+		}
+
+	public function setValue(mixed $value, array $parameters) : void
+		{
+		$class = \array_shift($parameters);
+
+		if (! ($value instanceof $class))
+			{
+			throw new \PHPFUI\ORM\Exception(__METHOD__ . ': Error - ' . \get_debug_type($value) . ' is not an instance of ' . $class);
+			}
+
+		$this->currentRecord[$this->fieldName] = "{$value}";
+		}
+	}

src/PHPFUI/ORM/Migration.php

@@ -484,12 +484,12 @@ private function alter(string $type, string $table, string $field, string $extra
 		$this->alters[$table][] = $sql;
 		}
 
-	private function getFieldInfo(string $table, string $field) : ?PHPFUI\ORM\Schema\Field
+	private function getFieldInfo(string $table, string $fieldName) : ?\PHPFUI\ORM\Schema\Field
 		{
 		$fields = \PHPFUI\ORM::describeTable($table);
 		foreach ($fields as $field)
 			{
-			if ($field->name == $field)
+			if ($field->name == $fieldName)
 				{
 				return $field;
 				}