Merge pull request #82 from ChadSikorra/v1-more-fixes

[1.0.0] PHPStan / phpdoc clean-up.
FreeDSx · Jun 16, 2024 · 01d4a82 · 01d4a82
2 parents d9c7ae4 + f2eea41
commit 01d4a82
Show file tree

Hide file tree

Showing 27 changed files with 87 additions and 11 deletions.
diff --git a/composer.json b/composer.json
@@ -26,7 +26,7 @@
     "phpunit/phpunit": "^9.6",
     "symplify/easy-coding-standard": "^9.4",
     "friends-of-phpspec/phpspec-code-coverage": "^6.3",
-    "phpstan/phpstan": "^1.10",
+    "phpstan/phpstan": "^1.11",
     "symfony/process": "^5.4",
     "squizlabs/php_codesniffer": "^3.7",
     "slevomat/coding-standard": "^7.2"

diff --git a/phpstan.neon b/phpstan.neon
@@ -2,8 +2,6 @@ parameters:
     level: max
     paths:
         - %currentWorkingDirectory%/src
-    checkMissingIterableValueType: false
-    checkGenericClassInNonGenericObjectType: false
     treatPhpDocTypesAsCertain: false
     reportUnmatchedIgnoredErrors: false
     ignoreErrors:

diff --git a/src/FreeDSx/Ldap/ClientOptions.php b/src/FreeDSx/Ldap/ClientOptions.php
@@ -19,6 +19,9 @@ final class ClientOptions
 {
     private int $version = 3;
 
+    /**
+     * @var string[]
+     */
     private array $servers;
 
     private int $port = 389;

diff --git a/src/FreeDSx/Ldap/Control/ControlBag.php b/src/FreeDSx/Ldap/Control/ControlBag.php
@@ -25,6 +25,7 @@
 /**
  * Represents a set of controls.
  *
+ * @implements IteratorAggregate<Control>
  * @author Chad Sikorra <[email protected]>
  */
 class ControlBag implements IteratorAggregate, Countable

diff --git a/src/FreeDSx/Ldap/Entry/Attribute.php b/src/FreeDSx/Ldap/Entry/Attribute.php
@@ -31,6 +31,7 @@
 /**
  * Represents an entry attribute and any values.
  *
+ * @implements IteratorAggregate<int|string, string>
  * @author Chad Sikorra <[email protected]>
  */
 class Attribute implements IteratorAggregate, Countable, Stringable
@@ -48,7 +49,7 @@ class Attribute implements IteratorAggregate, Countable, Stringable
     private ?string $lcAttribute = null;
 
     /**
-     * @var string[]
+     * @var array<int|string, string>
      */
     private array $values;
 

diff --git a/src/FreeDSx/Ldap/Entry/Changes.php b/src/FreeDSx/Ldap/Entry/Changes.php
@@ -23,6 +23,7 @@
 /**
  * Represents a set of change objects.
  *
+ * @implements IteratorAggregate<Change>
  * @author Chad Sikorra <[email protected]>
  */
 class Changes implements Countable, IteratorAggregate

diff --git a/src/FreeDSx/Ldap/Entry/Dn.php b/src/FreeDSx/Ldap/Entry/Dn.php
@@ -29,10 +29,14 @@
 /**
  * Represents a Distinguished Name.
  *
+ * @implements IteratorAggregate<Rdn>
  * @author Chad Sikorra <[email protected]>
  */
 class Dn implements IteratorAggregate, Countable, Stringable
 {
+    /**
+     * @var ?Rdn[]
+     */
     private ?array $pieces = null;
 
     public function __construct(private readonly string $dn)

diff --git a/src/FreeDSx/Ldap/Entry/Entries.php b/src/FreeDSx/Ldap/Entry/Entries.php
@@ -30,6 +30,7 @@
  *
  * @author Chad Sikorra <[email protected]>
  *
+ * @implements IteratorAggregate<Entry>
  * @template T of Entry
  */
 class Entries implements Countable, IteratorAggregate

diff --git a/src/FreeDSx/Ldap/Entry/Entry.php b/src/FreeDSx/Ldap/Entry/Entry.php
@@ -25,10 +25,14 @@
 /**
  * Represents an Entry in LDAP.
  *
+ * @implements IteratorAggregate<Attribute>
  * @author Chad Sikorra <[email protected]>
  */
 class Entry implements IteratorAggregate, Countable, Stringable
 {
+    /**
+     * @var Attribute[]
+     */
     private array $attributes;
 
     private Dn $dn;
@@ -254,8 +258,13 @@ public function __get(string $name): ?Attribute
         return $this->get($name);
     }
 
-    public function __set(string $name, Stringable|string|array $value): void
-    {
+    /**
+     * @param Stringable|string|array<string|Stringable> $value
+     */
+    public function __set(
+        string $name,
+        Stringable|string|array $value
+    ): void {
         $this->set(
             $name,
             ...(is_array($value) ? $value : [(string) $value])
@@ -275,7 +284,7 @@ public function __unset(string $name): void
     /**
      * An alias of fromArray().
      *
-     * @param array<string, string|array> $attributes
+     * @param array<string, string|array<string|Stringable>> $attributes
      */
     public static function create(
         Dn|Stringable|string $dn,

diff --git a/src/FreeDSx/Ldap/Entry/Options.php b/src/FreeDSx/Ldap/Entry/Options.php
@@ -24,6 +24,7 @@
 /**
  * Represents a collection of attribute options.
  *
+ * @implements IteratorAggregate<Option>
  * @author Chad Sikorra <[email protected]>
  */
 class Options implements Countable, IteratorAggregate, Stringable

diff --git a/src/FreeDSx/Ldap/LdapClient.php b/src/FreeDSx/Ldap/LdapClient.php
@@ -269,6 +269,7 @@ public function rename(
     /**
      * Send a search response and return the entries.
      *
+     * @return Entries<Entry>
      * @throws OperationException
      */
     public function search(

diff --git a/src/FreeDSx/Ldap/Operation/Response/SearchResponse.php b/src/FreeDSx/Ldap/Operation/Response/SearchResponse.php
@@ -26,6 +26,9 @@
  */
 class SearchResponse extends SearchResultDone
 {
+    /**
+     * @var ?Entries<Entry>
+     */
     private ?Entries $entries = null;
 
     /**
@@ -47,6 +50,8 @@ public function __construct(
 
     /**
      * Returns the {@see Entry} objects associated with this result set.
+     *
+     * @return Entries<Entry>
      */
     public function getEntries(): Entries
     {

diff --git a/src/FreeDSx/Ldap/Operation/Response/SyncInfo/SyncIdSet.php b/src/FreeDSx/Ldap/Operation/Response/SyncInfo/SyncIdSet.php
@@ -42,6 +42,9 @@ class SyncIdSet extends SyncInfoMessage
 
     private bool $refreshDeletes;
 
+    /**
+     * @var string[]
+     */
     private array $entryUuids;
 
     /**

diff --git a/src/FreeDSx/Ldap/Protocol/ServerProtocolHandler.php b/src/FreeDSx/Ldap/Protocol/ServerProtocolHandler.php
@@ -57,6 +57,7 @@ public function __construct(
     /**
      * Listens for messages from the socket and handles the responses/actions needed.
      *
+     * @param array<string, mixed> $defaultContext
      * @throws EncoderException
      */
     public function handle(array $defaultContext = []): void
@@ -116,6 +117,7 @@ public function handle(array $defaultContext = []): void
     /**
      * Used asynchronously to end a client session when the server process is shutting down.
      *
+     * @param array<string, mixed> $context
      * @throws EncoderException
      */
     public function shutdown(array $context = []): void

diff --git a/src/FreeDSx/Ldap/Protocol/ServerProtocolHandler/SearchResult.php b/src/FreeDSx/Ldap/Protocol/ServerProtocolHandler/SearchResult.php
@@ -14,11 +14,15 @@
 namespace FreeDSx\Ldap\Protocol\ServerProtocolHandler;
 
 use FreeDSx\Ldap\Entry\Entries;
+use FreeDSx\Ldap\Entry\Entry;
 use FreeDSx\Ldap\Exception\InvalidArgumentException;
 use FreeDSx\Ldap\Operation\ResultCode;
 
 final class SearchResult
 {
+    /**
+     * @param Entries<Entry> $entries
+     */
     private function __construct(
         private readonly Entries $entries,
         private readonly string $baseDn = '',
@@ -29,6 +33,8 @@ private function __construct(
 
     /**
      * Make a successful server search result representation.
+     *
+     * @param Entries<Entry> $entries
      */
     public static function makeSuccessResult(
         Entries $entries,
@@ -46,6 +52,8 @@ public static function makeSuccessResult(
     /**
      * Make an error result for server search result representation. This could occur for any reason, such as a base DN
      * not existing. This result MUST not return a success result code.
+     *
+     * @param ?Entries<Entry> $entries
      */
     public static function makeErrorResult(
         int $resultCode,
@@ -65,6 +73,9 @@ public static function makeErrorResult(
         );
     }
 
+    /**
+     * @return Entries<Entry>
+     */
     public function getEntries(): Entries
     {
         return $this->entries;

diff --git a/src/FreeDSx/Ldap/Search/DirSync.php b/src/FreeDSx/Ldap/Search/DirSync.php
@@ -20,6 +20,7 @@
 use FreeDSx\Ldap\Controls;
 use FreeDSx\Ldap\Entry\Attribute;
 use FreeDSx\Ldap\Entry\Entries;
+use FreeDSx\Ldap\Entry\Entry;
 use FreeDSx\Ldap\Exception\OperationException;
 use FreeDSx\Ldap\Exception\RuntimeException;
 use FreeDSx\Ldap\LdapClient;
@@ -116,6 +117,7 @@ public function hasChanges(): bool
      * Get the changes as entries. This may be empty if there are no changes since the last query. This should be
      * followed with a hasChanges() call to determine if more changes are still available.
      *
+     * @return Entries<Entry>
      * @throws OperationException
      */
     public function getChanges(): Entries

diff --git a/src/FreeDSx/Ldap/Search/Filter/AndFilter.php b/src/FreeDSx/Ldap/Search/Filter/AndFilter.php
@@ -16,10 +16,12 @@
 use Countable;
 use IteratorAggregate;
 use Stringable;
+use Traversable;
 
 /**
  * Represents a logical 'and' filter. RFC 4511, 4.5.1
  *
+ * @implements IteratorAggregate<FilterInterface>
  * @author Chad Sikorra <[email protected]>
  */
 class AndFilter implements FilterContainerInterface, IteratorAggregate, Countable, Stringable

diff --git a/src/FreeDSx/Ldap/Search/Filter/OrFilter.php b/src/FreeDSx/Ldap/Search/Filter/OrFilter.php
@@ -20,6 +20,7 @@
 /**
  * Represents a logical 'or' filter. RFC 4511, 4.5.1
  *
+ * @implements IteratorAggregate<FilterInterface>
  * @author Chad Sikorra <[email protected]>
  */
 class OrFilter implements FilterContainerInterface, IteratorAggregate, Countable, Stringable

diff --git a/src/FreeDSx/Ldap/Search/FilterParser.php b/src/FreeDSx/Ldap/Search/FilterParser.php
@@ -443,7 +443,8 @@ private function unescapeValue(string $value): string
     }
 
     /**
-     * @psalm-param 0|positive-int $child
+     * @return array{0: int, 1: ?int}
+     *
      * @throws FilterParseException
      */
     private function parseContainerStart(int $i, ?int $child): array

diff --git a/src/FreeDSx/Ldap/Search/Paging.php b/src/FreeDSx/Ldap/Search/Paging.php
@@ -17,6 +17,7 @@
 use FreeDSx\Ldap\Control\PagingControl;
 use FreeDSx\Ldap\Controls;
 use FreeDSx\Ldap\Entry\Entries;
+use FreeDSx\Ldap\Entry\Entry;
 use FreeDSx\Ldap\Exception\OperationException;
 use FreeDSx\Ldap\Exception\ProtocolException;
 use FreeDSx\Ldap\LdapClient;
@@ -83,6 +84,8 @@ public function end(): self
     /**
      * Get the next set of entries of results.
      *
+     * @return Entries<Entry>
+     *
      * @throws OperationException
      */
     public function getEntries(?int $size = null): Entries
@@ -109,6 +112,8 @@ public function sizeEstimate(): ?int
     }
 
     /**
+     * @return Entries<Entry>
+     *
      * @throws OperationException
      */
     private function send(?int $size = null): Entries

diff --git a/src/FreeDSx/Ldap/Search/Result/ReferralResult.php b/src/FreeDSx/Ldap/Search/Result/ReferralResult.php
@@ -26,7 +26,7 @@
 use function implode;
 
 /**
- * @template T of LdapUrl[]
+ * @implements IteratorAggregate<int, LdapUrl>
  */
 final class ReferralResult implements Countable, IteratorAggregate, Stringable
 {
@@ -50,7 +50,7 @@ public function getMessage(): LdapMessageResponse
     /**
      * Get the referrals returned for this result reference.
      *
-     * @return LdapUrl[]
+     * @return array<int, LdapUrl>
      */
     public function getReferrals(): array
     {

diff --git a/src/FreeDSx/Ldap/Search/Vlv.php b/src/FreeDSx/Ldap/Search/Vlv.php
@@ -20,6 +20,7 @@
 use FreeDSx\Ldap\Control\Vlv\VlvResponseControl;
 use FreeDSx\Ldap\Controls;
 use FreeDSx\Ldap\Entry\Entries;
+use FreeDSx\Ldap\Entry\Entry;
 use FreeDSx\Ldap\Exception\OperationException;
 use FreeDSx\Ldap\Exception\ProtocolException;
 use FreeDSx\Ldap\LdapClient;
@@ -194,6 +195,8 @@ public function isAtStartOfList(): bool
     }
 
     /**
+     * @return Entries<Entry>
+     *
      * @throws ProtocolException
      * @throws OperationException
      */
@@ -203,6 +206,8 @@ public function getEntries(): Entries
     }
 
     /**
+     * @return Entries<Entry>
+     *
      * @throws OperationException
      * @throws ProtocolException
      */

diff --git a/src/FreeDSx/Ldap/Server/LoggerTrait.php b/src/FreeDSx/Ldap/Server/LoggerTrait.php
@@ -29,6 +29,8 @@ trait LoggerTrait
     /**
      * Logs a message and then throws a runtime exception.
      *
+     * @param array<string, mixed> $context
+     *
      * @throws RuntimeException
      */
     private function logAndThrow(
-Original file line number
+Diff line change
@@ Expand Up / @@ -42,6 +42,9 @@ class SyncIdSet extends SyncInfoMessage @@
         private bool $refreshDeletes;
+        /**
+         * @var string[]
+         */
         private array $entryUuids;
         /**
@@ Expand Down @@