improved phpDoc types

Author: dg

src/Bridges/SecurityDI/SecurityExtension.php

@@ -53,7 +53,7 @@ public function getConfigSchema(): Nette\Schema\Schema
 
 	public function loadConfiguration(): void
 	{
-		/** @var object{debugger: bool, users: array, roles: array, resources: array, authentication: \stdClass} $config */
+		/** @var object{debugger: bool, users: array<string, string|array{password: string, roles?: string|string[], data?: array<string, mixed>}>, roles: array<string, string|string[]|null>, resources: array<string, string|null>, authentication: \stdClass} $config */
 		$config = $this->config;
 		$builder = $this->getContainerBuilder();
 

src/Bridges/SecurityHttp/CookieStorage.php

@@ -84,6 +84,7 @@ public function setExpiration(?string $expire, bool $clearIdentity): void
 	}
 
 
+	/** @param  'Lax'|'Strict'|'None'|null  $sameSite */
 	public function setCookieParameters(
 		?string $name = null,
 		?string $domain = null,

src/Security/IAuthenticator.php

@@ -10,7 +10,7 @@
 
 /**
  * @deprecated  update to Nette\Security\Authenticator
- * @method IIdentity authenticate(array $credentials)
+ * @method IIdentity authenticate(array{string, string} $credentials)
  */
 interface IAuthenticator
 {

src/Security/IIdentity.php

@@ -10,18 +10,19 @@
 
 /**
  * Represents the user of application.
- * @method array getData()
+ * @method array<string, mixed> getData()
  */
 interface IIdentity
 {
 	/**
 	 * Returns the ID of user.
-	 * @return mixed
+	 * @return string|int
 	 */
 	function getId();
 
 	/**
 	 * Returns a list of roles that the user is a member of.
+	 * @return string[]
 	 */
 	function getRoles(): array;
 

src/Security/Identity.php

@@ -13,17 +13,25 @@
 /**
  * @deprecated  use Nette\Security\SimpleIdentity
  * @property   string|int $id
- * @property   array $roles
- * @property   array $data
+ * @property   string[] $roles
+ * @property   array<string,mixed> $data
  */
 class Identity implements IIdentity
 {
 	private string|int $id;
+
+	/** @var string[] */
 	private array $roles;
+
+	/** @var array<string, mixed> */
 	private array $data;
 
 
-	public function __construct(string|int $id, $roles = null, ?iterable $data = null)
+	/**
+	 * @param  string|string[]|null  $roles
+	 * @param  ?iterable<string, mixed>  $data
+	 */
+	public function __construct(string|int $id, string|array|null $roles = null, ?iterable $data = null)
 	{
 		$this->setId($id);
 		$this->setRoles((array) $roles);
@@ -54,6 +62,7 @@ public function getId(): string|int
 
 	/**
 	 * Sets a list of roles that the user is a member of.
+	 * @param  string[]  $roles
 	 */
 	public function setRoles(array $roles): static
 	{
@@ -64,6 +73,7 @@ public function setRoles(array $roles): static
 
 	/**
 	 * Returns a list of roles that the user is a member of.
+	 * @return string[]
 	 */
 	public function getRoles(): array
 	{
@@ -73,6 +83,7 @@ public function getRoles(): array
 
 	/**
 	 * Returns user data.
+	 * @return array<string, mixed>
 	 */
 	public function getData(): array
 	{

src/Security/Passwords.php

@@ -18,10 +18,10 @@ class Passwords
 {
 	/**
 	 * Configures the hashing algorithm and its options.
-	 * @see https://php.net/manual/en/password.constants.php
 	 */
 	public function __construct(
 		private readonly string $algo = PASSWORD_DEFAULT,
+		/** @var array<string, mixed>  algorithm-specific options, see https://php.net/manual/en/password.constants.php */
 		private readonly array $options = [],
 	) {
 	}

src/Security/Permission.php

@@ -18,10 +18,13 @@
  */
 class Permission implements Authorizator
 {
+	/** @var array<string, array{parents: array<string, true>, children: array<string, true>}> */
 	private array $roles = [];
+
+	/** @var array<string, array{parent: ?string, children: array<string, true>}> */
 	private array $resources = [];
 
-	/** Access Control List rules; whitelist (deny everything to all) by default */
+	/** @var array<string, mixed> Access Control List rules; whitelist (deny everything to all) by default */
 	private array $rules = [
 		'allResources' => [
 			'allRoles' => [
@@ -46,6 +49,7 @@ class Permission implements Authorizator
 	/**
 	 * Adds a Role to the list. The most recently added parent
 	 * takes precedence over parents that were previously added.
+	 * @param  string|string[]|null  $parents
 	 * @throws Nette\InvalidArgumentException
 	 * @throws Nette\InvalidStateException
 	 */
@@ -106,6 +110,7 @@ private function checkRole(string $role, bool $exists = true): void
 
 	/**
 	 * Returns all Roles.
+	 * @return list<string>
 	 */
 	public function getRoles(): array
 	{
@@ -115,6 +120,7 @@ public function getRoles(): array
 
 	/**
 	 * Returns existing Role's parents ordered by ascending priority.
+	 * @return list<string>
 	 */
 	public function getRoleParents(string $role): array
 	{
@@ -267,6 +273,7 @@ private function checkResource(string $resource, bool $exists = true): void
 
 	/**
 	 * Returns all Resources.
+	 * @return list<string>
 	 */
 	public function getResources(): array
 	{
@@ -365,6 +372,10 @@ public function removeAllResources(): static
 	/**
 	 * Allows one or more Roles access to [certain $privileges upon] the specified Resource(s).
 	 * If $assertion is provided, then it must return true in order for rule to apply.
+	 * @param  string|string[]|null  $roles
+	 * @param  string|string[]|null  $resources
+	 * @param  string|string[]|null  $privileges
+	 * @param  callable(self, ?string, ?string, ?string): bool  $assertion
 	 */
 	public function allow(
 		string|array|null $roles = self::All,
@@ -381,6 +392,10 @@ public function allow(
 	/**
 	 * Denies one or more Roles access to [certain $privileges upon] the specified Resource(s).
 	 * If $assertion is provided, then it must return true in order for rule to apply.
+	 * @param  string|string[]|null  $roles
+	 * @param  string|string[]|null  $resources
+	 * @param  string|string[]|null  $privileges
+	 * @param  callable(self, ?string, ?string, ?string): bool  $assertion
 	 */
 	public function deny(
 		string|array|null $roles = self::All,
@@ -396,6 +411,9 @@ public function deny(
 
 	/**
 	 * Removes "allow" permissions from the list in the context of the given Roles, Resources, and privileges.
+	 * @param  string|string[]|null  $roles
+	 * @param  string|string[]|null  $resources
+	 * @param  string|string[]|null  $privileges
 	 */
 	public function removeAllow(
 		string|array|null $roles = self::All,
@@ -410,6 +428,9 @@ public function removeAllow(
 
 	/**
 	 * Removes "deny" restrictions from the list in the context of the given Roles, Resources, and privileges.
+	 * @param  string|string[]|null  $roles
+	 * @param  string|string[]|null  $resources
+	 * @param  string|string[]|null  $privileges
 	 */
 	public function removeDeny(
 		string|array|null $roles = self::All,
@@ -424,6 +445,10 @@ public function removeDeny(
 
 	/**
 	 * Performs operations on Access Control List rules.
+	 * @param  string|string[]|null  $roles
+	 * @param  string|string[]|null  $resources
+	 * @param  string|string[]|null  $privileges
+	 * @param  callable(self, ?string, ?string, ?string): bool  $assertion
 	 * @throws Nette\InvalidStateException
 	 */
 	protected function setRule(
@@ -711,6 +736,7 @@ private function getRuleType(?string $resource, ?string $role, ?string $privileg
 	/**
 	 * Returns the rules associated with a Resource and a Role, or null if no such rules exist.
 	 * If the $create parameter is true, then a rule set is first created and then returned to the caller.
+	 * @return array<string, mixed>|null
 	 */
 	private function &getRules(?string $resource, ?string $role, bool $create = false): ?array
 	{

src/Security/SimpleAuthenticator.php

@@ -13,15 +13,13 @@
  */
 class SimpleAuthenticator implements Authenticator
 {
-	/**
-	 * @param  array  $passwords list of pairs username => password
-	 * @param  array  $roles list of pairs username => role[]
-	 * @param  array  $data list of pairs username => mixed[]
-	 */
 	public function __construct(
+		/** @var array<string, string> */
 		#[\SensitiveParameter]
 		private array $passwords,
+		/** @var array<string, string|string[]|null> */
 		private array $roles = [],
+		/** @var array<string, array<string, mixed>> */
 		private array $data = [],
 	) {
 	}

src/Security/User.php

@@ -16,10 +16,10 @@
  * User authentication and authorization.
  *
  * @property-read bool $loggedIn
- * @property-read IIdentity $identity
- * @property-read string|int $id
- * @property-read array $roles
- * @property-read int $logoutReason
+ * @property-read ?IIdentity $identity
+ * @property-read string|int|null $id
+ * @property-read string[] $roles
+ * @property-read ?int $logoutReason
  * @property   IAuthenticator $authenticator
  * @property   Authorizator $authorizator
  */
@@ -250,6 +250,7 @@ final public function getLogoutReason(): ?int
 
 	/**
 	 * Returns effective roles of the user. Unauthenticated users get the guest role.
+	 * @return string[]
 	 */
 	public function getRoles(): array
 	{