From 94fb93494dcdec2264744b4bc820a4a3f0af03ac Mon Sep 17 00:00:00 2001 From: Alex Standiford Date: Sun, 20 Sep 2026 15:14:57 -0400 Subject: [PATCH 1/4] Document existing database value shapes --- .wordlist.txt | 36 +++++++++++++++++++- lib/Factories/Column.php | 10 +++--- lib/Factories/Index.php | 10 ++++-- lib/Interfaces/JunctionTableQueryService.php | 6 ++-- 4 files changed, 52 insertions(+), 10 deletions(-) diff --git a/.wordlist.txt b/.wordlist.txt index 7261aef..cd9cad6 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -23,4 +23,38 @@ Traceback nodejs npm fediverse -readme \ No newline at end of file +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 diff --git a/lib/Factories/Column.php b/lib/Factories/Column.php index fdc82a4..cd737d4 100644 --- a/lib/Factories/Column.php +++ b/lib/Factories/Column.php @@ -6,7 +6,9 @@ final class Column { protected string $name; protected string $type; + /** @var array|null */ protected ?array $typeArgs = null; + /** @var array */ protected array $attributes = []; /** @@ -17,8 +19,8 @@ final class Column /** * @param string $name * @param string $type - * @param array|null $typeArgs - * @param ...$attributes + * @param array|null $typeArgs + * @param mixed ...$attributes */ public function __construct(string $name, string $type, ?array $typeArgs = null, ...$attributes) { @@ -51,7 +53,7 @@ public function getType(): string /** * Returns the length limitation on the item, or null if not set. * - * @return ?array + * @return array|null */ public function getTypeArgs(): ?array { @@ -59,7 +61,7 @@ public function getTypeArgs(): ?array } /** - * @return string[] + * @return array */ public function getAttributes(): array { diff --git a/lib/Factories/Index.php b/lib/Factories/Index.php index a79686e..f1b6dce 100644 --- a/lib/Factories/Index.php +++ b/lib/Factories/Index.php @@ -5,10 +5,16 @@ final class Index { protected ?string $name; + /** @var array */ protected array $columns; protected ?string $type = null; + /** @var array */ protected array $attributes = []; + /** + * @param array $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 */ 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 */ public function getAttributes(): array { diff --git a/lib/Interfaces/JunctionTableQueryService.php b/lib/Interfaces/JunctionTableQueryService.php index b0ad041..d11a1c3 100644 --- a/lib/Interfaces/JunctionTableQueryService.php +++ b/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; -} \ No newline at end of file +} From cb178052a1ae7ebaa74d8af869328ebb68a77fd7 Mon Sep 17 00:00:00 2001 From: Alex Standiford Date: Sun, 20 Sep 2026 15:19:03 -0400 Subject: [PATCH 2/4] Document table schema result shapes --- lib/Services/TableSchemaService.php | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/lib/Services/TableSchemaService.php b/lib/Services/TableSchemaService.php index b96c361..9c963eb 100644 --- a/lib/Services/TableSchemaService.php +++ b/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 { From bab7d2634442a62f3db2bf36bab744e1d56ce02f Mon Sep 17 00:00:00 2001 From: Alex Standiford Date: Sun, 20 Sep 2026 15:20:08 -0400 Subject: [PATCH 3/4] Document datastore trait test shapes --- .../Unit/Traits/WithDatastoreHandlerMethodsTest.php | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/tests/Unit/Traits/WithDatastoreHandlerMethodsTest.php b/tests/Unit/Traits/WithDatastoreHandlerMethodsTest.php index 82a7b08..dafe973 100644 --- a/tests/Unit/Traits/WithDatastoreHandlerMethodsTest.php +++ b/tests/Unit/Traits/WithDatastoreHandlerMethodsTest.php @@ -337,6 +337,10 @@ class DummyDatastoreHandler { use WithDatastoreHandlerMethods; + /** + * @param class-string $model + * @param ModelAdapter $modelAdapter + */ public function __construct( DatabaseServiceProvider $serviceProvider, Table $table, @@ -351,11 +355,19 @@ public function __construct( $this->modelAdapter = $modelAdapter; } + /** + * @param non-empty-array $ids + * @return mixed + */ public function findByIdentity(array $ids) { return $this->findFromCompound($ids); } + /** + * @param array $ids + * @return array + */ public function exposeCacheContext(array $ids): array { return $this->getCacheContextForItem($ids); From 792b67999397d2373dee93ca7eef8c23794f1da4 Mon Sep 17 00:00:00 2001 From: Alex Standiford Date: Sun, 20 Sep 2026 15:29:17 -0400 Subject: [PATCH 4/4] Document datastore trait iterable values --- lib/Traits/WithDatastoreHandlerMethods.php | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/lib/Traits/WithDatastoreHandlerMethods.php b/lib/Traits/WithDatastoreHandlerMethods.php index dbd3ac6..e9a2949 100644 --- a/lib/Traits/WithDatastoreHandlerMethods.php +++ b/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 $conditions * @return void * @throws DatastoreErrorException */ @@ -213,6 +213,7 @@ public function deleteWhere(array $conditions): void } /** + * @param array|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 $identities list of identities keyed by the field name for the identity. - * @return array + * @return array */ 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 $attributes + * @param array $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 $attributes + * @param array $fields + * @return array */ 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 $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 $data + * @param array|null $updateIdentity * @return void * @throws DuplicateEntryException * @throws DatastoreErrorException