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.
 	 *
@@ -56,7 +56,7 @@ public function getDirty() : array;
 	 *
 	 * @return mixed|array
 	 */
-	public function getOriginal( string $key = null );
+	public function getOriginal( ?string $key = null );
 
 	/**
 	 * Determines if the model has the given property.
@@ -79,7 +79,7 @@ public static function hasProperty( string $key ) : bool;
 	 *
 	 * @return bool
 	 */
-	public function isClean( string $attribute = null ) : bool;
+	public function isClean( ?string $attribute = null ) : bool;
 
 	/**
 	 * Determines if a given attribute is dirty.
@@ -90,7 +90,7 @@ public function isClean( string $attribute = null ) : bool;
 	 *
 	 * @return bool
 	 */
-	public function isDirty( string $attribute = null ) : bool;
+	public function isDirty( ?string $attribute = null ) : bool;
 
 	/**
 	 * Validates an attribute to a PHP type.

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.
 	 *
@@ -51,10 +55,55 @@ abstract class Model implements ModelInterface, Arrayable, JsonSerializable {
 	 *
 	 * @param array<string,mixed> $attributes Attributes.
 	 */
-	public function __construct( array $attributes = [] ) {
+	final public function __construct( array $attributes = [] ) {
 		$this->fill( array_merge( static::getPropertyDefaults(), $attributes ) );
 
 		$this->syncOriginal();
+
+		$this->afterConstruct();
+	}
+
+	/**
+	 * This method is meant to be overridden by the model to perform actions after the model is constructed.
+	 *
+	 * @since 2.0.0
+	 */
+	protected function afterConstruct() {
+		// This method is meant to be overridden by the model to perform actions after the model is constructed.
+		return;
+	}
+
+	/**
+	 * 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." );
+		}
 	}
 
 	/**
@@ -120,7 +169,7 @@ public function getDirty() : array {
 	 *
 	 * @return mixed|array
 	 */
-	public function getOriginal( string $key = null ) {
+	public function getOriginal( ?string $key = null ) {
 		return $key ? $this->original[ $key ] : $this->original;
 	}
 
@@ -285,7 +334,7 @@ public static function hasProperty( string $key ) : bool {
 	 *
 	 * @return bool
 	 */
-	public function isClean( string $attribute = null ) : bool {
+	public function isClean( ?string $attribute = null ) : bool {
 		return ! $this->isDirty( $attribute );
 	}
 
@@ -298,7 +347,7 @@ public function isClean( string $attribute = null ) : bool {
 	 *
 	 * @return bool
 	 */
-	public function isDirty( string $attribute = null ) : bool {
+	public function isDirty( ?string $attribute = null ) : bool {
 		if ( ! $attribute ) {
 			return (bool) $this->getDirty();
 		}
@@ -354,6 +403,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 ModelBuildsFromData
  */
 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;
@@ -38,7 +40,7 @@ public function __construct( string $modelClass ) {
 	 *
 	 * @param null|string $column
 	 */
-	public function count( $column = null ) : int {
+	public function count( ?string $column = null ) : int {
 		$column = ( ! $column || $column === '*' ) ? '1' : trim( $column );
 
 		if ( '1' === $column ) {
@@ -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::fromData( $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, 'fromData' ], $results );
 	}
 }