refactor: strengthens types across files

Author: JasonTheAdams

src/Models/Contracts/ModelCrud.php

@@ -7,7 +7,7 @@
 /**
  * @since 1.0.0
  */
-interface ModelCrud {
+interface ModelCrud extends ModelBuildsFromData {
 	/**
 	 * @since 1.0.0
 	 *

src/Models/Model.php

@@ -4,7 +4,6 @@
 
 use InvalidArgumentException;
 use JsonSerializable;
-use RuntimeException;
 use StellarWP\Models\Contracts\Arrayable;
 use StellarWP\Models\Contracts\Model as ModelInterface;
 use StellarWP\Models\ValueObjects\Relationship;
@@ -38,7 +37,7 @@ abstract class Model implements ModelInterface, Arrayable, JsonSerializable {
 	/**
 	 * Relationships that have already been loaded and don't need to be loaded again.
 	 *
-	 * @var array<string,Model|list<Model>>
+	 * @var array<string,Model|list<Model>|null>
 	 */
 	private $cachedRelations = [];
 
@@ -59,17 +58,20 @@ final public function __construct( array $attributes = [] ) {
 	 *
 	 * @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.
+	protected function afterConstruct(): void {
 		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.
 	 *
+	 * Note: Type casting is performed at runtime based on property definitions. PHPStan cannot statically verify
+	 * the resulting types, so we suppress type-checking errors for the cast operations.
+	 *
 	 * @since 2.0.0 changed to static
 	 *
-	 * @param string $type
+	 * @param ModelPropertyDefinition $definition The property definition.
 	 * @param mixed  $value The query data value to cast, probably a string.
 	 * @param string $property The property being casted.
 	 *
@@ -89,11 +91,12 @@ protected static function castValueForProperty( ModelPropertyDefinition $definit
 			throw new InvalidArgumentException( "Property '$property' has multiple types: " . implode( ', ', $type ) . ". To support additional types, implement a custom castValueForProperty() method." );
 		}
 
+		// Runtime type casting based on property definition - PHPStan cannot verify this statically
 		switch ( $type[0] ) {
 			case 'int':
-				return (int) $value;
+				return (int) $value; // @phpstan-ignore-line
 			case 'string':
-				return (string) $value;
+				return (string) $value; // @phpstan-ignore-line
 			case 'bool':
 				return (bool) filter_var( $value, FILTER_VALIDATE_BOOLEAN );
 			case 'array':
@@ -203,10 +206,13 @@ public static function getPropertyDefinition( string $key ): ModelPropertyDefini
 	 * @return array<string,ModelPropertyDefinition>
 	 */
 	public static function getPropertyDefinitions(): array {
-		static $definition = null;
+		/** @var array<string,ModelPropertyDefinition>|null $cachedDefinitions */
+		static $cachedDefinitions = null;
 
-		if ( $definition === null ) {
+		if ( $cachedDefinitions === null ) {
 			$definitions = array_merge( static::$properties, static::properties() );
+			/** @var array<string,ModelPropertyDefinition> $processedDefinitions */
+			$processedDefinitions = [];
 
 			foreach ( $definitions as $key => $definition ) {
 				if ( ! is_string( $key ) ) {
@@ -217,13 +223,13 @@ public static function getPropertyDefinitions(): array {
 					$definition = ModelPropertyDefinition::fromShorthand( $definition );
 				}
 
-				$definitions[ $key ] = $definition->lock();
+				$processedDefinitions[ $key ] = $definition->lock();
 			}
 
-			$definition = $definitions;
+			$cachedDefinitions = $processedDefinitions;
 		}
 
-		return $definition;
+		return $cachedDefinitions;
 	}
 
 	/**
@@ -251,6 +257,36 @@ public function isSet( string $key ): bool {
 		return $this->propertyCollection->isSet( $key );
 	}
 
+	/**
+	 * Checks if a method exists that returns a ModelQueryBuilder instance.
+	 *
+	 * @since 2.0.0
+	 *
+	 * @param string $method Method name.
+	 *
+	 * @return bool
+	 */
+	protected function hasRelationshipMethod( string $method ): bool {
+		if ( ! method_exists( $this, $method ) ) {
+			return false;
+		}
+
+		try {
+			$reflectionMethod = new \ReflectionMethod( $this, $method );
+			$returnType = $reflectionMethod->getReturnType();
+
+			if ( ! $returnType instanceof \ReflectionNamedType ) {
+				return false;
+			}
+
+			$typeName = $returnType->getName();
+
+			return $typeName === ModelQueryBuilder::class || is_subclass_of( $typeName, ModelQueryBuilder::class );
+		} catch ( \ReflectionException $e ) {
+			return false;
+		}
+	}
+
 	/**
 	 * Returns a relationship.
 	 *
@@ -261,7 +297,7 @@ public function isSet( string $key ): bool {
 	 * @return Model|list<Model>|null
 	 */
 	protected function getRelationship( string $key ) {
-		if ( ! is_callable( [ $this, $key ] ) ) {
+		if ( ! $this->hasRelationshipMethod( $key ) ) {
 			$exception = Config::getInvalidArgumentException();
 			throw new $exception( "$key() does not exist." );
 		}
@@ -270,16 +306,23 @@ protected function getRelationship( string $key ) {
 			return $this->cachedRelations[ $key ];
 		}
 
-		$relationship = static::$relationships[ $key ];
+		/** @var ModelQueryBuilder<Model> $queryBuilder */
+		$queryBuilder = $this->$key();
 
-		switch ( $relationship ) {
+		switch ( static::$relationships[ $key ] ) {
 			case Relationship::BELONGS_TO:
 			case Relationship::HAS_ONE:
-				return $this->cachedRelations[ $key ] = $this->$key()->get();
+				$result = $queryBuilder->get();
+				/** @var Model|null $result */
+				$this->cachedRelations[ $key ] = $result;
+				return $result;
 			case Relationship::HAS_MANY:
 			case Relationship::BELONGS_TO_MANY:
 			case Relationship::MANY_TO_MANY:
-				return $this->cachedRelations[ $key ] = $this->$key()->getAll();
+				$result = $queryBuilder->getAll();
+				/** @var list<Model>|null $result */
+				$this->cachedRelations[ $key ] = $result;
+				return $result;
 		}
 
 		return null;
@@ -413,7 +456,7 @@ public static function fromData($data, $mode = self::BUILD_MODE_IGNORE_EXTRA) {
 
 		$initialValues = [];
 
-		foreach (static::$properties as $key => $type) {
+		foreach (static::$properties as $key => $_) {
 			if ( ! array_key_exists( $key, $data ) ) {
 				// Skip missing properties when BUILD_MODE_IGNORE_MISSING is set
 				if ( $mode & self::BUILD_MODE_IGNORE_MISSING ) {
@@ -422,7 +465,6 @@ public static function fromData($data, $mode = self::BUILD_MODE_IGNORE_EXTRA) {
 				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().
 			$initialValues[ $key ] = static::castValueForProperty( static::getPropertyDefinition( $key ), $data[ $key ], $key );
 		}
 

src/Models/ModelFactory.php

@@ -59,7 +59,7 @@ public function make( array $attributes = [] ) {
 	/**
 	 * @since 1.2.3
 	 */
-	public function makeAndResolveTo($property): Closure
+	public function makeAndResolveTo(string $property): Closure
 	{
 		return function() use ($property) {
 			return is_array($results = $this->make())
@@ -92,7 +92,7 @@ public function create( array $attributes = [] ) {
 	/**
 	 * @since 1.2.3
 	 */
-	public function createAndResolveTo( $property ): Closure {
+	public function createAndResolveTo( string $property ): Closure {
 		return function() use ( $property ) {
 			return is_array( $results = $this->create() )
 				? array_column( $results, $property )
@@ -106,6 +106,7 @@ public function createAndResolveTo( $property ): Closure {
 	 * @since 1.2.3 Add support for resolving Closures.
 	 * @since 1.0.0
 	 *
+	 * @param array<string,mixed> $attributes
 	 * @return M
 	 */
 	protected function makeInstance( array $attributes ) {
@@ -123,6 +124,8 @@ function( $attribute ) {
 	 * Configure the factory.
 	 *
 	 * @since 1.0.0
+	 *
+	 * @return ModelFactory<M>
 	 */
 	public function configure() : self {
 		return $this;
@@ -132,6 +135,8 @@ public function configure() : self {
 	 * Sets the number of models to generate.
 	 *
 	 * @since 1.0.0
+	 *
+	 * @return ModelFactory<M>
 	 */
 	public function count( int $count ) : self {
 		$this->count = $count;

src/Models/ModelProperty.php

@@ -83,6 +83,8 @@ public function getKey(): string {
 	 * Get the original value of the property.
 	 *
 	 * @since 2.0.0
+	 *
+	 * @return mixed
 	 */
 	public function getOriginalValue() {
 		return $this->originalValue;
@@ -92,6 +94,8 @@ public function getOriginalValue() {
 	 * Get the value of the property.
 	 *
 	 * @since 2.0.0
+	 *
+	 * @return mixed
 	 */
 	public function getValue() {
 		return $this->value ?? null;
@@ -153,6 +157,8 @@ public function commitChanges(): void {
 	 * Sets the value of the property.
 	 *
 	 * @since 2.0.0
+	 *
+	 * @param mixed $value
 	 */
 	public function setValue( $value ): self {
 		if ( ! $this->definition->isValidValue( $value ) ) {

src/Models/ModelPropertyCollection.php

@@ -67,7 +67,7 @@ public function count(): int {
 	 *
 	 * @since 2.0.0
 	 *
-	 * @param callable(ModelProperty,string):bool $callback
+	 * @param callable $callback
 	 * @param int $mode The mode as used in array_filter() which determines the arguments passed to the callback.
 	 */
 	public function filter( callable $callback, $mode = 0 ): ModelPropertyCollection {
@@ -80,6 +80,7 @@ public function filter( callable $callback, $mode = 0 ): ModelPropertyCollection
 	 * @since 2.0.0
 	 *
 	 * @param array<string,ModelPropertyDefinition> $propertyDefinitions
+	 * @param array<string,mixed> $initialValues
 	 * @return ModelPropertyCollection
 	 */
 	public static function fromPropertyDefinitions( array $propertyDefinitions, array $initialValues = [] ): ModelPropertyCollection {
@@ -241,11 +242,14 @@ public function isSet( string $key ): bool {
 	 * @return array<string,TMapValue>
 	 */
 	public function map( callable $callback ) {
-		return $this->reduce( static function( $carry, ModelProperty $property ) use ( $callback ) {
+		$reducer = static function( array $carry, ModelProperty $property ) use ( $callback ): array {
 			$carry[ $property->getKey() ] = $callback( $property );
 
 			return $carry;
-		}, [] );
+		};
+
+		/** @var array<string,TMapValue> */
+		return $this->reduce( $reducer, [] );
 	}
 
 	/**
@@ -255,7 +259,7 @@ public function map( callable $callback ) {
 	 *
 	 * @template TReduceInitial
 	 * @template TReduceResult
-	 * @param callable(TReduceResult,ModelProperty):TReduceResult $callback
+	 * @param callable(TReduceInitial|TReduceResult,ModelProperty):(TReduceInitial|TReduceResult) $callback
 	 * @param TReduceInitial $initial
 	 * @return TReduceResult|TReduceInitial
 	 */
@@ -288,7 +292,7 @@ public function revertProperty( string $key ): void {
 	 *
 	 * @param array<string,mixed> $values
 	 */
-	public function setValues( array $values ) {
+	public function setValues( array $values ): void {
 		foreach ( $values as $key => $value ) {
 			if ( ! $this->has( $key ) ) {
 				throw new InvalidArgumentException( 'Property ' . $key . ' does not exist.' );
@@ -317,6 +321,8 @@ public function tap( callable $callback ): self {
 	 * Unset a property.
 	 *
 	 * @since 2.0.0
+	 *
+	 * @param string $key
 	 */
 	public function unsetProperty( $key ): void {
 		$this->getOrFail( $key )->unset();

src/Models/ModelPropertyDefinition.php

@@ -28,7 +28,7 @@ class ModelPropertyDefinition {
 	 *
 	 * @since 2.0.0
 	 *
-	 * @var Closure|null A closure that accepts the value and property instance as parameters and returns the cast value.
+	 * @var Closure A closure that accepts the value and property instance as parameters and returns the cast value.
 	 */
 	private Closure $castMethod;
 
@@ -274,6 +274,7 @@ public function isValidValue( $value ): bool {
 			case 'double':
 				return $this->supportsType( 'float' );
 			case 'object':
+				/** @var object $value */
 				if ( $this->supportsType( 'object' ) ) {
 					return true;
 				} else {

src/Models/ModelQueryBuilder.php

@@ -40,7 +40,7 @@ public function __construct( string $modelClass ) {
 	 *
 	 * @param null|string $column
 	 */
-	public function count( ?string $column = null ) : int {
+	public function count( $column = null ) : int {
 		$column = ( ! $column || $column === '*' ) ? '1' : trim( $column );
 
 		if ( '1' === $column ) {
@@ -60,10 +60,11 @@ public function count( ?string $column = null ) : int {
 	 *
 	 * @param string $output
 	 *
-	 * @return M|null
+	 * @return M|array<string,mixed>|object|null
 	 */
-	public function get( $output = self::MODEL ): ?Model {
+	public function get( $output = self::MODEL ) {
 		if ( $output !== self::MODEL ) {
+			/** @var array<string,mixed>|object|null */
 			return parent::get( $output );
 		}
 
@@ -73,6 +74,7 @@ public function get( $output = self::MODEL ): ?Model {
 			return null;
 		}
 
+		/** @var array<string,mixed>|object $row */
 		return $this->model::fromData( $row );
 	}
 
@@ -81,19 +83,22 @@ public function get( $output = self::MODEL ): ?Model {
 	 *
 	 * @since 1.0.0
 	 *
-	 * @return list<M>|null
+	 * @return list<M|array<string,mixed>|object>|null
 	 */
 	public function getAll( $output = self::MODEL ) : ?array {
 		if ( $output !== self::MODEL ) {
+			/** @var list<array<string,mixed>|object>|null */
 			return parent::getAll( $output );
 		}
 
+		/** @var list<object> */
 		$results = DB::get_results( $this->getSQL() );
 
 		if ( ! $results ) {
 			return null;
 		}
 
+		/** @var list<M> */
 		return array_map( [ $this->model, 'fromData' ], $results );
 	}
 }