docs: add types 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 RowArray array<int|string, float|int|null|string>
+ * @phpstan-type EventDataBeforeInsert array{data: RowArray}
+ * @phpstan-type EventDataAfterInsert array{id: int|string, data: RowArray, result: bool}
+ * @phpstan-type EventDataBeforeFind array{id?: int|string, method: string, singleton: bool, limit?: int, offset?: int}
+ * @phpstan-type EventDataAfterFind array{id: int|string|null|list<int|string>, data: RowArray|list<RowArray>|object|null, method: string, singleton: bool}
+ * @phpstan-type EventDataBeforeUpdate array{id: null|list<int|string>, data: RowArray}
+ * @phpstan-type EventDataAfterUpdate array{id: null|list<int|string>, data: RowArray|object, result: bool}
+ * @phpstan-type EventDataBeforeDelete array{id: null|list<int|string>, purge: bool}
+ * @phpstan-type EventDataAfterDelete 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 ? RowArray|object|null : list<RowArray|object>)
      */
     public function find($id = null)
     {

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 RowArray from \CodeIgniter\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 ? RowArray|null|object : list<RowArray|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<RowArray|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 RowArray|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()
     {