Support LDAP_OPT_DIAGNOSTIC_MESSAGE

src/Adldap.php

@@ -2,6 +2,7 @@
 
 namespace Adldap;
 
+use Adldap\Classes\AdldapError;
 use Adldap\Exceptions\AdldapException;
 use Adldap\Interfaces\ConnectionInterface;
 use Adldap\Classes\AdldapSearch;
@@ -822,7 +823,14 @@ public function getRootDse($attributes = ['*', '+'])
      * This may indeed be a 'Success' message but if you get an unknown error
      * it might be worth calling this function to see what errors were raised
      *
-     * @return string
+     * Note that this will usually return a string, unless setExtendedErrors()
+     * has been called on Connection\Ldap
+     *
+     * When setExtendedErrors has been set, this will return false if the last
+     * request completed successfully. If not, it will return a new instance of
+     * AdldapError.
+     * 
+     * @return bool|string|AdldapError
      */
     public function getLastError()
     {

src/Classes/AdldapError.php

@@ -0,0 +1,51 @@
+<?php
+namespace Adldap\Classes;
+
+class AdldapError
+{
+    /**
+     * @var int the error code from ldap_errno
+     */
+    private $errorCode = null;
+
+    /**
+     * @var string the error message from ldap_error
+     */
+    private $errorMessage = null;
+
+    /**
+     * @var string the diagnostic message when retrieved after an ldap_error
+     */
+    private $diagnosticMessage = null;
+
+    public function __construct($errorCode, $errorMessage, $diagnosticMessage)
+    {
+        $this->errorCode = $errorCode;
+        $this->errorMessage = $errorMessage;
+        $this->diagnosticMessage;
+    }
+
+    /**
+     * @return int
+     */
+    public function getErrorCode()
+    {
+        return $this->errorCode;
+    }
+
+    /**
+     * @return string
+     */
+    public function getErrorMessage()
+    {
+        return $this->errorMessage;
+    }
+
+    /**
+     * @return string
+     */
+    public function getDiagnosticMessage()
+    {
+        return $this->diagnosticMessage;
+    }
+}

src/Connections/Ldap.php

@@ -2,6 +2,7 @@
 
 namespace Adldap\Connections;
 
+use Adldap\Classes\AdldapError;
 use Adldap\Exceptions\AdldapException;
 use Adldap\Traits\LdapFunctionSupportTrait;
 use Adldap\Interfaces\ConnectionInterface;
@@ -70,6 +71,14 @@ class Ldap implements ConnectionInterface
      */
     protected $suppressErrors = true;
 
+    /**
+     * Define whether extended errors (returning an AdldapError)
+     * should be performed.
+     *
+     * @var bool
+     */
+    protected $extendedErrors = false;
+
     /**
      * Returns true / false if the
      * current connection instance is using
@@ -160,6 +169,17 @@ public function showErrors()
         return $this;
     }
 
+    /**
+     * Sets the extendedErrors property to true.
+     * @return $this
+     */
+    public function setExtendedErrors()
+    {
+        $this->extendedErrors = true;
+
+        return $this;
+    }
+
     /**
      * Set's the current connection
      * to use SSL.
@@ -268,6 +288,30 @@ public function countEntries($searchResults)
      */
     public function getLastError()
     {
+        if ($this->extendedErrors) {
+            $diagMessage = '';
+            $errorNumber = ldap_errno($this->getConnection());
+
+            // if we have a returned value of 0, there was nothing but success!
+            // http://php.net/manual/en/function.ldap-errno.php
+            if ($errorNumber == 0) {
+                return false;
+            }
+
+            $errorString = ldap_err2str($errorNumber);
+
+            if (defined('LDAP_OPT_DIAGNOSTIC_MESSAGE')) {
+                // we are using an ldap library that supports getting diagnostic msgs.
+                if ($this->suppressErrors) {
+                    $diagMessage = @ldap_get_option($this->getConnection(), LDAP_OPT_DIAGNOSTIC_MESSAGE, $err);
+                } else {
+                    $diagMessage = ldap_get_option($this->getConnection(), LDAP_OPT_DIAGNOSTIC_MESSAGE, $err);
+                }
+            }
+
+            return new AdldapError($errorNumber, $errorString, $diagMessage);
+        }
+
         if ($this->suppressErrors) {
             return @ldap_error($this->getConnection());
         }