Correct datastore static contracts

composer.json

@@ -24,6 +24,9 @@
             "email": "alex@standiford.us"
         }
     ],
+    "require": {
+        "phpnomad/event": "^1.0"
+    },
     "require-dev": {
         "doctrine/instantiator": "^1.5",
         "myclabs/deep-copy": ">=1.13.4 <1.14",

lib/Events/ModelsMerged.php

@@ -10,14 +10,19 @@
  */
 class ModelsMerged implements Event
 {
+    /** @var T */
     protected DataModel $mergedModel;
+
+    /** @var array<array-key, T> */
     protected array $removedModels;
+
+    /** @var T */
     protected DataModel $originalModel;
 
     /**
      * @param T $mergedModel
      * @param T $originalModel
-     * @param T[] $removedModels
+     * @param array<array-key, T> $removedModels
      */
     public function __construct(DataModel $mergedModel, DataModel $originalModel, array $removedModels)
     {
@@ -35,7 +40,7 @@ public function getOriginalModel(): DataModel
     }
 
     /**
-     * @return T[]
+     * @return array<array-key, T>
      */
     public function getRemovedModels(): array
     {
@@ -54,4 +59,4 @@ public static function getId(): string
     {
         return 'datastore_models_merged';
     }
-}
+}

lib/Events/RecordDeleted.php

@@ -8,11 +8,13 @@
 class RecordDeleted implements Event
 {
     protected string $type;
+
+    /** @var array<string, mixed> */
     protected array $identity;
 
     /**
      * @param class-string<DataModel>|string $type
-     * @param array $identity
+     * @param array<string, mixed> $identity
      */
     public function __construct(string $type, array $identity)
     {
@@ -23,7 +25,7 @@ public function __construct(string $type, array $identity)
     /**
      * Gets the identity for the record that was deleted.
      *
-     * @return array
+     * @return array<string, mixed>
      */
     public function getIdentity(): array
     {
@@ -44,4 +46,4 @@ public static function getId(): string
     {
         return 'record_deleted';
     }
-}
+}

lib/Events/RecordUpdated.php

@@ -6,10 +6,17 @@
 
 class RecordUpdated implements Event
 {
+	/** @var array<string, mixed> */
 	protected array  $data;
+
+	/** @var array<string, mixed> */
 	protected array  $identity;
 	protected string $type;
 
+	/**
+	 * @param array<string, mixed> $identity
+	 * @param array<string, mixed> $data
+	 */
 	public function __construct(string $type, array $identity, array $data)
 	{
 		$this->identity = $identity;
@@ -20,7 +27,7 @@ public function __construct(string $type, array $identity, array $data)
 	/**
 	 * Gets the data used to store the record in the database.
 	 *
-	 * @return array
+	 * @return array<string, mixed>
 	 */
 	public function getData() : array
 	{
@@ -30,7 +37,7 @@ public function getData() : array
 	/**
 	 * Gets the identity for the record that was updated.
 	 *
-	 * @return array
+	 * @return array<string, mixed>
 	 */
 	public function getIdentity() : array
 	{
@@ -51,4 +58,4 @@ public static function getId() : string
 	{
 		return 'record_updated';
 	}
-}
+}

lib/Factories/IdentityToWhere.php

@@ -4,8 +4,10 @@
 
 class IdentityToWhere
 {
+    /** @var array<string, mixed> */
     protected array $identity;
 
+    /** @param array<string, mixed> $identity */
     public function __construct(array $identity)
     {
         $this->identity = $identity;
@@ -14,7 +16,7 @@ public function __construct(array $identity)
     /**
      * Returns the where statement for a given identity.
      *
-     * @return array
+     * @return array<array-key, array{column: string, operator: '=', value: mixed}>
      */
     public function toWhere(): array
     {
@@ -25,4 +27,4 @@ public function toWhere(): array
 
         return $where;
     }
-}
+}

lib/Interfaces/CanConvertModelToArray.php

@@ -9,7 +9,7 @@ interface CanConvertModelToArray
 {
     /**
      * @param TModel $model
-     * @return array
+     * @return array<string, mixed>
      */
     public function toArray(DataModel $model): array;
-}
+}

lib/Interfaces/Datastore.php

@@ -7,7 +7,7 @@
 use PHPNomad\Datastore\Exceptions\RecordNotFoundException;
 
 /**
- * @template T of <DataModel>
+ * @template T of DataModel
  */
 interface Datastore
 {

lib/Interfaces/DatastoreHasCounts.php

@@ -19,7 +19,11 @@ public function getEstimatedCount(): int;
     /**
      * Count the results with conditions, using AND/OR.
      *
-     * @param array{type: string, clauses: array{column: string, operator: string, value: mixed}[]} $conditions
+     * @param list<array{
+     *     type?: string,
+     *     groupType?: string,
+     *     clauses: list<array{column: string|list<string>, operator: string, value: mixed}>
+     * }> $conditions
      * @return int
      * @throws DatastoreErrorException
      */
@@ -42,4 +46,4 @@ public function countAndWhere(array $conditions): int;
      * @throws DatastoreErrorException
      */
     public function countOrWhere(array $conditions): int;
-}
+}

lib/Interfaces/DatastoreHasPrimaryKey.php

@@ -21,8 +21,8 @@ public function find($id): DataModel;
     /**
      * Retrieve a set of records by their primary keys.
      *
-     * @param array $ids
-     * @return array
+     * @param array<array-key, mixed> $ids
+     * @return array<array-key, DataModel>
      * @throws DatastoreErrorException
      */
     public function findMultiple(array $ids): array;
@@ -48,4 +48,4 @@ public function update($id, array $attributes): void;
      * @throws RecordNotFoundException
      */
     public function delete($id): void;
-}
+}

lib/Interfaces/DatastoreHasWhere.php

@@ -7,14 +7,14 @@
 use PHPNomad\Datastore\Exceptions\RecordNotFoundException;
 
 /**
- * @template T of <DataModel>
+ * @template T of DataModel
  */
 interface DatastoreHasWhere {
     /**
      * Query with conditions, using a combination of AND/OR.
      * Classes implementing this should assume type and groupType are AND if they are not set.
      *
-     * @param array{type?: string, groupType?: string, clauses: array{column: string, operator: string, value: mixed}[]}[] $conditions
+     * @param array<array-key, array{type?: string, groupType?: string, clauses: array<array-key, array{column: string|list<string>, operator: string, value: mixed}>}> $conditions
      * @param positive-int|null $limit
      * @param positive-int|null $offset
      * @return T[]
@@ -25,7 +25,7 @@ public function where(array $conditions, ?int $limit = null, ?int $offset = null
     /**
      * Query with conditions, using AND.
      *
-     * @param array{column: string, operator: string, value: mixed}[] $conditions
+     * @param array<array-key, array{column: string|list<string>, operator: string, value: mixed}> $conditions
      * @param positive-int|null $limit
      * @param positive-int|null $offset
      * @return T[]
@@ -36,7 +36,7 @@ public function andWhere(array $conditions, ?int $limit = null, ?int $offset = n
     /**
      * Query with conditions, using OR.
      *
-     * @param array{column: string, operator: string, value: mixed}[] $conditions
+     * @param array<array-key, array{column: string|list<string>, operator: string, value: mixed}> $conditions
      * @param positive-int|null $limit
      * @param positive-int|null $offset
      * @return T[]
@@ -57,10 +57,10 @@ public function deleteWhere(array $conditions): void;
      * Finds the first available record that has the specified value in the specified column.
      *
      * @param string $field
-     * @param $value
+     * @param mixed $value
      * @return T
      * @throws DatastoreErrorException
      * @throws RecordNotFoundException
      */
     public function findBy(string $field, $value): DataModel;
-}
+}

lib/Interfaces/JunctionContextProvider.php

@@ -14,7 +14,7 @@ public function getResource(): string;
     /**
      * Gets the datastore that binds to the opposite table.
      *
-     * @return Datastore&DatastoreHasPrimaryKey
+     * @return Datastore<DataModel>&DatastoreHasPrimaryKey
      */
     public function getDatastore(): Datastore;
 
@@ -24,4 +24,4 @@ public function getDatastore(): Datastore;
      * @return string
      */
     public function getJunctionFieldName(): string;
-}
+}

lib/Interfaces/JunctionHandler.php

@@ -26,7 +26,7 @@ public function getIdsFromResource(string $resource, int $id, int $limit, int $o
      * @param int $id
      * @param int $limit
      * @param int $offset
-     * @return array
+     * @return array<array-key, DataModel>
      * @throws DatastoreErrorException
      */
     public function getModelsFromResource(string $resource, int $id, int $limit, int $offset): array;
@@ -63,4 +63,4 @@ public function bind(string $resource, int $id, int $bindingId): void;
      * @throws DatastoreErrorException
      */
     public function unbind(string $resource, int $id, int $bindingId): void;
-}
+}

lib/Interfaces/ModelAdapter.php

@@ -4,12 +4,13 @@
 
 /**
  * @template TModel of DataModel
+ * @extends CanConvertModelToArray<TModel>
  */
 interface ModelAdapter extends CanConvertModelToArray
 {
     /**
-     * @param array $array
+     * @param array<string, mixed> $array
      * @return TModel
      */
     public function toModel(array $array): DataModel;
-}
+}