mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 08:58:56 +00:00
450 lines
14 KiB
XML
450 lines
14 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
|
|
<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 several PHP APIs
|
|
for accessing the MySQL database. Users can choose between the
|
|
<link linkend="book.mysqli">mysqli</link> or
|
|
<link linkend="ref.pdo-mysql">PDO_MySQL</link> extensions.
|
|
</para>
|
|
<para>
|
|
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 extension, <literal>mysqli</literal>, is
|
|
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 different APIs to connect to MySQL. Below we show
|
|
the APIs provided by the 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 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']);
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<emphasis role="bold">Feature comparison</emphasis>
|
|
</para>
|
|
<para>
|
|
The overall performance of both 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>
|
|
<informaltable xml:id="mysqlinfo.api.choosing.changelog">
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry></entry>
|
|
<entry>ext/mysqli</entry>
|
|
<entry>PDO_MySQL</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>PHP version introduced</entry>
|
|
<entry>5.0</entry>
|
|
<entry>5.1</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Included with PHP 7.x and 8.x</entry>
|
|
<entry>Yes</entry>
|
|
<entry>Yes</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Development status</entry>
|
|
<entry>Active</entry>
|
|
<entry>Active</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Lifecycle</entry>
|
|
<entry>Active</entry>
|
|
<entry>Active</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Recommended for new projects</entry>
|
|
<entry>Yes</entry>
|
|
<entry>Yes</entry>
|
|
</row>
|
|
<row>
|
|
<entry>OOP Interface</entry>
|
|
<entry>Yes</entry>
|
|
<entry>Yes</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Procedural Interface</entry>
|
|
<entry>Yes</entry>
|
|
<entry>No</entry>
|
|
</row>
|
|
<row>
|
|
<entry>API supports non-blocking, asynchronous queries with mysqlnd</entry>
|
|
<entry>Yes</entry>
|
|
<entry>No</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Persistent Connections</entry>
|
|
<entry>Yes</entry>
|
|
<entry>Yes</entry>
|
|
</row>
|
|
<row>
|
|
<entry>API supports Charsets</entry>
|
|
<entry>Yes</entry>
|
|
<entry>Yes</entry>
|
|
</row>
|
|
<row>
|
|
<entry>API supports server-side Prepared Statements</entry>
|
|
<entry>Yes</entry>
|
|
<entry>Yes</entry>
|
|
</row>
|
|
<row>
|
|
<entry>API supports client-side Prepared Statements</entry>
|
|
<entry>No</entry>
|
|
<entry>Yes</entry>
|
|
</row>
|
|
<row>
|
|
<entry>API supports Stored Procedures</entry>
|
|
<entry>Yes</entry>
|
|
<entry>Yes</entry>
|
|
</row>
|
|
<row>
|
|
<entry>API supports Multiple Statements</entry>
|
|
<entry>Yes</entry>
|
|
<entry>Most</entry>
|
|
</row>
|
|
<row>
|
|
<entry>API supports Transactions</entry>
|
|
<entry>Yes</entry>
|
|
<entry>Yes</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Transactions can be controlled with SQL</entry>
|
|
<entry>Yes</entry>
|
|
<entry>Yes</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Supports all MySQL 5.1+ functionality</entry>
|
|
<entry>Yes</entry>
|
|
<entry>Most</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 and PDO_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. 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
|
|
|
|
// Alternatively recommended, compiles with mysqlnd
|
|
$ ./configure --with-mysqli --with-pdo-mysql
|
|
|
|
// Not recommended, compiles with libmysqlclient
|
|
$ ./configure --with-mysqli=/path/to/mysql_config --with-pdo-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 xml:id="mysqlinfo.library.choosing.changelog">
|
|
<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>Compile default (for all MySQL extensions)</entry>
|
|
<entry>Yes</entry>
|
|
<entry>No</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Compression protocol support</entry>
|
|
<entry>Yes</entry>
|
|
<entry>Yes</entry>
|
|
</row>
|
|
<row>
|
|
<entry>SSL support</entry>
|
|
<entry>Yes</entry>
|
|
<entry>Yes</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Named pipe support</entry>
|
|
<entry>Yes</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>Automatic reconnect</entry>
|
|
<entry>No</entry>
|
|
<entry>Optional</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</chapter>
|
|
|
|
&reference.mysqlinfo.concepts;
|
|
|
|
</book>
|
|
|
|
&reference.mysqli.book;
|
|
&reference.mysql-xdevapi.book;
|
|
&reference.mysql.book;
|
|
&reference.mysqlnd.book;
|
|
|
|
</set>
|