1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
|
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 329924 $ -->
<set xml:id="set.mysqlinfo">
<title>MySQL Drivers and Plugins</title>
<titleabbrev>MySQL</titleabbrev>
<info xml:id="mysqlinfo.info">
<abstract>
<para>
PHP offers several MySQL drivers and plugins for accessing and
handling MySQL.
</para>
<para>
The differences and functionality of the MySQL extensions are described
within the overview of this section.
</para>
</abstract>
</info>
<book xml:id="mysql">
<title>Overview of the MySQL PHP drivers</title>
<info xml:id="mysqlinfo.intro">
<title>Introduction</title>
<abstract>
<para>
There are three PHP APIs for accessing the MySQL database. This guide
explains the <link linkend="mysqlinfo.terminology">terminology</link>
used to describe each API, information about
<link linkend="mysqlinfo.api.choosing">choosing which API</link> to
use, and also information to help choose which MySQL
<link linkend="mysqlinfo.library.choosing">library to use</link> with
the API.
</para>
</abstract>
</info>
<chapter xml:id="mysqlinfo.terminology" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Terminology overview</title>
<para>
This section provides an introduction to the options available to
you when developing a PHP application that needs to interact with a
MySQL database.
</para>
<para>
<emphasis role="bold">What is an API?</emphasis>
</para>
<para>
An Application Programming Interface, or API, defines the classes,
methods, functions and variables that your application will need to
call in order to carry out its desired task. In the case of PHP
applications that need to communicate with databases the necessary
APIs are usually exposed via PHP extensions.
</para>
<para>
APIs can be procedural or object-oriented. With a procedural API you
call functions to carry out tasks, with the object-oriented API you
instantiate classes and then call methods on the resulting objects.
Of the two the latter is usually the preferred interface, as it is
more modern and leads to better organized code.
</para>
<para>
When writing PHP applications that need to connect to the MySQL
server there are several API options available. This document
discusses what is available and how to select the best solution for
your application.
</para>
<para>
<emphasis role="bold">What is a Connector?</emphasis>
</para>
<para>
In the MySQL documentation, the term <emphasis>connector</emphasis>
refers to a piece of software that allows your application to
connect to the MySQL database server. MySQL provides connectors for
a variety of languages, including PHP.
</para>
<para>
If your PHP application needs to communicate with a database server
you will need to write PHP code to perform such activities as
connecting to the database server, querying the database and other
database-related functions. Software is required to provide the API
that your PHP application will use, and also handle the
communication between your application and the database server,
possibly using other intermediate libraries where necessary. This
software is known generically as a connector, as it allows your
application to <emphasis>connect</emphasis> to a database server.
</para>
<para>
<emphasis role="bold">What is a Driver?</emphasis>
</para>
<para>
A driver is a piece of software designed to communicate with a
specific type of database server. The driver may also call a
library, such as the MySQL Client Library or the MySQL Native
Driver. These libraries implement the low-level protocol used to
communicate with the MySQL database server.
</para>
<para>
By way of an example, the <link linkend="mysqli.overview.pdo">PHP
Data Objects (PDO)</link> database abstraction layer may use one of
several database-specific drivers. One of the drivers it has
available is the PDO MYSQL driver, which allows it to interface with
the MySQL server.
</para>
<para>
Sometimes people use the terms connector and driver interchangeably,
this can be confusing. In the MySQL-related documentation the term
<quote>driver</quote> is reserved for software that provides
the database-specific part of a connector package.
</para>
<para>
<emphasis role="bold">What is an Extension?</emphasis>
</para>
<para>
In the PHP documentation you will come across another term -
<emphasis>extension</emphasis>. The PHP code consists of a core,
with optional extensions to the core functionality. PHP's
MySQL-related extensions, such as the <literal>mysqli</literal>
extension, and the <literal>mysql</literal> extension, are
implemented using the PHP extension framework.
</para>
<para>
An extension typically exposes an API to the PHP programmer, to
allow its facilities to be used programmatically. However, some
extensions which use the PHP extension framework do not expose an
API to the PHP programmer.
</para>
<para>
The PDO MySQL driver extension, for example, does not expose an API
to the PHP programmer, but provides an interface to the PDO layer
above it.
</para>
<para>
The terms API and extension should not be taken to mean the same
thing, as an extension may not necessarily expose an API to the
programmer.
</para>
</chapter>
<chapter xml:id="mysqlinfo.api.choosing" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Choosing an API</title>
<para>
PHP offers three different APIs to connect to MySQL. Below we show
the APIs provided by the mysql, mysqli, and PDO extensions. Each code snippet
creates a connection to a MySQL server running on "example.com" using
the username "user" and the password "password". And a query is run to
greet the user.
</para>
<para>
<example>
<title>Comparing the three MySQL APIs</title>
<programlisting role="php">
<![CDATA[
<?php
// mysqli
$mysqli = new mysqli("example.com", "user", "password", "database");
$result = $mysqli->query("SELECT 'Hello, dear MySQL user!' AS _message FROM DUAL");
$row = $result->fetch_assoc();
echo htmlentities($row['_message']);
// PDO
$pdo = new PDO('mysql:host=example.com;dbname=database', 'user', 'password');
$statement = $pdo->query("SELECT 'Hello, dear MySQL user!' AS _message FROM DUAL");
$row = $statement->fetch(PDO::FETCH_ASSOC);
echo htmlentities($row['_message']);
// mysql
$c = mysql_connect("example.com", "user", "password");
mysql_select_db("database");
$result = mysql_query("SELECT 'Hello, dear MySQL user!' AS _message FROM DUAL");
$row = mysql_fetch_assoc($result);
echo htmlentities($row['_message']);
?>
]]>
</programlisting>
</example>
</para>
<para>
<emphasis role="bold">Recommended API</emphasis>
</para>
<para>
It is recommended to use either the <link linkend="book.mysqli">mysqli</link>
or <link linkend="ref.pdo-mysql">PDO_MySQL</link> extensions.
It is not recommended to use the old <link linkend="ref.mysql">mysql</link>
extension for new development, as it has been deprecated as of PHP 5.5.0
and will be removed in the future. A detailed feature comparison matrix is
provided below. The overall performance of all three extensions is
considered to be about the same. Although the performance of the extension
contributes only a fraction of the total run time of a PHP web request.
Often, the impact is as low as 0.1%.
</para>
<para>
<emphasis role="bold">Feature comparison</emphasis>
</para>
<informaltable>
<tgroup cols="4">
<thead>
<row>
<entry></entry>
<entry>ext/mysqli</entry>
<entry>PDO_MySQL</entry>
<entry>ext/mysql</entry>
</row>
</thead>
<tbody>
<row>
<entry>PHP version introduced</entry>
<entry>5.0</entry>
<entry>5.1</entry>
<entry>2.0</entry>
</row>
<row>
<entry>Included with PHP 5.x</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Development status</entry>
<entry>Active</entry>
<entry>Active</entry>
<entry>Maintenance only</entry>
</row>
<row>
<entry>Lifecycle</entry>
<entry>Active</entry>
<entry>Active</entry>
<entry>Deprecated</entry>
</row>
<row>
<entry>Recommended for new projects</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>No</entry>
</row>
<row>
<entry>OOP Interface</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>No</entry>
</row>
<row>
<entry>Procedural Interface</entry>
<entry>Yes</entry>
<entry>No</entry>
<entry>Yes</entry>
</row>
<row>
<entry>API supports non-blocking, asynchronous queries with mysqlnd</entry>
<entry>Yes</entry>
<entry>No</entry>
<entry>No</entry>
</row>
<row>
<entry>Persistent Connections</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
<row>
<entry>API supports Charsets</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
<row>
<entry>API supports server-side Prepared Statements</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>No</entry>
</row>
<row>
<entry>API supports client-side Prepared Statements</entry>
<entry>No</entry>
<entry>Yes</entry>
<entry>No</entry>
</row>
<row>
<entry>API supports Stored Procedures</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>No</entry>
</row>
<row>
<entry>API supports Multiple Statements</entry>
<entry>Yes</entry>
<entry>Most</entry>
<entry>No</entry>
</row>
<row>
<entry>API supports Transactions</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>No</entry>
</row>
<row>
<entry>Transactions can be controlled with SQL</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Supports all MySQL 5.1+ functionality</entry>
<entry>Yes</entry>
<entry>Most</entry>
<entry>No</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</chapter>
<chapter xml:id="mysqlinfo.library.choosing" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Choosing a library</title>
<para>
The mysqli, PDO_MySQL and mysql PHP extensions are lightweight wrappers on
top of a C client library. The extensions can either use the
<link linkend="book.mysqlnd">mysqlnd</link> library or the <literal>libmysqlclient</literal>
library. Choosing a library is a compile time decision.
</para>
<para>
The mysqlnd library is part of the PHP distribution since 5.3.0. It offers
features like lazy connections and query caching, features that are not available
with libmysqlclient, so using the built-in mysqlnd library is highly recommended.
See the <link linkend="book.mysqlnd">mysqlnd documentation</link> for
additional details, and a listing of features and functionality that it offers.
</para>
<para>
<example>
<title>Configure commands for using mysqlnd or libmysqlclient</title>
<programlisting role="shell">
<![CDATA[
// Recommended, compiles with mysqlnd
$ ./configure --with-mysqli=mysqlnd --with-pdo-mysql=mysqlnd --with-mysql=mysqlnd
// Not recommended, compiles with libmysqlclient
$ ./configure --with-mysqli=/path/to/mysql_config --with-pdo-mysql=/path/to/mysql_config --with-mysql=/path/to/mysql_config
]]>
</programlisting>
</example>
</para>
<para>
<emphasis role="bold">Library feature comparison</emphasis>
</para>
<para>
It is recommended to use the <link linkend="book.mysqlnd">mysqlnd</link>
library instead of the MySQL Client Server library (libmysqlclient). Both
libraries are supported and constantly being improved.
</para>
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry></entry>
<entry>MySQL native driver (<link linkend="book.mysqlnd">mysqlnd</link>)</entry>
<entry>MySQL client server library (<literal>libmysqlclient</literal>)</entry>
</row>
</thead>
<tbody>
<row>
<entry>Part of the PHP distribution</entry>
<entry>Yes</entry>
<entry>No</entry>
</row>
<row>
<entry>PHP version introduced</entry>
<entry>5.3.0</entry>
<entry>N/A</entry>
</row>
<row>
<entry>License</entry>
<entry>PHP License 3.01</entry>
<entry>Dual-License</entry>
</row>
<row>
<entry>Development status</entry>
<entry>Active</entry>
<entry>Active</entry>
</row>
<row>
<entry>Lifecycle</entry>
<entry>No end announced</entry>
<entry>No end announced</entry>
</row>
<row>
<entry>PHP 5.4 compile default (for all MySQL extensions)</entry>
<entry>Yes</entry>
<entry>No</entry>
</row>
<row>
<entry>PHP 5.3 compile default (for all MySQL extensions)</entry>
<entry>No</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Compression protocol support</entry>
<entry>Yes (5.3.1+)</entry>
<entry>Yes</entry>
</row>
<row>
<entry>SSL support</entry>
<entry>Yes (5.3.3+)</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Named pipe support</entry>
<entry>Yes (5.3.4+)</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Non-blocking, asynchronous queries</entry>
<entry>Yes</entry>
<entry>No</entry>
</row>
<row>
<entry>Performance statistics</entry>
<entry>Yes</entry>
<entry>No</entry>
</row>
<row>
<entry>LOAD LOCAL INFILE respects the <link linkend="ini.open-basedir">open_basedir directive</link></entry>
<entry>Yes</entry>
<entry>No</entry>
</row>
<row>
<entry>Uses PHP's native memory management system (e.g., follows PHP memory limits)</entry>
<entry>Yes</entry>
<entry>No</entry>
</row>
<row>
<entry>Return numeric column as double (COM_QUERY)</entry>
<entry>Yes</entry>
<entry>No</entry>
</row>
<row>
<entry>Return numeric column as string (COM_QUERY)</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Plugin API</entry>
<entry>Yes</entry>
<entry>Limited</entry>
</row>
<row>
<entry>Read/Write splitting for MySQL Replication</entry>
<entry>Yes, with plugin</entry>
<entry>No</entry>
</row>
<row>
<entry>Load Balancing</entry>
<entry>Yes, with plugin</entry>
<entry>No</entry>
</row>
<row>
<entry>Fail over</entry>
<entry>Yes, with plugin</entry>
<entry>No</entry>
</row>
<row>
<entry>Lazy connections</entry>
<entry>Yes, with plugin</entry>
<entry>No</entry>
</row>
<row>
<entry>Query caching</entry>
<entry>Yes, with plugin</entry>
<entry>No</entry>
</row>
<row>
<entry>Transparent query manipulations (E.g., auto-EXPLAIN or monitoring)</entry>
<entry>Yes, with plugin</entry>
<entry>No</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</chapter>
&reference.mysqlinfo.concepts;
</book>
&reference.mysql.book;
&reference.mysqli.book;
&reference.mysqlnd.book;
&reference.mysqlnd-ms.book;
&reference.mysqlnd-qc.book;
&reference.mysqlnd-uh.book;
&reference.mysqlnd-mux.book;
&reference.mysqlnd-memcache.book;
</set>
|
