enum support

Author: phpfui

README.md

@@ -1,7 +1,7 @@
 # PHPFUI\ORM [![Tests](https://github.com/phpfui/ORM/actions/workflows/tests.yml/badge.svg)](https://github.com/phpfui/ORM/actions?query=workflow%3Atests) [![Latest Packagist release](https://img.shields.io/packagist/v/phpfui/ORM.svg)](https://packagist.org/packages/phpfui/ORM) ![](https://img.shields.io/badge/PHPStan-level%206-brightgreen.svg?style=flat)
 
 ### PHPFUI\ORM a minimal Object Relational Mapper (ORM) for MySQL, MariaDB and SQLite3
-Why another PHP ORM? In writing minimal and fast websites, it was determined that existing PHP ORM solutions were overly complex. **PHPFUI\ORM** is a little more than 6K lines of code in under 50 files.  It is designed to have a minimal memory footprint and excellent execution times for most database needs.
+Why another PHP ORM? In writing minimal and fast websites, it was determined that existing PHP ORM solutions were overly complex. **PHPFUI\ORM** is a little more than 6.5K lines of code in under 50 files.  It is designed to have a minimal memory footprint and excellent execution times for most database needs.
 
 **PHPFUI\ORM** is not an attempt to write an abstraction around SQL as other ORMs do, rather it is a way to work with SQL that closely matches the semantics of SQL, with the power of PHP objects.  It allows PHP to manipulate SQL queries without having to write SQL in plain text. This is very useful for queries generated via user interfaces where the user is given a lot of flexability in how a query is defined.
 

Tests/Unit/JoinTest.php

@@ -4,11 +4,11 @@
 
 class JoinTest extends \PHPUnit\Framework\TestCase
 	{
-	public function testBadTableJoin() : void
+	public function testBadJoin() : void
 		{
 		$this->expectException(\PHPFUI\ORM\Exception::class);
 		$table = new \Tests\App\Table\InventoryTransaction();
-		$table->addJoin('fred');
+		$table->addJoin('employee');
 		}
 
 	public function testBadJoinType() : void
@@ -19,11 +19,10 @@ public function testBadJoinType() : void
 		$table->addJoin('fred', type:'fred');
 		}
 
-	public function testBadJoin() : void
+	public function testBadTableJoin() : void
 		{
 		$this->expectException(\PHPFUI\ORM\Exception::class);
 		$table = new \Tests\App\Table\InventoryTransaction();
-		$table->addJoin('employee');
+		$table->addJoin('fred');
 		}
 	}
-

docs/5. Virtual Fields.md

@@ -170,3 +170,35 @@ class Invoice extends \Tests\App\Record\Definition\Order
 $invoice = new Invoice(20);
 echo 'Lead Weeks: ' . $invoice->invoice_date->diffInWeeks($invoice->due_date);
 ```
+
+## Type Safe Enum Support
+In PHP 8.1 and above, you can add enum support easily. Assume this is your enum:
+```php
+namespace App\Enum;
+enum IncludeMembership : int
+  {
+  case NO = 0;
+  case NEW_MEMBERS_ONLY = 1;
+  case EXTEND_MEMBERSHIP = 2;
+  case RENEW_MEMBERSHIP = 3;
+  }
+```
+You can define the event.includeMembership field to use enums instead of integer values.
+```php
+class Event extends \App\Record\Definition\Event
+ {
+ protected static array $virtualFields = [
+ 'includeMembership' => [\PHPFUI\ORM\Enum::class, \App\Enum\IncludeMembership::class],
+ ];
+ }
+```
+Your code would now look like this:
+```php
+if (\App\Enum\IncludeMembership::NEW_MEMBERS_ONLY == $event->includeMembership)
+```
+You can also set and save the enum directly:
+```php
+$event->includeMembership = \App\Enum\IncludeMembership:NO;
+$event->update();
+```
+Enum assignments are type safe. Attempting to set the enum with an incorrect type will throw an exception.

src/PHPFUI/ORM/Enum.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace PHPFUI\ORM;
+
+class Enum extends \PHPFUI\ORM\VirtualField
+	{
+	/**
+	 * @param array<mixed> $parameters optional
+	 */
+	public function getValue(array $parameters) : mixed
+		{
+		$enum = $parameters[0];
+
+		return $enum::from($this->currentRecord->offsetGet($this->fieldName));
+		}
+
+	/**
+	 * @param array<mixed> $parameters optional
+	 */
+	public function setValue(mixed $value, array $parameters) : void
+		{
+		$enum = $parameters[0];
+
+		if ($value instanceof $enum)
+			{
+			$this->currentRecord->offsetSet($this->fieldName, $value->value);
+
+			return;
+			}
+
+		throw new \PHPFUI\ORM\Exception('You can not assign a variable of type ' . \get_debug_type($value) . ' to an enum type of ' . $enum);
+		}
+	}

src/PHPFUI/ORM/Record.php

@@ -505,13 +505,25 @@ public function loadFromSQL(string $sql, array $input = []) : bool
 		return true;
 		}
 
-	public function offsetGet(mixed $offset) : mixed
+	/**
+	 * Low level get access to underlying data to implement ArrayAccess
+	 */
+	public function offsetGet($offset) : mixed
 		{
 		$this->validateFieldExists($offset);
 
 		return $this->current[$offset] ?? null;
 		}
 
+	/**
+	 * Low level set access to underlying data to implement ArrayAccess
+	 */
+	public function offsetSet($offset, $value) : void
+		{
+		$this->validateFieldExists($offset);
+		$this->current[$offset] = $value;
+		}
+
  /**
   * Read a record from the db. If more than one match, only the first is loaded.
   *

src/PHPFUI/ORM/Table.php

@@ -176,12 +176,13 @@ public function addJoin(string $table, string | \PHPFUI\ORM\Condition $on = '',
 			$thisFields = $this->getFields();
 			$joinFields = $joinTable->getFields();
 			$keys = $this->getPrimaryKeys();
-			$thisPrimaryKey = array_shift($keys);
-			if (array_key_exists($on, $thisFields) && array_key_exists($on, $joinFields))
+			$thisPrimaryKey = \array_shift($keys);
+
+			if (\array_key_exists($on, $thisFields) && \array_key_exists($on, $joinFields))
 				{
 				// do nothing here, just exclude this case
 				}
-			else if (array_key_exists($thisPrimaryKey, $joinFields))
+			elseif (\array_key_exists($thisPrimaryKey, $joinFields))
 				{
 				// join on master table primary key
 				$on = $thisPrimaryKey;