mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-21 11:28:55 +00:00
f803865331
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@146654 c90b9560-bf6c-de11-be94-00142212c4b1
179 lines
7 KiB
XML
179 lines
7 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision: 1.7 $ -->
|
|
<!-- splitted from ./en/functions/ldap.xml, last change in rev 1.17 -->
|
|
<refentry id="function.ldap-search">
|
|
<refnamediv>
|
|
<refname>ldap_search</refname>
|
|
<refpurpose>Search LDAP tree</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>resource</type><methodname>ldap_search</methodname>
|
|
<methodparam><type>resource</type><parameter>link_identifier</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>base_dn</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>filter</parameter></methodparam>
|
|
<methodparam choice="opt"><type>array</type><parameter>attributes</parameter></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>attrsonly</parameter></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>sizelimit</parameter></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>timelimit</parameter></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>deref</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<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 an 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, e.g. 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 eighth 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>
|
|
<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>
|
|
The search filter can be simple or advanced, using boolean
|
|
operators in the format described in the LDAP documentation (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">
|
|
<![CDATA[
|
|
<?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);
|
|
|
|
echo $info["count"]." entries returned\n";
|
|
?>
|
|
]]>
|
|
</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>
|
|
|
|
<!-- 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
|
|
indent-tabs-mode:nil
|
|
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
|
|
-->
|