overview.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<chapter xml:id="mysqli.overview" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">

  <title>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 mysqli
    extension, and the PDO MySQL driver 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>

  <para>
    <emphasis role="bold">What are the main PHP API offerings for using
    MySQL?</emphasis>
  </para>

  <para>
    There are two main API options when considering connecting to a
    MySQL database server:
  </para>

  <itemizedlist>

    <listitem>
      <para>
        PHP's mysqli Extension
      </para>
    </listitem>

    <listitem>
      <para>
        PHP Data Objects (PDO)
      </para>
    </listitem>

  </itemizedlist>

  <para>
    Each has its own advantages and disadvantages. The following
    discussion aims to give a brief introduction to the key aspects of
    each API.
  </para>

  <para>
    <emphasis role="bold">What is PHP's mysqli Extension?</emphasis>
  </para>

  <para>
    The <literal>mysqli</literal> extension, or as it is sometimes
    known, the MySQL <emphasis>improved</emphasis> extension, was
    developed to take advantage of new features found in MySQL systems
    versions 4.1.3 and newer. The <literal>mysqli</literal> extension is
    included with PHP versions 5 and later.
  </para>

  <para>
    The <literal>mysqli</literal> extension has a number of benefits,
    the key enhancements over the <literal>mysql</literal> extension
    being:

    <itemizedlist>

      <listitem>
        <para>
          Object-oriented interface
        </para>
      </listitem>

      <listitem>
        <para>
          Support for Prepared Statements
        </para>
      </listitem>

      <listitem>
        <para>
          Support for Multiple Statements
        </para>
      </listitem>

      <listitem>
        <para>
          Support for Transactions
        </para>
      </listitem>

      <listitem>
        <para>
          Enhanced debugging capabilities
        </para>
      </listitem>

    </itemizedlist>
  </para>

  <para>
    As well as the object-oriented interface the extension also provides
    a procedural interface.
  </para>

  <para>
    The <literal>mysqli</literal> extension is built using the PHP
    extension framework, its source code is located in the directory
    <filename>ext/mysqli</filename>.
  </para>

  <para>
    For further information on the <literal>mysqli</literal> extension,
    see <xref linkend="book.mysqli"/>.
  </para>

  <para xml:id="mysqli.overview.pdo">
    <emphasis role="bold">What is PDO?</emphasis>
  </para>

  <para>
    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.
  </para>

  <para>
    Other examples of database abstraction layers include JDBC for Java
    applications and DBI for Perl.
  </para>

  <para>
    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.
  </para>

  <para>
    PDO is implemented using the PHP extension framework, its source
    code is located in the directory <filename>ext/pdo</filename>.
  </para>

  <para>
    For further information on PDO, see the
    <xref linkend="book.pdo"/>.
  </para>

  <para>
    <emphasis role="bold">What is the PDO MYSQL driver?</emphasis>
  </para>

  <para>
    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.
  </para>

  <para>
    The PDO MYSQL driver is one of several available PDO drivers. Other
    PDO drivers available include those for the Firebird and PostgreSQL
    database servers.
  </para>

  <para>
    The PDO MYSQL driver is implemented using the PHP extension
    framework. Its source code is located in the directory
    <filename>ext/pdo_mysql</filename>. It does not expose an API to the
    PHP programmer.
  </para>

  <para>
    For further information on the PDO MYSQL driver, see
    <xref linkend="ref.pdo-mysql"/>.
  </para>

  <para xml:id="mysqli.overview.mysqlnd">
    <emphasis role="bold">What is PHP's MySQL Native Driver?</emphasis>
  </para>

  <para>
    In order to communicate with the MySQL database server, <literal>mysqli</literal> 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
    <literal>libmysqlclient</literal>.
  </para>

  <para>
    However, the interface presented by <literal>libmysqlclient</literal> was
    not optimized for communication with PHP applications, as
    <literal>libmysqlclient</literal> was originally designed with C
    applications in mind. For this reason, the MySQL Native Driver,
    <literal>mysqlnd</literal>, was developed as an alternative to
    <literal>libmysqlclient</literal> for PHP applications.
  </para>

  <para>
    Both, the <literal>mysqli</literal> extension and the PDO MySQL driver can
    each be individually configured to use either
    <literal>libmysqlclient</literal> or <literal>mysqlnd</literal>. As
    <literal>mysqlnd</literal> is designed specifically to be utilised
    in the PHP system it has numerous memory and speed enhancements over
    <literal>libmysqlclient</literal>. You are strongly encouraged to take
    advantage of these improvements.
  </para>

  <para>
    The MySQL Native Driver is implemented using the PHP extension
    framework. The source code is located in
    <filename>ext/mysqlnd</filename>. It does not expose an API to the
    PHP programmer.
  </para>

<!-- TODO
  <para>
    For further information on the MySQL Native Driver, see
    <xref linkend="book.mysqlnd"/>.
  </para>
-->

  <para>
    <emphasis role="bold">Comparison of Features</emphasis>
  </para>

  <para>
    The following table compares the functionality of the main
    methods of connecting to MySQL from PHP:
  </para>

  <table xml:id="mysqli.overview.option.comparison">
   <title>Comparison of MySQL API options for PHP</title>
    <tgroup cols="3">
      <colspec colwidth="34*"/>
      <colspec colwidth="33*"/>
      <colspec colwidth="33*"/>
      <thead>
        <row>
          <entry></entry>
          <entry>PHP's mysqli Extension</entry>
          <entry>PDO (Using PDO MySQL Driver and MySQL Native Driver)</entry>
        </row>
      </thead>
      <tbody>
        <row>
          <entry>PHP version introduced</entry>
          <entry>5.0</entry>
          <entry>5.0</entry>
        </row>
        <row>
          <entry>MySQL development status</entry>
          <entry>Active development</entry>
          <entry>Active development</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>Supports all MySQL 4.1+ functionality</entry>
          <entry>Yes</entry>
          <entry>Most</entry>
        </row>
      </tbody>
    </tgroup>
  </table>
<!--
  <para>
    <emphasis role="bold">Further information</emphasis>
  </para>

  <para>
    The PHP distribution and documentation are available from the
    <link xlink:href="&url.php;">PHP Web site</link>.
  </para>
-->
</chapter>