reference/mysqli/mysqli/construct.xml
390278d79b453af8f2f0837596c4cd25882b951a
...
...
@@ -3,6 +3,7 @@
3
3
<refentry xml:id="mysqli.construct" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
5
5
<refname>mysqli::__construct</refname>
6
+
<refname>mysqli::connect</refname>
6
7
<refname>mysqli_connect</refname>
7
8
<refpurpose>Open a new connection to the MySQL server</refpurpose>
8
9
</refnamediv>
...
...
@@ -10,27 +11,36 @@
10
11
<refsect1 role="description">
11
12
&reftitle.description;
12
13
<para>&style.oop;</para>
13
-
<constructorsynopsis>
14
-
<methodname>mysqli::__construct</methodname>
15
-
<methodparam choice="opt"><type>string</type><parameter>host</parameter><initializer>ini_get("mysqli.default_host")</initializer></methodparam>
16
-
<methodparam choice="opt"><type>string</type><parameter>username</parameter><initializer>ini_get("mysqli.default_user")</initializer></methodparam>
17
-
<methodparam choice="opt"><type>string</type><parameter>passwd</parameter><initializer>ini_get("mysqli.default_pw")</initializer></methodparam>
18
-
<methodparam choice="opt"><type>string</type><parameter>dbname</parameter><initializer>""</initializer></methodparam>
19
-
<methodparam choice="opt"><type>int</type><parameter>port</parameter><initializer>ini_get("mysqli.default_port")</initializer></methodparam>
20
-
<methodparam choice="opt"><type>string</type><parameter>socket</parameter><initializer>ini_get("mysqli.default_socket")</initializer></methodparam>
14
+
<constructorsynopsis role="mysqli">
15
+
<modifier>public</modifier> <methodname>mysqli::__construct</methodname>
16
+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>hostname</parameter><initializer>&null;</initializer></methodparam>
17
+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>username</parameter><initializer>&null;</initializer></methodparam>
18
+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>password</parameter><initializer>&null;</initializer></methodparam>
19
+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>database</parameter><initializer>&null;</initializer></methodparam>
20
+
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>port</parameter><initializer>&null;</initializer></methodparam>
21
+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>socket</parameter><initializer>&null;</initializer></methodparam>
21
22
</constructorsynopsis>
23
+
<methodsynopsis role="mysqli">
24
+
<modifier>public</modifier> <type>bool</type><methodname>mysqli::connect</methodname>
25
+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>hostname</parameter><initializer>&null;</initializer></methodparam>
26
+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>username</parameter><initializer>&null;</initializer></methodparam>
27
+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>password</parameter><initializer>&null;</initializer></methodparam>
28
+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>database</parameter><initializer>&null;</initializer></methodparam>
29
+
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>port</parameter><initializer>&null;</initializer></methodparam>
30
+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>socket</parameter><initializer>&null;</initializer></methodparam>
31
+
</methodsynopsis>
22
32
<para>&style.procedural;</para>
23
33
<methodsynopsis>
24
-
<type>mysqli</type><methodname>mysqli_connect</methodname>
25
-
<methodparam choice="opt"><type>string</type><parameter>host</parameter><initializer>ini_get("mysqli.default_host")</initializer></methodparam>
26
-
<methodparam choice="opt"><type>string</type><parameter>username</parameter><initializer>ini_get("mysqli.default_user")</initializer></methodparam>
27
-
<methodparam choice="opt"><type>string</type><parameter>passwd</parameter><initializer>ini_get("mysqli.default_pw")</initializer></methodparam>
28
-
<methodparam choice="opt"><type>string</type><parameter>dbname</parameter><initializer>""</initializer></methodparam>
29
-
<methodparam choice="opt"><type>int</type><parameter>port</parameter><initializer>ini_get("mysqli.default_port")</initializer></methodparam>
30
-
<methodparam choice="opt"><type>string</type><parameter>socket</parameter><initializer>ini_get("mysqli.default_socket")</initializer></methodparam>
34
+
<type class="union"><type>mysqli</type><type>false</type></type><methodname>mysqli_connect</methodname>
35
+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>hostname</parameter><initializer>&null;</initializer></methodparam>
36
+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>username</parameter><initializer>&null;</initializer></methodparam>
37
+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>password</parameter><initializer>&null;</initializer></methodparam>
38
+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>database</parameter><initializer>&null;</initializer></methodparam>
39
+
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>port</parameter><initializer>&null;</initializer></methodparam>
40
+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>socket</parameter><initializer>&null;</initializer></methodparam>
31
41
</methodsynopsis>
32
42
<para>
33
-
Opens a connection to the MySQL Server running on.
43
+
Opens a connection to the MySQL Server.
34
44
</para>
35
45
</refsect1>
36
46

...
...
@@ -39,13 +49,13 @@
39
49
<para>
40
50
<variablelist>
41
51
<varlistentry>
42
-
<term><parameter>host</parameter></term>
52
+
<term><parameter>hostname</parameter></term>
43
53
<listitem>
44
54
<para>
45
-
Can be either a host name or an IP address. Passing the &null; value
46
-
or the string "localhost" to this parameter, the local host is
47
-
assumed. When possible, pipes will be used instead of the TCP/IP
48
-
protocol.
55
+
Can be either a host name or an IP address. When passing &null;, the value is retrieved from
56
+
<link linkend="ini.mysqli.default-host">mysqli.default_host</link>.
57
+
When possible, pipes will be used instead of the TCP/IP protocol.
58
+
The TCP/IP protocol is used if a host name and port number are provided together e.g. <literal>localhost:3308</literal>.
49
59
</para>
50
60
<para>
51
61
Prepending host by <literal>p:</literal> opens a persistent connection.
...
...
@@ -58,27 +68,25 @@
58
68
<term><parameter>username</parameter></term>
59
69
<listitem>
60
70
<para>
61
-
The MySQL user name.
71
+
The MySQL username or &null; to assume the username based on the
72
+
<link linkend="ini.mysqli.default-user">mysqli.default_user</link> ini option.
62
73
</para>
63
74
</listitem>
64
75
</varlistentry>
65
76
<varlistentry>
66
-
<term><parameter>passwd</parameter></term>
77
+
<term><parameter>password</parameter></term>
67
78
<listitem>
68
79
<para>
69
-
If not provided or &null;, the MySQL server will attempt to authenticate
70
-
the user against those user records which have no password only. This
71
-
allows one username to be used with different permissions (depending
72
-
on if a password as provided or not).
80
+
The MySQL password or &null; to assume the password based on the
81
+
<link linkend="ini.mysqli.default-pw">mysqli.default_pw</link> ini option.
73
82
</para>
74
83
</listitem>
75
84
</varlistentry>
76
85
<varlistentry>
77
-
<term><parameter>dbname</parameter></term>
86
+
<term><parameter>database</parameter></term>
78
87
<listitem>
79
88
<para>
80
-
If provided will specify the default database to be used when
81
-
performing queries.
89
+
The default database to be used when performing queries or &null;.
82
90
</para>
83
91
</listitem>
84
92
</varlistentry>
...
...
@@ -86,7 +94,8 @@
86
94
<term><parameter>port</parameter></term>
87
95
<listitem>
88
96
<para>
89
-
Specifies the port number to attempt to connect to the MySQL server.
97
+
The port number to attempt to connect to the MySQL server or &null; to assume the port based on the
98
+
<link linkend="ini.mysqli.default-port">mysqli.default_port</link> ini option.
90
99
</para>
91
100
</listitem>
92
101
</varlistentry>
...
...
@@ -94,14 +103,15 @@
94
103
<term><parameter>socket</parameter></term>
95
104
<listitem>
96
105
<para>
97
-
Specifies the socket or named pipe that should be used.
106
+
The socket or named pipe that should be used or &null; to assume the socket based on the
107
+
<link linkend="ini.mysqli.default-socket">mysqli.default_socket</link> ini option.
98
108
</para>
99
109
<note>
100
110
<para>
101
111
Specifying the <parameter>socket</parameter> parameter will not
102
112
explicitly determine the type of connection to be used when
103
113
connecting to the MySQL server. How the connection is made to the
104
-
MySQL database is determined by the <parameter>host</parameter>
114
+
MySQL database is determined by the <parameter>hostname</parameter>
105
115
parameter.
106
116
</para>
107
117
</note>
...
...
@@ -114,10 +124,20 @@
114
124
<refsect1 role="returnvalues">
115
125
&reftitle.returnvalues;
116
126
<para>
117
-
Returns an object which represents the connection to a MySQL Server.
127
+
<function>mysqli_connect</function> returns an object which represents the connection to a MySQL Server,
128
+
&return.falseforfailure;.
129
+
</para>
130
+
<para>
131
+
<methodname>mysqli::connect</methodname> returns &true; on success&return.falseforfailure;.
132
+
Prior to PHP 8.1.0, returns &null; on success.
118
133
</para>
119
134
</refsect1>
120
135

136
+
<refsect1 role="errors">
137
+
&reftitle.errors;
138
+
&mysqli.conditionalexception;
139
+
</refsect1>
140
+

121
141
<refsect1 role="changelog">
122
142
&reftitle.changelog;
123
143
<para>
...
...
@@ -131,9 +151,15 @@
131
151
</thead>
132
152
<tbody>
133
153
<row>
134
-
<entry>5.3.0</entry>
154
+
<entry>8.1.0</entry>
155
+
<entry>
156
+
<methodname>mysqli::connect</methodname> now returns &true; instead of &null; on success.
157
+
</entry>
158
+
</row>
159
+
<row>
160
+
<entry>7.4.0</entry>
135
161
<entry>
136
-
Added the ability of persistent connections.
162
+
All parameters are now nullable.
137
163
</entry>
138
164
</row>
139
165
</tbody>
...
...
@@ -150,79 +176,100 @@
150
176
<programlisting role="php">
151
177
<![CDATA[
152
178
<?php
153
-
$mysqli = new mysqli('localhost', 'my_user', 'my_password', 'my_db');
154
179

155
-
/*
156
-
* This is the "official" OO way to do it,
157
-
* BUT $connect_error was broken until PHP 5.2.9 and 5.3.0.
158
-
*/
159
-
if ($mysqli->connect_error) {
160
-
die('Connect Error (' . $mysqli->connect_errno . ') '
161
-
. $mysqli->connect_error);
162
-
}
180
+
/* You should enable error reporting for mysqli before attempting to make a connection */
181
+
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
163
182

164
-
/*
165
-
* Use this instead of $connect_error if you need to ensure
166
-
* compatibility with PHP versions prior to 5.2.9 and 5.3.0.
167
-
*/
168
-
if (mysqli_connect_error()) {
169
-
die('Connect Error (' . mysqli_connect_errno() . ') '
170
-
. mysqli_connect_error());
171
-
}
183
+
$mysqli = new mysqli('localhost', 'my_user', 'my_password', 'my_db');
172
184

173
-
echo 'Success... ' . $mysqli->host_info . "\n";
185
+
/* Set the desired charset after establishing a connection */
186
+
$mysqli->set_charset('utf8mb4');
174
187

175
-
$mysqli->close();
176
-
?>
188
+
printf("Success... %s\n", $mysqli->host_info);
177
189
]]>
178
190
</programlisting>
179
-
<para>&style.oop; when extending mysqli class</para>
191
+
<para>&style.procedural;</para>
180
192
<programlisting role="php">
181
193
<![CDATA[
182
194
<?php
183
195

184
-
class foo_mysqli extends mysqli {
185
-
public function __construct($host, $user, $pass, $db) {
186
-
parent::__construct($host, $user, $pass, $db);
196
+
/* You should enable error reporting for mysqli before attempting to make a connection */
197
+
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
198
+

199
+
$mysqli = mysqli_connect('localhost', 'my_user', 'my_password', 'my_db');
200
+

201
+
/* Set the desired charset after establishing a connection */
202
+
mysqli_set_charset($mysqli, 'utf8mb4');
203
+

204
+
printf("Success... %s\n", mysqli_get_host_info($mysqli));
205
+
]]>
206
+
</programlisting>
207
+
&examples.outputs.similar;
208
+
<screen>
209
+
<![CDATA[
210
+
Success... localhost via TCP/IP
211
+
]]>
212
+
</screen>
213
+
</example>
214
+
<example>
215
+
<title>Extending mysqli class</title>
216
+
<programlisting role="php">
217
+
<![CDATA[
218
+
<?php
187
219

188
-
if (mysqli_connect_error()) {
189
-
die('Connect Error (' . mysqli_connect_errno() . ') '
190
-
. mysqli_connect_error());
191
-
}
220
+
class FooMysqli extends mysqli {
221
+
public function __construct($host, $user, $pass, $db, $port, $socket, $charset) {
222
+
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
223
+
parent::__construct($host, $user, $pass, $db, $port, $socket);
224
+
$this->set_charset($charset);
192
225
}
193
226
}
194
227

195
-
$db = new foo_mysqli('localhost', 'my_user', 'my_password', 'my_db');
228
+
$db = new FooMysqli('localhost', 'my_user', 'my_password', 'my_db', 3306, null, 'utf8mb4');
229
+
]]>
230
+
</programlisting>
231
+
</example>
232
+
<example>
233
+
<title>Manual error handling</title>
234
+
<para>If error reporting is disabled, the developer is responsible for checking and handling failures</para>
235
+
<para>&style.oop;</para>
236
+
<programlisting role="php">
237
+
<![CDATA[
238
+
<?php
196
239

197
-
echo 'Success... ' . $db->host_info . "\n";
240
+
error_reporting(0);
241
+
mysqli_report(MYSQLI_REPORT_OFF);
242
+
$mysqli = new mysqli('localhost', 'my_user', 'my_password', 'my_db');
243
+
if ($mysqli->connect_errno) {
244
+
throw new RuntimeException('mysqli connection error: ' . $mysqli->connect_error);
245
+
}
198
246

199
-
$db->close();
200
-
?>
247
+
/* Set the desired charset after establishing a connection */
248
+
$mysqli->set_charset('utf8mb4');
249
+
if ($mysqli->errno) {
250
+
throw new RuntimeException('mysqli error: ' . $mysqli->error);
251
+
}
201
252
]]>
202
253
</programlisting>
203
254
<para>&style.procedural;</para>
204
255
<programlisting role="php">
205
256
<![CDATA[
206
257
<?php
207
-
$link = mysqli_connect('localhost', 'my_user', 'my_password', 'my_db');
208
258

209
-
if (!$link) {
210
-
die('Connect Error (' . mysqli_connect_errno() . ') '
211
-
. mysqli_connect_error());
259
+
error_reporting(0);
260
+
mysqli_report(MYSQLI_REPORT_OFF);
261
+
$mysqli = mysqli_connect('localhost', 'my_user', 'my_password', 'my_db');
262
+
if (mysqli_connect_errno()) {
263
+
throw new RuntimeException('mysqli connection error: ' . mysqli_connect_error());
212
264
}
213
265

214
-
echo 'Success... ' . mysqli_get_host_info($link) . "\n";
215
-

216
-
mysqli_close($link);
217
-
?>
266
+
/* Set the desired charset after establishing a connection */
267
+
mysqli_set_charset($mysqli, 'utf8mb4');
268
+
if (mysqli_errno($mysqli)) {
269
+
throw new RuntimeException('mysqli error: ' . mysqli_error($mysqli));
270
+
}
218
271
]]>
219
272
</programlisting>
220
-
&examples.outputs;
221
-
<screen>
222
-
<![CDATA[
223
-
Success... MySQL host info: localhost via TCP/IP
224
-
]]>
225
-
</screen>
226
273
</example>
227
274
</refsect1>
228
275

...
...
@@ -231,10 +278,9 @@ Success... MySQL host info: localhost via TCP/IP
231
278
&mysqli.charset.note;
232
279
<note>
233
280
<para>
234
-
OO syntax only: If a connection fails an object is still returned. To check
235
-
if the connection failed then use either the
236
-
<function>mysqli_connect_error</function> function or the <link
237
-
linkend="mysqli.connect-error">mysqli->connect_error</link> property as in
281
+
&style.oop; only: If the connection fails, an object is still returned. To check
282
+
whether the connection failed, use either the
283
+
<function>mysqli_connect_error</function> function or the <link linkend="mysqli.connect-error">mysqli-&gt;connect_error</link> property as in
238
284
the preceding examples.
239
285
</para>
240
286
</note>
...
...
@@ -252,8 +298,7 @@ Success... MySQL host info: localhost via TCP/IP
252
298
</note>
253
299
<note>
254
300
<para>
255
-
Error "Can't create TCP/IP socket (10106)" usually means that the <link
256
-
linkend="ini.variables-order">variables_order</link> configure directive
301
+
Error "Can't create TCP/IP socket (10106)" usually means that the <link linkend="ini.variables-order">variables_order</link> configure directive
257
302
doesn't contain character <literal>E</literal>. On Windows, if the
258
303
environment is not copied the <literal>SYSTEMROOT</literal> environment
259
304
variable won't be available and PHP will have problems loading Winsock.
...
...
@@ -275,7 +320,6 @@ Success... MySQL host info: localhost via TCP/IP
275
320
</refsect1>
276
321

277
322
</refentry>
278
-

279
323
<!-- Keep this comment at the end of the file
280
324
Local variables:
281
325
mode: sgml
282
326



Tools (Spanish Manual)