{"record":{"id":"a1e30692412c0d90","repo":"BookStackApp/BookStack","slug":"errors-ldap-extension-not-installed","errorCode":null,"errorMessage":"errors.ldap_extension_not_installed","messagePattern":"errors\\.ldap_extension_not_installed","errorType":"exception","errorClass":"LdapException","httpStatus":null,"severity":"critical","filePath":"app/Access/LdapService.php","lineNumber":227,"sourceCode":"    }\n\n    /**\n     * Get the connection to the LDAP server.\n     * Creates a new connection if one does not exist.\n     *\n     * @throws LdapException\n     *\n     * @return resource|\\LDAP\\Connection\n     */\n    protected function getConnection()\n    {\n        if ($this->ldapConnection !== null) {\n            return $this->ldapConnection;\n        }\n\n        // Check LDAP extension in installed\n        if (!function_exists('ldap_connect') && config('app.env') !== 'testing') {\n            throw new LdapException(trans('errors.ldap_extension_not_installed'));\n        }\n\n        // Disable certificate verification.\n        // This option works globally and must be set before a connection is created.\n        if ($this->config['tls_insecure']) {\n            $this->ldap->setOption(null, LDAP_OPT_X_TLS_REQUIRE_CERT, LDAP_OPT_X_TLS_NEVER);\n        }\n\n        // Configure any user-provided CA cert files for LDAP.\n        // This option works globally and must be set before a connection is created.\n        if ($this->config['tls_ca_cert']) {\n            $this->configureTlsCaCerts($this->config['tls_ca_cert']);\n        }\n\n        $ldapHost = $this->parseServerString($this->config['server']);\n        $ldapConnection = $this->ldap->connect($ldapHost);\n\n        if ($ldapConnection === false) {","sourceCodeStart":209,"sourceCodeEnd":245,"githubUrl":"https://github.com/BookStackApp/BookStack/blob/18f8469a1c72f8cc8497e9372635e6dea5028071/app/Access/LdapService.php#L209-L245","documentation":"LdapException thrown by LdapService::getConnection when the PHP LDAP extension is unavailable — function_exists('ldap_connect') is false and the environment is not 'testing'. The library cannot create any LDAP connection without the extension, so it fails fast with an explanatory message.","triggerScenarios":"Any call reaching getConnection (getUserWithAttributes, validateUserCredentials, getParentsOfGroup) on a PHP runtime where the php-ldap extension is not installed/enabled, outside the testing environment.","commonSituations":"php-ldap missing on the host or in the Docker image; extension present for CLI but not enabled for web-server SAPI (or vice versa); upgrade to a new PHP version where the ext wasn't reinstalled; using LDAP features on a host built without LDAP support.","solutions":["Install the PHP LDAP extension (e.g. apt-get install php-ldap / docker-php-ext-install ldap)","Enable it: add extension=ldap.so (or php_ldap.dll on Windows) to the relevant php.ini and restart PHP-FPM/Apache","Confirm via php -m or phpinfo() that 'ldap' is listed for the SAPI the app uses","If LDAP isn't needed, avoid triggering LDAP login/sync features"],"exampleFix":"# before\nphp -m | grep ldap   # (no result)\n# after\napt-get install -y php-ldap && systemctl restart php8.2-fpm","handlingStrategy":"validation","validationCode":"if (!function_exists('ldap_connect')) {\n    throw new RuntimeException('PHP LDAP extension is not installed/enabled.');\n}","typeGuard":null,"tryCatchPattern":"try {\n    $user = $ldapService->getUserWithAttributes($username);\n} catch (\\BookStack\\Exceptions\\LdapException $e) {\n    abort(503, 'LDAP is not available on this host: ' . $e->getMessage());\n}","preventionTips":["Add php-ldap to your deployment image/infrastructure-as-code","Verify the extension for both CLI and web SAPIs after PHP upgrades","Health-check function_exists('ldap_connect') at deploy time"],"tags":["ldap","php-extension","environment"],"backgroundTag":"missing-php-extension","analyzedSha":"18f8469a1c72f8cc8497e9372635e6dea5028071","analyzedAt":"2026-09-02T19:49:33.068Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-10T02:17:09.455Z"}