app/Services/Ldap/LdapConnectionHelper.php

@@ -1,21 +1,37 @@
 <?php
 
+// Strenge Typprüfung für Parameter- und Rückgabetypen aktivieren.
 declare(strict_types=1);
 
 namespace App\Services\Ldap;
 
 use RuntimeException;
 
+/**
+ * Hilfsklasse zum Aufbau einer LDAP/LDAPS-Verbindung.
+ *
+ * Aufgaben:
+ * - liest Server, Port und Timeout aus der LDAP-Konfiguration
+ * - erstellt eine LDAP-Verbindung
+ * - setzt die notwendigen Optionen (Protokollversion, Netzwerk-Timeout)
+ *
+ * Wichtig:
+ * - Diese Klasse führt KEIN ldap_bind durch.
+ * - Das Bind (mit Benutzer- oder Service-Konto) erfolgt in den Fach-Services
+ *   wie LdapAuthService oder LdapDirectoryService.
+ */
 class LdapConnectionHelper
 {
-    /** @var array<string, mixed> */
+    /** @var array<string, mixed> LDAP-spezifische Konfiguration (server, port, timeout, etc.) */
     private array $config;
 
     /**
-     * @param array<string, mixed> $ldapConfig
+     * @param array<string, mixed> $ldapConfig Teilbereich "ldap" aus der config.php
      */
     public function __construct(array $ldapConfig)
     {
+        // LDAP-Konfiguration in der Instanz speichern.
+        // Dadurch steht sie in allen Methoden dieser Klasse zur Verfügung.
         $this->config = $ldapConfig;
     }
 
@@ -24,26 +40,43 @@ class LdapConnectionHelper
      * aber ohne Bind. Den Bind führen die aufrufenden Services durch.
      *
      * @return resource LDAP-Verbindungs-Handle
+     *
+     * @throws RuntimeException wenn der Server nicht konfiguriert ist oder die Verbindung scheitert
      */
     public function createConnection()
     {
+        // Server, Port und Timeout aus der Konfiguration lesen.
+        // Die Null-Koaleszenz-Operatoren (??) setzen Standardwerte, falls Keys fehlen.
         $server  = (string)($this->config['server'] ?? '');
         $port    = (int)($this->config['port'] ?? 636);
         $timeout = (int)($this->config['timeout'] ?? 5);
 
+        // Ohne Server-Adresse kann keine Verbindung aufgebaut werden.
         if ($server === '') {
             throw new RuntimeException('LDAP-Konfiguration ist unvollständig (server fehlt).');
         }
 
+        // Verbindung zum LDAP/AD-Server herstellen.
+        // ldap_connect liefert entweder ein Verbindungs-Handle (Resource) oder false.
         $connection = ldap_connect($server, $port);
 
+        // Wenn keine Verbindung aufgebaut werden konnte, Exception werfen.
         if ($connection === false) {
             throw new RuntimeException('LDAP-Verbindung konnte nicht aufgebaut werden.');
         }
 
+        // LDAP-Version auf 3 setzen, dies ist die gängige Standardversion.
         ldap_set_option($connection, LDAP_OPT_PROTOCOL_VERSION, 3);
+
+        // Netzwerk-Timeout setzen, damit Anfragen nicht ewig hängen bleiben.
         ldap_set_option($connection, LDAP_OPT_NETWORK_TIMEOUT, $timeout);
 
+        // Referral-Following deaktivieren (0 = aus).
+        // Das verhindert, dass der Client automatisch zu anderen LDAP-Servern weitergeleitet wird.
+        ldap_set_option($connection, LDAP_OPT_REFERRALS, 0);
+
+        // Verbindungs-Handle an aufrufende Services zurückgeben.
+        // Dort wird dann der eigentliche ldap_bind durchgeführt.
         return $connection;
     }
 }