SchemaModel Introduction

Author: dpanta94

src/Models/Config.php

@@ -3,6 +3,7 @@
 namespace StellarWP\Models;
 
 use InvalidArgumentException;
+use RuntimeException;
 
 class Config {
 	/**
@@ -21,10 +22,12 @@ class Config {
 	 * @since 1.0.0
 	 *
 	 * @return string
+	 *
+	 * @throws RuntimeException If the hook prefix is not set.
 	 */
 	public static function getHookPrefix(): string {
 		if ( ! static::$hookPrefix ) {
-			throw new \RuntimeException(
+			throw new RuntimeException(
 				sprintf(
 					'You must provide a hook prefix via %1$s before using the stellarwp/models library.',
 					__CLASS__ . '::setHookPrefix()'
@@ -66,10 +69,13 @@ public static function reset() {
 	 * @param string $hook_prefix
 	 *
 	 * @return void
+	 *
+	 * @throws RuntimeException         If the hook prefix has already been set.
+	 * @throws InvalidArgumentException If the sanitized hook prefix is not the same as the original hook prefix.
 	 */
 	public static function setHookPrefix( string $hook_prefix ) {
 		if ( ! empty( static::$hookPrefix ) ) {
-			throw new \RuntimeException(
+			throw new RuntimeException(
 				sprintf(
 					'The %1$s has already been called and set to %2$s.',
 					__CLASS__ . '::setHookPrefix()',
@@ -81,7 +87,7 @@ public static function setHookPrefix( string $hook_prefix ) {
 		$sanitized_prefix = preg_replace( '/[^a-z0-9_-]/', '', $hook_prefix );
 
 		if ( $sanitized_prefix !== $hook_prefix ) {
-			throw new \InvalidArgumentException( 'Hook prefix must only contain lowercase letters, numbers, "_", or "-".' );
+			throw new InvalidArgumentException( 'Hook prefix must only contain lowercase letters, numbers, "_", or "-".' );
 		}
 
 		static::$hookPrefix = $hook_prefix;
@@ -95,10 +101,12 @@ public static function setHookPrefix( string $hook_prefix ) {
 	 * @param string $class
 	 *
 	 * @return void
+	 *
+	 * @throws InvalidArgumentException If the provided InvalidArgumentException class is not or does not extend InvalidArgumentException.
 	 */
 	public static function setInvalidArgumentException( string $class ) {
 		if ( ! is_a( $class, InvalidArgumentException::class, true ) ) {
-			throw new \InvalidArgumentException( 'The provided InvalidArgumentException class must be or must extend ' . InvalidArgumentException::class . '.' );
+			throw new InvalidArgumentException( 'The provided InvalidArgumentException class must be or must extend ' . InvalidArgumentException::class . '.' );
 		}
 
 		static::$invalidArgumentException = $class;
@@ -112,6 +120,8 @@ public static function setInvalidArgumentException( string $class ) {
 	 * @param string $message
 	 *
 	 * @return void
+	 *
+	 * @throws InvalidArgumentException Always, thats what it does.
 	 */
 	public static function throwInvalidArgumentException( string $message ): void {
 		throw new static::$invalidArgumentException( $message );

src/Models/Contracts/Model.php

@@ -99,7 +99,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.
@@ -110,7 +110,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/SchemaModel.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace StellarWP\Models\Contracts;
+
+interface SchemaModel extends Model {
+	public function get_primary_value();
+
+	public function set_primary_value( $value ): void;
+
+	public function getTableInterface();
+
+	public function __call( string $name, array $arguments );
+
+	public function getRelationships(): array;
+
+	public function deleteRelationshipData( string $key ): void;
+
+	public function addToRelationship( string $key, int $id ): void;
+
+	public function removeFromRelationship( string $key, int $id ): void;
+
+	public function save(): int;
+
+	public function delete(): bool;
+}

src/Models/Model.php

@@ -1,16 +1,47 @@
 <?php
+/**
+ * The model.
+ *
+ * @since 1.0.0
+ *
+ * @package StellarWP\Models;
+ */
 
 namespace StellarWP\Models;
 
 use JsonSerializable;
-use RuntimeException;
 use StellarWP\Models\Contracts\Arrayable;
 use StellarWP\Models\Contracts\Model as ModelInterface;
 use StellarWP\Models\ValueObjects\Relationship;
-
+use InvalidArgumentException;
+
+/**
+ * The model.
+ *
+ * @since 1.0.0
+ *
+ * @package StellarWP\Models;
+ */
 abstract class Model implements ModelInterface, Arrayable, JsonSerializable {
+	/**
+	 * The build mode for the model.
+	 *
+	 * @var int
+	 */
 	public const BUILD_MODE_STRICT = 0;
+
+	/**
+	 * The build mode for the model.
+	 *
+	 * @var int
+	 */
 	public const BUILD_MODE_IGNORE_MISSING = 1;
+
+	/**
+	 * The build mode for the model.
+	 *
+	 * @var int
+	 */
 	public const BUILD_MODE_IGNORE_EXTRA = 2;
 
 	/**
@@ -25,21 +56,21 @@ abstract class Model implements ModelInterface, Arrayable, JsonSerializable {
 	 *
 	 * @var array<string,string|array>
 	 */
-	protected static $properties = [];
+	protected static array $properties = [];
 
 	/**
 	 * The model relationships assigned to their relationship types.
 	 *
 	 * @var array<string,string>
 	 */
-	protected static $relationships = [];
+	protected static array $relationships = [];
 
 	/**
 	 * Relationships that have already been loaded and don't need to be loaded again.
 	 *
 	 * @var Model[]
 	 */
-	private $cachedRelations = [];
+	private array $cachedRelations = [];
 
 	/**
 	 * Constructor.
@@ -63,6 +94,8 @@ public function __construct( array $attributes = [] ) {
 	 * @param string $property The property being casted.
 	 *
 	 * @return mixed
+	 *
+	 * @throws InvalidArgumentException If the value is not valid for the property.
 	 */
 	protected static function castValueForProperty( ModelPropertyDefinition $definition, $value, string $property ) {
 		if ( $definition->isValidValue( $value ) || $value === null ) {
@@ -75,7 +108,7 @@ protected static function castValueForProperty( ModelPropertyDefinition $definit
 
 		$type = $definition->getType();
 		if ( count( $type ) !== 1 ) {
-			throw new \InvalidArgumentException( "Property '$property' has multiple types: " . implode( ', ', $type ) . ". To support additional types, implement a custom castValueForProperty() method." );
+			throw new InvalidArgumentException( "Property '$property' has multiple types: " . implode( ', ', $type ) . ". To support additional types, implement a custom castValueForProperty() method." );
 		}
 
 		switch ( $type[0] ) {
@@ -169,6 +202,8 @@ public function getAttribute( string $key, $default = null ) {
 	 * @since 1.0.0
 	 *
 	 * @return array<string,mixed>
+	 *
+	 * @throws InvalidArgumentException If the property does not exist.
 	 */
 	public function getDirty() : array {
 		return $this->propertyCollection->getDirtyValues();
@@ -178,7 +213,7 @@ public static function getPropertyDefinition( string $key ): ModelPropertyDefini
 		$definitions = static::getPropertyDefinitions();
 
 		if ( ! isset( $definitions[ $key ] ) ) {
-			throw new \InvalidArgumentException( 'Property ' . $key . ' does not exist.' );
+			throw new InvalidArgumentException( 'Property ' . $key . ' does not exist.' );
 		}
 
 		return $definitions[ $key ];
@@ -190,6 +225,8 @@ public static function getPropertyDefinition( string $key ): ModelPropertyDefini
 	 * @since 2.0.0
 	 *
 	 * @return array<string,ModelPropertyDefinition>
+	 *
+	 * @throws InvalidArgumentException If the property key is not a string.
 	 */
 	public static function getPropertyDefinitions(): array {
 		static $definition = null;
@@ -199,7 +236,7 @@ public static function getPropertyDefinitions(): array {
 
 			foreach ( $definitions as $key => $definition ) {
 				if ( ! is_string( $key ) ) {
-					throw new \InvalidArgumentException( 'Property key must be a string.' );
+					throw new InvalidArgumentException( 'Property key must be a string.' );
 				}
 
 				if ( ! $definition instanceof ModelPropertyDefinition ) {
@@ -224,7 +261,7 @@ public static function getPropertyDefinitions(): array {
 	 *
 	 * @return mixed|array
 	 */
-	public function getOriginal( string $key = null ) {
+	public function getOriginal( ?string $key = null ) {
 		return $key ? $this->propertyCollection->getOrFail( $key )->getOriginalValue() : $this->propertyCollection->getOriginalValues();
 	}
 
@@ -368,7 +405,7 @@ public static function isPropertyTypeValid( string $key, $value ) : bool {
 	 */
 	#[\ReturnTypeWillChange]
 	public function jsonSerialize() {
-		return get_object_vars( $this );
+		return $this->toArray();
 	}
 
 	/**

src/Models/ModelPropertyCollection.php

@@ -4,13 +4,19 @@
 
 namespace StellarWP\Models;
 
+use Countable;
+use IteratorAggregate;
+use InvalidArgumentException;
+use ArrayIterator;
+use Traversable;
+
 /**
  * A collection of properties for a model.
  *
  * Some philosophical notes:
  * 		* The collection is immutable. Once created, the collection cannot be changed.
  */
-class ModelPropertyCollection implements \Countable, \IteratorAggregate {
+class ModelPropertyCollection implements Countable, IteratorAggregate {
 	/**
 	 * The properties.
 	 *
@@ -23,15 +29,18 @@ class ModelPropertyCollection implements \Countable, \IteratorAggregate {
 	 *
 	 * @since 2.0.0
 	 * @param array<string,ModelProperty> $properties
+	 *
+	 * @throws InvalidArgumentException If the property key is not a string.
+	 * @throws InvalidArgumentException If the property is not an instance of ModelProperty.
 	 */
 	public function __construct( array $properties = [] ) {
 		foreach ( $properties as $key => $property ) {
 			if ( ! is_string( $key ) ) {
-				throw new \InvalidArgumentException( 'Property key must be a string.' );
+				throw new InvalidArgumentException( 'Property key must be a string.' );
 			}
 
 			if ( ! $property instanceof ModelProperty ) {
-				throw new \InvalidArgumentException( 'Property must be an instance of ModelProperty.' );
+				throw new InvalidArgumentException( 'Property must be an instance of ModelProperty.' );
 			}
 
 			$this->properties[$key] = $property;
@@ -53,7 +62,7 @@ public function commitChangedProperties(): void {
 	 * @since 2.0.0
 	 */
 	public function count(): int {
-		return count($this->properties);
+		return count( $this->properties );
 	}
 
 	/**
@@ -74,17 +83,20 @@ public function filter( callable $callback, $mode = 0 ): ModelPropertyCollection
 	 *
 	 * @param array<string,ModelPropertyDefinition> $propertyDefinitions
 	 * @return ModelPropertyCollection
+	 *
+	 * @throws InvalidArgumentException If the property key is not a string.
+	 * @throws InvalidArgumentException If the property definition is not an instance of ModelPropertyDefinition.
 	 */
 	public static function fromPropertyDefinitions( array $propertyDefinitions, array $initialValues = [] ): ModelPropertyCollection {
 		$properties = [];
 
 		foreach ( $propertyDefinitions as $key => $definition ) {
 			if ( ! is_string( $key ) ) {
-				throw new \InvalidArgumentException( 'Property key must be a string.' );
+				throw new InvalidArgumentException( 'Property key must be a string.' );
 			}
 
 			if ( ! $definition instanceof ModelPropertyDefinition ) {
-				throw new \InvalidArgumentException( 'Property definition must be an instance of ModelPropertyDefinition.' );
+				throw new InvalidArgumentException( 'Property definition must be an instance of ModelPropertyDefinition.' );
 			}
 
 			if ( isset( $initialValues[$key] ) ) {
@@ -102,8 +114,8 @@ public static function fromPropertyDefinitions( array $propertyDefinitions, arra
 	 *
 	 * @since 2.0.0
 	 */
-	public function getIterator(): \Traversable {
-		return new \ArrayIterator($this->properties);
+	public function getIterator(): Traversable {
+		return new ArrayIterator($this->properties);
 	}
 
 	/**
@@ -137,10 +149,12 @@ public function getDirtyValues(): array {
 	 * Get a property by key. If the property does not exist, throw an exception.
 	 *
 	 * @since 2.0.0
+	 *
+	 * @throws InvalidArgumentException If the property does not exist.
 	 */
 	public function getOrFail( string $key ): ModelProperty {
 		if ( ! $this->has( $key ) ) {
-			throw new \InvalidArgumentException( 'Property ' . $key . ' does not exist.' );
+			throw new InvalidArgumentException( 'Property ' . $key . ' does not exist.' );
 		}
 
 		return $this->properties[$key];
@@ -265,17 +279,24 @@ public function revertProperty( string $key ): void {
 	 * Set the values of the properties.
 	 *
 	 * @since 2.0.0
+	 *
+	 * @throws InvalidArgumentException If the property does not exist.
 	 */
 	public function setValues( array $values ) {
 		foreach ( $values as $key => $value ) {
 			if ( ! $this->has( $key ) ) {
-				throw new \InvalidArgumentException( 'Property ' . $key . ' does not exist.' );
+				throw new InvalidArgumentException( 'Property ' . $key . ' does not exist.' );
 			}
 
 			$this->properties[$key]->setValue( $value );
 		}
 	}
 
+	/**
+	 * Tap the properties.
+	 *
+	 * @since 2.0.0
+	 */
 	public function tap( callable $callback ): self {
 		foreach ( $this->properties as $property ) {
 			$callback( $property );

src/Models/ModelPropertyDefinition.php

@@ -263,7 +263,7 @@ public function requiredOnSave(): self {
 	 * Whether the property supports the given type.
 	 */
 	public function supportsType( string $type ): bool {
-		return in_array( $type, $this->type );
+		return in_array( $type, $this->type, true );
 	}
 
 	/**