Document existing database value shapes

.wordlist.txt

@@ -23,4 +23,38 @@ Traceback
 nodejs
 npm
 fediverse
-readme
+readme
+CacheableService
+ClauseBuilder
+datastore
+DatabaseServiceProvider
+DateCreatedFactory
+DateModifiedFactory
+EventStrategy
+findMultiple
+ForeignKeyFactory
+getUnprefixedName
+getIndices
+https
+IdentifiableDatabaseDatastoreHandler
+idx
+JunctionTable
+LoggerStrategy
+lookups
+modelAdapter
+PHPNomad
+phpnomad
+postHandler
+PostDatabaseDatastoreHandler
+PostsTable
+PrimaryKeyFactory
+QueryBuilder
+QueryStrategy
+schemas
+serviceProvider
+TableSchemaService
+tableSchemaService
+toColumn
+txt
+VARCHAR
+WithDatastoreHandlerMethods

lib/Factories/Column.php

@@ -6,7 +6,9 @@ final class Column
 {
     protected string $name;
     protected string $type;
+    /** @var array<array-key, mixed>|null */
     protected ?array $typeArgs = null;
+    /** @var array<array-key, mixed> */
     protected array $attributes = [];
 
     /**
@@ -17,8 +19,8 @@ final class Column
 	/**
 	 * @param string   $name
 	 * @param string   $type
-	 * @param array|null $typeArgs
-	 * @param          ...$attributes
+	 * @param array<array-key, mixed>|null $typeArgs
+	 * @param mixed ...$attributes
 	 */
     public function __construct(string $name, string $type, ?array $typeArgs = null, ...$attributes)
     {
@@ -51,15 +53,15 @@ public function getType(): string
     /**
      * Returns the length limitation on the item, or null if not set.
      *
-     * @return ?array
+     * @return array<array-key, mixed>|null
      */
     public function getTypeArgs(): ?array
     {
         return $this->typeArgs;
     }
 
     /**
-     * @return string[]
+     * @return array<array-key, mixed>
      */
     public function getAttributes(): array
     {

lib/Factories/Index.php

@@ -5,10 +5,16 @@
 final class Index
 {
     protected ?string $name;
+    /** @var array<array-key, mixed> */
     protected array $columns;
     protected ?string $type = null;
+    /** @var array<array-key, mixed> */
     protected array $attributes = [];
 
+    /**
+     * @param array<array-key, mixed> $columns
+     * @param mixed ...$attributes
+     */
     public function __construct(
         array $columns,
         ?string $name = null,
@@ -34,7 +40,7 @@ public function getName(): ?string
     /**
      * Gets the columns that are part of the index.
      *
-     * @return array|string[]
+     * @return array<array-key, mixed>
      */
     public function getColumns(): array
     {
@@ -54,7 +60,7 @@ public function getType(): ?string
     /**
      * Gets any additional attributes or options for the index.
      *
-     * @return array
+     * @return array<array-key, mixed>
      */
     public function getAttributes(): array
     {

lib/Interfaces/JunctionTableQueryService.php

@@ -22,7 +22,7 @@ public function getIdsFromTable(string $tableName, int $id, int $limit, int $off
     /**
      * Associates the specified ID with the junctioning ID of the other table.
      *
-     * @param string $tableName The name table the ID came from.
+     * @param string $table The name table the ID came from.
      * @param int $id The ID associated with the $table argument.
      * @param int $bindingId The ID to bind the ID to.
      * @return void
@@ -33,10 +33,10 @@ public function bind(string $table, int $id, int $bindingId): void;
     /**
      * Disassociates the specified ID with the junctioning ID of the other table.
      *
-     * @param string $tableName The name table the ID came from.
+     * @param string $table The name table the ID came from.
      * @param int $id The ID associated with the $table argument.
      * @param int $bindingId The ID to bind the ID to.
      * @return void
      */
     public function unbind(string $table, int $id, int $bindingId): void;
-}
+}

lib/Services/TableSchemaService.php

@@ -155,7 +155,7 @@ public function getJunctionColumnNameFromTable(TableInterface $table): string
 
     /**
      * @param TableInterface $table
-     * @return mixed
+     * @return Column
      * @throws ColumnNotFoundException
      */
     public function getPrimaryColumnNameForTable(TableInterface $table): Column
@@ -167,15 +167,17 @@ public function getPrimaryColumnNameForTable(TableInterface $table): Column
             throw new ColumnNotFoundException('Junction Tables must have exactly one primary key column.');
         }
 
-        return Arr::first($primaryColumns);
+        /** @var Column $primaryColumn */
+        $primaryColumn = Arr::first($primaryColumns);
+
+        return $primaryColumn;
     }
 
     /**
      * Gets the cache key for this table. Used to cut back on processing when making this table.
      *
-     * @param TableInterface $table
      * @param string $id
-     * @return array
+     * @return array{for: class-string, id: string}
      */
     protected function getCacheContext(string $id): array
     {

lib/Traits/WithDatastoreHandlerMethods.php

@@ -195,7 +195,7 @@ protected function applyPhpDefaults(array $attributes): array
     /**
      * Delete all items that fit the specified condition.
      *
-     * @param array $conditions
+     * @param array<array-key, mixed> $conditions
      * @return void
      * @throws DatastoreErrorException
      */
@@ -213,6 +213,7 @@ public function deleteWhere(array $conditions): void
     }
 
     /**
+     * @param array<array-key, string>|null $select
      * @return $this
      */
     protected function initiateQuery(?int $limit = null, ?int $offset = null, ?string $orderBy = null, string $order = 'ASC', array $select = null)
@@ -307,7 +308,7 @@ protected function buildConditions(array $groups)
      * one of them, leaving the other to serve stale reads.
      *
      * @param array<string, int|string> $identities list of identities keyed by the field name for the identity.
-     * @return array
+     * @return array<array-key, mixed>
      */
     protected function getCacheContextForItem(array $identities): array
     {
@@ -462,8 +463,8 @@ public function updateCompound($ids, array $attributes): void
     }
 
     /**
-     * @param array $attributes
-     * @param array $fields
+     * @param array<array-key, mixed> $attributes
+     * @param array<array-key, mixed> $fields
      * @return void
      * @throws DatastoreErrorException
      * @throws DuplicateEntryException
@@ -496,9 +497,9 @@ protected function maybeThrowForDuplicateIdentity(array $attributes, array $fiel
     }
 
     /**
-     * @param array $attributes
-     * @param array $fields
-     * @return array
+     * @param array<array-key, mixed> $attributes
+     * @param array<array-key, mixed> $fields
+     * @return array<array-key, mixed>
      */
     protected function removeIdentifiableFields(array $attributes, array $fields): array
     {
@@ -508,7 +509,7 @@ protected function removeIdentifiableFields(array $attributes, array $fields): a
     /**
      * Looks up records to check if a record with the specified unique columns already exists.
      *
-     * @param array $data
+     * @param array<array-key, mixed> $data
      * @return DataModel[] List of existing items that match the unique constraints.
      * @throws DatastoreErrorException
      * @throws RecordNotFoundException
@@ -553,8 +554,8 @@ protected function getDuplicates(array $data): array
 
 
     /**
-     * @param array $data
-     * @param array|null $updateIdentity
+     * @param array<array-key, mixed> $data
+     * @param array<array-key, mixed>|null $updateIdentity
      * @return void
      * @throws DuplicateEntryException
      * @throws DatastoreErrorException

tests/Unit/Traits/WithDatastoreHandlerMethodsTest.php

@@ -337,6 +337,10 @@ class DummyDatastoreHandler
 {
     use WithDatastoreHandlerMethods;
 
+    /**
+     * @param class-string<DataModel> $model
+     * @param ModelAdapter<DataModel> $modelAdapter
+     */
     public function __construct(
         DatabaseServiceProvider $serviceProvider,
         Table $table,
@@ -351,11 +355,19 @@ public function __construct(
         $this->modelAdapter = $modelAdapter;
     }
 
+    /**
+     * @param non-empty-array<string, int> $ids
+     * @return mixed
+     */
     public function findByIdentity(array $ids)
     {
         return $this->findFromCompound($ids);
     }
 
+    /**
+     * @param array<string, int|string> $ids
+     * @return array<array-key, mixed>
+     */
     public function exposeCacheContext(array $ids): array
     {
         return $this->getCacheContextForItem($ids);