Merge pull request #1051 from kenjis/docs-update-phpdoc-array

docs: update PHPDoc array types

src/Auth.php

@@ -177,7 +177,7 @@ public function getProvider(): UserModel
      * own, additional, features on top of the required ones,
      * like "remember-me" functionality.
      *
-     * @param string[] $args
+     * @param list<string> $args
      *
      * @throws AuthenticationException
      */

src/Authentication/Authenticators/Session.php

@@ -501,7 +501,7 @@ private function setAuthAction(): bool
     /**
      * Gets identities for action
      *
-     * @return UserIdentity[]
+     * @return list<UserIdentity>
      */
     private function getIdentitiesForAction(User $user): array
     {
@@ -512,7 +512,7 @@ private function getIdentitiesForAction(User $user): array
     }
 
     /**
-     * @return string[]
+     * @return list<string>
      */
     private function getActionTypes(): array
     {

src/Authentication/JWT/JWSAdapterInterface.php

@@ -20,7 +20,7 @@ interface JWSAdapterInterface
     /**
      * Issues Signed JWT (JWS)
      *
-     * @param array<mixed>               $payload The payload.
+     * @param array<string, mixed>       $payload The payload.
      * @param string                     $keyset  The key group.
      *                                            The array key of Config\AuthJWT::$keys.
      * @param array<string, string>|null $headers An array with header elements to attach.

src/Authentication/Traits/HasAccessTokens.php

@@ -34,8 +34,8 @@ trait HasAccessTokens
     /**
      * Generates a new personal access token for this user.
      *
-     * @param string   $name   Token name
-     * @param string[] $scopes Permissions the token grants
+     * @param string       $name   Token name
+     * @param list<string> $scopes Permissions the token grants
      */
     public function generateAccessToken(string $name, array $scopes = ['*']): AccessToken
     {
@@ -81,7 +81,7 @@ public function revokeAllAccessTokens(): void
     /**
      * Retrieves all personal access tokens for this user.
      *
-     * @return AccessToken[]
+     * @return list<AccessToken>
      */
     public function accessTokens(): array
     {

src/Authentication/Traits/HasHmacTokens.php

@@ -35,8 +35,8 @@ trait HasHmacTokens
     /**
      * Generates a new personal HMAC token for this user.
      *
-     * @param string   $name   Token name
-     * @param string[] $scopes Permissions the token grants
+     * @param string       $name   Token name
+     * @param list<string> $scopes Permissions the token grants
      *
      * @throws ReflectionException
      */
@@ -73,7 +73,7 @@ public function revokeAllHmacTokens(): void
     /**
      * Retrieves all personal HMAC tokens for this user.
      *
-     * @return AccessToken[]
+     * @return list<AccessToken>
      */
     public function hmacTokens(): array
     {

src/Authorization/Traits/Authorizable.php

@@ -399,15 +399,15 @@ private function saveGroupsOrPermissions(string $type, $model, array $cache): vo
     }
 
     /**
-     * @return string[]
+     * @return list<string>
      */
     private function getConfigGroups(): array
     {
         return array_keys(setting('AuthGroups.groups'));
     }
 
     /**
-     * @return string[]
+     * @return list<string>
      */
     private function getConfigPermissions(): array
     {

src/Config/Auth.php

@@ -137,8 +137,7 @@ class Auth extends BaseConfig
      * when using the 'chain' filter. Each Authenticator listed will be checked.
      * If no match is found, then the next in the chain will be checked.
      *
-     * @var string[]
-     * @phpstan-var list<string>
+     * @var list<string>
      */
     public array $authenticationChain = [
         'session',
@@ -264,7 +263,7 @@ class Auth extends BaseConfig
      * You can add custom classes as long as they adhere to the
      * CodeIgniter\Shield\Authentication\Passwords\ValidatorInterface.
      *
-     * @var class-string<ValidatorInterface>[]
+     * @var list<class-string<ValidatorInterface>>
      */
     public array $passwordValidators = [
         CompositionValidator::class,

src/Config/AuthJWT.php

@@ -49,7 +49,7 @@ class AuthJWT extends BaseConfig
      * The key of the array is the key group name.
      * The first key of the group is used for signing.
      *
-     * @var array<string, array<int, array<string, string>>>
+     * @var         array<string, array<int, array<string, string>>>
      * @phpstan-var array<string, list<array<string, string>>>
      */
     public array $keys = [

src/Controllers/ActionController.php

@@ -31,7 +31,7 @@ class ActionController extends BaseController
     /**
      * Perform an initial check if we have a valid action or not.
      *
-     * @param string[] $params
+     * @param list<string> $params
      *
      * @return Response|string
      */

src/Controllers/LoginController.php

@@ -84,8 +84,7 @@ public function loginAction(): RedirectResponse
     /**
      * Returns the rules that should be used for validation.
      *
-     * @return         array<string, array<string, array<string>|string>>
-     * @phpstan-return array<string, array<string, string|list<string>>>
+     * @return array<string, array<string, list<string>|string>>
      */
     protected function getValidationRules(): array
     {

src/Controllers/MagicLinkController.php

@@ -241,8 +241,7 @@ private function recordLoginAttempt(
     /**
      * Returns the rules that should be used for validation.
      *
-     * @return         array<string, array<string, array<string>|string>>
-     * @phpstan-return array<string, array<string, string|list<string>>>
+     * @return array<string, array<string, list<string>|string>>
      */
     protected function getValidationRules(): array
     {

src/Controllers/RegisterController.php

@@ -169,8 +169,7 @@ protected function getUserEntity(): User
     /**
      * Returns the rules that should be used for validation.
      *
-     * @return         array<string, array<string, array<string>|string>>
-     * @phpstan-return array<string, array<string, string|list<string>>>
+     * @return array<string, array<string, list<string>|string>>
      */
     protected function getValidationRules(): array
     {

src/Entities/Entity.php

@@ -24,7 +24,7 @@ abstract class Entity extends FrameworkEntity
     /**
      * Custom convert handlers
      *
-     * @var array<string, string>
+     * @var         array<string, string>
      * @phpstan-var array<string, class-string>
      */
     protected $castHandlers = [

src/Entities/User.php

@@ -26,13 +26,13 @@
 use CodeIgniter\Shield\Traits\Resettable;
 
 /**
- * @property string|null         $email
- * @property int|string|null     $id
- * @property UserIdentity[]|null $identities
- * @property Time|null           $last_active
- * @property string|null         $password
- * @property string|null         $password_hash
- * @property string|null         $username
+ * @property string|null             $email
+ * @property int|string|null         $id
+ * @property list<UserIdentity>|null $identities
+ * @property Time|null               $last_active
+ * @property string|null             $password
+ * @property string|null             $password_hash
+ * @property string|null             $username
  */
 class User extends Entity
 {
@@ -44,7 +44,7 @@ class User extends Entity
     use Bannable;
 
     /**
-     * @var UserIdentity[]|null
+     * @var list<UserIdentity>|null
      */
     private ?array $identities = null;
 
@@ -53,9 +53,7 @@ class User extends Entity
     private ?string $password_hash = null;
 
     /**
-     * @var string[]
-     * @phpstan-var list<string>
-     * @psalm-var list<string>
+     * @var list<string>
      */
     protected $dates = [
         'created_at',
@@ -107,7 +105,7 @@ private function populateIdentities(): void
      *
      * @param string $type 'all' returns all identities.
      *
-     * @return UserIdentity[]
+     * @return list<UserIdentity>
      */
     public function getIdentities(string $type = 'all'): array
     {

src/Entities/UserIdentity.php

@@ -45,9 +45,7 @@ class UserIdentity extends Entity
     ];
 
     /**
-     * @var string[]
-     * @phpstan-var list<string>
-     * @psalm-var list<string>
+     * @var list<string>
      */
     protected $dates = [
         'expires',

src/Models/UserIdentityModel.php

@@ -144,8 +144,8 @@ public function createCodeIdentity(
     /**
      * Generates a new personal access token for the user.
      *
-     * @param string   $name   Token name
-     * @param string[] $scopes Permissions the token grants
+     * @param string       $name   Token name
+     * @param list<string> $scopes Permissions the token grants
      */
     public function generateAccessToken(User $user, string $name, array $scopes = ['*']): AccessToken
     {
@@ -210,7 +210,7 @@ public function getAccessTokenById($id, User $user): ?AccessToken
     }
 
     /**
-     * @return AccessToken[]
+     * @return list<AccessToken>
      */
     public function getAllAccessTokens(User $user): array
     {
@@ -242,8 +242,8 @@ public function getHmacTokenByKey(string $key): ?AccessToken
     /**
      * Generates a new personal access token for the user.
      *
-     * @param string   $name   Token name
-     * @param string[] $scopes Permissions the token grants
+     * @param string       $name   Token name
+     * @param list<string> $scopes Permissions the token grants
      *
      * @throws Exception
      * @throws ReflectionException
@@ -321,7 +321,7 @@ public function getHmacTokenById($id, User $user): ?AccessToken
      *
      * @param User $user User object
      *
-     * @return AccessToken[]
+     * @return list<AccessToken>
      */
     public function getAllHmacTokens(User $user): array
     {
@@ -384,7 +384,7 @@ public function getIdentityBySecret(string $type, ?string $secret): ?UserIdentit
     /**
      * Returns all identities.
      *
-     * @return UserIdentity[]
+     * @return list<UserIdentity>
      */
     public function getIdentities(User $user): array
     {
@@ -394,9 +394,9 @@ public function getIdentities(User $user): array
     }
 
     /**
-     * @param int[]|string[] $userIds
+     * @param list<int>|list<string> $userIds
      *
-     * @return UserIdentity[]
+     * @return list<UserIdentity>
      */
     public function getIdentitiesByUserIds(array $userIds): array
     {
@@ -419,9 +419,9 @@ public function getIdentityByType(User $user, string $type): ?UserIdentity
     /**
      * Returns all identities for the specific types.
      *
-     * @param string[] $types
+     * @param list<string> $types
      *
-     * @return UserIdentity[]
+     * @return list<UserIdentity>
      */
     public function getIdentitiesByTypes(User $user, array $types): array
     {
@@ -507,7 +507,7 @@ public function revokeAllAccessTokens(User $user): void
     /**
      * Force password reset for multiple users.
      *
-     * @param int[]|string[] $userIds
+     * @param list<int>|list<string> $userIds
      */
     public function forceMultiplePasswordReset(array $userIds): void
     {

src/Models/UserModel.php

@@ -113,10 +113,10 @@ protected function fetchIdentities(array $data): array
     /**
      * Map our users by ID to make assigning simpler
      *
-     * @param array          $data       Event $data
-     * @param UserIdentity[] $identities
+     * @param array              $data       Event $data
+     * @param list<UserIdentity> $identities
      *
-     * @return         User[]                  UserId => User object
+     * @return         list<User>              UserId => User object
      * @phpstan-return array<int|string, User> UserId => User object
      */
     private function assignIdentities(array $data, array $identities): array

tests/Authentication/HasAccessTokensTest.php

@@ -66,7 +66,7 @@ public function testAccessTokens(): void
             ['user_id' => $this->user->id, 'type' => 'access_token', 'secret' => 'secretToken2']
         );
 
-        /** @var AccessToken[] $tokens */
+        /** @var list<AccessToken> $tokens */
         $tokens = $this->user->accessTokens();
 
         $this->assertCount(2, $tokens);

tests/Language/AbstractTranslationTestCase.php

@@ -89,8 +89,7 @@ abstract class AbstractTranslationTestCase extends TestCase
      * class and the contained values will be skipped in
      * testAllIncludedLanguageKeysAreTranslated.
      *
-     * @var string[]
-     * @phpstan-var list<string>
+     * @var list<string>
      */
     protected array $excludedLocaleKeyTranslations = [];
 
@@ -360,7 +359,7 @@ final public function testAllLocalizationParametersAreNotTranslated(string $loca
     }
 
     /**
-     * @return string[][]
+     * @return array<string, list<string>>
      */
     final public static function localesProvider(): iterable
     {
@@ -393,7 +392,7 @@ final public function testLocaleHasCorrespondingTestCaseFile(string $locale): vo
     /**
      * Get all the ISO 639-1 and 639-2 locale codes.
      *
-     * @return array<string, array<string>>
+     * @return array<string, list<string>>
      */
     final public function translationKeys(): array
     {