reference/ldap/functions/ldap-connect.xml
57c38af2b053068ad0f1dfdead8128b957ccf4f0
57c38af2b053068ad0f1dfdead8128b957ccf4f0
...
...
@@ -9,14 +9,30 @@
9
9
<refsect1 role="description">
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
-
<type>resource</type><methodname>ldap_connect</methodname>
13
-
<methodparam choice="opt"><type>string</type><parameter>hostname</parameter><initializer>&null;</initializer></methodparam>
12
+
<type class="union"><type>LDAP\Connection</type><type>false</type></type><methodname>ldap_connect</methodname>
13
+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>uri</parameter><initializer>&null;</initializer></methodparam>
14
+
</methodsynopsis>
15
+
<warning>
16
+
<simpara>
17
+
As of PHP 8.3.0, the <emphasis>following</emphasis> signature is deprecated.
18
+
</simpara>
19
+
</warning>
20
+
<methodsynopsis>
21
+
<type class="union"><type>LDAP\Connection</type><type>false</type></type><methodname>ldap_connect</methodname>
22
+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>host</parameter><initializer>&null;</initializer></methodparam>
14
23
<methodparam choice="opt"><type>int</type><parameter>port</parameter><initializer>389</initializer></methodparam>
15
24
</methodsynopsis>
16
25
<para>
17
-
Establishes a connection to a LDAP server on a specified
18
-
<parameter>hostname</parameter> and <parameter>port</parameter>.
26
+
Creates an <classname>LDAP\Connection</classname> connection and checks whether the given
27
+
<parameter>uri</parameter> is plausible.
19
28
</para>
29
+
<note>
30
+
<simpara>
31
+
This function does <emphasis>not</emphasis> open a connection.
32
+
It checks whether the given parameters are plausible and can be used
33
+
to open a connection as soon as one is needed.
34
+
</simpara>
35
+
</note>
20
36
</refsect1>
21
37
22
38
<refsect1 role="parameters">
...
...
@@ -24,13 +40,25 @@
24
40
<para>
25
41
<variablelist>
26
42
<varlistentry>
27
-
<term><parameter>hostname</parameter></term>
43
+
<term><parameter>uri</parameter></term>
28
44
<listitem>
29
45
<para>
30
-
If you are using OpenLDAP 2.x.x you can specify a URL instead of the
31
-
hostname. To use LDAP with SSL, compile OpenLDAP 2.x.x with SSL
32
-
support, configure PHP with SSL, and set this parameter as
33
-
<literal>ldaps://hostname/</literal>.
46
+
A full LDAP URI of the form <literal>ldap://hostname:port</literal>
47
+
or <literal>ldaps://hostname:port</literal> for SSL encryption.
48
+
</para>
49
+
<para>
50
+
You can also provide multiple LDAP-URIs separated by a space as one string
51
+
</para>
52
+
<para>
53
+
Note that <literal>hostname:port</literal> is not a supported LDAP URI as the schema is missing.
54
+
</para>
55
+
</listitem>
56
+
</varlistentry>
57
+
<varlistentry>
58
+
<term><parameter>host</parameter></term>
59
+
<listitem>
60
+
<para>
61
+
The hostname to connect to.
34
62
</para>
35
63
</listitem>
36
64
</varlistentry>
...
...
@@ -38,7 +66,7 @@
38
66
<term><parameter>port</parameter></term>
39
67
<listitem>
40
68
<para>
41
-
The port to connect to. Not used when using URLs.
69
+
The port to connect to.
42
70
</para>
43
71
</listitem>
44
72
</varlistentry>
...
...
@@ -49,19 +77,52 @@
49
77
<refsect1 role="returnvalues">
50
78
&reftitle.returnvalues;
51
79
<para>
52
-
Returns a positive LDAP link identifier on success, or &false; on error.
53
-
When OpenLDAP 2.x.x is used, <function>ldap_connect</function> will always
54
-
return a <type>resource</type> as it does not actually connect but just
80
+
Returns an <classname>LDAP\Connection</classname> instance when the provided LDAP URI
81
+
seems plausible. It's a syntactic check of the provided parameter but the server(s) will not
82
+
be contacted! If the syntactic check fails it returns &false;.
83
+
<function>ldap_connect</function> will otherwise
84
+
return a <classname>LDAP\Connection</classname> instance as it does not actually connect but just
55
85
initializes the connecting parameters. The actual connect happens with
56
-
the next calls to ldap_* funcs, usually with
86
+
the next calls to ldap_* functions, usually with
57
87
<function>ldap_bind</function>.
58
88
</para>
59
89
<para>
60
-
If no arguments are specified then the link identifier of the already
61
-
opened link will be returned.
90
+
If no argument is specified then the <classname>LDAP\Connection</classname> instance of the already
91
+
opened connection will be returned.
62
92
</para>
63
93
</refsect1>
64
94
95
+
<refsect1 role="changelog">
96
+
&reftitle.changelog;
97
+
<informaltable>
98
+
<tgroup cols="2">
99
+
<thead>
100
+
<row>
101
+
<entry>&Version;</entry>
102
+
<entry>&Description;</entry>
103
+
</row>
104
+
</thead>
105
+
<tbody>
106
+
<row>
107
+
<entry>8.3.0</entry>
108
+
<entry>
109
+
Calling <function>ldap_connect</function> with separate
110
+
<parameter>hostname</parameter> and <parameter>port</parameter>
111
+
is now deprecated.
112
+
</entry>
113
+
</row>
114
+
<row>
115
+
<entry>8.1.0</entry>
116
+
<entry>
117
+
Returns an <classname>LDAP\Connection</classname> instance now;
118
+
previously, a &resource; was returned.
119
+
</entry>
120
+
</row>
121
+
</tbody>
122
+
</tgroup>
123
+
</informaltable>
124
+
</refsect1>
125
+
65
126
<refsect1 role="examples">
66
127
&reftitle.examples;
67
128
<para>
...
...
@@ -72,12 +133,11 @@
72
133
<?php
73
134
74
135
// LDAP variables
75
-
$ldaphost = "ldap.example.com"; // your ldap servers
76
-
$ldapport = 389; // your ldap server's port number
136
+
$ldapuri = "ldap://ldap.example.com:389"; // your ldap-uri
77
137
78
138
// Connecting to LDAP
79
-
$ldapconn = ldap_connect($ldaphost, $ldapport)
80
-
or die("Could not connect to $ldaphost");
139
+
$ldapconn = ldap_connect($ldapuri)
140
+
or die("That LDAP-URI was not parseable");
81
141
82
142
?>
83
143
]]>
...
...
@@ -95,7 +155,7 @@ $ldaphost = "ldaps://ldap.example.com/";
95
155
96
156
// Connecting to LDAP
97
157
$ldapconn = ldap_connect($ldaphost)
98
-
or die("Could not connect to {$ldaphost}");
158
+
or die("That LDAP-URI was not parseable");
99
159
100
160
?>
101
161
]]>
...
...
@@ -114,7 +174,6 @@ $ldapconn = ldap_connect($ldaphost)
114
174
</refsect1>
115
175
116
176
</refentry>
117
-
118
177
<!-- Keep this comment at the end of the file
119
178
Local variables:
120
179
mode: sgml
121
180