mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 17:08:54 +00:00
c920b537bc
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@61303 c90b9560-bf6c-de11-be94-00142212c4b1
1696 lines
58 KiB
XML
1696 lines
58 KiB
XML
<?xml encoding="iso-8859-1"?>
|
|
<!-- $Revision: 1.34 $ -->
|
|
<reference id="ref.ldap">
|
|
<title>LDAP functions</title>
|
|
<titleabbrev>LDAP</titleabbrev>
|
|
|
|
<partintro>
|
|
<sect1 id="ldap.intro">
|
|
<title>Introduction to LDAP</title>
|
|
<para>
|
|
LDAP is the Lightweight Directory Access Protocol, and is a
|
|
protocol used to access "Directory Servers". The Directory is a
|
|
special kind of database that holds information in a tree
|
|
structure.
|
|
</para>
|
|
<para>
|
|
The concept is similar to your hard disk directory structure,
|
|
except that in this context, the root directory is "The world"
|
|
and the first level subdirectories are "countries". Lower levels
|
|
of the directory structure contain entries for companies,
|
|
organisations or places, while yet lower still we find directory
|
|
entries for people, and perhaps equipment or documents.
|
|
</para>
|
|
<para>
|
|
To refer to a file in a subdirectory on your hard disk, you might
|
|
use something like
|
|
</para>
|
|
<literallayout>
|
|
/usr/local/myapp/docs
|
|
</literallayout>
|
|
<para>
|
|
The forwards slash marks each division in the reference, and the
|
|
sequence is read from left to right.
|
|
</para>
|
|
<para>
|
|
The equivalent to the fully qualified file reference in LDAP is
|
|
the "distinguished name", referred to simply as "dn". An example
|
|
dn might be.
|
|
</para>
|
|
<literallayout>
|
|
cn=John Smith,ou=Accounts,o=My Company,c=US
|
|
</literallayout>
|
|
<para>
|
|
The comma marks each division in the reference, and the sequence
|
|
is read from right to left. You would read this dn as ..
|
|
</para>
|
|
<literallayout>
|
|
country = US
|
|
organization = My Company
|
|
organizationalUnit = Accounts
|
|
commonName = John Smith
|
|
</literallayout>
|
|
<para>
|
|
In the same way as there are no hard rules about how you organise
|
|
the directory structure of a hard disk, a directory server
|
|
manager can set up any structure that is meaningful for the
|
|
purpose. However, there are some conventions that are used. The
|
|
message is that you can not write code to access a directory
|
|
server unless you know something about its structure, any more
|
|
than you can use a database without some knowledge of what is
|
|
available.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="ldap-example">
|
|
<title>Complete code example</title>
|
|
<para>
|
|
Retrieve information for all entries where the surname starts
|
|
with "S" from a directory server, displaying an extract with
|
|
name and email address.
|
|
</para>
|
|
|
|
<example>
|
|
<title>LDAP search example</title>
|
|
<programlisting role="php">
|
|
<?php
|
|
// basic sequence with LDAP is connect, bind, search, interpret search
|
|
// result, close connection
|
|
|
|
echo "<h3>LDAP query test</h3>";
|
|
echo "Connecting ...";
|
|
$ds=ldap_connect("localhost"); // must be a valid LDAP server!
|
|
echo "connect result is ".$ds."<p>";
|
|
|
|
if ($ds) {
|
|
echo "Binding ...";
|
|
$r=ldap_bind($ds); // this is an "anonymous" bind, typically
|
|
// read-only access
|
|
echo "Bind result is ".$r."<p>";
|
|
|
|
echo "Searching for (sn=S*) ...";
|
|
// Search surname entry
|
|
$sr=ldap_search($ds,"o=My Company, c=US", "sn=S*");
|
|
echo "Search result is ".$sr."<p>";
|
|
|
|
echo "Number of entires returned is ".ldap_count_entries($ds,$sr)."<p>";
|
|
|
|
echo "Getting entries ...<p>";
|
|
$info = ldap_get_entries($ds, $sr);
|
|
echo "Data for ".$info["count"]." items returned:<p>";
|
|
|
|
for ($i=0; $i<$info["count"]; $i++) {
|
|
echo "dn is: ". $info[$i]["dn"] ."<br>";
|
|
echo "first cn entry is: ". $info[$i]["cn"][0] ."<br>";
|
|
echo "first email entry is: ". $info[$i]["mail"][0] ."<p>";
|
|
}
|
|
|
|
echo "Closing connection";
|
|
ldap_close($ds);
|
|
|
|
} else {
|
|
echo "<h4>Unable to connect to LDAP server</h4>";
|
|
}
|
|
?>
|
|
</programlisting>
|
|
</example>
|
|
|
|
<sect2 id="ldap.using">
|
|
<title>Using the PHP LDAP calls</title>
|
|
<para>
|
|
You will need to get and compile LDAP client libraries from
|
|
either the University of Michigan ldap-3.3 package or the
|
|
Netscape Directory SDK 3.0. You will also need to recompile PHP
|
|
with LDAP support enabled before PHP's LDAP calls will work.
|
|
</para><para>
|
|
Before you can use the LDAP calls you will need to know ..
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
The name or address of the directory server you will use
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The "base dn" of the server (the part of the world directory
|
|
that is held on this server, which could be "o=My
|
|
Company,c=US")
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Whether you need a password to access the server (many servers
|
|
will provide read access for an "anonymous bind" but require a
|
|
password for anything else)
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<para>
|
|
The typical sequence of LDAP calls you will make in an
|
|
application will follow this pattern:
|
|
<literallayout>
|
|
ldap_connect() // establish connection to server
|
|
|
|
|
ldap_bind() // anonymous or authenticated "login"
|
|
|
|
|
do something like search or update the directory
|
|
and display the results
|
|
|
|
|
ldap_close() // "logout"
|
|
</literallayout></para>
|
|
</sect2>
|
|
|
|
|
|
<sect2 id="ldap.moreinfo">
|
|
<title>More Information</title>
|
|
<para>
|
|
Lots of information about LDAP can be found at
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<ulink url="&url.ldap.netscape;">Netscape</ulink>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<ulink url="&url.ldap.michigan;">University of Michigan</ulink>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<ulink url="&url.ldap.openldap;">OpenLDAP Project</ulink>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<ulink url="&url.ldap.ldapworld;">LDAP World</ulink>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
The Netscape SDK contains a helpful Programmer's Guide in .html
|
|
format.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
</partintro>
|
|
|
|
|
|
<refentry id="function.ldap-add">
|
|
<refnamediv>
|
|
<refname>ldap_add</refname>
|
|
<refpurpose>Add entries to LDAP directory</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>ldap_add</function></funcdef>
|
|
<paramdef>int <parameter>link_identifier</parameter></paramdef>
|
|
<paramdef>string <parameter>dn</parameter></paramdef>
|
|
<paramdef>array <parameter>entry</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
returns &true; on success and &false; on error.
|
|
</para><para>
|
|
The <function>ldap_add</function> function is used to add entries
|
|
in the LDAP directory. The DN of the entry to be added is
|
|
specified by dn. Array entry specifies the information about the
|
|
entry. The values in the entries are indexed by individual
|
|
attributes. In case of multiple values for an attribute, they are
|
|
indexed using integers starting with 0.
|
|
</para>
|
|
<informalexample>
|
|
<literallayout>
|
|
entry["attribute1"] = value
|
|
entry["attribute2"][0] = value1
|
|
entry["attribute2"][1] = value2
|
|
</literallayout>
|
|
</informalexample>
|
|
<example>
|
|
<title>Complete example with authenticated bind</title>
|
|
<programlisting role="php">
|
|
<?php
|
|
$ds=ldap_connect("localhost"); // assuming the LDAP server is on this host
|
|
|
|
if ($ds) {
|
|
// bind with appropriate dn to give update access
|
|
$r=ldap_bind($ds,"cn=root, o=My Company, c=US", "secret");
|
|
|
|
// prepare data
|
|
$info["cn"]="John Jones";
|
|
$info["sn"]="Jones";
|
|
$info["mail"]="jonj@here.and.now";
|
|
$info["objectclass"]="person";
|
|
|
|
// add data to directory
|
|
$r=ldap_add($ds, "cn=John Jones, o=My Company, c=US", $info);
|
|
|
|
ldap_close($ds);
|
|
} else {
|
|
echo "Unable to connect to LDAP server";
|
|
}
|
|
?>
|
|
</programlisting>
|
|
</example>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.ldap-bind">
|
|
<refnamediv>
|
|
<refname>ldap_bind</refname>
|
|
<refpurpose>Bind to LDAP directory</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>ldap_bind</function></funcdef>
|
|
<paramdef>int <parameter>link_identifier</parameter></paramdef>
|
|
<paramdef>string <parameter><optional>bind_rdn</optional></parameter></paramdef>
|
|
<paramdef>string <parameter><optional>bind_password</optional></parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Binds to the LDAP directory with specified RDN and
|
|
password. Returns &true; on success and &false; on error.</para>
|
|
<para>
|
|
<function>ldap_bind</function> does a bind operation on the
|
|
directory. bind_rdn and bind_password are optional. If not
|
|
specified, anonymous bind is attempted.</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.ldap-close">
|
|
<refnamediv>
|
|
<refname>ldap_close</refname>
|
|
<refpurpose>Close link to LDAP server</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>ldap_close</function></funcdef>
|
|
<paramdef>int <parameter>link_identifier</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns &true; on success, &false; on error.</para>
|
|
<para>
|
|
<function>ldap_close</function> closes the link to the LDAP
|
|
server that's associated with the specified
|
|
<parameter>link_identifier</parameter>.</para>
|
|
<para>
|
|
This call is internally identical to
|
|
<function>ldap_unbind</function>. The LDAP API uses the call
|
|
<function>ldap_unbind</function>, so perhaps you should use this
|
|
in preference to <function>ldap_close</function>.</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.ldap-compare">
|
|
<refnamediv>
|
|
<refname>ldap_compare</refname>
|
|
<refpurpose>Compare value of attribute found in entry specified with DN</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>ldap_compare</function></funcdef>
|
|
<paramdef>int <parameter>link_identifier</parameter></paramdef>
|
|
<paramdef>string <parameter>dn</parameter></paramdef>
|
|
<paramdef>string <parameter>attribute</parameter></paramdef>
|
|
<paramdef>string <parameter>value</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<simpara>
|
|
Returns &true; if <parameter>value</parameter> matches otherwise returns &false;. Returns -1 on error.
|
|
</simpara>
|
|
<para>
|
|
<function>ldap_compare</function> is used to compare <parameter>value</parameter>
|
|
of <parameter>attribute</parameter> to value of same attribute in LDAP directory
|
|
entry specified with <parameter>dn</parameter>.
|
|
</para>
|
|
<simpara>
|
|
The following example demonstrates how to check whether or not given password matches
|
|
the one defined in DN specified entry.
|
|
</simpara>
|
|
<example>
|
|
<title>Complete example of password check</title>
|
|
<programlisting role="php">
|
|
<?php
|
|
|
|
$ds=ldap_connect("localhost"); // assuming the LDAP server is on this host
|
|
|
|
if ($ds) {
|
|
|
|
// bind
|
|
if(ldap_bind($ds)) {
|
|
|
|
// prepare data
|
|
$dn = "cn=Matti Meikku, ou=My Unit, o=My Company, c=FI";
|
|
$value = "secretpassword";
|
|
$attr = "password";
|
|
|
|
// compare value
|
|
$r=ldap_compare($ds, $dn, $attr, $value);
|
|
|
|
if ($r === -1) {
|
|
echo "Error: ".ldap_error($ds);
|
|
} elseif ($r === TRUE) {
|
|
echo "Password correct.";
|
|
} elseif ($r === FALSE) {
|
|
echo "Wrong guess! Password incorrect.";
|
|
}
|
|
|
|
} else {
|
|
echo "Unable to bind to LDAP server.";
|
|
}
|
|
|
|
ldap_close($ds);
|
|
|
|
} else {
|
|
echo "Unable to connect to LDAP server.";
|
|
}
|
|
?>
|
|
|
|
</programlisting>
|
|
</example>
|
|
<note>
|
|
<para>
|
|
<function>ldap_compare</function> can NOT be used to compare BINARY values!
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
This function was added in 4.0.2.
|
|
</para>
|
|
</note>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.ldap-connect">
|
|
<refnamediv>
|
|
<refname>ldap_connect</refname>
|
|
<refpurpose>Connect to an LDAP server</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>ldap_connect</function></funcdef>
|
|
<paramdef>string <parameter><optional>hostname</optional></parameter></paramdef>
|
|
<paramdef>int <parameter><optional>port</optional></parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns a positive LDAP link identifier on success, or &false; on
|
|
error.</para>
|
|
<para>
|
|
<function>ldap_connect</function> establishes a connection to a
|
|
LDAP server on a specified <parameter>hostname</parameter> and
|
|
<parameter>port</parameter>. Both the arguments are optional. If
|
|
no arguments are specified then the link identifier of the
|
|
already opened link will be returned. If only
|
|
<parameter>hostname</parameter> is specified, then the port
|
|
defaults to 389.</para>
|
|
<para>
|
|
If you are using OpenLDAP 2.x.x you can specify a URL instead of the
|
|
hostname. To use LDAP with SSL, compile OpenLDAP 2.x.x with SSL
|
|
support, configure PHP with SSL, and use ldaps://hostname/ as
|
|
host parameter. The port parameter is not used when using URLs.
|
|
URL and SSL support were added in 4.0.4.</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.ldap-count-entries">
|
|
<refnamediv>
|
|
<refname>ldap_count_entries</refname>
|
|
<refpurpose>Count the number of entries in a search</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>ldap_count_entries</function></funcdef>
|
|
<paramdef>int <parameter>link_identifier</parameter></paramdef>
|
|
<paramdef>int <parameter>result_identifier</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns number of entries in the result or &false; on error.</para>
|
|
<para>
|
|
<function>ldap_count_entries</function> returns the number of
|
|
entries stored in the result of previous search
|
|
operations. <parameter>result_identifier</parameter> identifies
|
|
the internal ldap result.</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.ldap-delete">
|
|
<refnamediv>
|
|
<refname>ldap_delete</refname>
|
|
<refpurpose>Delete an entry from a directory</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>ldap_delete</function></funcdef>
|
|
<paramdef>int <parameter>link_identifier</parameter></paramdef>
|
|
<paramdef>string <parameter>dn</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns &true; on success and &false; on error.</para>
|
|
<para>
|
|
<function>ldap_delete</function> function delete a particular
|
|
entry in LDAP directory specified by dn.</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.ldap-dn2ufn">
|
|
<refnamediv>
|
|
<refname>ldap_dn2ufn</refname>
|
|
<refpurpose>Convert DN to User Friendly Naming format</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>ldap_dn2ufn</function></funcdef>
|
|
<paramdef>string <parameter>dn</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>ldap_dn2ufn</function> function is used to turn a DN
|
|
into a more user-friendly form, stripping off type names.</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.ldap-err2str">
|
|
<refnamediv>
|
|
<refname>ldap_err2str</refname>
|
|
<refpurpose>
|
|
Convert LDAP error number into string error message
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>ldap_err2str</function></funcdef>
|
|
<paramdef>int <parameter>errno</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
returns string error message.</para>
|
|
<para>
|
|
This function returns the string error message explaining the
|
|
error number errno. While LDAP errno numbers are standardized,
|
|
different libraries return different or even localized textual
|
|
error messages. Never check for a specific error message text,
|
|
but always use an error number to check.</para>
|
|
<para>
|
|
See also <function>ldap_errno</function> and
|
|
<function>ldap_error</function>.
|
|
|
|
<example>
|
|
<title>Enumerating all LDAP error messages</title>
|
|
<programlisting role="php">
|
|
<?php
|
|
for($i=0; $i<100; $i++) {
|
|
printf("Error $i: %s<br>\n", ldap_err2str($i));
|
|
}
|
|
?>
|
|
</programlisting>
|
|
</example></para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.ldap-errno">
|
|
<refnamediv>
|
|
<refname>ldap_errno</refname>
|
|
<refpurpose>
|
|
Return the LDAP error number of the last LDAP command
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>ldap_errno</function></funcdef>
|
|
<paramdef>int <parameter>link_id</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
return the LDAP error number of the last LDAP command for this
|
|
link.</para>
|
|
<para>
|
|
This function returns the standardized error number returned by
|
|
the last LDAP command for the given link identifier. This number
|
|
can be converted into a textual error message using
|
|
<function>ldap_err2str</function>.</para>
|
|
<para>
|
|
Unless you lower your warning level in your php.ini sufficiently
|
|
or prefix your LDAP commands with @ (at) characters to suppress
|
|
warning output, the errors generated will also show up in your
|
|
HTML output.
|
|
<example>
|
|
<title>Generating and catching an error</title>
|
|
<programlisting role="php">
|
|
<?php
|
|
// This example contains an error, which we will catch.
|
|
$ld = ldap_connect("localhost");
|
|
$bind = ldap_bind($ld);
|
|
// syntax error in filter expression (errno 87),
|
|
// must be "objectclass=*" to work.
|
|
$res = @ldap_search($ld, "o=Myorg, c=DE", "objectclass");
|
|
if (!$res) {
|
|
printf("LDAP-Errno: %s<br>\n", ldap_errno($ld));
|
|
printf("LDAP-Error: %s<br>\n", ldap_error($ld));
|
|
die("Argh!<br>\n");
|
|
}
|
|
$info = ldap_get_entries($ld, $res);
|
|
printf("%d matching entries.<br>\n", $info["count"]);
|
|
?>
|
|
</programlisting>
|
|
</example></para>
|
|
<para>
|
|
see also <function>ldap_err2str</function> and
|
|
<function>ldap_error</function>.</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.ldap-error">
|
|
<refnamediv>
|
|
<refname>ldap_error</refname>
|
|
<refpurpose>
|
|
Return the LDAP error message of the last LDAP command
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>ldap_error</function></funcdef>
|
|
<paramdef>int <parameter>link_id</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
returns string error message.</para>
|
|
<para>
|
|
This function returns the string error message explaining the
|
|
error generated by the last LDAP command for the given link
|
|
identifier. While LDAP errno numbers are standardized, different
|
|
libraries return different or even localized textual error
|
|
messages. Never check for a specific error message text, but
|
|
always use an error number to check.</para>
|
|
<para>
|
|
Unless you lower your warning level in your
|
|
<filename>php.ini</filename> sufficiently or prefix your LDAP
|
|
commands with <literal>@</literal> (at) characters to suppress
|
|
warning output, the errors generated will also show up in your
|
|
HTML output.</para>
|
|
<para>
|
|
see also <function>ldap_err2str</function> and
|
|
<function>ldap_errno</function>.</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.ldap-explode-dn">
|
|
<refnamediv>
|
|
<refname>ldap_explode_dn</refname>
|
|
<refpurpose>Splits DN into its component parts</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>array <function>ldap_explode_dn</function></funcdef>
|
|
<paramdef>string <parameter>dn</parameter></paramdef>
|
|
<paramdef>int <parameter>with_attrib</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>ldap_explode_dn</function> function is used to split
|
|
the a DN returned by <function>ldap_get_dn</function> and breaks
|
|
it up into its component parts. Each part is known as Relative
|
|
Distinguished Name, or RDN. <function>ldap_explode_dn</function>
|
|
returns an array of all those components.
|
|
<parameter>with_attrib</parameter> is used to request if the RDNs
|
|
are returned with only values or their attributes as well. To
|
|
get RDNs with the attributes (i.e. in attribute=value format) set
|
|
<parameter>with_attrib</parameter> to 0 and to get only values
|
|
set it to 1.</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.ldap-first-attribute">
|
|
<refnamediv>
|
|
<refname>ldap_first_attribute</refname>
|
|
<refpurpose>Return first attribute</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>ldap_first_attribute</function></funcdef>
|
|
<paramdef>int <parameter>link_identifier</parameter></paramdef>
|
|
<paramdef>int <parameter>result_entry_identifier</parameter></paramdef>
|
|
<paramdef>int <parameter>ber_identifier</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns the first attribute in the entry on success and &false; on
|
|
error.
|
|
</para>
|
|
<para>
|
|
Similar to reading entries, attributes are also read one by one
|
|
from a particular entry.
|
|
<function>ldap_first_attribute</function> returns the first
|
|
attribute in the entry pointed by the entry identifier.
|
|
Remaining attributes are retrieved by calling
|
|
<function>ldap_next_attribute</function> successively.
|
|
<parameter>ber_identifier</parameter> is the identifier to
|
|
internal memory location pointer. It is passed by reference. The
|
|
same <parameter>ber_identifier</parameter> is passed to the
|
|
<function>ldap_next_attribute</function> function, which modifies
|
|
that pointer.
|
|
</para>
|
|
<para>
|
|
see also <function>ldap_get_attributes</function></para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.ldap-first-entry">
|
|
<refnamediv>
|
|
<refname>ldap_first_entry</refname>
|
|
<refpurpose>Return first result id</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>ldap_first_entry</function></funcdef>
|
|
<paramdef>int <parameter>link_identifier</parameter></paramdef>
|
|
<paramdef>int <parameter>result_identifier</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns the result entry identifier for the first entry on
|
|
success and &false; on error.</para>
|
|
<para>
|
|
Entries in the LDAP result are read sequentially using the
|
|
<function>ldap_first_entry</function> and
|
|
<function>ldap_next_entry</function>
|
|
functions. <function>ldap_first_entry</function> returns the
|
|
entry identifier for first entry in the result. This entry
|
|
identifier is then supplied to
|
|
<function>lap_next_entry</function> routine to get successive
|
|
entries from the result.</para>
|
|
<para>
|
|
see also <function>ldap_get_entries</function>.</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.ldap-free-result">
|
|
<refnamediv>
|
|
<refname>ldap_free_result</refname>
|
|
<refpurpose>Free result memory</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>ldap_free_result</function></funcdef>
|
|
<paramdef>int <parameter>result_identifier</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns &true; on success and &false; on error.</para>
|
|
<para>
|
|
<function>ldap_free_result</function> frees up the memory
|
|
allocated internally to store the result and pointed by the
|
|
<parameter>result_identifier</parameter>. All result memory will
|
|
be automatically freed when the script terminates.</para>
|
|
<para>
|
|
Typically all the memory allocated for the ldap result gets freed
|
|
at the end of the script. In case the script is making successive
|
|
searches which return large result sets,
|
|
<function>ldap_free_result</function> could be called to keep the
|
|
runtime memory usage by the script low.</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.ldap-get-attributes">
|
|
<refnamediv>
|
|
<refname>ldap_get_attributes</refname>
|
|
<refpurpose>Get attributes from a search result entry</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>array <function>ldap_get_attributes</function></funcdef>
|
|
<paramdef>int <parameter>link_identifier</parameter></paramdef>
|
|
<paramdef>int
|
|
<parameter>result_entry_identifier</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns a complete entry information in a multi-dimensional array
|
|
on success and &false; on error.</para>
|
|
<para>
|
|
<function>ldap_get_attributes</function> function is used to
|
|
simplify reading the attributes and values from an entry in the
|
|
search result. The return value is a multi-dimensional array of
|
|
attributes and values.</para>
|
|
<para>
|
|
Having located a specific entry in the directory, you can find
|
|
out what information is held for that entry by using this
|
|
call. You would use this call for an application which "browses"
|
|
directory entries and/or where you do not know the structure of
|
|
the directory entries. In many applications you will be searching
|
|
for a specific attribute such as an email address or a surname,
|
|
and won't care what other data is held.</para>
|
|
<para>
|
|
<informalexample><literallayout>
|
|
return_value["count"] = number of attributes in the entry
|
|
return_value[0] = first attribute
|
|
return_value[n] = nth attribute
|
|
|
|
return_value["attribute"]["count"] = number of values for attribute
|
|
return_value["attribute"][0] = first value of the attribute
|
|
return_value["attribute"][i] = ith value of the attribute
|
|
</literallayout></informalexample>
|
|
|
|
<example>
|
|
<title>Show the list of attributes held for a particular directory
|
|
entry </title>
|
|
<programlisting role="php">
|
|
// $ds is the link identifier for the directory
|
|
|
|
// $sr is a valid search result from a prior call to
|
|
// one of the ldap directory search calls
|
|
|
|
$entry = ldap_first_entry($ds, $sr);
|
|
|
|
$attrs = ldap_get_attributes($ds, $entry);
|
|
|
|
echo $attrs["count"]." attributes held for this entry:<p>";
|
|
|
|
for ($i=0; $i<$attrs["count"]; $i++)
|
|
echo $attrs[$i]."<br>";
|
|
</programlisting>
|
|
</example></para>
|
|
|
|
<para>
|
|
see also <function>ldap_first_attribute</function> and
|
|
<function>ldap_next_attribute</function></para>
|
|
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.ldap-get-dn">
|
|
<refnamediv>
|
|
<refname>ldap_get_dn</refname>
|
|
<refpurpose>Get the DN of a result entry</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>ldap_get_dn</function></funcdef>
|
|
<paramdef>int <parameter>link_identifier</parameter></paramdef>
|
|
<paramdef>int <parameter>result_entry_identifier</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns the DN of the result entry and &false; on error.</para>
|
|
<para>
|
|
<function>ldap_get_dn</function> function is used to find out the
|
|
DN of an entry in the result.</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.ldap-get-entries">
|
|
<refnamediv>
|
|
<refname>ldap_get_entries</refname>
|
|
<refpurpose>Get all result entries</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>array <function>ldap_get_entries</function></funcdef>
|
|
<paramdef>int <parameter>link_identifier</parameter></paramdef>
|
|
<paramdef>int <parameter>result_identifier</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns a complete result information in a multi-dimenasional
|
|
array on success and &false; on error.</para>
|
|
<para>
|
|
<function>ldap_get_entries</function> function is used to
|
|
simplify reading multiple entries from the result and then
|
|
reading the attributes and multiple values. The entire
|
|
information is returned by one function call in a
|
|
multi-dimensional array. The structure of the array is as
|
|
follows.</para>
|
|
<para>
|
|
The attribute index is converted to lowercase. (Attributes are
|
|
case-insensitive for directory servers, but not when used as
|
|
array indices)
|
|
|
|
<informalexample>
|
|
<literallayout>
|
|
return_value["count"] = number of entries in the result
|
|
return_value[0] : refers to the details of first entry
|
|
|
|
return_value[i]["dn"] = DN of the ith entry in the result
|
|
|
|
return_value[i]["count"] = number of attributes in ith entry
|
|
return_value[i][j] = jth attribute in the ith entry in the result
|
|
|
|
return_value[i]["attribute"]["count"] = number of values for
|
|
attribute in ith entry
|
|
return_value[i]["attribute"][j] = jth value of attribute in ith entry
|
|
</literallayout>
|
|
</informalexample></para>
|
|
|
|
<para>
|
|
see also <function>ldap_first_entry</function> and
|
|
<function>ldap_next_entry</function></para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.ldap-get-option">
|
|
<refnamediv>
|
|
<refname>ldap_get_option</refname>
|
|
<refpurpose>Get the current value for given option</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>bool <function>ldap_get_option</function></funcdef>
|
|
<paramdef>int <parameter>link_identifier</parameter></paramdef>
|
|
<paramdef>int <parameter>option</parameter></paramdef>
|
|
<paramdef>mixed <parameter>retval</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Sets <parameter>retval</parameter> to the value of the specified option,
|
|
and returns &true; on success and &false; on error.</para>
|
|
<para>
|
|
The parameter <parameter>option</parameter> can be one of:
|
|
LDAP_OPT_DEREF, LDAP_OPT_SIZELIMIT, LDAP_OPT_TIMELIMIT,
|
|
LDAP_OPT_PROTOCOL_VERSION, LDAP_OPT_ERROR_NUMBER, LDAP_OPT_REFERRALS,
|
|
LDAP_OPT_RESTART, LDAP_OPT_HOST_NAME, LDAP_OPT_ERROR_STRING,
|
|
LDAP_OPT_MATCHED_DN. These are described in
|
|
<ulink url="&url.ldap.openldap-c-api;">draft-ietf-ldapext-ldap-c-api-xx.txt</ulink>
|
|
</para>
|
|
<para>This function is only available when using OpenLDAP 2.x.x OR Netscape Directory SDK x.x, and was
|
|
added in PHP 4.0.4</para>
|
|
|
|
<para>
|
|
<example>
|
|
<title>Check protocol version</title>
|
|
<programlisting role="php">
|
|
// $ds is a valid link identifier for a directory server
|
|
if (ldap_get_option($ds, LDAP_OPT_PROTOCOL_VERSION, $version))
|
|
echo "Using protocol version $version";
|
|
else
|
|
echo "Unable to determine protocol version";
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
|
|
<para>
|
|
See also <function>ldap_set_option</function>.</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.ldap-get-values">
|
|
<refnamediv>
|
|
<refname>ldap_get_values</refname>
|
|
<refpurpose>Get all values from a result entry</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>array <function>ldap_get_values</function></funcdef>
|
|
<paramdef>int <parameter>link_identifier</parameter></paramdef>
|
|
<paramdef>int <parameter>result_entry_identifier</parameter></paramdef>
|
|
<paramdef>string <parameter>attribute</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns an array of values for the attribute on success and &false;
|
|
on error.</para>
|
|
<para>
|
|
<function>ldap_get_values</function> function is used to read all
|
|
the values of the attribute in the entry in the result. entry is
|
|
specified by the
|
|
<parameter>result_entry_identifier</parameter>. The number of
|
|
values can be found by indexing "count" in the resultant
|
|
array. Individual values are accessed by integer index in the
|
|
array. The first index is 0.</para>
|
|
<para>
|
|
This call needs a <parameter>result_entry_identifier</parameter>,
|
|
so needs to be preceded by one of the ldap search calls and one
|
|
of the calls to get an individual entry.</para>
|
|
<para>
|
|
You application will either be hard coded to look for certain
|
|
attributes (such as "surname" or "mail") or you will have to use
|
|
the <function>ldap_get_attributes</function> call to work out
|
|
what attributes exist for a given entry.</para>
|
|
<para>
|
|
LDAP allows more than one entry for an attribute, so it can, for
|
|
example, store a number of email addresses for one person's
|
|
directory entry all labeled with the attribute "mail"
|
|
|
|
<informalexample>
|
|
<literallayout>
|
|
return_value["count"] = number of values for attribute
|
|
return_value[0] = first value of attribute
|
|
return_value[i] = ith value of attribute
|
|
</literallayout>
|
|
</informalexample>
|
|
|
|
<example>
|
|
<title>List all values of the "mail" attribute for a
|
|
directory entry </title>
|
|
<programlisting role="php">
|
|
// $ds is a valid link identifier for a directory server
|
|
|
|
// $sr is a valid search result from a prior call to
|
|
// one of the ldap directory search calls
|
|
|
|
// $entry is a valid entry identifier from a prior call to
|
|
// one of the calls that returns a directory entry
|
|
|
|
$values = ldap_get_values($ds, $entry,"mail");
|
|
|
|
echo $values["count"]." email addresses for this entry.<p>";
|
|
|
|
for ($i=0; $i < $values["count"]; $i++)
|
|
echo $values[$i]."<br>";
|
|
</programlisting>
|
|
</example></para>
|
|
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.ldap-get-values-len">
|
|
<refnamediv>
|
|
<refname>ldap_get_values_len</refname>
|
|
<refpurpose>Get all binary values from a result entry</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>array <function>ldap_get_values_len</function></funcdef>
|
|
<paramdef>int <parameter>link_identifier</parameter></paramdef>
|
|
<paramdef>int <parameter>result_entry_identifier</parameter></paramdef>
|
|
<paramdef>string <parameter>attribute</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns an array of values for the attribute on success and &false;
|
|
on error.</para>
|
|
<para>
|
|
<function>ldap_get_values_len</function> function is used to read all
|
|
the values of the attribute in the entry in the result. entry is
|
|
specified by the
|
|
<parameter>result_entry_identifier</parameter>. The number of
|
|
values can be found by indexing "count" in the resultant
|
|
array. Individual values are accessed by integer index in the
|
|
array. The first index is 0.</para>
|
|
<para>
|
|
This function is used exactly like
|
|
<function>ldap_get_values</function> except that it handles
|
|
binary data and not string data.</para>
|
|
<note>
|
|
<para>
|
|
This function was added in 4.0.
|
|
</para>
|
|
</note>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.ldap-list">
|
|
<refnamediv>
|
|
<refname>ldap_list</refname>
|
|
<refpurpose>Single-level search</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>ldap_list</function></funcdef>
|
|
<paramdef>int <parameter>link_identifier</parameter></paramdef>
|
|
<paramdef>string <parameter>base_dn</parameter></paramdef>
|
|
<paramdef>string <parameter>filter</parameter></paramdef>
|
|
<paramdef>array
|
|
<parameter><optional>attributes</optional></parameter></paramdef>
|
|
<paramdef>int
|
|
<parameter><optional>attrsonly</optional></parameter>
|
|
</paramdef>
|
|
<paramdef>int
|
|
<parameter><optional>sizelimit</optional></parameter>
|
|
</paramdef>
|
|
<paramdef>int
|
|
<parameter><optional>timelimit</optional></parameter>
|
|
</paramdef>
|
|
<paramdef>int
|
|
<parameter><optional>deref</optional></parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns a search result identifier or &false; on error.</para>
|
|
<para>
|
|
<function>ldap_list</function> performs the search for a specified
|
|
filter on the directory with the scope LDAP_SCOPE_ONELEVEL.</para>
|
|
<para>
|
|
LDAP_SCOPE_ONELEVEL means that the search should only return
|
|
information that is at the level immediately below the base dn
|
|
given in the call. (Equivalent to typing "ls" and getting a list
|
|
of files and folders in the current working directory.)</para>
|
|
<para>
|
|
This call takes 5 optional parameters. See <function>ldap_search</function>
|
|
notes.
|
|
<note>
|
|
<para>
|
|
These optional parameters were added in 4.0.2:
|
|
<parameter>attrsonly</parameter>,
|
|
<parameter>sizelimit</parameter>,
|
|
<parameter>timelimit</parameter>,
|
|
<parameter>deref</parameter>.
|
|
</para>
|
|
</note>
|
|
|
|
<example>
|
|
<title>Produce a list of all organizational units of an organization
|
|
</title>
|
|
<programlisting role="php3">
|
|
// $ds is a valid link identifier for a directory server
|
|
|
|
$basedn = "o=My Company, c=US";
|
|
$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] ;
|
|
</programlisting>
|
|
</example></para>
|
|
<para>
|
|
From 4.0.5 on it's also possible to do parallel searches. See
|
|
<function>ldap_search</function> for details.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.ldap-modify">
|
|
<refnamediv>
|
|
<refname>ldap_modify</refname>
|
|
<refpurpose>Modify an LDAP entry</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>ldap_modify</function></funcdef>
|
|
<paramdef>int <parameter>link_identifier</parameter></paramdef>
|
|
<paramdef>string <parameter>dn</parameter></paramdef>
|
|
<paramdef>array <parameter>entry</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns &true; on success and &false; on error.</para>
|
|
<para>
|
|
<function>ldap_modify</function> function is used to modify the
|
|
existing entries in the LDAP directory. The structure of the
|
|
entry is same as in <function>ldap_add</function>.</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.ldap-mod-add">
|
|
<refnamediv>
|
|
<refname>ldap_mod_add</refname>
|
|
<refpurpose>Add attribute values to current attributes</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>ldap_mod_add</function></funcdef>
|
|
<paramdef>int <parameter>link_identifier</parameter></paramdef>
|
|
<paramdef>string <parameter>dn</parameter></paramdef>
|
|
<paramdef>array <parameter>entry</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
returns &true; on success and &false; on error.</para>
|
|
<para>
|
|
This function adds attribute(s) to the specified dn. It
|
|
performs the modification at the attribute level as opposed to the
|
|
object level. Object-level additions are done by the
|
|
<function>ldap_add</function> function.</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.ldap-mod-del">
|
|
<refnamediv>
|
|
<refname>ldap_mod_del</refname>
|
|
<refpurpose>Delete attribute values from current attributes</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>ldap_mod_del</function></funcdef>
|
|
<paramdef>int <parameter>link_identifier</parameter></paramdef>
|
|
<paramdef>string <parameter>dn</parameter></paramdef>
|
|
<paramdef>array <parameter>entry</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
returns &true; on success and &false; on error.</para>
|
|
<para>
|
|
This function removes attribute(s) from the specified dn. It
|
|
performs the modification at the attribute level as opposed to the
|
|
object level. Object-level deletions are done by the
|
|
<function>ldap_del</function> function.</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.ldap-mod-replace">
|
|
<refnamediv>
|
|
<refname>ldap_mod_replace</refname>
|
|
<refpurpose>Replace attribute values with new ones</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>ldap_mod_replace</function></funcdef>
|
|
<paramdef>int <parameter>link_identifier</parameter></paramdef>
|
|
<paramdef>string <parameter>dn</parameter></paramdef>
|
|
<paramdef>array <parameter>entry</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
returns &true; on success and &false; on error.</para>
|
|
<para>
|
|
This function replaces attribute(s) from the specified dn. It
|
|
performs the modification at the attribute level as opposed to the
|
|
object level. Object-level modifications are done by the
|
|
<function>ldap_modify</function> function.</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.ldap-next-attribute">
|
|
<refnamediv>
|
|
<refname>ldap_next_attribute</refname>
|
|
<refpurpose>Get the next attribute in result</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>ldap_next_attribute</function></funcdef>
|
|
<paramdef>int <parameter>link_identifier</parameter></paramdef>
|
|
<paramdef>int <parameter>result_entry_identifier</parameter></paramdef>
|
|
<paramdef>int <parameter>ber_identifier</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns the next attribute in an entry on success and &false; on
|
|
error.</para>
|
|
<para>
|
|
<function>ldap_next_attribute</function> is called to retrieve
|
|
the attributes in an entry. The internal state of the pointer is
|
|
maintained by the <parameter>ber_identifier</parameter>. It is
|
|
passed by reference to the function. The first call to
|
|
<function>ldap_next_attribute</function> is made with the
|
|
<parameter>result_entry_identifier</parameter> returned from
|
|
<function>ldap_first_attribute</function>.</para>
|
|
<para>
|
|
see also <function>ldap_get_attributes</function></para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.ldap-next-entry">
|
|
<refnamediv>
|
|
<refname>ldap_next_entry</refname>
|
|
<refpurpose>Get next result entry</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>ldap_next_entry</function></funcdef>
|
|
<paramdef>int <parameter>link_identifier</parameter></paramdef>
|
|
<paramdef>int <parameter>result_entry_identifier</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns entry identifier for the next entry in the result whose
|
|
entries are being read starting with
|
|
<function>ldap_first_entry</function>. If there are no more
|
|
entries in the result then it returns &false;.</para>
|
|
<para>
|
|
<function>ldap_next_entry</function> function is used to retrieve
|
|
the entries stored in the result. Successive calls to the
|
|
<function>ldap_next_entry</function> return entries one by one
|
|
till there are no more entries. The first call to
|
|
<function>ldap_next_entry</function> is made after the call to
|
|
<function>ldap_first_entry</function> with the result_identifier
|
|
as returned from the <function>ldap_first_entry</function>.</para>
|
|
<para>
|
|
see also <function>ldap_get_entries</function></para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.ldap-read">
|
|
<refnamediv>
|
|
<refname>ldap_read</refname>
|
|
<refpurpose>Read an entry</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>ldap_read</function></funcdef>
|
|
<paramdef>int <parameter>link_identifier</parameter></paramdef>
|
|
<paramdef>string <parameter>base_dn</parameter></paramdef>
|
|
<paramdef>string <parameter>filter</parameter></paramdef>
|
|
<paramdef>array
|
|
<parameter><optional>attributes</optional></parameter></paramdef>
|
|
<paramdef>int
|
|
<parameter><optional>attrsonly</optional></parameter>
|
|
</paramdef>
|
|
<paramdef>int
|
|
<parameter><optional>sizelimit</optional></parameter>
|
|
</paramdef>
|
|
<paramdef>int
|
|
<parameter><optional>timelimit</optional></parameter>
|
|
</paramdef>
|
|
<paramdef>int
|
|
<parameter><optional>deref</optional></parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns a search result identifier or &false; on error.</para>
|
|
<para>
|
|
<function>ldap_read</function> performs the search for a
|
|
specified filter on the directory with the scope
|
|
LDAP_SCOPE_BASE. So it is equivalent to reading an entry from the
|
|
directory.</para>
|
|
<para>
|
|
An empty filter is not allowed. If you want to retrieve
|
|
absolutely all information for this entry, use a filter of
|
|
"objectClass=*". If you know which entry types are used on the
|
|
directory server, you might use an appropriate filter such as
|
|
"objectClass=inetOrgPerson".</para>
|
|
<para>
|
|
This call takes 5 optional parameters. See <function>ldap_search</function>
|
|
notes.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
These optional parameters were added in 4.0.2:
|
|
<parameter>attrsonly</parameter>,
|
|
<parameter>sizelimit</parameter>,
|
|
<parameter>timelimit</parameter>,
|
|
<parameter>deref</parameter>.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
From 4.0.5 on it's also possible to do parallel searches. See
|
|
<function>ldap_search</function> for details.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.ldap-rename">
|
|
<refnamediv>
|
|
<refname>ldap_rename</refname>
|
|
<refpurpose>Modify the name of an entry</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>bool <function>ldap_rename</function></funcdef>
|
|
<paramdef>int <parameter>link_identifier</parameter></paramdef>
|
|
<paramdef>string <parameter>dn</parameter></paramdef>
|
|
<paramdef>string <parameter>newrdn</parameter></paramdef>
|
|
<paramdef>string <parameter>newparent</parameter></paramdef>
|
|
<paramdef>bool <parameter>deleteoldrdn</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
The entry specified by <parameter>dn</parameter> is renamed/moved.
|
|
The new RDN is specified by <parameter>newrdn</parameter> and the
|
|
new parent/superior entry is specified
|
|
by <parameter>newparent</parameter>. If the parameter
|
|
<parameter>deleteoldrdn</parameter> is &true; the old RDN value(s)
|
|
is removed, else the old RDN value(s) is retained as
|
|
non-distinguished values of the entry. &true; is returned on
|
|
success and &false; is returned on error.</para>
|
|
<para>This function currently only works with LDAPv3. You may have
|
|
to use <function>ldap_set_option()</function> prior to binding to
|
|
use LDAPv3.</para>
|
|
<para>This function is only available when using OpenLDAP 2.x.x OR
|
|
Netscape Directory SDK x.x, and was added in PHP 4.0.5.</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.ldap-search">
|
|
<refnamediv>
|
|
<refname>ldap_search</refname>
|
|
<refpurpose>Search LDAP tree</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>ldap_search</function></funcdef>
|
|
<paramdef>int <parameter>link_identifier</parameter></paramdef>
|
|
<paramdef>string <parameter>base_dn</parameter></paramdef>
|
|
<paramdef>string <parameter>filter</parameter></paramdef>
|
|
<paramdef>array
|
|
<parameter><optional>attributes</optional></parameter>
|
|
</paramdef>
|
|
<paramdef>int
|
|
<parameter><optional>attrsonly</optional></parameter>
|
|
</paramdef>
|
|
<paramdef>int
|
|
<parameter><optional>sizelimit</optional></parameter>
|
|
</paramdef>
|
|
<paramdef>int
|
|
<parameter><optional>timelimit</optional></parameter>
|
|
</paramdef>
|
|
<paramdef>int
|
|
<parameter><optional>deref</optional></parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns a search result identifier or &false; on error.</para>
|
|
<para>
|
|
<function>ldap_search</function> performs the search for a
|
|
specified filter on the directory with the scope of
|
|
LDAP_SCOPE_SUBTREE. This is equivalent to searching the entire
|
|
directory. <parameter>base_dn</parameter> specifies the base DN
|
|
for the directory.</para>
|
|
<para>
|
|
There is a optional fourth parameter, that can be added to
|
|
restrict the attributes and values returned by the server to just
|
|
those required. This is much more efficient than the default
|
|
action (which is to return all attributes and their associated
|
|
values). The use of the fourth parameter should therefore be
|
|
considered good practice.</para>
|
|
<para>
|
|
The fourth parameter is a standard PHP string array of the
|
|
required attributes, eg array("mail","sn","cn") Note that the
|
|
"dn" is always returned irrespective of which attributes types
|
|
are requested.</para>
|
|
<para>
|
|
Note too that some directory server hosts will be configured to
|
|
return no more than a preset number of entries. If this occurs,
|
|
the server will indicate that it has only returned a partial
|
|
results set. This occurs also if the sixth parameter
|
|
<parameter>sizelimit</parameter> has been used to limit the count
|
|
of fetched entries.
|
|
</para>
|
|
<para>
|
|
The fifth parameter <parameter>attrsonly</parameter> should be
|
|
set to 1 if only attribute types are wanted.
|
|
If set to 0 both attributes types and attribute values are fetched
|
|
which is the default behaviour.
|
|
</para>
|
|
<para>
|
|
With the sixth parameter <parameter>sizelimit</parameter> it is
|
|
possible to limit the count of entries fetched.
|
|
Setting this to 0 means no limit.
|
|
NOTE: This parameter can NOT override server-side preset sizelimit.
|
|
You can set it lower though.
|
|
</para>
|
|
<para>
|
|
The seventh parameter <parameter>timelimit</parameter> sets the number
|
|
of seconds how long is spend on the search.
|
|
Setting this to 0 means no limit.
|
|
NOTE: This parameter can NOT override server-side preset timelimit.
|
|
You can set it lower though.
|
|
</para>
|
|
<para>
|
|
The eigth parameter <parameter>deref</parameter> specifies how aliases
|
|
should be handled during the search. It can be one of the following:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>
|
|
LDAP_DEREF_NEVER - (default) aliases are never dereferenced.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
LDAP_DEREF_SEARCHING - aliases should be dereferenced during the search
|
|
but not when locating the base object of the search.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
LDAP_DEREF_FINDING - aliases should be dereferenced when
|
|
locating the base object but not during the search.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
LDAP_DEREF_ALWAYS - aliases should be dereferenced always.
|
|
</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
These optional parameters were added in 4.0.2:
|
|
<parameter>attrsonly</parameter>,
|
|
<parameter>sizelimit</parameter>,
|
|
<parameter>timelimit</parameter>,
|
|
<parameter>deref</parameter>.
|
|
</para>
|
|
<para>
|
|
The search filter can be simple or advanced, using boolean
|
|
operators in the format described in the LDAP doumentation (see
|
|
the <ulink url="&url.ldap.filters;">Netscape Directory SDK</ulink>
|
|
for full information on filters).</para>
|
|
<para>
|
|
The example below retrieves the organizational unit, surname,
|
|
given name and email address for all people in "My Company" where
|
|
the surname or given name contains the substring $person. This
|
|
example uses a boolean filter to tell the server to look for
|
|
information in more than one attribute.
|
|
|
|
<example>
|
|
<title>LDAP search</title>
|
|
<programlisting role="php">
|
|
// $ds is a valid link identifier for a directory server
|
|
|
|
// $person is all or part of a person's name, eg "Jo"
|
|
|
|
$dn = "o=My Company, c=US";
|
|
$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<p>";
|
|
</programlisting>
|
|
</example></para>
|
|
<para>
|
|
From 4.0.5 on it's also possible to do parallel searches. To do this
|
|
you use an array of link identifiers, rather than a single identifier,
|
|
as the first argument. If you don't want the same base DN and the
|
|
same filter for all the searches, you can also use an array of base DNs
|
|
and/or an array of filters. Those arrays must be of the same size as
|
|
the link identifier array since the first entries of the arrays are
|
|
used for one search, the second entries are used for another, and so
|
|
on. When doing parallel searches an array of search result
|
|
identifiers is returned, except in case of error, then the entry
|
|
corresponding to the search will be &false;. This is very much like
|
|
the value normally returned, except that a result identifier is always
|
|
returned when a search was made. There are some rare cases where the
|
|
normal search returns &false; while the parallel search returns an
|
|
identifier.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.ldap-set-option">
|
|
<refnamediv>
|
|
<refname>ldap_set_option</refname>
|
|
<refpurpose>Set the value of the given option</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>bool <function>ldap_set_option</function></funcdef>
|
|
<paramdef>int <parameter>link_identifier</parameter></paramdef>
|
|
<paramdef>int <parameter>option</parameter></paramdef>
|
|
<paramdef>mixed <parameter>newval</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Sets the value of the specified option to be
|
|
<parameter>newval</parameter>, and returns &true; on success and &false;
|
|
on error.</para>
|
|
<para>
|
|
The parameter <parameter>option</parameter> can be one of:
|
|
LDAP_OPT_DEREF, LDAP_OPT_SIZELIMIT, LDAP_OPT_TIMELIMIT,
|
|
LDAP_OPT_PROTOCOL_VERSION, LDAP_OPT_ERROR_NUMBER, LDAP_OPT_REFERRALS,
|
|
LDAP_OPT_RESTART, LDAP_OPT_HOST_NAME, LDAP_OPT_ERROR_STRING,
|
|
LDAP_OPT_MATCHED_DN, LDAP_OPT_SERVER_CONTROLS, LDAP_OPT_CLIENT_CONTROLS.
|
|
Here's a brief description, see
|
|
<ulink url="&url.ldap.openldap-c-api;">draft-ietf-ldapext-ldap-c-api-xx.txt</ulink> for details.</para>
|
|
<para>
|
|
The options LDAP_OPT_DEREF, LDAP_OPT_SIZELIMIT, LDAP_OPT_TIMELIMIT,
|
|
LDAP_OPT_PROTOCOL_VERSION and LDAP_OPT_ERROR_NUMBER have integer value,
|
|
LDAP_OPT_REFERRALS and LDAP_OPT_RESTART have boolean value, and the
|
|
options LDAP_OPT_HOST_NAME, LDAP_OPT_ERROR_STRING and LDAP_OPT_MATCHED_DN
|
|
have string value. The first example illustrates their use. The options
|
|
LDAP_OPT_SERVER_CONTROLS and LDAP_OPT_CLIENT_CONTROLS require a list of
|
|
controls, this means that the value must be an array of controls. A
|
|
control consists of an <emphasis>oid</emphasis> identifying the control,
|
|
an optional <emphasis>value</emphasis>, and an optional flag for
|
|
<emphasis>criticality</emphasis>. In PHP a control is given by an
|
|
array containing an element with the key <emphasis>oid</emphasis>
|
|
and string value, and two optional elements. The optional
|
|
elements are key <emphasis>value</emphasis> with string value
|
|
and key <emphasis>iscritical</emphasis> with boolean value.
|
|
<emphasis>iscritical</emphasis> defaults to <emphasis>&false;</emphasis>
|
|
if not supplied. See also the second example below.</para>
|
|
<para>
|
|
This function is only available when using
|
|
OpenLDAP 2.x.x OR Netscape Directory SDK x.x, and was
|
|
added in PHP 4.0.4</para>
|
|
<para>
|
|
<example>
|
|
<title>Set protocol version</title>
|
|
<programlisting role="php">
|
|
// $ds is a valid link identifier for a directory server
|
|
if (ldap_set_option($ds, LDAP_OPT_PROTOCOL_VERSION, 3))
|
|
echo "Using LDAPv3";
|
|
else
|
|
echo "Failed to set protocol version to 3";
|
|
</programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Set server controls</title>
|
|
<programlisting role="php">
|
|
// $ds is a valid link identifier for a directory server
|
|
// control with no value
|
|
$ctrl1 = array("oid" => "1.2.752.58.10.1", "iscritical" => TRUE);
|
|
// iscritical defaults to FALSE
|
|
$ctrl2 = array("oid" => "1.2.752.58.1.10", "value" => "magic");
|
|
// try to set both controls
|
|
if (!ldap_set_option($ds, LDAP_OPT_SERVER_CONTROLS, array($ctrl1, $ctrl2)))
|
|
echo "Failed to set server controls";
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
See also <function>ldap_get_option</function>.</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.ldap-unbind">
|
|
<refnamediv>
|
|
<refname>ldap_unbind</refname>
|
|
<refpurpose>Unbind from LDAP directory</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>ldap_unbind</function></funcdef>
|
|
<paramdef>int <parameter>link_identifier</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns &true; on success and &false; on error.</para>
|
|
<para>
|
|
<function>ldap_unbind</function> function unbinds from the LDAP
|
|
directory.</para>
|
|
</refsect1>
|
|
</refentry>
|
|
</reference>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"../../manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|