Document that the 2nd parameter of ldap_connect is deprecated

This is only a soft deprecation, since otherwise a lot of existing code would
break.  Still, preferably an LDAP-URI should be passed to ldap_connect().

Based on a patch provided by heiglandreas@php.net

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@347310 c90b9560-bf6c-de11-be94-00142212c4b1

Author: cmb69

reference/ldap/functions/ldap-connect.xml

@@ -8,6 +8,16 @@
 
  <refsect1 role="description">
   &reftitle.description;
+  <methodsynopsis>
+   <type>resource</type><methodname>ldap_connect</methodname>
+   <methodparam choice="opt"><type>string</type><parameter>ldap_uri</parameter><initializer>&null;</initializer></methodparam>
+  </methodsynopsis>
+  <warning>
+   <simpara>
+    The <emphasis>following</emphasis> signature is still supported for backwards
+    compatibility, but is considered deprecated and should not be used anymore!
+   </simpara>
+  </warning> 
   <methodsynopsis>
    <type>resource</type><methodname>ldap_connect</methodname>
    <methodparam choice="opt"><type>string</type><parameter>host</parameter><initializer>&null;</initializer></methodparam>
@@ -31,11 +41,10 @@
   <para>
    <variablelist>
     <varlistentry>
-     <term><parameter>host</parameter></term>
+     <term><parameter>ldap_uri</parameter></term>
      <listitem>
       <para>
-       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>
+       A full LDAP URI of the form <literal>ldap://hostname:port</literal>
        or <literal>ldaps://hostname:port</literal> for SSL encryption.
       </para>
       <para>
@@ -46,11 +55,19 @@
       </para>
      </listitem>
     </varlistentry>
+    <varlistentry>
+     <term><parameter>host</parameter></term>
+     <listitem>
+      <para>
+       The hostname to connect to.
+      </para>
+     </listitem>
+    </varlistentry>
     <varlistentry>
      <term><parameter>port</parameter></term>
      <listitem>
       <para>
-       The port to connect to. Not used when using LDAP URIs.
+       The port to connect to.
       </para>
      </listitem>
     </varlistentry>
@@ -61,17 +78,17 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   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
+   Returns a positive LDAP link identifier when the provided LDAP URI
+   seems plausible. It's a syntactic check of the provided parameter 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
+   <function>ldap_connect</function> will otherwise
    return a <type>resource</type> as it does not actually connect but just
    initializes the connecting parameters.  The actual connect happens with
    the next calls to ldap_* funcs, usually with
    <function>ldap_bind</function>.
   </para>
   <para>
-   If no arguments are specified then the link identifier of the already
+   If no argument is specified then the link identifier of the already
    opened link will be returned.
   </para>
  </refsect1>
@@ -86,12 +103,11 @@
 <?php
 
 // LDAP variables
-$ldaphost = "ldap.example.com";  // your ldap servers
-$ldapport = 389;                 // your ldap server's port number
+$ldapuri = "ldap://ldap.example.com:389";  // your ldap-uri
 
 // Connecting to LDAP
-$ldapconn = ldap_connect($ldaphost, $ldapport)
-          or die("Could not connect to $ldaphost");
+$ldapconn = ldap_connect($ldapuri)
+          or die("That LDAP-URI was not parseable");
 
 ?>
 ]]>
@@ -109,7 +125,7 @@ $ldaphost = "ldaps://ldap.example.com/";
 
 // Connecting to LDAP
 $ldapconn = ldap_connect($ldaphost)
-          or die("Could not connect to {$ldaphost}");
+          or die("That LDAP-URI was not parseable");
 
 ?>
 ]]>