MFB: Upgrade to the new-reference-structure

- (Created missing setup sections in setup.xml, if any)
 - Moved the intro to book.xml
 - Changed the intro ID from <extname>.intro to intro.<extname>
 - Moved the constants entity to book.xml
 - changed constants.xml to be an appendix
 - Moevd the examples into its own chapter
	NOTE: The chapter ID is 'ldap.examples', the first ID is 'ldap.examples-basic'
 - Moved the requirements and resources sections to setup.xml
 - Moved the configure and ini entities to setup.xml
 - Moved the 'ldap.using' section into its own chapter (using.xml)


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@248858 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Hannes Magnusson 2007-12-23 20:56:25 +00:00
parent 5a84c17e07
commit 979ed852e4
6 changed files with 349 additions and 227 deletions

118
reference/ldap/book.xml Normal file
View file

@ -0,0 +1,118 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.2 $ -->
<!-- Purpose: remote.other -->
<!-- Membership: bundled, external -->
<book xml:id="book.ldap" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>LDAP</title>
<!-- {{{ preface -->
<preface xml:id="intro.ldap">
&reftitle.intro;
<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>
<para>
Lots of information about LDAP can be found at
</para>
<itemizedlist>
<listitem>
<para>
<link xlink:href="&url.ldap.netscape;">Mozilla</link>
</para>
</listitem>
<listitem>
<para>
<link xlink:href="&url.ldap.openldap;">OpenLDAP Project</link>
</para>
</listitem>
</itemizedlist>
<para>
The Netscape SDK contains a helpful
<link xlink:href="&url.ldap.netscape.sdk.docs;">Programmer's Guide</link> in
HTML format.
</para>
</preface>
<!-- }}} -->
&reference.ldap.setup;
&reference.ldap.constants;
&reference.ldap.using;
&reference.ldap.examples;
&reference.ldap.reference;
</book>
<!-- 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
-->

View file

@ -1,6 +1,6 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<section xml:id="ldap.constants" xmlns="http://docbook.org/ns/docbook">
<!-- $Revision: 1.5 $ -->
<appendix xml:id="ldap.constants" xmlns="http://docbook.org/ns/docbook">
&reftitle.constants;
&extension.constants;
<variablelist>
@ -239,7 +239,7 @@
</listitem>
</varlistentry>
</variablelist>
</section>
</appendix>
<!-- Keep this comment at the end of the file
Local variables:

View file

@ -0,0 +1,82 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.2 $ -->
<chapter xml:id="ldap.examples" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.examples;
<section xml:id="ldap.examples-basic">
<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">
<![CDATA[
<?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 . "<br />";
if ($ds) {
echo "Binding ...";
$r=ldap_bind($ds); // this is an "anonymous" bind, typically
// read-only access
echo "Bind result is " . $r . "<br />";
echo "Searching for (sn=S*) ...";
// Search surname entry
$sr=ldap_search($ds, "o=My Company, c=US", "sn=S*");
echo "Search result is " . $sr . "<br />";
echo "Number of entires returned is " . ldap_count_entries($ds, $sr) . "<br />";
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] . "<br /><hr />";
}
echo "Closing connection";
ldap_close($ds);
} else {
echo "<h4>Unable to connect to LDAP server</h4>";
}
?>
]]>
</programlisting>
</example>
</section>
</chapter>
<!-- 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
-->

View file

@ -1,230 +1,12 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.17 $ -->
<!-- Purpose: remote.other -->
<!-- Membership: bundled, external -->
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.18 $ -->
<reference xml:id="ref.ldap" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>LDAP Functions</title>
<titleabbrev>LDAP</titleabbrev>
<reference xml:id="ref.ldap" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>LDAP &Functions;</title>
&reference.ldap.entities.functions;
<partintro>
<section xml:id="ldap.intro">
&reftitle.intro;
<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>
<para>
Lots of information about LDAP can be found at
</para>
</reference>
<itemizedlist>
<listitem>
<para>
<link xlink:href="&url.ldap.netscape;">Mozilla</link>
</para>
</listitem>
<listitem>
<para>
<link xlink:href="&url.ldap.openldap;">OpenLDAP Project</link>
</para>
</listitem>
</itemizedlist>
<para>
The Netscape SDK contains a helpful
<link xlink:href="&url.ldap.netscape.sdk.docs;">Programmer's Guide</link> in
HTML format.
</para>
</section>
<section xml:id="ldap.requirements">
&reftitle.required;
<para>
You will need to get and compile LDAP client libraries from either
<link xlink:href="&url.ldap.openldap.source;">OpenLDAP</link> or <link
xlink:href="&url.ldap.bind9;">Bind9.net</link> in order to compile PHP with
LDAP support.
<!--
The other links are dead.. (7/7/2005)
So were those Netscape links - updated netscape.sdk link to mozilla.org
now. Also added new entity, url.ldap.bind9, which offers a win32 binary
amongst other things (31/7/2005)
either the University of Michigan <link xlink:href="&url.ldap.mt;">
ldap-3.3 package</link>, <link xlink:href="&url.ldap.netscape.sdk;"> Netscape
Directory SDK 3.0</link> or <link xlink:href="&url.ldap.openldap.source;">
OpenLDAP</link> to compile PHP with LDAP support.
-->
</para>
</section>
&reference.ldap.configure;
&reference.ldap.ini;
<section xml:id="ldap.resources">
&reftitle.resources;
<para>
Most LDAP functions operate on or return resources (e.g.
<function>ldap_connect</function> returns a positive LDAP link identifier
required by most LDAP functions).
</para>
</section>
&reference.ldap.constants;
<section xml:id="ldap.examples">
&reftitle.examples;
<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">
<![CDATA[
<?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 . "<br />";
if ($ds) {
echo "Binding ...";
$r=ldap_bind($ds); // this is an "anonymous" bind, typically
// read-only access
echo "Bind result is " . $r . "<br />";
echo "Searching for (sn=S*) ...";
// Search surname entry
$sr=ldap_search($ds, "o=My Company, c=US", "sn=S*");
echo "Search result is " . $sr . "<br />";
echo "Number of entires returned is " . ldap_count_entries($ds, $sr) . "<br />";
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] . "<br /><hr />";
}
echo "Closing connection";
ldap_close($ds);
} else {
echo "<h4>Unable to connect to LDAP server</h4>";
}
?>
]]>
</programlisting>
</example>
</section>
<section xml:id="ldap.using">
<title>Using the PHP LDAP calls</title>
<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>
</section>
</partintro>
&reference.ldap.entities.functions;
</reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml

72
reference/ldap/setup.xml Normal file
View file

@ -0,0 +1,72 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.2 $ -->
<chapter xml:id="ldap.setup" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.setup;
<!-- {{{ Requirements -->
<section xml:id="ldap.requirements">
&reftitle.required;
<para>
You will need to get and compile LDAP client libraries from either
<link xlink:href="&url.ldap.openldap.source;">OpenLDAP</link> or <link
xlink:href="&url.ldap.bind9;">Bind9.net</link> in order to compile PHP with
LDAP support.
<!--
FIXME:
The other links are dead.. (7/7/2005)
So were those Netscape links - updated netscape.sdk link to mozilla.org
now. Also added new entity, url.ldap.bind9, which offers a win32 binary
amongst other things (31/7/2005)
either the University of Michigan <link xlink:href="&url.ldap.mt;">
ldap-3.3 package</link>, <link xlink:href="&url.ldap.netscape.sdk;"> Netscape
Directory SDK 3.0</link> or <link xlink:href="&url.ldap.openldap.source;">
OpenLDAP</link> to compile PHP with LDAP support.
-->
</para>
</section>
<!-- }}} -->
<!-- {{{ Installation -->
&reference.ldap.configure;
<!-- }}} -->
<!-- {{{ Configuration -->
&reference.ldap.ini;
<!-- }}} -->
<!-- {{{ Resources -->
<section xml:id="ldap.resources">
&reftitle.resources;
<para>
Most LDAP functions operate on or return resources (e.g.
<function>ldap_connect</function> returns a positive LDAP link identifier
required by most LDAP functions).
</para>
</section>
<!-- }}} -->
</chapter>
<!-- 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
-->

68
reference/ldap/using.xml Normal file
View file

@ -0,0 +1,68 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.2 $ -->
<chapter xml:id="ldap.using" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Using the PHP LDAP calls</title>
<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>
</chapter>
<!-- 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
-->