refactor: use native phpdocs wherever possible

Author: paulbalandan

app/Config/Cookie.php

@@ -85,7 +85,7 @@ class Cookie extends BaseConfig
      * (empty string) means default SameSite attribute set by browsers (`Lax`)
      * will be set on cookies. If set to `None`, `$secure` must also be set.
      *
-     * @phpstan-var 'None'|'Lax'|'Strict'|''
+     * @var ''|'Lax'|'None'|'Strict'
      */
     public string $samesite = 'Lax';
 

system/API/ResponseTrait.php

@@ -69,8 +69,7 @@ trait ResponseTrait
      * Either 'json' or 'xml'. If null is set, it will be determined through
      * content negotiation.
      *
-     * @var         string|null
-     * @phpstan-var 'html'|'json'|'xml'|null
+     * @var 'html'|'json'|'xml'|null
      */
     protected $format = 'json';
 
@@ -348,8 +347,7 @@ protected function format($data = null)
     /**
      * Sets the format the response should be in.
      *
-     * @param         string|null  $format Response format
-     * @phpstan-param 'json'|'xml' $format
+     * @param 'json'|'xml' $format Response format
      *
      * @return $this
      */

system/Autoloader/Autoloader.php

@@ -219,8 +219,7 @@ public function addNamespace($namespace, ?string $path = null)
      *
      * If a prefix param is set, returns only paths to the given prefix.
      *
-     * @return         array<string, list<string>>|list<string>
-     * @phpstan-return ($prefix is null ? array<string, list<string>> : list<string>)
+     * @return ($prefix is null ? array<string, list<string>> : list<string>)
      */
     public function getNamespace(?string $prefix = null)
     {

system/BaseModel.php

@@ -793,8 +793,7 @@ public function getInsertID()
      * @phpstan-param row_array|object|null $row
      * @param         bool                  $returnID Whether insert ID should be returned or not.
      *
-     * @return         bool|int|string                               insert ID or true on success. false on failure.
-     * @phpstan-return ($returnID is true ? int|string|false : bool)
+     * @return ($returnID is true ? false|int|string : bool)
      *
      * @throws ReflectionException
      */

system/CodeIgniter.php

@@ -141,7 +141,7 @@ class CodeIgniter
      *  web:     Invoked by HTTP request
      *  php-cli: Invoked by CLI via `php public/index.php`
      *
-     * @phpstan-var 'php-cli'|'web'
+     * @var 'php-cli'|'web'|null
      */
     protected ?string $context = null;
 
@@ -1128,7 +1128,7 @@ protected function callExit($code)
     /**
      * Sets the app context.
      *
-     * @phpstan-param 'php-cli'|'web' $context
+     * @param 'php-cli'|'web' $context
      *
      * @return $this
      */

system/Commands/Translation/LocalizationFinder.php

@@ -361,8 +361,7 @@ private function isSubDirectory(string $directory, string $rootDirectory): bool
     /**
      * @param list<SplFileInfo> $files
      *
-     * @return         array<string, array|int>
-     * @phpstan-return array{'foundLanguageKeys': array<string, array<string, string>>, 'badLanguageKeys': array<int, array<int, string>>, 'countFiles': int}
+     * @return array{'foundLanguageKeys': array<string, array<string, string>>, 'badLanguageKeys': array<int, array<int, string>>, 'countFiles': int}
      */
     private function findLanguageKeysInFiles(array $files): array
     {

system/Common.php

@@ -69,8 +69,7 @@ function app_timezone(): string
      *    cache()->save('foo', 'bar');
      *    $foo = cache('bar');
      *
-     * @return         array|bool|CacheInterface|float|int|object|string|null
-     * @phpstan-return ($key is null ? CacheInterface : array|bool|float|int|object|string|null)
+     * @return ($key is null ? CacheInterface : mixed)
      */
     function cache(?string $key = null)
     {
@@ -201,8 +200,7 @@ function command(string $command)
      *
      * @param class-string<ConfigTemplate>|string $name
      *
-     * @return         ConfigTemplate|null
-     * @phpstan-return ($name is class-string<ConfigTemplate> ? ConfigTemplate : object|null)
+     * @return ($name is class-string<ConfigTemplate> ? ConfigTemplate : object|null)
      */
     function config(string $name, bool $getShared = true)
     {
@@ -404,11 +402,11 @@ function env(string $key, $default = null)
      * If $data is an array, then it loops over it, escaping each
      * 'value' of the key/value pairs.
      *
-     * @param         array|string                         $data
-     * @phpstan-param 'html'|'js'|'css'|'url'|'attr'|'raw' $context
-     * @param         string|null                          $encoding Current encoding for escaping.
-     *                                                               If not UTF-8, we convert strings from this encoding
-     *                                                               pre-escaping and back to this encoding post-escaping.
+     * @param array|string                         $data
+     * @param 'attr'|'css'|'html'|'js'|'raw'|'url' $context
+     * @param string|null                          $encoding Current encoding for escaping.
+     *                                                       If not UTF-8, we convert strings from this encoding
+     *                                                       pre-escaping and back to this encoding post-escaping.
      *
      * @return array|string
      *
@@ -796,8 +794,7 @@ function log_message(string $level, string $message, array $context = []): void
      *
      * @param class-string<ModelTemplate>|string $name
      *
-     * @return         ModelTemplate|null
-     * @phpstan-return ($name is class-string<ModelTemplate> ? ModelTemplate : object|null)
+     * @return ($name is class-string<ModelTemplate> ? ModelTemplate : object|null)
      */
     function model(string $name, bool $getShared = true, ?ConnectionInterface &$conn = null)
     {
@@ -810,9 +807,8 @@ function model(string $name, bool $getShared = true, ?ConnectionInterface &$conn
      * Provides access to "old input" that was set in the session
      * during a redirect()->withInput().
      *
-     * @param         string|null                                $default
-     * @param         false|string                               $escape
-     * @phpstan-param false|'attr'|'css'|'html'|'js'|'raw'|'url' $escape
+     * @param string|null                                $default
+     * @param 'attr'|'css'|'html'|'js'|'raw'|'url'|false $escape
      *
      * @return array|string|null
      */
@@ -965,8 +961,7 @@ function route_to(string $method, ...$params)
      *    session()->set('foo', 'bar');
      *    $foo = session('bar');
      *
-     * @return         array|bool|float|int|object|Session|string|null
-     * @phpstan-return ($val is null ? Session : array|bool|float|int|object|string|null)
+     * @return ($val is null ? Session : mixed)
      */
     function session(?string $val = null)
     {
@@ -1123,8 +1118,7 @@ function stringify_attributes($attributes, bool $js = false): string
      * @param non-empty-string|null    $name
      * @param (callable(): mixed)|null $callable
      *
-     * @return         mixed|Timer
-     * @phpstan-return ($name is null ? Timer : ($callable is (callable(): mixed) ? mixed : Timer))
+     * @return ($name is null ? Timer : ($callable is (callable(): mixed) ? mixed : Timer))
      */
     function timer(?string $name = null, ?callable $callable = null)
     {

system/DataCaster/DataCaster.php

@@ -113,10 +113,9 @@ public function setTypes(array $types): static
      * Add ? at the beginning of the type (i.e. ?string) to get `null`
      * instead of casting $value when $value is null.
      *
-     * @param         mixed       $value  The value to convert
-     * @param         string      $field  The field name
-     * @param         string      $method Allowed to "get" and "set"
-     * @phpstan-param 'get'|'set' $method
+     * @param mixed       $value  The value to convert
+     * @param string      $field  The field name
+     * @param 'get'|'set' $method Allowed to "get" and "set"
      */
     public function castAs(mixed $value, string $field, string $method = 'get'): mixed
     {

system/DataConverter/DataConverter.php

@@ -21,8 +21,6 @@
  * PHP data <==> DataSource data converter
  *
  * @see \CodeIgniter\DataConverter\DataConverterTest
- *
- * @template TEntity of object
  */
 final class DataConverter
 {
@@ -32,6 +30,8 @@ final class DataConverter
     private readonly DataCaster $dataCaster;
 
     /**
+     * @template TEntity of object
+     *
      * @param array<string, class-string> $castHandlers Custom convert handlers
      *
      * @internal
@@ -52,14 +52,14 @@ public function __construct(
          * Static reconstruct method name or closure to reconstruct an object.
          * Used by reconstruct().
          *
-         * @phpstan-var (Closure(array<string, mixed>): TEntity)|string|null
+         * @var (Closure(array<string, mixed>): TEntity)|string|null
          */
         private readonly Closure|string|null $reconstructor = 'reconstruct',
         /**
          * Extract method name or closure to extract data from an object.
          * Used by extract().
          *
-         * @phpstan-var (Closure(TEntity, bool, bool): array<string, mixed>)|string|null
+         * @var (Closure(TEntity, bool, bool): array<string, mixed>)|string|null
          */
         private readonly Closure|string|null $extractor = null,
     ) {
@@ -105,11 +105,12 @@ public function toDataSource(array $phpData): array
     /**
      * Takes database data array and creates a specified type object.
      *
-     * @param         class-string          $classname
-     * @phpstan-param class-string<TEntity> $classname
-     * @param         array<string, mixed>  $row       Raw data from database
+     * @template TEntity of object
+     *
+     * @param class-string<TEntity> $classname
+     * @param array<string, mixed>  $row       Raw data from database
      *
-     * @phpstan-return TEntity
+     * @return TEntity
      *
      * @internal
      */

system/Database/BaseConnection.php

@@ -206,16 +206,14 @@ abstract class BaseConnection implements ConnectionInterface
     /**
      * Connection ID
      *
-     * @var         false|object|resource
-     * @phpstan-var false|TConnection
+     * @var false|TConnection
      */
     public $connID = false;
 
     /**
      * Result ID
      *
-     * @var         false|object|resource
-     * @phpstan-var false|TResult
+     * @var false|TResult
      */
     public $resultID = false;
 
@@ -498,8 +496,7 @@ abstract protected function _close();
     /**
      * Create a persistent database connection.
      *
-     * @return         false|object|resource
-     * @phpstan-return false|TConnection
+     * @return false|TConnection
      */
     public function persistentConnect()
     {
@@ -512,8 +509,7 @@ public function persistentConnect()
      * get that connection. If you pass either alias in and only a single
      * connection is present, it must return the sole connection.
      *
-     * @return         false|object|resource
-     * @phpstan-return TConnection
+     * @return false|TConnection
      */
     public function getConnection(?string $alias = null)
     {
@@ -592,8 +588,7 @@ public function addTableAlias(string $alias)
     /**
      * Executes the query against the database.
      *
-     * @return         false|object|resource
-     * @phpstan-return false|TResult
+     * @return false|TResult
      */
     abstract protected function execute(string $sql);
 
@@ -607,8 +602,7 @@ abstract protected function execute(string $sql);
      *
      * @param array|string|null $binds
      *
-     * @return         BaseResult|bool|Query                       BaseResult when “read” type query, bool when “write” type query, Query when prepared query
-     * @phpstan-return BaseResult<TConnection, TResult>|bool|Query
+     * @return BaseResult<TConnection, TResult>|bool|Query
      *
      * @todo BC set $queryClass default as null in 4.1
      */
@@ -726,8 +720,7 @@ public function query(string $sql, $binds = null, bool $setEscapeFlags = true, s
      * is performed, nor are transactions handled. Simply takes a raw
      * query string and returns the database-specific result id.
      *
-     * @return         false|object|resource
-     * @phpstan-return false|TResult
+     * @return false|TResult
      */
     public function simpleQuery(string $sql)
     {
@@ -1065,8 +1058,7 @@ public function getConnectDuration(int $decimals = 6): string
      * @param bool                       $protectIdentifiers Protect table or column names?
      * @param bool                       $fieldExists        Supplied $item contains a column name?
      *
-     * @return         array|string
-     * @phpstan-return ($item is array ? array : string)
+     * @return ($item is array ? array : string)
      */
     public function protectIdentifiers($item, bool $prefixSingle = false, ?bool $protectIdentifiers = null, bool $fieldExists = true)
     {
@@ -1270,8 +1262,7 @@ private function escapeTableName(TableName $tableName): string
      *
      * @param array|string $item
      *
-     * @return         array|string
-     * @phpstan-return ($item is array ? array : string)
+     * @return ($item is array ? array : string)
      */
     public function escapeIdentifiers($item)
     {
@@ -1355,8 +1346,7 @@ abstract public function affectedRows(): int;
      *
      * @param array|bool|float|int|object|string|null $str
      *
-     * @return         array|float|int|string
-     * @phpstan-return ($str is array ? array : float|int|string)
+     * @return ($str is array ? array : float|int|string)
      */
     public function escape($str)
     {
@@ -1787,8 +1777,7 @@ public function isWriteType($sql): bool
      *
      * Must return an array with keys 'code' and 'message':
      *
-     * @return         array<string, int|string|null>
-     * @phpstan-return array{code: int|string|null, message: string|null}
+     * @return array{code: int|string|null, message: string|null}
      */
     abstract public function error(): array;