diff --git a/reference/mysqli/book.xml b/reference/mysqli/book.xml
index ec8dd7660b..f634f3f508 100644
--- a/reference/mysqli/book.xml
+++ b/reference/mysqli/book.xml
@@ -1,40 +1,60 @@
-
+
-
+
MySQL Improved Extension
+
Mysqli
-
-
+
+
+
&reftitle.intro;
- The mysqli extension allows you to access the functionality provided by
- MySQL 4.1 and above. More information about the MySQL Database server
- can be found at &url.mysql;
+ The mysqli extension allows you to access the
+ functionality provided by MySQL 4.1 and above. More information about
+ the MySQL Database server can be found at
+ &url.mysql;
+
- Documentation for MySQL can be found at
+
+
+
+ Documentation for MySQL can be found at
+ &url.mysql.docs;.
+
- Parts of this documentation included from MySQL manual with permissions of MySQL AB.
+ Parts of this documentation included from MySQL manual with
+ permissions of MySQL AB.
+
Examples
+
- All Examples in the MySQLI documentation use the world database from MySQL AB.
- The world database can be found at &url.mysql.example;
+ All Examples in the MySQLI documentation use the world database from
+ MySQL AB. The world database can be found at
+ &url.mysql.example;
+
+
-
+
+
+ &reference.mysqli.overview;
&reference.mysqli.setup;
&reference.mysqli.constants;
+ &reference.mysqli.summary;
&reference.mysqli.mysqli;
&reference.mysqli.mysqli-stmt;
&reference.mysqli.mysqli-result;
@@ -42,7 +62,6 @@
&reference.mysqli.reference;
-
-
diff --git a/reference/mysqli/overview.xml b/reference/mysqli/overview.xml
new file mode 100644
index 0000000000..95b84bb9c1
--- /dev/null
+++ b/reference/mysqli/overview.xml
@@ -0,0 +1,498 @@
+
+
+
+
+ Overview
+
+
+ This section provides an introduction to the options available to
+ you when developing a PHP application that needs to interact with a
+ MySQL database.
+
+
+
+ What is an API?
+
+
+
+ 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.
+
+
+
+ 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 organised code.
+
+
+
+ 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.
+
+
+
+ What is a Connector?
+
+
+
+ In the MySQL documentation, the term connector
+ 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.
+
+
+
+ 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 connect to a database server.
+
+
+
+ What is a Driver?
+
+
+
+ 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.
+
+
+
+ By way of an example, the PHP
+ Data Objects (PDO) 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.
+
+
+
+ Sometimes people use the terms connector and driver interchangeably,
+ this can be confusing. In the MySQL-related documentation the term
+ driver is reserved for software that provides
+ the database-specific part of a connector package.
+
+
+
+ What is an Extension?
+
+
+
+ In the PHP documentation you will come across another term -
+ extension. The PHP code consists of a core,
+ with optional extensions to the core functionality. PHP's
+ MySQL-related extensions, such as the mysqli
+ extension, and the mysql extension, are
+ implemented using the PHP extension framework.
+
+
+
+ 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.
+
+
+
+ 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.
+
+
+
+ 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.
+
+
+
+ What are the main PHP API offerings for using
+ MySQL?
+
+
+
+ There are three main API options when considering connecting to a
+ MySQL database server:
+
+
+
+
+
+
+ PHP's MySQL Extension
+
+
+
+
+
+ PHP's mysqli Extension
+
+
+
+
+
+ PHP Data Objects (PDO)
+
+
+
+
+
+
+ Each has its own advantages and disadvantages. The following
+ discussion aims to give a brief introduction to the key aspects of
+ each API.
+
+
+
+ What is PHP's MySQL Extension?
+
+
+
+ This is the original extension designed to allow you to develop PHP
+ applications that interact with a MySQL database. The
+ mysql extension provides a procedural interface
+ and is intended for use only with MySQL versions older than 4.1.3.
+ This extension can be used with versions of MySQL 4.1.3 or newer,
+ but not all of the latest MySQL server features will be available.
+
+
+
+
+ If you are using MySQL versions 4.1.3 or later it is
+ strongly recommended that you use the
+ mysqli extension instead.
+
+
+
+
+ The mysql extension source code is located in the
+ PHP extension directory ext/mysql.
+
+
+
+ For further information on the mysql extension,
+ see .
+
+
+
+ What is PHP's mysqli Extension?
+
+
+
+ The mysqli extension, or as it is sometimes
+ known, the MySQL improved extension, was
+ developed to take advantage of new features found in MySQL systems
+ versions 4.1.3 and newer. The mysqli extension is
+ included with PHP versions 5 and later.
+
+
+
+ The mysqli extension has a number of benefits,
+ the key enhancements over the mysql extension
+ being:
+
+
+
+
+
+ Object-oriented interface
+
+
+
+
+
+ Support for Prepared Statements
+
+
+
+
+
+ Support for Multiple Statements
+
+
+
+
+
+ Support for Transactions
+
+
+
+
+
+ Enhanced debugging capabilities
+
+
+
+
+
+ Embedded server support
+
+
+
+
+
+
+
+
+ If you are using MySQL versions 4.1.3 or later it is
+ strongly recommended that you use this
+ extension.
+
+
+
+
+ As well as the object-oriented interface the extension also provides
+ a procedural interface.
+
+
+
+ The mysqli extension is built using the PHP
+ extension frameowrk, its source code is located in the directory
+ ext/mysqli.
+
+
+
+ For further information on the mysqli extension,
+ see .
+
+
+
+ What is PDO?
+
+
+
+ PHP Data Objects, or PDO, is a database abstraction layer
+ specifically for PHP applications. PDO provides a consistent API for
+ your PHP application regardless of the type of database server your
+ application will connect to. In theory, if you are using the PDO
+ API, you could switch the database server you used, from say
+ Firebird to MySQL, and only need to make minor changes to your PHP
+ code.
+
+
+
+ Other examples of database abstraction layers include JDBC for Java
+ applications and DBI for Perl.
+
+
+
+ While PDO has its advantages, such as a clean, simple, portable API,
+ its main disadvantage is that it doesn't allow you to use all of the
+ advanced features that are available in the latest versions of MySQL
+ server. For example, PDO does not allow you to use MySQL's support
+ for Multiple Statements.
+
+
+
+ PDO is implemented using the PHP extension framework, its source
+ code is located in the directory ext/pdo.
+
+
+
+ For further information on PDO, see the
+ .
+
+
+
+ What is the PDO MYSQL driver?
+
+
+
+ The PDO MYSQL driver is not an API as such, at least from the PHP
+ programmer's perspective. In fact the PDO MYSQL driver sits in the
+ layer below PDO itself and provides MySQL-specific functionality.
+ The programmer still calls the PDO API, but PDO uses the PDO MYSQL
+ driver to carry out communication with the MySQL server.
+
+
+
+ The PDO MYSQL driver is one of several available PDO drivers. Other
+ PDO drivers available include those for the Firebird and PostgreSQL
+ database servers.
+
+
+
+ The PDO MYSQL driver is implemented using the PHP extension
+ framework. Its source code is located in the directory
+ ext/pdo_mysql. It does not expose an API to the
+ PHP programmer.
+
+
+
+ For further information on the PDO MYSQL driver, see
+ .
+
+
+
+ What is PHP's MySQL Native Driver?
+
+
+
+ In order to communicate with the MySQL database server the
+ mysql extension, mysqli and
+ the PDO MYSQL driver each use a low-level library that implements
+ the required protocol. In the past, the only available library was
+ the MySQL Client Library, otherwise known as
+ libmysql.
+
+
+
+ However, the interface presented by libmysql was
+ not optimized for communication with PHP applications, as
+ libmysql was originally designed with C
+ applications in mind. For this reason the MySQL Native Driver,
+ mysqlnd, was developed as an alternative to
+ libmysql for PHP applications.
+
+
+
+ The mysql extension, the
+ mysqli extension and the PDO MySQL driver can
+ each be individually configured to use either
+ libmysql or mysqlnd. As
+ mysqlnd is designed specifically to be utilised
+ in the PHP system it has numerous memory and speed enhancements over
+ libmysql. You are strongly encouraged to take
+ advantage of these improvements.
+
+
+
+
+ The MySQL Native Driver can only be used with MySQL server
+ versions 4.1.3 and later.
+
+
+
+
+ The MySQL Native Driver is implemented using the PHP extension
+ framework. The source code is located in
+ ext/mysqlnd. It does not expose an API to the
+ PHP programmer.
+
+
+
+
+
+ Comparison of Features
+
+
+
+ The following table compares the functionality of the three main
+ methods of connecting to MySQL from PHP:
+
+
+
+
+
+
+
+
+
+
+
+ PHP's mysqli Extension
+ PDO (Using PDO MySQL Driver and MySQL Native Driver)
+ PHP's MySQL Extension
+
+
+
+
+ PHP version introduced
+ 5.0
+ 5.0
+ Prior to 3.0
+
+
+ Included with PHP 5.x
+ yes
+ yes
+ Yes
+
+
+ Comes with PHP 6.0
+ Yes
+ Yes
+ Yes
+
+
+ MySQL development status
+ Active development
+ Active development as of PHP 5.3
+ Maintenance only
+
+
+ Recommended by MySQL for new projects
+ Yes - preferred option
+ Yes
+ No
+
+
+ API supports Charsets
+ Yes
+ Yes
+ No
+
+
+ API supports server-side Prepared Statements
+ Yes
+ Yes
+ No
+
+
+ API supports client-side Prepared Statements
+ No
+ Yes
+ No
+
+
+ API supports Stored Procedures
+ Yes
+ Yes
+ No
+
+
+ API supports Multiple Statements
+ Yes
+ Most
+ No
+
+
+ Supports all MySQL 4.1+ functionality
+ Yes
+ Most
+ No
+
+
+
+
+
+
+ Further information
+
+
+
+