PHP4手册:函数库及函数(二十四) LDAP 目录协定函式库
December 21th,2008 22:39:58 Category :
PHP+Mysql
Click (577)--------------------------------------------------------------------------------
LDAP 目录协定函式库
--------------------------------------------------------------------------------
本函式库共有 25 个函式
LDAP (Lightweight Directory Access Protocol) 是一种轻量的目录存取协定，提供客户从各个角落连接到目录伺服器中。在 RFC 1777 及 RFC 1778 中对 LDAP 有较深入的描述，亦可参考 Netscape 站上有关 LDAP 方面的资料。
在 LDAP 的协定之中，很像硬碟目录结构或倒过来的树状结构。LDAP 的根就是全世界，第一级是属于国别 (countries) 性质的层级，之后可能会有公司 (organization) 的层级，接着是部门 (organizationalUnit)，再来为个人。而就像档案，每个人都会有所谓的显名 (distinguished name, 简称 dn)，dn 可能像酱子 cn=John Smith,ou=Accounts,o=My Company,c=US。
// 本例使用到 connect, bind, search, interpret search
// result, close connection 等等 LDAP 的功能。
echo "
LDAP 搜寻测试
";
echo "连线中 ...";
$ds=ldap_connect("localhost"); // 先连上有效的 LDAP 伺服器
echo "连上 ".$ds."
";
if ($ds) {
echo "Binding ...";
$r=ldap_bind($ds); // 匿名的 bind，为唯读属性
echo "Bind 传回 ".$r."
";
echo "Searching for (sn=S*) ..."; // 找寻 S 开头的姓氏
$sr=ldap_search($ds,"o=My Company, c=US", "sn=S*");
echo "Search 传回 ".$sr."
";
echo "S 开头的姓氏有 ".ldap_count_entries($ds,$sr)." 个
";
echo "取回姓氏资料 ...
";
$info = ldap_get_entries($ds, $sr);
echo "资料传回 ".$info["count"]." 笔:
";
for ($i=0; $i<$info["count"]; $i++) {
echo "dn 为: ". $info[$i]["dn"] ."
";
echo "cn 为: ". $info[$i]["cn"][0] ."
";
echo "email 为: ". $info[$i]["mail"][0] ."
";
}
echo "关闭连结";
ldap_close($ds);
} else {
echo "
无法连接到 LDAP 伺服器
";
}
?>
欲使用 LDAP 伺服器功能要先在 Web 伺服器安装 LDAP 客户端程式，较着名的有美国密西根大学的 ldap-3.3 套件或者是 Netscape 的 Directory SDK。可到下列网址找回来安装
Netscape http://developer.netscape.com/tech/directory/
密西根大学 http://www.umich.edu/~dirsvcs/ldap/index.html
OpenLDAP 计划 http://www.openldap.com
LDAP World http://elvira.innosoft.com/ldapworld
ldap_add: 增加 LDAP 名录的条目。
ldap_mod_add: 增加 LDAP 名录的属性。
ldap_mod_del: 删除 LDAP 名录的属性。
ldap_mod_replace: 新的 LDAP 名录取代旧属性。
ldap_bind: 系住 LDAP 目录。
ldap_close: 结束 LDAP 连结。
ldap_connect: 连上 LDAP 伺服器。
ldap_count_entries: 搜寻结果的数目。
ldap_delete: 删除指定资源。
ldap_dn2ufn: 将 dn 转成易读的名字。
ldap_explode_dn: 切开 dn 的栏位。
ldap_first_attribute: 取得第一笔资源的属性。
ldap_first_entry: 取得第一笔结果代号。
ldap_free_result: 释放传回资料记忆体。
ldap_get_attributes: 取得传回资料的属性。
ldap_get_dn: 取得 DN 值。
ldap_get_entries: 取得全部传回资料。
ldap_get_values: 取得全部传回值。
ldap_list: 列出简表。
ldap_modify: 改变 LDAP 名录的属性。
ldap_next_attribute: 取得传回资料的下笔属性。
ldap_next_entry: 取得下一笔结果代号。
ldap_read: 取得目前的资料属性。
ldap_search: 列出树状简表。
ldap_unbind: 结束 LDAP 连结。
--------------------------------------------------------------------------------
函式:ldap_add()
--------------------------------------------------------------------------------
LDAP 目录协定函式库
ldap_add
增加 LDAP 名录的条目。
语法: boolean ldap_add(int handle, string dn, array entry);
传回值: 布林值
函式种类: 网路系统
内容说明
本函式用来加入新的条目到 LDAP 名录之中。参数 handle 为开启 LDAP 的代号。参数 dn 为要加入条目的具体 dn 字串。参数 entry 为阵列，为个体所有的条目，阵列的内容是条目的相关资讯。若无错误则传回 true 值。
使用范例
$ds=ldap_connect("localhost"); // 连上 LDAP 伺服器
if ($ds) {
// 系住恰当的 dn
$r=ldap_bind($ds,"cn=root, o=A2Z Company, c=TW", "secret");
// 预先准备好新条目的资料
$info["cn"]="Wilson Peng";
$info["sn"]="Peng";
$info["mail"]="wilson@wilson.gs";
$info["objectclass"]="person";
// 加入新条目
$r=ldap_add($ds, "cn=Wilson Peng, o=A2Z Company, c=TW", $info);
ldap_close($ds);
} else {
echo "抱歉，无法连上 LDAP 伺服器。";
}
?>
--------------------------------------------------------------------------------
函式:ldap_mod_add()
--------------------------------------------------------------------------------
LDAP 目录协定函式库
ldap_mod_add
增加 LDAP 名录的属性。
语法: boolean ldap_mod_add(int handle, string dn, array entry);
传回值: 布林值
函式种类: 网路系统
内容说明
本函式用来加入新的属性到 LDAP 名录之中。参数 handle 为开启 LDAP 的代号。参数 dn 为要加入条目的具体 dn 字串。参数 entry 为阵列，为个体所有的属性，阵列的内容是名录属性的相关资讯。若无错误则传回 true 值。
参考
ldap_modify()
--------------------------------------------------------------------------------
函式:ldap_mod_del()
--------------------------------------------------------------------------------
LDAP 目录协定函式库
ldap_mod_del
删除 LDAP 名录的属性。
语法: boolean ldap_mod_del(int handle, string dn, array entry);
传回值: 布林值
函式种类: 网路系统
内容说明
本函式用来删除到 LDAP 名录之中的指定属性。参数 handle 为开启 LDAP 的代号。参数 dn 为要加入条目的具体 dn 字串。参数 entry 为阵列，为个体所有的属性，阵列的内容是名录属性的相关资讯。若无错误则传回 true 值。
--------------------------------------------------------------------------------
函式:ldap_mod_replace()
--------------------------------------------------------------------------------
LDAP 目录协定函式库
ldap_mod_replace
新的 LDAP 名录取代旧属性。
语法: boolean ldap_mod_replace(int handle, string dn, array entry);
传回值: 布林值
函式种类: 网路系统
内容说明
本函式用来用新的指定属性取代 LDAP 名录之中的属性。参数 handle 为开启 LDAP 的代号。参数 dn 为要加入条目的具体 dn 字串。参数 entry 为阵列，为个体所有的属性，阵列的内容是名录属性的相关资讯。若无错误则传回 true 值
--------------------------------------------------------------------------------
函式:ldap_bind()
--------------------------------------------------------------------------------
LDAP 目录协定函式库
ldap_bind
系住 LDAP 目录。
语法: boolean ldap_bind(int handle, string [bind_rdn], string [bind_password]);
传回值: 布林值
函式种类: 网路系统
内容说明
本函式用来系住特定的 RDN 和使用者密码。参数 handle 为开启 LDAP 的代号。参数 bind_rdn 及 bind_password 可省略。当未指定使用者的 RDN 及密码时，则系住匿名使用者。若无错误则传回 true 值。
--------------------------------------------------------------------------------
函式:ldap_close()
--------------------------------------------------------------------------------
LDAP 目录协定函式库
ldap_close
结束 LDAP 连结。
语法: boolean ldap_close(int handle);
传回值: 布林值
函式种类: 网路系统
内容说明
本函式将关闭与 LDAP 伺服器的连结。参数 handle 为开启 LDAP 的代号。实际上这个函式就是 ldap_unbind() 的别名而已。若无错误则传回 true 值。
参考
ldap_unbind()
--------------------------------------------------------------------------------
函式:ldap_connect()
--------------------------------------------------------------------------------
LDAP 目录协定函式库
ldap_connect
连上 LDAP 伺服器。
语法: int ldap_connect(string [hostname], int [port]);
传回值: 整数
函式种类: 网路系统
内容说明
本函式用来连结 LDAP 的伺服器。参数 hostname 若省略，则传回现在的连结代号，也就是 handle。参数 port 亦可省略，内定值为 389。执行若无错误则传回连结代号，发生错误则传回 false。
--------------------------------------------------------------------------------
函式:ldap_count_entries()
--------------------------------------------------------------------------------
LDAP 目录协定函式库
ldap_count_entries
搜寻结果的数目。
语法: int ldap_count_entries(int handle, int result_identifier);
传回值: 整数
函式种类: 网路系统
内容说明
本函式用来取得搜寻的结果数目。参数 handle 为开启 LDAD 伺服器的代号。参数 result_identifier 为 ldap_search() 所传回的搜寻代号。执行若无错误则传回寻找到的数目，发生错误则传回 false。
--------------------------------------------------------------------------------
函式:ldap_delete()
--------------------------------------------------------------------------------
LDAP 目录协定函式库
ldap_delete
删除指定资源。
语法: boolean ldap_delete(int handle, string dn);
传回值: 布林值
函式种类: 网路系统
内容说明
本函式用来删除指定 dn 的资料。参数 handle 为开启 LDAD 伺服器的代号。参数 dn 为指定的显名 (distinguished name)。发生错误则传回 false，若无错误则传回 true。
--------------------------------------------------------------------------------
函式:ldap_dn2ufn()
--------------------------------------------------------------------------------
LDAP 目录协定函式库
ldap_dn2ufn
将 dn 转成易读的名字。
语法: string ldap_dn2ufn(string dn);
传回值: 字串
函式种类: 网路系统
内容说明
本函式用来转换 dn 的名字成为较易读取的名字 ufn (User Friendly Name)。参数 dn 为欲转换的字串。传回值即为 ufn 字串
--------------------------------------------------------------------------------
函式:ldap_explode_dn()
--------------------------------------------------------------------------------
LDAP 目录协定函式库
ldap_explode_dn
切开 dn 的栏位。
语法: array ldap_explode_dn(string dn, int attrib);
传回值: 阵列
函式种类: 网路系统
内容说明
本函式将 dn 中的各栏位切开，切开后的每个栏位即为 RDN (Relative Distinguished Name)。参数 dn 为欲切开的字串。参数 attrib 若为 0 表示传回该栏的属性，若为 1 则表示传回该栏的值。传回值置于阵列之中。
--------------------------------------------------------------------------------
函式:ldap_first_attribute()
--------------------------------------------------------------------------------
LDAP 目录协定函式库
ldap_first_attribute
取得第一笔资源的属性。
语法: string ldap_first_attribute(int handle, int result_entry_identifier, int ber_identifier);
传回值: 字串
函式种类: 网路系统
内容说明
本函式用来取得 LDAP 中第一笔资源的属性。参数 handle 为开启 LDAP 的代号。参数 result_entry_identifier 将由 ldap_next_attribute() 沿用。参数 ber_identifier 为指标，意即需在前面加上 & 符号。
参考
ldap_get_attributes() ldap_next_attribute()
--------------------------------------------------------------------------------
函式:ldap_first_entry()
--------------------------------------------------------------------------------
LDAP 目录协定函式库
ldap_first_entry
取得第一笔结果代号。
语法: int ldap_first_entry(int handle, int result_identifier);
传回值: 整数
函式种类: 网路系统
内容说明
本函式用来取得 LDAP 中第一笔结果的代号 ID。参数 handle 为开启 LDAP 的代号。参数 result_identifier 为 ldap_search() 所传回的搜寻代号。若有错误则传回 false。
参考
ldap_get_entries()
--------------------------------------------------------------------------------
函式:ldap_free_result()
--------------------------------------------------------------------------------
LDAP 目录协定函式库
ldap_free_result
释放传回资料记忆体。
语法: int ldap_free_result(int result_identifier);
传回值: 整数
函式种类: 网路系统
内容说明
本函式用来释放传回资料所使用的记忆体。若没有使用本函式释放记忆体，程式结束时也会自动释放。
--------------------------------------------------------------------------------
函式:ldap_get_attributes()
--------------------------------------------------------------------------------
LDAP 目录协定函式库
ldap_get_attributes
取得传回资料的属性。
语法: array ldap_get_attributes(int handle, int result_entry_identifier);
传回值: 阵列
函式种类: 网路系统
内容说明
本函式用来取得 LDAP 中所有资源的属性。参数 handle 为开启 LDAP 的代号。参数 result_entry_identifier 将由 ldap_next_attribute() 沿用。传回值为阵列资料，阵列元素从零开始依次为属性的值。例如
return_value["count"] : 属性个数
return_value[0] : 第一个属性
return_value[n] : 第n+1个属性
return_value["attribute"]["count"] : 属性值个数
return_value["attribute"][0] : 第一个属性值
return_value["attribute"][i] : 第i+1个属性值
使用范例
下面范例为片段的程式
$entry = ldap_first_entry($ds, $sr);
$attrs = ldap_get_attributes($ds, $entry);
echo $attrs["count"]." 笔属性资料如下:
\n";
for ($i=0; $i<$attrs["count"]; $i++) {
echo $attrs[$i]."
";
}
?>
参考
ldap_first_attribute() ldap_next_attribute()
--------------------------------------------------------------------------------
函式:ldap_get_dn()
--------------------------------------------------------------------------------
LDAP 目录协定函式库
ldap_get_dn
取得 DN 值。
语法: string ldap_get_dn(int handle, int result_entry_identifier);
传回值: 字串
函式种类: 网路系统
内容说明
本函式用来取得 LDAP 的显名 (DN, distinguished name)字串值。参数 handle 为开启 LDAP 的代号。参数 result_identifier 为 ldap_search() 所传回的搜寻代号。若有错误则传回 false。
--------------------------------------------------------------------------------
函式:ldap_get_entries()
--------------------------------------------------------------------------------
LDAP 目录协定函式库
ldap_get_entries
取得全部传回资料。
语法: array ldap_get_entries(int handle, int result_identifier);
传回值: 阵列
函式种类: 网路系统
内容说明
本函式用来取得 LDAP 的全部传回资料。参数 handle 为开启 LDAP 的代号。传回值为阵列资料，例如
return_value["count"] : 传回资料笔数
return_value[0] : 第一笔传回资料
return_value[i]["dn"] : 第 i+1 笔资料的 DN
return_value[i]["count"] : 第 i+1 笔资料的数目
return_value[i][j] : 第 i+1 笔资料的第 j 值
return_value[i]["attribute"]["count"] : 第 i+1 笔资料的属性数
return_value[i]["attribute"][j] : 第 i+1 笔资料的第 j 个属性
参考
ldap_first_entry() ldap_next_entry()
--------------------------------------------------------------------------------
函式:ldap_get_values()
--------------------------------------------------------------------------------
LDAP 目录协定函式库
ldap_get_values
取得全部传回值。
语法: array ldap_get_values(int handle, int result_entry_identifier, string attribute);
传回值: 阵列
函式种类: 网路系统
内容说明
本函式用来取得 LDAP 的全部传回资料值。参数 handle 为开启 LDAP 的代号。参数 attribute 有 surname 及 mail 二种。传回值为阵列资料值，例如
return_value["count"] : 属性值总数
return_value[0] : 第一个属性值
return_value[i] : 第 i+1 个属性值
使用范例
下例为片段程式
$values = ldap_get_values($ds, $entry, "mail");
echo $values["count"]." 笔电子邮件地址:
\n";
for ($i=0; $i < $values["count"]; $i++) {
echo $values[$i]."
";
}
?>
--------------------------------------------------------------------------------
函式:ldap_list()
--------------------------------------------------------------------------------
LDAP 目录协定函式库
ldap_list
列出简表。
语法: int ldap_list(int handle, string base_dn, string filter, array [attributes]);
传回值: 整数
函式种类: 网路系统
内容说明
本函式用来列出单层 (One Level) 的资料，实际上它等于ldap_searchldap_search()，只是将值域改成 LDAP_SCOPE_ONELEVEL，本函式作用有点像 DOS 的 dir 或是 UNIX 的 ls。参数 handle 为开启 LDAP 的代号。参数 base_dn 为最基本的 dn 条件值，例如包括 o 和 c 二栏位。参数 filter 为布林条件，它的语法可以在 Netscape 站上找一份 dirsdkpg.pdf 档案，其中的 Search Syntax 一部份有详细的说明。参数 attributes 可省略，用来设定更细的列出属性。
使用范例
这个范例为片段程式
$basedn = "o=SuperPHP Company, c=TW";
$justthese = array("ou");
$sr=ldap_list($ds, $basedn, "ou=*", $justthese);
$info = ldap_get_entries($ds, $sr);
for ($i=0; $i<$info["count"]; $i++) {
echo $info[$i]["ou"][0] ;
}
?>
参考
ldap_read() ldap_search()
--------------------------------------------------------------------------------
函式:ldap_modify()
--------------------------------------------------------------------------------
LDAP 目录协定函式库
ldap_modify
改变 LDAP 名录的属性。
语法: boolean ldap_modify(int handle, string dn, array entry);
传回值: 布林值
函式种类: 网路系统
内容说明
本函式用来改变 LDAP 伺服器上目前所在名录上的属性。参数 handle 为开启 LDAP 的代号。参数 dn 为要加入条目的具体 dn 字串。参数 entry 为阵列，为个体所有的属性，阵列的内容是名录属性的相关资讯。若无错误则传回 true 值。
使用范例
本例为 nickt@powys.gov.uk 提出的片段 (23-Apr-1999)
$newinfo[mail]="nick@county.gov.uk";
ldap_modify($valid_ldaplink, $valid_dn, $newinfo);
?>
参考
ldap_mod_add()
--------------------------------------------------------------------------------
函式:ldap_next_attribute()
--------------------------------------------------------------------------------
LDAP 目录协定函式库
ldap_next_attribute
取得传回资料的下笔属性。
语法: string ldap_next_attribute(int handle, int result_entry_identifier, int ber_identifier);
传回值: 字串
函式种类: 网路系统
内容说明
本函式用来取得 LDAP 中所在传回的下笔属性。参数 handle 为开启 LDAP 的代号。参数 result_entry_identifier 将由 ldap_next_attribute() 沿用。参数 ber_identifier 为指标，意即需在前面加上 & 符号。
参考
ldap_get_attributes() ldap_first_attribute()
--------------------------------------------------------------------------------
函式:ldap_next_entry()
--------------------------------------------------------------------------------
LDAP 目录协定函式库
ldap_next_entry
取得下一笔结果代号。
语法: int ldap_next_entry(int handle, int result_entry_identifier);
传回值: 整数
函式种类: 网路系统
内容说明
本函式用来取得 LDAP 中目前指标的下笔资料代号。参数 handle 为开启 LDAP 的代号。参数 result_identifier 为 ldap_search() 所传回的搜寻代号。若有错误则传回 false。
参考
ldap_first_entry() ldap_get_entries()
--------------------------------------------------------------------------------
函式:ldap_read()
--------------------------------------------------------------------------------
LDAP 目录协定函式库
ldap_read
取得目前的资料属性。
语法: int ldap_read(int handle, string base_dn, string filter, array [attributes]);
传回值: 整数
函式种类: 网路系统
内容说明
本函式用来列出树状资料，它的值域条件是 LDAP_SCOPE_BASE。参数 handle 为开启 LDAP 的代号。参数 base_dn 为最基本的 dn 条件值，例如包括 o 和 c 二栏位。参数 filter 为布林条件，它的语法可以在 Netscape 站上找一份 dirsdkpg.pdf 档案，其中的 Search Syntax 一部份有详细的说明。参数 attributes 可省略，用来设定更细的列出属性。
参考
ldap_list() ldap_search()
--------------------------------------------------------------------------------
函式:ldap_search()
--------------------------------------------------------------------------------
LDAP 目录协定函式库
ldap_search
列出树状简表。
语法: int ldap_search(int handle, string base_dn, string filter, array [attributes]);
传回值: 整数
函式种类: 网路系统
内容说明
本函式用来列出树状资料，它的值域条件是 LDAP_SCOPE_SUBTREE。参数 handle 为开启 LDAP 的代号。参数 base_dn 为最基本的 dn 条件值，例如包括 o 和 c 二栏位。参数 filter 为布林条件，它的语法可以在 Netscape 站上找一份 dirsdkpg.pdf 档案，其中的 Search Syntax 一部份有详细的说明。参数 attributes 可省略，用来设定更细的列出属性。
使用范例
下面范例为片段程式
$dn = "o=SuperLDAP Company, c=TW";
$filter="(|(sn=$person*)(givenname=$person*))";
$justthese = array( "ou", "sn", "givenname", "mail");
$sr=ldap_search($ds, $dn, $filter, $justthese);
$info = ldap_get_entries($ds, $sr);
print $info["count"]." entries returned
";
?>
参考
ldap_list() ldap_read()
--------------------------------------------------------------------------------
函式:ldap_unbind()
--------------------------------------------------------------------------------
LDAP 目录协定函式库
ldap_unbind
结束 LDAP 连结。
语法: boolean ldap_unbind(int handle);
传回值: 布林值
函式种类: 网路系统
内容说明
本函式将关闭与 LDAP 伺服器的连结。参数 handle 为开启 LDAP 的代号。若无错误则传回 true 值。
参考
ldap_close()
