reference/mysqlinfo/set.xml
f3c97392225bcb44afff9ddc86529179c81d0f8e
f3c97392225bcb44afff9ddc86529179c81d0f8e
...
...
@@ -21,28 +21,24 @@
21
21
<book xml:id="mysql">
22
22
<title>Overview of the MySQL PHP drivers</title>
23
23
24
-
<info xml:id="mysqlinfo.intro">
24
+
<preface xml:id="mysqlinfo.intro">
25
25
<title>Introduction</title>
26
-
<abstract>
27
-
<para>
28
-
Depending on the version of PHP, there are either two or three PHP APIs
29
-
for accessing the MySQL database. PHP 5 users can choose between the
30
-
deprecated <link linkend="book.mysql">mysql</link> extension,
31
-
<link linkend="book.mysqli">mysqli</link>, or
32
-
<link linkend="ref.pdo-mysql">PDO_MySQL</link>. PHP 7 removes the mysql
33
-
extension, leaving only the latter two options.
34
-
</para>
35
-
<para>
36
-
This guide explains the
37
-
<link linkend="mysqlinfo.terminology">terminology</link> used to describe
38
-
each API, information about
39
-
<link linkend="mysqlinfo.api.choosing">choosing which API</link> to
40
-
use, and also information to help choose which MySQL
41
-
<link linkend="mysqlinfo.library.choosing">library to use</link> with
42
-
the API.
43
-
</para>
44
-
</abstract>
45
-
</info>
26
+
<para>
27
+
There are several PHP APIs
28
+
for accessing the MySQL database. Users can choose between the
29
+
<link linkend="book.mysqli">mysqli</link> or
30
+
<link linkend="ref.pdo-mysql">PDO_MySQL</link> extensions.
31
+
</para>
32
+
<para>
33
+
This guide explains the
34
+
<link linkend="mysqlinfo.terminology">terminology</link> used to describe
35
+
each API, information about
36
+
<link linkend="mysqlinfo.api.choosing">choosing which API</link> to
37
+
use, and also information to help choose which MySQL
38
+
<link linkend="mysqlinfo.library.choosing">library to use</link> with
39
+
the API.
40
+
</para>
41
+
</preface>
46
42
47
43
<chapter xml:id="mysqlinfo.terminology" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
48
44
<title>Terminology overview</title>
...
...
@@ -68,7 +64,7 @@
68
64
APIs can be procedural or object-oriented. With a procedural API you
69
65
call functions to carry out tasks, with the object-oriented API you
70
66
instantiate classes and then call methods on the resulting objects.
71
-
Of the two the latter is usually the preferred interface, as it is
67
+
Of the two, the latter is usually the preferred interface, as it is
72
68
more modern and leads to better organized code.
73
69
</para>
74
70
...
...
@@ -134,11 +130,10 @@
134
130
</para>
135
131
136
132
<para>
137
-
In the PHP documentation you will come across another term -
133
+
In the PHP documentation, you will come across another term -
138
134
<emphasis>extension</emphasis>. The PHP code consists of a core,
139
135
with optional extensions to the core functionality. PHP's
140
-
MySQL-related extensions, such as the <literal>mysqli</literal>
141
-
extension, and the <literal>mysql</literal> extension, are
136
+
MySQL-related extension, <literal>mysqli</literal>, is
142
137
implemented using the PHP extension framework.
143
138
</para>
144
139
...
...
@@ -165,15 +160,15 @@
165
160
<chapter xml:id="mysqlinfo.api.choosing" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
166
161
<title>Choosing an API</title>
167
162
<para>
168
-
PHP offers three different APIs to connect to MySQL. Below we show
169
-
the APIs provided by the mysql, mysqli, and PDO extensions. Each code snippet
163
+
PHP offers different APIs to connect to MySQL. Below we show
164
+
the APIs provided by the mysqli and PDO extensions. Each code snippet
170
165
creates a connection to a MySQL server running on "example.com" using
171
166
the username "user" and the password "password". And a query is run to
172
167
greet the user.
173
168
</para>
174
169
<para>
175
170
<example>
176
-
<title>Comparing the three MySQL APIs</title>
171
+
<title>Comparing the MySQL APIs</title>
177
172
<programlisting role="php">
178
173
<![CDATA[
179
174
<?php
...
...
@@ -188,43 +183,50 @@ $pdo = new PDO('mysql:host=example.com;dbname=database', 'user', 'password');
188
183
$statement = $pdo->query("SELECT 'Hello, dear MySQL user!' AS _message FROM DUAL");
189
184
$row = $statement->fetch(PDO::FETCH_ASSOC);
190
185
echo htmlentities($row['_message']);
186
+
]]>
187
+
</programlisting>
188
+
</example>
189
+
</para>
190
+
<para>
191
+
<example>
192
+
<title>Comparing prepared statements</title>
193
+
<programlisting role="php">
194
+
<![CDATA[
195
+
<?php
196
+
// mysqli
197
+
$mysqli = new mysqli("example.com", "user", "password", "database");
198
+
$statement = $mysqli->prepare("SELECT District FROM City WHERE Name=?");
199
+
$statement->execute(["Amersfoort"]);
200
+
$result = $statement->get_result();
201
+
$row = $result->fetch_assoc();
202
+
echo htmlentities($row['District']);
191
203
192
-
// mysql
193
-
$c = mysql_connect("example.com", "user", "password");
194
-
mysql_select_db("database");
195
-
$result = mysql_query("SELECT 'Hello, dear MySQL user!' AS _message FROM DUAL");
196
-
$row = mysql_fetch_assoc($result);
197
-
echo htmlentities($row['_message']);
198
-
?>
204
+
// PDO
205
+
$pdo = new PDO('mysql:host=example.com;dbname=database', 'user', 'password');
206
+
$statement = $pdo->prepare("SELECT District FROM City WHERE Name=?");
207
+
$statement->execute(["Amersfoort"]);
208
+
$row = $statement->fetch(PDO::FETCH_ASSOC);
209
+
echo htmlentities($row['District']);
199
210
]]>
200
211
</programlisting>
201
212
</example>
202
213
</para>
203
214
<para>
204
-
<emphasis role="bold">Recommended API</emphasis>
215
+
<emphasis role="bold">Feature comparison</emphasis>
205
216
</para>
206
217
<para>
207
-
It is recommended to use either the <link linkend="book.mysqli">mysqli</link>
208
-
or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extensions.
209
-
It is not recommended to use the old <link linkend="ref.mysql">mysql</link>
210
-
extension for new development, as it was deprecated in PHP 5.5.0 and was
211
-
removed in PHP 7. A detailed feature comparison matrix is provided below.
212
-
The overall performance of all three extensions is considered to be about
218
+
The overall performance of both extensions is considered to be about
213
219
the same. Although the performance of the extension contributes only a
214
220
fraction of the total run time of a PHP web request. Often, the impact is
215
221
as low as 0.1%.
216
222
</para>
217
-
<para>
218
-
<emphasis role="bold">Feature comparison</emphasis>
219
-
</para>
220
-
<informaltable>
221
-
<tgroup cols="4">
223
+
<informaltable xml:id="mysqlinfo.api.choosing.changelog">
224
+
<tgroup cols="3">
222
225
<thead>
223
226
<row>
224
227
<entry></entry>
225
228
<entry>ext/mysqli</entry>
226
229
<entry>PDO_MySQL</entry>
227
-
<entry>ext/mysql</entry>
228
230
</row>
229
231
</thead>
230
232
<tbody>
...
...
@@ -232,109 +234,86 @@ echo htmlentities($row['_message']);
232
234
<entry>PHP version introduced</entry>
233
235
<entry>5.0</entry>
234
236
<entry>5.1</entry>
235
-
<entry>2.0</entry>
236
237
</row>
237
238
<row>
238
-
<entry>Included with PHP 5.x</entry>
239
+
<entry>Included with PHP 7.x and 8.x</entry>
239
240
<entry>Yes</entry>
240
241
<entry>Yes</entry>
241
-
<entry>Yes</entry>
242
-
</row>
243
-
<row>
244
-
<entry>Included with PHP 7.x</entry>
245
-
<entry>Yes</entry>
246
-
<entry>Yes</entry>
247
-
<entry>No</entry>
248
242
</row>
249
243
<row>
250
244
<entry>Development status</entry>
251
245
<entry>Active</entry>
252
246
<entry>Active</entry>
253
-
<entry>Maintenance only in 5.x; removed in 7.x</entry>
254
247
</row>
255
248
<row>
256
249
<entry>Lifecycle</entry>
257
250
<entry>Active</entry>
258
251
<entry>Active</entry>
259
-
<entry>Deprecated in 5.x; removed in 7.x</entry>
260
252
</row>
261
253
<row>
262
254
<entry>Recommended for new projects</entry>
263
255
<entry>Yes</entry>
264
256
<entry>Yes</entry>
265
-
<entry>No</entry>
266
257
</row>
267
258
<row>
268
259
<entry>OOP Interface</entry>
269
260
<entry>Yes</entry>
270
261
<entry>Yes</entry>
271
-
<entry>No</entry>
272
262
</row>
273
263
<row>
274
264
<entry>Procedural Interface</entry>
275
265
<entry>Yes</entry>
276
266
<entry>No</entry>
277
-
<entry>Yes</entry>
278
267
</row>
279
268
<row>
280
269
<entry>API supports non-blocking, asynchronous queries with mysqlnd</entry>
281
270
<entry>Yes</entry>
282
271
<entry>No</entry>
283
-
<entry>No</entry>
284
272
</row>
285
273
<row>
286
274
<entry>Persistent Connections</entry>
287
275
<entry>Yes</entry>
288
276
<entry>Yes</entry>
289
-
<entry>Yes</entry>
290
277
</row>
291
278
<row>
292
279
<entry>API supports Charsets</entry>
293
280
<entry>Yes</entry>
294
281
<entry>Yes</entry>
295
-
<entry>Yes</entry>
296
282
</row>
297
283
<row>
298
284
<entry>API supports server-side Prepared Statements</entry>
299
285
<entry>Yes</entry>
300
286
<entry>Yes</entry>
301
-
<entry>No</entry>
302
287
</row>
303
288
<row>
304
289
<entry>API supports client-side Prepared Statements</entry>
305
290
<entry>No</entry>
306
291
<entry>Yes</entry>
307
-
<entry>No</entry>
308
292
</row>
309
293
<row>
310
294
<entry>API supports Stored Procedures</entry>
311
295
<entry>Yes</entry>
312
296
<entry>Yes</entry>
313
-
<entry>No</entry>
314
297
</row>
315
298
<row>
316
299
<entry>API supports Multiple Statements</entry>
317
300
<entry>Yes</entry>
318
301
<entry>Most</entry>
319
-
<entry>No</entry>
320
302
</row>
321
303
<row>
322
304
<entry>API supports Transactions</entry>
323
305
<entry>Yes</entry>
324
306
<entry>Yes</entry>
325
-
<entry>No</entry>
326
307
</row>
327
308
<row>
328
309
<entry>Transactions can be controlled with SQL</entry>
329
310
<entry>Yes</entry>
330
311
<entry>Yes</entry>
331
-
<entry>Yes</entry>
332
312
</row>
333
313
<row>
334
314
<entry>Supports all MySQL 5.1+ functionality</entry>
335
315
<entry>Yes</entry>
336
316
<entry>Most</entry>
337
-
<entry>No</entry>
338
317
</row>
339
318
</tbody>
340
319
</tgroup>
...
...
@@ -344,13 +323,13 @@ echo htmlentities($row['_message']);
344
323
<chapter xml:id="mysqlinfo.library.choosing" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
345
324
<title>Choosing a library</title>
346
325
<para>
347
-
The mysqli, PDO_MySQL and mysql PHP extensions are lightweight wrappers on
326
+
The mysqli and PDO_MySQL PHP extensions are lightweight wrappers on
348
327
top of a C client library. The extensions can either use the
349
328
<link linkend="book.mysqlnd">mysqlnd</link> library or the <literal>libmysqlclient</literal>
350
329
library. Choosing a library is a compile time decision.
351
330
</para>
352
331
<para>
353
-
The mysqlnd library is part of the PHP distribution since 5.3.0. It offers
332
+
The mysqlnd library is part of the PHP distribution. It offers
354
333
features like lazy connections and query caching, features that are not available
355
334
with libmysqlclient, so using the built-in mysqlnd library is highly recommended.
356
335
See the <link linkend="book.mysqlnd">mysqlnd documentation</link> for
...
...
@@ -362,13 +341,13 @@ echo htmlentities($row['_message']);
362
341
<programlisting role="shell">
363
342
<![CDATA[
364
343
// Recommended, compiles with mysqlnd
365
-
$ ./configure --with-mysqli=mysqlnd --with-pdo-mysql=mysqlnd --with-mysql=mysqlnd
344
+
$ ./configure --with-mysqli=mysqlnd --with-pdo-mysql=mysqlnd
366
345
367
-
// Alternatively recommended, compiles with mysqlnd as of PHP 5.4
368
-
$ ./configure --with-mysqli --with-pdo-mysql --with-mysql
346
+
// Alternatively recommended, compiles with mysqlnd
347
+
$ ./configure --with-mysqli --with-pdo-mysql
369
348
370
349
// Not recommended, compiles with libmysqlclient
371
-
$ ./configure --with-mysqli=/path/to/mysql_config --with-pdo-mysql=/path/to/mysql_config --with-mysql=/path/to/mysql_config
350
+
$ ./configure --with-mysqli=/path/to/mysql_config --with-pdo-mysql=/path/to/mysql_config
372
351
]]>
373
352
</programlisting>
374
353
</example>
...
...
@@ -381,7 +360,7 @@ $ ./configure --with-mysqli=/path/to/mysql_config --with-pdo-mysql=/path/to/mysq
381
360
library instead of the MySQL Client Server library (libmysqlclient). Both
382
361
libraries are supported and constantly being improved.
383
362
</para>
384
-
<informaltable>
363
+
<informaltable xml:id="mysqlinfo.library.choosing.changelog">
385
364
<tgroup cols="3">
386
365
<thead>
387
366
<row>
...
...
@@ -417,28 +396,23 @@ $ ./configure --with-mysqli=/path/to/mysql_config --with-pdo-mysql=/path/to/mysq
417
396
<entry>No end announced</entry>
418
397
</row>
419
398
<row>
420
-
<entry>PHP 5.4 and above; compile default (for all MySQL extensions)</entry>
399
+
<entry>Compile default (for all MySQL extensions)</entry>
421
400
<entry>Yes</entry>
422
401
<entry>No</entry>
423
402
</row>
424
403
<row>
425
-
<entry>PHP 5.3; compile default (for all MySQL extensions)</entry>
426
-
<entry>No</entry>
427
-
<entry>Yes</entry>
428
-
</row>
429
-
<row>
430
404
<entry>Compression protocol support</entry>
431
-
<entry>Yes (5.3.1+)</entry>
405
+
<entry>Yes</entry>
432
406
<entry>Yes</entry>
433
407
</row>
434
408
<row>
435
409
<entry>SSL support</entry>
436
-
<entry>Yes (5.3.3+)</entry>
410
+
<entry>Yes</entry>
437
411
<entry>Yes</entry>
438
412
</row>
439
413
<row>
440
414
<entry>Named pipe support</entry>
441
-
<entry>Yes (5.3.4+)</entry>
415
+
<entry>Yes</entry>
442
416
<entry>Yes</entry>
443
417
</row>
444
418
<row>
...
...
@@ -477,34 +451,9 @@ $ ./configure --with-mysqli=/path/to/mysql_config --with-pdo-mysql=/path/to/mysq
477
451
<entry>Limited</entry>
478
452
</row>
479
453
<row>
480
-
<entry>Read/Write splitting for MySQL Replication</entry>
481
-
<entry>Yes, with plugin</entry>
482
-
<entry>No</entry>
483
-
</row>
484
-
<row>
485
-
<entry>Load Balancing</entry>
486
-
<entry>Yes, with plugin</entry>
487
-
<entry>No</entry>
488
-
</row>
489
-
<row>
490
-
<entry>Fail over</entry>
491
-
<entry>Yes, with plugin</entry>
492
-
<entry>No</entry>
493
-
</row>
494
-
<row>
495
-
<entry>Lazy connections</entry>
496
-
<entry>Yes, with plugin</entry>
497
-
<entry>No</entry>
498
-
</row>
499
-
<row>
500
-
<entry>Query caching</entry>
501
-
<entry>Yes, with plugin</entry>
502
-
<entry>No</entry>
503
-
</row>
504
-
<row>
505
-
<entry>Transparent query manipulations (E.g., auto-EXPLAIN or monitoring)</entry>
506
-
<entry>Yes, with plugin</entry>
454
+
<entry>Automatic reconnect</entry>
507
455
<entry>No</entry>
456
+
<entry>Optional</entry>
508
457
</row>
509
458
</tbody>
510
459
</tgroup>
...
...
@@ -516,12 +465,8 @@ $ ./configure --with-mysqli=/path/to/mysql_config --with-pdo-mysql=/path/to/mysq
516
465
</book>
517
466
518
467
&reference.mysqli.book;
468
+
&reference.mysql-xdevapi.book;
519
469
&reference.mysql.book;
520
470
&reference.mysqlnd.book;
521
-
&reference.mysqlnd-ms.book;
522
-
&reference.mysqlnd-qc.book;
523
-
&reference.mysqlnd-uh.book;
524
-
&reference.mysqlnd-mux.book;
525
-
&reference.mysqlnd-memcache.book;
526
471
527
472
</set>
528
473