From b53f049553ccfa88e6c63cb3d3b526e447583663 Mon Sep 17 00:00:00 2001
From: kenjis <kenji.uui@gmail.com>
Date: Fri, 10 Nov 2023 19:02:33 +0900
Subject: [PATCH 1/2] docs: add types for PHPStan

---
 system/BaseModel.php | 11 +++++++++++
 system/Model.php     | 11 ++++++++---
 2 files changed, 19 insertions(+), 3 deletions(-)

diff --git a/system/BaseModel.php b/system/BaseModel.php
index e8e746e64c25..f9eed92b1d49 100644
--- a/system/BaseModel.php
+++ b/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)
     {
diff --git a/system/Model.php b/system/Model.php
index 1873804a3c2d..d2f531998fef 100644
--- a/system/Model.php
+++ b/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()
     {

From 76757983726bb457c2df92581a025ea22797c261 Mon Sep 17 00:00:00 2001
From: kenjis <kenji.uui@gmail.com>
Date: Fri, 10 Nov 2023 19:03:12 +0900
Subject: [PATCH 2/2] docs: update PHPDoc types

---
 system/Database/BaseBuilder.php | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/system/Database/BaseBuilder.php b/system/Database/BaseBuilder.php
index 12bd14f73ab1..badf2d35cdfc 100644
--- a/system/Database/BaseBuilder.php
+++ b/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
      */