refactor: Update types for `BaseModel`, `Model` and dependencies #9711

neznaika0 · 2025-09-06T16:08:42Z

Description
Updated PHPDoc, clarified arrays, duplicate comments have been removed from the Model and did some work with dots.
I generated the API using phpDocumentor. I didn't notice any serious problems.

Some questions:

I did not find a test for sampling from the array $id for BaseModel::doFind()
Can someone explain the phrase? Can it be improved?

This method works only with dbCalls
phpDocumentor does not understand conditional values for @return, it is necessary to duplicate complex conditions in @phpstan-return
Look at doFindColumn() findColumn() - not sure about the type accuracy
⚠️ BaseModel::getIdValue() does not return an array. Right? I have removed PHPDoc and array checking. Is it possible to use 0, '0' for ID? Otherwise, I would have added the checks to BaseModel::shouldUpdate().
Tell me if you need to update the guide or changelog.

Checklist:

Securely signed commits
Component(s) with PHPDoc blocks, only if necessary or adds value (without duplication)
Unit testing, with >80% coverage
User guide updated
Conforms to style guide

michalsn

Some methods have a $testing parameter, which set to true, will not execute the query and just return the SQL.
No array - as we do not support composite keys in the model right now. Support for 0 and '0' is problematic, and I would rather not allow it, as it will cause problems when combined with $db->insertID(), which uses 0 to indicate a failure.

michalsn · 2025-09-08T06:38:43Z

system/BaseModel.php

-     * Used by asArray() and asObject() to provide
+     * The temporary format of the result.
+     *
+     * Used by `$this->asArray()` and `$this->asObject()` to provide


Why are you adding $this everywhere? It makes the comments longer and doesn't add value (at least from my perspective). Do backticks actually change the syntax in phpDocumentor? If yes, please use them consistently everywhere - if not, please remove them.

Yes, phpDocumentor supports Markdown. Therefore, we can mark some code as bold... I added a clarification to explicitly indicate a method rather than a function. This may seem redundant, but it's not a problem to reduce it. We're considering a PR together to address this.

system/BaseModel.php

neznaika0 · 2025-09-08T07:37:13Z

Some methods have a $testing parameter, which set to true, will not execute the query and just return the SQL.

No array - as we do not support composite keys in the model right now. Support for 0 and '0' is problematic, and I would rather not allow it, as it will cause problems when combined with $db->insertID(), which uses 0 to indicate a failure.

I don't need to change the message?
not 3? I'll add a check 0? You have an issue Possible bug: Model functions (doDelete, doFirst, etc..) ignores zero as id #9577 where it's found: that in general, the $id check is different in methods. Is it acceptable to move it to a separate method if possible?

michalsn

The message can stay, for reference.

michalsn · 2025-09-08T18:27:22Z

system/BaseModel.php

+     *
+     * @throws InvalidArgumentException
+     */
+    protected function hasRationalPrimaryKey($id): bool


The primary key in our model refers more to the column name, so this may be misleading.

I have no idea how we can name it... isUsableValueId()? 🤷‍♂️

The goal for these checks is purely to satisfy PHPStan or validate the allowed data?

Initially, I remove phpstan errors. The next step was formed by itself - we can validate the ID value.

I would set the relationship to PK. For now, all checks are used for it. But it can be renamed to hasRationalId() if it is used for table joins, for example.

The "rational" part of the method doesn't really speak to me, to be honest.

Well... let's forget about validating the primary key for now - I'm not convinced we need to do that.

Remove the check or what, back to if ($id)?

rational - based on logic. If there is a problem with the translation.

Using if ($id) would likely bring us back to square one, with PHPStan raising an error.

Yes, I know what “rational” means, but I don't think it's a good fit here.

I'm leaning towards leaving the code as it is (without introducing an additional method), but unifying the values in in_array. Happy to hear others' opinions.

@samsonasik @paulbalandan i need help.

Sorry, what was the issue? Is it the underlying code or the method naming? Or both?

@paulbalandan The question is about the usefulness of the method. I would check the ID for a correct value. Since earlier the check was if ($id) {}

If the ID may not always be PK, let's rename it to hasAllowedValueId() and otherwise. I cannot say for all cases where the ID is used (Postgres, OCI8..), at the moment this check is acceptable.

github-actions · 2025-09-10T14:11:36Z

👋 Hi, @neznaika0!

We detected conflicts in your PR against the base branch 🙊
You may want to sync 🔄 your branch with upstream!

Ref: Syncing Your Branch

paulbalandan · 2025-10-03T16:44:22Z

system/Database/BaseBuilder.php

-     * @param non-empty-string|null                                      $key
-     * @param array|BaseBuilder|(Closure(BaseBuilder): BaseBuilder)|null $values The values searched on, or anonymous function with subquery
+     * @param non-empty-string|null                                                    $key
+     * @param array<int|string, >|BaseBuilder|(Closure(BaseBuilder): BaseBuilder)|null $values The values searched on, or anonymous function with subquery


Looks like the array is missing the value type?

This is a list of IDs for whereIn(). Do you think it's acceptable to have string keys or just a list? As $qb->whereIn('user.id', [0 => 123, 'user_id2' => 134])

paulbalandan · 2025-10-03T16:46:51Z

system/BaseModel.php

     * used during data validation.
     *
-     * @var array<string, array<string, string>>
+     * @var array<string, array<string, string>> The column is used as the keys.


For this @var and the previous ones: does @var accept a description after the type?

Yes. But it looks like a typo. Although the `DataCaster` has the same principle. I can leave it.

paulbalandan · 2025-10-03T16:49:17Z

system/BaseModel.php

+     * @return         list<object|row_array>|object|row_array|null                          The resulting row of data or null.
+     * @phpstan-return ($singleton is true ? object|row_array|null : list<object|row_array>)


this was done because phpdocumentor doesn't understand conditional return types, right? then, does it also understand custom phpstan types like this row_array? If not, then @return should be all native PHPDoc and @phpstan-return should be the conditional return + phpstan-type

See https://codeigniter4.github.io/api/classes/CodeIgniter-Model.html#method_doInsert
Yes, I misunderstood and changed @phpstan-param. You need to return individual comments. Thanks.

paulbalandan · 2025-10-03T16:52:49Z

system/BaseModel.php

-     * @param string $columnName Column Name
-     *
-     * @return array|null The resulting row of data, or null if no data found.
+     * @return list<bool|float|int|list<mixed>|object|string|null>|null The resulting row of data, or null if no data found


Can this be just list<mixed>? I really see no point in expanding the mixed type to its long form if we cannot further refine the types by reducing the types in union. This is just verbose.

In some PR kenjis asked to replace mixed with a similar list. If possible, I'll shorten it.

Yeah, with the intention of shortening the union to the actual types. Historically, IDEs would add the mixed phpdoc if the structural element has no type.

If the change was mixed -> string|int|null (for example) because those were the actual types and not the all-encompassing mixed then the change is useful. If the change was mixed -> array|bool|int|float|object|string|null with no type refinement because the element actually can take anything or unknown, then I would be fine with sticking to mixed as the short form.

paulbalandan · 2025-10-03T16:57:03Z

system/BaseModel.php

+     *
+     * @throws InvalidArgumentException
+     */
+    protected function hasAllowedValueId($id): bool


We're in PHP 8.1 and this is a new method so we can safely add the parameter types so that the is_bool check below is no longer needed.

The type is too extensive. list|int|string|null You're right, i can delete it, because checking against the list of acceptable values.

paulbalandan · 2025-10-03T16:59:30Z

system/BaseModel.php

+     * Especially the values 0, '0', '' are rarely used or are invalid.
+     * Example, if you add an entry with ID=0, it will be an error for `$this->insertID`.
+     *
+     * @param array<int|string, int|string>|float|int|string|null $id


is float allowed as PK? would this be just int|string or a list of them? also i don't see a case where you pass a string-keyed array in here.

Ok. Changed

paulbalandan · 2025-10-03T17:00:53Z

system/BaseModel.php

    }
+
+    /**
+     * Checking that the ID has a rational value.


I would propose naming this method as isIdAllowedAsPrimaryKey() as that is really the purpose of this method. Or maybe isIdValidAsPrimaryKey() something.

paulbalandan · 2025-10-03T17:07:35Z

system/BaseModel.php

+            throw new InvalidArgumentException('The ID value should not be boolean.');
+        }
+
+        return ! in_array($id, [0, '0', '', 0.0], true) && (is_numeric($id) || is_string($id));


Depending on what the @param should actually be in above, I would propose to do the check using if guard style. More verbose but clearer I believe.

$pkCandidates = is_array($id) ? $id : [$id]; foreach ($pkCandidates as $candidate) { if (is_int($candidate) && $candidate === 0) { return false; } if (is_string($candidate) && in_array($candidate, ['0', ''], true)) { return false; } } return true;

neznaika0 force-pushed the refactor/model-types branch from 42136ab to 11a3252 Compare September 6, 2025 16:29

michalsn reviewed Sep 8, 2025

View reviewed changes

github-actions bot added the stale Pull requests with conflicts label Sep 10, 2025

neznaika0 added 4 commits September 14, 2025 17:39

refactor: Update types for BaseModel, Model and dependencies

23acf7e

docs: Add changelog cleanValidationRules()

cf6bb6d

refactor: Add new hasRationalPrimaryKey()

4c14510

refactor: Rename hasRationalPrimaryKey()

0174725

neznaika0 force-pushed the refactor/model-types branch from e985209 to 0174725 Compare September 14, 2025 15:08

paulbalandan reviewed Oct 3, 2025

View reviewed changes

		* @return list<object\|row_array>\|object\|row_array\|null The resulting row of data or null.
		* @phpstan-return ($singleton is true ? object\|row_array\|null : list<object\|row_array>)

refactor: Update types for BaseModel, Model and dependencies #9711

Are you sure you want to change the base?

refactor: Update types for BaseModel, Model and dependencies #9711

Uh oh!

Conversation

neznaika0 commented Sep 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

michalsn left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

neznaika0 commented Sep 8, 2025

Uh oh!

michalsn left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Sep 10, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

neznaika0 Oct 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

neznaika0 Oct 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

refactor: Update types for `BaseModel`, `Model` and dependencies #9711

refactor: Update types for `BaseModel`, `Model` and dependencies #9711

neznaika0 commented Sep 6, 2025 •

edited

Loading

neznaika0 Oct 4, 2025 •

edited

Loading

neznaika0 Oct 4, 2025 •

edited

Loading