在 ServBay 中使用 PHP 的 OpenLDAP 擴充套件

ServBay 是一款強大且多元的本地 Web 開發環境，支援多種技術棧。對於需要與 LDAP（輕量級目錄存取協定）伺服器互動的 PHP 應用開發者，ServBay 預先整合了 PHP 的 OpenLDAP 擴充套件，可方便啟用並使用。本文將帶您如何在 ServBay 環境下善用這一擴充套件，實現用戶認證、目錄查詢等功能。

什麼是 OpenLDAP 以及 PHP 的 OpenLDAP 擴充套件？

OpenLDAP 是一套受歡迎的開源實作，提供基於 LDAP 協定的目錄服務。LDAP 協定是一種應用層協定，主要用於存取及維護分散式的目錄資訊服務，在企業環境中被廣泛用於用戶身份驗證、組織架構管理、通訊錄服務等。

PHP 的 OpenLDAP 擴充套件（常稱為 ldap 擴充套件）是 PHP 的一個模組，提供與 LDAP 伺服器通訊相關的函式庫。藉由這套擴充套件，PHP 應用程式能夠連線到 LDAP 伺服器，執行綁定（驗證）、搜尋、新增、修改、刪除目錄項目等操作。

在 ServBay 中，重點是 PHP 內建的這個 OpenLDAP 客戶端擴充套件，它允許您的 PHP 程式連結並操作外部的 LDAP 伺服器。ServBay 本身並不包含 OpenLDAP 伺服器。

PHP OpenLDAP 擴充套件的主要功能

透過 PHP 的 OpenLDAP 擴充套件，您可以：

連接 LDAP 伺服器：與指定的 LDAP 伺服器建立連線。
執行綁定操作：進行匿名綁定，或使用 DN（Distinguished Name，辨別名稱）與密碼進行驗證綁定。
查詢目錄：根據篩選條件、搜尋基底與範圍查詢目錄內的項目。
讀取項目信息：取得搜尋結果中每個項目的屬性與值。
執行修改操作：新增項目、刪除項目、修改項目屬性。
處理 LDAP 錯誤：取得操作時失敗的錯誤訊息。

ServBay 中 PHP OpenLDAP 擴充套件的版本相容性

ServBay 支援同時安裝與執行多個 PHP 版本。PHP 的 OpenLDAP 擴充套件一般隨官方 PHP 發佈包一同提供，並且在 ServBay 的 PHP 套件中預設包含。這代表您在使用 ServBay 選擇的 PHP 版本時，大多情況下已可直接使用 OpenLDAP 擴充套件。

如何驗證 PHP OpenLDAP 擴充套件是否已啟用

雖然 ServBay 旨在提供開箱即用的體驗，且通常預設啟用常用擴充套件，驗證狀態始終是一個好習慣。最簡單的辦法，就是透過 phpinfo() 函式。

在您的 ServBay 網站根目錄（預設為 /Applications/ServBay/www）下建立新的 PHP 檔案，例如 info.php。
在 info.php 檔案中新增下列內容：
php
```
<?php
phpinfo();
?>
```
1
2
3
使用瀏覽器存取您在 ServBay 設定對應此檔案的網站網址（例如 http://servbay.demo/info.php）。
在顯示的 phpinfo() 頁面中，尋找標題為 ldap 的區塊。
若可見 ldap 區塊，且裡面顯示相關設定（例如 LDAP Support enabled），即可代表 PHP 的 OpenLDAP 擴充套件已正確載入並啟用。

若查找不到 ldap 區塊，或 LDAP Support 顯示為 disabled，您可能需要檢查 ServBay 中該 PHP 版本的安裝設定，或洽詢 ServBay 支援協助。不過絕大多數情境下，該擴充套件皆預設啟用。

在 PHP 程式中使用 OpenLDAP

確認已啟用 OpenLDAP 擴充套件後，您便可在 PHP 應用程式裡透過 ldap_* 系列函式與 LDAP 伺服器互動。以下是一個基本範例，示範如何連結 LDAP 伺服器、執行管理員綁定、搜尋用戶並嘗試用戶驗證。

重要提醒： 下述程式碼中的 LDAP 伺服器地址、連接埠、管理員 DN、密碼、搜尋基底、用戶過濾條件、用戶密碼等，皆為範例用佔位文字。實務中必須用您要連線之 LDAP 伺服器的實際設定與資訊替換。切勿在生產環境中將敏感資訊（如密碼）硬編進程式碼。

範例程式：基礎連線、查詢與驗證

請將下列代碼儲存於 ServBay 網站目錄下 PHP 檔案（例：ldap_test.php），並於瀏覽器中存取執行。

php

<?php

// --- LDAP 連線設定 ---
// 請替換為您的 LDAP 伺服器地址。如需使用 LDAPS (SSL/TLS)，請用 ldaps:// 開頭，預設埠號為 636。
$ldapURI = "ldap://ldap.example.com:389";
// 請替換為具有搜尋權限的 LDAP 管理員或用戶的 DN（辨別名稱）
$ldapAdminRdn = "cn=admin,dc=example,dc=com";
// 請替換為上述管理員 DN 對應的密碼
$ldapAdminPassword = "admin_password";

// --- 用戶查詢與驗證設定 ---
// 請替換為 LDAP 目錄中用戶所屬的查詢基底 DN
$searchBase = "dc=example,dc=com";
// 請替換為搜尋特定用戶時使用的過濾條件。例如搜尋 uid 為 'servbay-demo' 的用戶。
$searchFilter = "(uid=servbay-demo)";
// 請替換為要驗證的用戶密碼
$userPasswordToAuthenticate = "user_password_for_servbay_demo";


echo "<h2>ServBay 中 PHP OpenLDAP 範例</h2>";

// 1. 連線 LDAP 伺服器
echo "<p>嘗試連線到 LDAP 伺服器: {$ldapURI}...</p>";
$ldapConn = ldap_connect($ldapURI);

if (!$ldapConn) {
    die("<p style='color: red;'>錯誤：無法連線到 LDAP 伺服器。</p>");
}
echo "<p style='color: green;'>成功連線至 LDAP 伺服器。</p>";

// 設定 LDAP 選項（建議設定協定版本且不跟隨 referrals）
ldap_set_option($ldapConn, LDAP_OPT_PROTOCOL_VERSION, 3);
ldap_set_option($ldapConn, LDAP_OPT_REFERRALS, 0);

// 2. 使用管理員帳號進行綁定（供搜尋等需要權限的操作）
echo "<p>嘗試使用管理員 DN '{$ldapAdminRdn}' 綁定...</p>";
if (!ldap_bind($ldapConn, $ldapAdminRdn, $ldapAdminPassword)) {
    echo "<p style='color: red;'>錯誤：管理員綁定失敗。</p>";
    echo "<p style='color: red;'>LDAP 錯誤: " . ldap_error($ldapConn) . "</p>";
    ldap_unbind($ldapConn); // 關閉連線
    die();
}
echo "<p style='color: green;'>管理員綁定成功。</p>";

// 3. 查詢用戶
echo "<p>嘗試於基底 DN '{$searchBase}' 使用過濾條件 '{$searchFilter}' 查詢...</p>";
$searchResult = ldap_search($ldapConn, $searchBase, $searchFilter);

if (!$searchResult) {
    echo "<p style='color: red;'>錯誤：LDAP 查詢失敗。</p>";
    echo "<p style='color: red;'>LDAP 錯誤: " . ldap_error($ldapConn) . "</p>";
    ldap_unbind($ldapConn); // 關閉連線
    die();
}
echo "<p style='color: green;'>查詢成功。</p>";

// 4. 取得查詢結果
$entries = ldap_get_entries($ldapConn, $searchResult);

if ($entries["count"] > 0) {
    echo "<p>找到 {$entries["count"]} 個符合條件的項目。</p>";
    // 假設只需取得第一筆符合的用戶資料
    $userDn = $entries[0]["dn"];
    echo "<p>第一個符合的用戶 DN: <strong>{$userDn}</strong></p>";

    // 5. 嘗試用找到的用戶 DN 與密碼進行驗證綁定
    echo "<p>嘗試用用戶 DN '{$userDn}' 進行驗證綁定...</p>";
    // 注意：此處執行用戶驗證綁定，不同於管理員綁定
    if (@ldap_bind($ldapConn, $userDn, $userPasswordToAuthenticate)) {
        echo "<p style='color: green;'>用戶驗證成功！</p>";
    } else {
        echo "<p style='color: red;'>用戶驗證失敗。</p>";
        echo "<p style='color: red;'>LDAP 錯誤: " . ldap_error($ldapConn) . "</p>";
    }

} else {
    echo "<p>查無符合過濾條件 '{$searchFilter}' 的用戶。</p>";
}

// 6. 關閉 LDAP 連線
echo "<p>關閉 LDAP 連線...</p>";
ldap_unbind($ldapConn);
echo "<p style='color: green;'>連線已關閉。</p>";

?>

程式碼說明

連線（ldap_connect）：建立與 LDAP 伺服器的連線，回傳連線資源識別碼。
設定選項（ldap_set_option）：調整連線行為。LDAP_OPT_PROTOCOL_VERSION, 3 設定為 LDAPv3（現行主流），LDAP_OPT_REFERRALS, 0 停用 referrals（多數單純應用不需開啟）。
綁定（ldap_bind）：於 LDAP 伺服器進行身份驗證。
- 匿名綁定：ldap_bind($ldapConn) —— 無 DN 及密碼，權限通常有限。
- 驗證綁定：ldap_bind($ldapConn, $dn, $password) —— 使用指定 DN 及密碼。範例內先以管理員 DN 綁定（供查詢用），再用找到的用戶 DN 綁定進行用戶驗證。
查詢（ldap_search）：於指定查詢基底 DN (searchBase)，配合過濾條件 (searchFilter)，搜尋符合的項目。
取得條目（ldap_get_entries）：整合查詢結果，取得所有相關目錄項目之資料，回傳含戶資料的陣列。
關閉連線（ldap_unbind）：結束與 LDAP 伺服器的連結並釋放資源。

注意事項

LDAP 伺服器需求：本文僅說明如何於 PHP 利用 OpenLDAP 客戶端 擴充套件。您需有可用之 LDAP 伺服器（可獨立於 ServBay 部署並管理之 OpenLDAP、本地測試伺服器，或遠端企業用 LDAP/Active Directory）。
安全性：於生產環境管理 LDAP 憑證時，務必遵循資訊安全最佳實踐，如採用環境變數或安全設定檔，並盡可能以 LDAPS (LDAP over SSL/TLS，預設埠 636) 加密連線，避免明文 LDAP (埠 389)。
錯誤處理：範例僅做了基礎錯誤處理。實務開發時建議加強錯誤捕捉與日誌紀錄機制。
DN 格式：DN（辨別名稱）格式十分嚴謹，請確保填寫與您的 LDAP 伺服器設定準確匹配。

常見問題 (FAQ)

Q: 我在 phpinfo() 裡沒看見 ldap 區塊，或顯示為未啟用，該怎麼辦？

A: 在 ServBay，PHP OpenLDAP 擴充套件預設大多是開啟狀態。如遇此狀況，請確保您觀看的是正確 PHP 版本對應的 phpinfo() 輸出。如仍未顯示，可能為 ServBay 特定版本或安裝異常，請嘗試重新安裝對應 PHP 套件，或諮詢 ServBay 支援人員。

Q: 執行 PHP 程式報錯：Call to undefined function ldap_connect()。

A: 這代表 PHP 的 OpenLDAP 擴充套件沒有被正確載入或啟用。請回頭參閱先前檢查方式，靠 phpinfo() 驗證擴充套件狀態。

Q: 擴充套件已啟用，但連線或綁定失敗，並顯示 LDAP 錯誤訊息。

A: 請仔細確認您的連線設定（伺服器地址、埠號）以及綁定的帳號（DN、密碼）無誤。LDAP 錯誤訊息（透過 ldap_error() 取得）通常能給出失敗原因的線索，例如 "Invalid credentials"（認證失敗）或 "Can't contact LDAP server"（無法連結伺服器）。務必確認您的 LDAP 伺服器執行中且網路可達。

總結

ServBay 為開發者提供了一個快速、便利的方式以取得和使用 PHP 的 OpenLDAP 擴充套件。只需簡單驗證步驟，您即可確保 PHP 環境已具備與 LDAP 伺服器溝通的能力。結合 PHP 豐富的 LDAP 函式庫，開發者可輕鬆在以 ServBay 打造的本地 Web 應用加上用戶認證、目錄資訊查詢等功能，大幅擴展應用場域與效益。

在 ServBay 中使用 PHP 的 OpenLDAP 擴充套件 ​

什麼是 OpenLDAP 以及 PHP 的 OpenLDAP 擴充套件？ ​

PHP OpenLDAP 擴充套件的主要功能 ​

ServBay 中 PHP OpenLDAP 擴充套件的版本相容性 ​

如何驗證 PHP OpenLDAP 擴充套件是否已啟用 ​

在 PHP 程式中使用 OpenLDAP ​

範例程式：基礎連線、查詢與驗證 ​

程式碼說明 ​

注意事項 ​

常見問題 (FAQ) ​

總結 ​