From 8b1746142cba11d521752933d9aa8a0a9935d37e Mon Sep 17 00:00:00 2001
From: Peter Cowburn <salathe@php.net>
Date: Sat, 30 Jan 2016 12:57:21 +0000
Subject: [PATCH] Clarify what ldap_connect actually does and what parameters
 are accepted (and which not)

--
Provided by Andreas Heigl (andreas@heigl.org)

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@338549 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/ldap/functions/ldap-connect.xml | 32 ++++++++++++++++-------
 1 file changed, 22 insertions(+), 10 deletions(-)

diff --git a/reference/ldap/functions/ldap-connect.xml b/reference/ldap/functions/ldap-connect.xml
index eb13a94bde..4d46d14f12 100644
--- a/reference/ldap/functions/ldap-connect.xml
+++ b/reference/ldap/functions/ldap-connect.xml
@@ -10,12 +10,17 @@
   &reftitle.description;
   <methodsynopsis>
    <type>resource</type><methodname>ldap_connect</methodname>
-   <methodparam choice="opt"><type>string</type><parameter>hostname</parameter><initializer>&null;</initializer></methodparam>
+   <methodparam choice="opt"><type>string</type><parameter>host</parameter><initializer>&null;</initializer></methodparam>
    <methodparam choice="opt"><type>int</type><parameter>port</parameter><initializer>389</initializer></methodparam>
   </methodsynopsis>
   <para>
-   Establishes a connection to a LDAP server on a specified
-   <parameter>hostname</parameter> and <parameter>port</parameter>.
+   Creates an LDAP link identifier and checks whether the given
+   <parameter>host</parameter> and <parameter>port</parameter> are plausible.
+  </para>
+  <para>
+   Note: This function does <emphasis>not</emphasis> open a connection.
+   It checks whether the given parameters are plausibe and can be used
+   to open a connection as soon as one is needed.
   </para>
  </refsect1>
 
@@ -24,13 +29,18 @@
   <para>
    <variablelist>
     <varlistentry>
-     <term><parameter>hostname</parameter></term>
+     <term><parameter>host</parameter></term>
      <listitem>
       <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 set this parameter as  
-       <literal>ldaps://hostname/</literal>.
+       This field supports using a hostname or, with OpenLDAP 2.x.x and
+       later, a full LDAP URI of the form <literal>ldap://hostname:port</literal>
+       or <literal>ldaps://hostname:port</literal> for SSL encryption.
+      </para>
+      <para>
+       You can also provide multiple LDAP-URIs separated by a space as one string
+      </para>
+      <para>
+       Note that <literal>hostname:port</literal> is not a supported LDAP URI as the schema is missing.
       </para>
      </listitem>
     </varlistentry>
@@ -38,7 +48,7 @@
      <term><parameter>port</parameter></term>
      <listitem>
       <para>
-       The port to connect to. Not used when using URLs.
+       The port to connect to. Not used when using LDAP URIs.
       </para>
      </listitem>
     </varlistentry>
@@ -49,7 +59,9 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Returns a positive LDAP link identifier on success, or &false; on error.
+   Returns a positive LDAP link identifier when the provided hostname/port combination or LDAP URI
+   seems plausible. It's a syntactic check of the provided parameters but the server(s) will not
+   be contacted! If the syntactic check fails it returns &false;.
    When OpenLDAP 2.x.x is used, <function>ldap_connect</function> will always
    return a <type>resource</type> as it does not actually connect but just
    initializes the connecting parameters.  The actual connect happens with