Merge pull request #8187 from kenjis/docs-Model-phpdoc-types

docs: add PHPDoc types to Model for PHPStan

Author: kenjis

system/BaseModel.php

@@ -41,6 +41,16 @@
  *      - ensure validation is run against objects when saving items
  *      - process various callbacks
  *      - allow intermingling calls to the db connection
+ *
+ * @phpstan-type row_array array<int|string, float|int|null|string>
+ * @phpstan-type event_data_beforeinsert array{data: row_array}
+ * @phpstan-type event_data_afterinsert array{id: int|string, data: row_array, result: bool}
+ * @phpstan-type event_data_beforefind array{id?: int|string, method: string, singleton: bool, limit?: int, offset?: int}
+ * @phpstan-type event_data_afterfind array{id: int|string|null|list<int|string>, data: row_array|list<row_array>|object|null, method: string, singleton: bool}
+ * @phpstan-type event_data_beforeupdate array{id: null|list<int|string>, data: row_array}
+ * @phpstan-type event_data_afterupdate array{id: null|list<int|string>, data: row_array|object, result: bool}
+ * @phpstan-type event_data_beforedelete array{id: null|list<int|string>, purge: bool}
+ * @phpstan-type event_data_afterdelete array{id: null|list<int|string>, data: null, purge: bool, result: bool}
  */
 abstract class BaseModel
 {
@@ -539,6 +549,7 @@ abstract public function chunk(int $size, Closure $userFunc);
      * @param array|int|string|null $id One primary key or an array of primary keys
      *
      * @return array|object|null The resulting row of data, or null.
+     * @phpstan-return ($id is int|string ? row_array|object|null : list<row_array|object>)
      */
     public function find($id = null)
     {

system/Database/BaseBuilder.php

@@ -2738,9 +2738,9 @@ public function getCompiledDelete(bool $reset = true): string
     /**
      * Compiles a delete string and runs the query
      *
-     * @param mixed $where
+     * @param array|RawSql|string $where
      *
-     * @return bool|string Returns a string if in test mode.
+     * @return bool|string Returns a SQL string if in test mode.
      *
      * @throws DatabaseException
      */

system/Model.php

@@ -84,6 +84,8 @@
  * @method $this where($key, $value = null, ?bool $escape = null)
  * @method $this whereIn(?string $key = null, $values = null, ?bool $escape = null)
  * @method $this whereNotIn(?string $key = null, $values = null, ?bool $escape = null)
+ *
+ * @phpstan-import-type row_array from BaseModel
  */
 class Model extends BaseModel
 {
@@ -178,6 +180,7 @@ public function setTable(string $table)
      * @param array|int|string|null $id        One primary key or an array of primary keys
      *
      * @return array|object|null The resulting row of data, or null.
+     * @phpstan-return ($singleton is true ? row_array|null|object : list<row_array|object>)
      */
     protected function doFind(bool $singleton, $id = null)
     {
@@ -224,6 +227,7 @@ protected function doFindColumn(string $columnName)
      * @param int $offset Offset
      *
      * @return array
+     * @phpstan-return list<row_array|object>
      */
     protected function doFindAll(int $limit = 0, int $offset = 0)
     {
@@ -244,6 +248,7 @@ protected function doFindAll(int $limit = 0, int $offset = 0)
      * This method works only with dbCalls.
      *
      * @return array|object|null
+     * @phpstan-return row_array|object|null
      */
     protected function doFirst()
     {
@@ -411,7 +416,7 @@ protected function doUpdateBatch(?array $set = null, ?string $index = null, int
      * @param array|int|string|null $id    The rows primary key(s)
      * @param bool                  $purge Allows overriding the soft deletes setting.
      *
-     * @return bool|string
+     * @return bool|string SQL string when testMode
      *
      * @throws DatabaseException
      */
@@ -450,7 +455,7 @@ protected function doDelete($id = null, bool $purge = false)
      * through soft deletes (deleted = 1)
      * This method works only with dbCalls.
      *
-     * @return bool|string Returns a string if in test mode.
+     * @return bool|string Returns a SQL string if in test mode.
      */
     protected function doPurgeDeleted()
     {
@@ -491,7 +496,7 @@ protected function doReplace(?array $data = null, bool $returnSQL = false)
      *  ['source' => 'message']
      * This method works only with dbCalls.
      *
-     * @return array<string,string>
+     * @return array<string, string>
      */
     protected function doErrors()
     {