2.0 — Feature: Built-in system for converting from query data

composer.json

@@ -14,7 +14,7 @@
   "config": {
     "preferred-install": "dist",
     "platform": {
-      "php": "7.0"
+      "php": "7.4"
     },
     "allow-plugins": {
       "kylekatarnls/update-helper": true

src/Models/Config.php

@@ -104,7 +104,16 @@ public static function setInvalidArgumentException( string $class ) {
 		static::$invalidArgumentException = $class;
 	}
 
-	public static function throwInvalidArgumentException( string $message ) {
+	/**
+	 * Convenience method for throwing the InvalidArgumentException.
+	 *
+	 * @since 2.0.0
+	 *
+	 * @param string $message
+	 *
+	 * @return void
+	 */
+	public static function throwInvalidArgumentException( string $message ): void {
 		throw new static::$invalidArgumentException( $message );
 	}
 }

src/Models/Contracts/Model.php

@@ -4,7 +4,7 @@
 
 use RuntimeException;
 
-interface Model {
+interface Model extends ModelBuildsFromData {
 	/**
 	 * Constructor.
 	 *

src/Models/Contracts/ModelBuildsFromData.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace StellarWP\Models\Contracts;
+
+use StellarWP\Models\ModelQueryBuilder;
+
+/**
+ * @since 2.0.0
+ */
+interface ModelBuildsFromData {
+	/**
+	 * @since 2.0.0
+	 *
+	 * @param array|object $data
+	 *
+	 * @return Model
+	 */
+	public static function fromData( $data );
+}

src/Models/Contracts/ModelReadOnly.php

@@ -7,7 +7,7 @@
 /**
  * @since 1.0.0
  */
-interface ModelReadOnly {
+interface ModelReadOnly extends ModelBuildsFromQueryData {
 	/**
 	 * @since 1.0.0
 	 *
@@ -23,13 +23,4 @@ public static function find( $id );
 	 * @return ModelQueryBuilder
 	 */
 	public static function query();
-
-	/**
-	 * @since 1.0.0
-	 *
-	 * @param $object
-	 *
-	 * @return Model
-	 */
-	public static function fromQueryBuilderObject( $object );
 }

src/Models/Model.php

@@ -9,6 +9,10 @@
 use StellarWP\Models\ValueObjects\Relationship;
 
 abstract class Model implements ModelInterface, Arrayable, JsonSerializable {
+	public const BUILD_MODE_STRICT = 0;
+	public const BUILD_MODE_IGNORE_MISSING = 1;
+	public const BUILD_MODE_IGNORE_EXTRA = 2;
+
 	/**
 	 * The model's attributes.
 	 *
@@ -57,6 +61,39 @@ public function __construct( array $attributes = [] ) {
 		$this->syncOriginal();
 	}
 
+	/**
+	 * Casts the value for the type, used when constructing a model from query data. If the model needs to support
+	 * additional types, especially class types, this method can be overridden.
+	 *
+	 * @since 2.0.0 changed to static
+	 *
+	 * @param string $type
+	 * @param mixed  $value The query data value to cast, probably a string.
+	 * @param string $property The property being casted.
+	 *
+	 * @return mixed
+	 */
+	protected static function castValueForProperty( string $type, $value, string $property ) {
+		if ( static::isPropertyTypeValid( $property, $value ) || $value === null ) {
+			return $value;
+		}
+
+		switch ( $type ) {
+			case 'int':
+				return (int) $value;
+			case 'string':
+				return (string) $value;
+			case 'bool':
+				return (bool) filter_var( $value, FILTER_VALIDATE_BOOLEAN );
+			case 'array':
+				return (array) $value;
+			case 'float':
+				return (float) filter_var( $value, FILTER_SANITIZE_NUMBER_FLOAT,FILTER_FLAG_ALLOW_FRACTION );
+			default:
+				Config::throwInvalidArgumentException( "Unexpected type: '$type'. To support additional types, implement a custom castValueForProperty() method." );
+		}
+	}
+
 	/**
 	 * Fills the model with an array of attributes.
 	 *
@@ -354,6 +391,49 @@ public function jsonSerialize() {
 		return get_object_vars( $this );
 	}
 
+	/**
+	 * Constructs a model instance from database query data.
+	 *
+	 * @param object|array $queryData
+	 * @param int $mode The level of strictness to take when constructing the object, by default it will ignore extra keys but error on missing keys.
+	 * @return static
+	 */
+	public static function fromData($data, $mode = self::BUILD_MODE_IGNORE_EXTRA) {
+		if ( ! is_object( $data ) && ! is_array( $data ) ) {
+			Config::throwInvalidArgumentException( 'Query data must be an object or array' );
+		}
+
+		$data = (array) $data;
+
+		// If we're not ignoring extra keys, check for them and throw an exception if any are found.
+		if ( ! ($mode & self::BUILD_MODE_IGNORE_EXTRA) ) {
+			$extraKeys = array_diff_key( (array) $data, static::$properties );
+			if ( ! empty( $extraKeys ) ) {
+				Config::throwInvalidArgumentException( 'Query data contains extra keys: ' . implode( ', ', array_keys( $extraKeys ) ) );
+			}
+		}
+
+		if ( ! ($mode & self::BUILD_MODE_IGNORE_MISSING) ) {
+			$missingKeys = array_diff_key( static::$properties, (array) $data );
+			if ( ! empty( $missingKeys ) ) {
+				Config::throwInvalidArgumentException( 'Query data is missing keys: ' . implode( ', ', array_keys( $missingKeys ) ) );
+			}
+		}
+
+		$instance = new static();
+
+		foreach (static::$properties as $key => $type) {
+			if ( ! array_key_exists( $key, $data ) ) {
+				Config::throwInvalidArgumentException( "Property '$key' does not exist." );
+			}
+
+			// Remember not to use $type, as it may be an array that includes the default value. Safer to use getPropertyType().
+			$instance->setAttribute($key, static::castValueForProperty(static::getPropertyType($key), $data[$key], $key));
+		}
+
+		return $instance;
+	}
+
 	/**
 	 * Returns the property keys.
 	 *

src/Models/ModelQueryBuilder.php

@@ -6,15 +6,17 @@
 use StellarWP\DB\DB;
 use StellarWP\DB\QueryBuilder\QueryBuilder;
 use StellarWP\DB\QueryBuilder\Clauses\RawSQL;
-use StellarWP\Models\Model;
-
+use StellarWP\Models\Contracts\Model;
+use StellarWP\Models\Contracts\ModelBuildsFromData;
 /**
  * @since 1.2.2  improve model generic
  * @since 1.0.0
  *
- * @template M of Model
+ * @template M of ModelBuildsFromQueryData
  */
 class ModelQueryBuilder extends QueryBuilder {
+	public const MODEL = 'model';
+
 	/**
 	 * @var class-string<M>
 	 */
@@ -24,8 +26,8 @@ class ModelQueryBuilder extends QueryBuilder {
 	 * @param class-string<M> $modelClass
 	 */
 	public function __construct( string $modelClass ) {
-		if ( ! is_subclass_of( $modelClass, Model::class ) ) {
-			throw new InvalidArgumentException( "$modelClass must be an instance of " . Model::class );
+		if ( ! is_subclass_of( $modelClass, ModelBuildsFromData::class ) ) {
+			throw new InvalidArgumentException( "$modelClass must implement " . ModelBuildsFromData::class );
 		}
 
 		$this->model = $modelClass;
@@ -58,14 +60,18 @@ public function count( $column = null ) : int {
 	 *
 	 * @return M|null
 	 */
-	public function get( $output = OBJECT ): ?Model {
-		$row = DB::get_row( $this->getSQL(), OBJECT );
+	public function get( $output = self::MODEL ): ?Model {
+		if ( $output !== self::MODEL ) {
+			return parent::get( $output );
+		}
+
+		$row = DB::get_row( $this->getSQL() );
 
 		if ( ! $row ) {
 			return null;
 		}
 
-		return $this->getRowAsModel( $row );
+		return $this->model::fromQueryData( $row );
 	}
 
 	/**
@@ -75,58 +81,17 @@ public function get( $output = OBJECT ): ?Model {
 	 *
 	 * @return M[]|null
 	 */
-	public function getAll( $output = OBJECT ) : ?array {
-		$results = DB::get_results( $this->getSQL(), OBJECT );
-
-		if ( ! $results ) {
-			return null;
-		}
-
-		if ( isset( $this->model ) ) {
-			return $this->getAllAsModel( $results );
-		}
-
-		return $results;
-	}
-
-	/**
-	 * Get row as model
-	 *
-	 * @since 1.0.0
-	 *
-	 * @param object|null $row
-	 *
-	 * @return M|null
-	 */
-	protected function getRowAsModel( $row ) {
-		$model = $this->model;
-
-		if ( ! method_exists( $model, 'fromQueryBuilderObject' ) ) {
-			throw new InvalidArgumentException( "fromQueryBuilderObject missing from $model" );
+	public function getAll( $output = self::MODEL ) : ?array {
+		if ( $output !== self::MODEL ) {
+			return parent::getAll( $output );
 		}
 
-		return $model::fromQueryBuilderObject( $row );
-	}
-
-	/**
-	 * Get results as models
-	 *
-	 * @since 1.0.0
-	 *
-	 * @param object[] $results
-	 *
-	 * @return M[]|null
-	 */
-	protected function getAllAsModel( array $results ) {
-		/** @var Contracts\ModelCrud $model */
-		$model = $this->model;
+		$results = DB::get_results( $this->getSQL() );
 
-		if ( ! method_exists( $model, 'fromQueryBuilderObject' ) ) {
-			throw new InvalidArgumentException( "fromQueryBuilderObject missing from $model" );
+		if ( ! $results ) {
+			return null;
 		}
 
-		return array_map( static function( $object ) use ( $model ) {
-			return $model::fromQueryBuilderObject( $object );
-		}, $results );
+		return array_map( [ $this->model, 'fromQueryData' ], $results );
 	}
 }

tests/_support/Helper/MockModel.php

@@ -11,6 +11,7 @@ class MockModel extends Model {
 		'lastName'     => 'string',
 		'emails'       => [ 'array', [] ],
 		'microseconds' => 'float',
-		'number'       => 'number',
+		'number'       => 'int',
+		'date'         => \DateTime::class,
 	];
 }

tests/wpunit/ModelFactoryTest.php

@@ -143,10 +143,12 @@ public function definition(): array {
 		};
 
 		$nestedFactory = new class(MockModel::class) extends ModelFactory {
+			private $counter = 0;
+
 			public function definition(): array {
-				static $counter = 1;
+				$this->counter++;
 				return [
-					'id' => $counter++,
+					'id' => $this->counter,
 				];
 			}
 		};

tests/wpunit/ModelTest.php

@@ -275,10 +275,8 @@ public function testShouldSetMultipleAttributes() {
 
 	/**
 	 * @since 1.0.0
-	 *
-	 * @return void
 	 */
-	public function testIsSet() {
+	public function testIsSet(): void {
 		$model = new MockModel();
 
 		// This has a default so we should see as set.
@@ -292,6 +290,42 @@ public function testIsSet() {
 		$this->assertTrue( $model->isSet( 'lastName' ) );
 	}
 
+	/**
+	 * @since 2.0.0
+	 */
+	public function testFromDataShouldCreateInstanceWithCorrectTypes(): void {
+		self::markTestSkipped( 'This is not finished yet.' );
+
+		$model = MockModel::fromData( [
+			'id' => '1',
+			'firstName' => 'Bill',
+			'lastName' => 'Murray',
+			'emails' => [ 'billMurray@givewp.com' ],
+			'microseconds' => '1234567890',
+			'number' => '1234567890',
+		], MockModel::BUILD_MODE_IGNORE_EXTRA & MockModel::BUILD_MODE_IGNORE_MISSING );
+
+		$this->assertEquals( 1, $model->id );
+		$this->assertEquals( 'Bill', $model->firstName );
+		$this->assertEquals( 'Murray', $model->lastName );
+		$this->assertEquals( [ 'billMurray@givewp.com' ], $model->emails );
+		$this->assertEquals( 1234567890, $model->microseconds );
+		$this->assertEquals( 1234567890, $model->number );
+	}
+
+	/**
+	 * @since 2.0.0
+	 */
+	public function testFromDataShouldThrowExceptionForNonPrimitiveTypes(): void {
+		self::markTestSkipped( 'This is not finished yet.' );
+
+		$this->expectException( Config::getInvalidArgumentException() );
+
+		MockModel::fromData( [
+			'date' => '123',
+		] );
+	}
+
 	/**
 	 * @since 1.0.0
 	 *