Allow processing search results as they come in via handlers. This gives more granular control over processing referral results / entry results and lets library users process results as they come in instead of waiting until the end of the result set.

Author: ChadSikorra

src/FreeDSx/Ldap/Operation/Request/SearchRequest.php

@@ -26,6 +26,8 @@
 use FreeDSx\Ldap\Exception\RuntimeException;
 use FreeDSx\Ldap\Protocol\Factory\FilterFactory;
 use FreeDSx\Ldap\Search\Filter\FilterInterface;
+use FreeDSx\Ldap\Search\Handler\EntryHandlerInterface;
+use FreeDSx\Ldap\Search\Handler\ReferralHandlerInterface;
 use function array_map;
 
 /**
@@ -106,6 +108,10 @@ class SearchRequest implements RequestInterface
      */
     private array $attributes = [];
 
+    private ?EntryHandlerInterface $entryHandler = null;
+
+    private ?ReferralHandlerInterface $referralHandler = null;
+
     public function __construct(
         FilterInterface $filter,
         Attribute|string ...$attributes
@@ -282,6 +288,30 @@ public function setFilter(FilterInterface $filter): self
         return $this;
     }
 
+    public function getEntryHandler(): ?EntryHandlerInterface
+    {
+        return $this->entryHandler;
+    }
+
+    public function useEntryHandler(?EntryHandlerInterface $entryHandler): self
+    {
+        $this->entryHandler = $entryHandler;
+
+        return $this;
+    }
+
+    public function getReferralHandler(): ?ReferralHandlerInterface
+    {
+        return $this->referralHandler;
+    }
+
+    public function useReferralHandler(?ReferralHandlerInterface $referralHandler): self
+    {
+        $this->referralHandler = $referralHandler;
+
+        return $this;
+    }
+
     /**
      * {@inheritDoc}
      *

src/FreeDSx/Ldap/Protocol/ClientProtocolHandler/ClientSearchHandler.php

@@ -27,6 +27,8 @@
 use FreeDSx\Ldap\Protocol\LdapMessageRequest;
 use FreeDSx\Ldap\Protocol\LdapMessageResponse;
 use FreeDSx\Ldap\Protocol\Queue\ClientQueue;
+use FreeDSx\Ldap\Search\Handler\EntryHandlerInterface;
+use FreeDSx\Ldap\Search\Handler\ReferralHandlerInterface;
 use FreeDSx\Ldap\Search\Result\EntryResult;
 use FreeDSx\Ldap\Search\Result\ReferralResult;
 use FreeDSx\Socket\Exception\ConnectionException;
@@ -69,6 +71,63 @@ public function handleResponse(
         ClientQueue $queue,
         ClientOptions $options,
     ): ?LdapMessageResponse {
+        /** @var SearchRequest $searchRequest */
+        $searchRequest = $messageTo->getRequest();
+
+        $entryHandler = $searchRequest->getEntryHandler();
+        $referralHandler = $searchRequest->getReferralHandler();
+
+        if ($entryHandler || $referralHandler) {
+            $finalResponse = $this->searchWithHandlers(
+                $messageFrom,
+                $messageTo,
+                $entryHandler,
+                $referralHandler,
+                $queue,
+            );
+        } else {
+            $finalResponse = $this->searchWithoutHandlers(
+                $messageFrom,
+                $messageTo,
+                $queue,
+            );
+        }
+
+        return parent::handleResponse(
+            $messageTo,
+            $finalResponse,
+            $queue,
+            $options
+        );
+    }
+
+    private function searchWithHandlers(
+        LdapMessageResponse $messageFrom,
+        LdapMessageRequest $messageTo,
+        ?EntryHandlerInterface $entryHandler,
+        ?ReferralHandlerInterface $referralHandler,
+        ClientQueue $queue,
+    ): LdapMessageResponse {
+        while (!$messageFrom->getResponse() instanceof SearchResultDone) {
+            $response = $messageFrom->getResponse();
+
+            if ($response instanceof SearchResultEntry) {
+                $entryHandler?->handleEntry(new EntryResult($messageFrom));
+            } elseif ($response instanceof SearchResultReference) {
+                $referralHandler?->handleReferral(new ReferralResult($messageFrom));
+            }
+
+            $messageFrom = $queue->getMessage($messageTo->getMessageId());
+        }
+
+        return $messageFrom;
+    }
+
+    private function searchWithoutHandlers(
+        LdapMessageResponse $messageFrom,
+        LdapMessageRequest $messageTo,
+        ClientQueue $queue,
+    ): LdapMessageResponse {
         $entryResults = [];
         $referralResults = [];
 
@@ -86,22 +145,15 @@ public function handleResponse(
 
         $ldapResult = $messageFrom->getResponse();
 
-        $finalResponse = new LdapMessageResponse(
+        return new LdapMessageResponse(
             $messageFrom->getMessageId(),
             new SearchResponse(
                 $ldapResult,
                 $entryResults,
                 $referralResults,
             ),
             ...$messageFrom->controls()
-                ->toArray()
-        );
-
-        return parent::handleResponse(
-            $messageTo,
-            $finalResponse,
-            $queue,
-            $options
+            ->toArray()
         );
     }
 }

src/FreeDSx/Ldap/Search/Handler/EntryHandlerInterface.php

@@ -0,0 +1,21 @@
+<?php
+
+/**
+ * This file is part of the FreeDSx LDAP package.
+ *
+ * (c) Chad Sikorra <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace FreeDSx\Ldap\Search\Handler;
+
+use FreeDSx\Ldap\Search\Result\EntryResult;
+
+interface EntryHandlerInterface
+{
+    public function handleEntry(EntryResult $entryResult): void;
+}

src/FreeDSx/Ldap/Search/Handler/ReferralHandlerInterface.php

@@ -0,0 +1,21 @@
+<?php
+
+/**
+ * This file is part of the FreeDSx LDAP package.
+ *
+ * (c) Chad Sikorra <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace FreeDSx\Ldap\Search\Handler;
+
+use FreeDSx\Ldap\Search\Result\ReferralResult;
+
+interface ReferralHandlerInterface
+{
+    public function handleReferral(ReferralResult $referralResult): void;
+}