Add PDO driver documentation

Book/index.rst

@@ -11,6 +11,7 @@ PHP 7
     php7/build_system.rst
     php7/internal_types.rst
     php7/extensions_design.rst
+    php7/pdo.rst
     php7/memory_management.rst
     php7/zend_engine.rst
     php7/debugging.rst

Book/php7/pdo.rst

@@ -0,0 +1,25 @@
+PDO Driver How-To
+=================
+
+The purpose of this How-To is to provide a basic understanding of the steps
+required to write a database driver that interfaces with the PDO layer.
+Please note that this is still an evolving API and as such, subject to
+change. This document was prepared based on version 0.3 of PDO.
+The learning curve is steep; expect to spend a lot of time on the
+prerequisites.
+
+Contents:
+
+.. toctree::
+    :maxdepth: 2
+
+    pdo/prerequisites.rst
+    pdo/preparation.rst
+    pdo/implementing.rst
+    pdo/building.rst
+    pdo/testing.rst
+    pdo/packaging.rst
+    pdo/pdo-dbh-t.rst
+    pdo/pdo-stmt-t.rst
+    pdo/constants.rst
+    pdo/error-handling.rst

Book/php7/pdo/building.rst

@@ -0,0 +1,31 @@
+Building
+========
+
+The build process is designed to work with PEAR.
+There are two files that are used to assist in configuring your
+package for building. The first is config.m4 which is the
+``autoconf`` configuration file for all platforms except
+Win32. The second is config.w32 which is a build configuration file for use
+on Win32. Skeleton files for these are built for you when you first set up
+your project. You then need to customize them to fit the needs of your
+project.  Once you've customized your config files, you can build your driver
+using the following sequence of commands:
+
+Before first build:
+
+.. code-block:: bash
+
+    $ sudo pecl install PDO
+
+For each build:
+
+.. code-block:: bash
+
+    $ cd pdo_SKEL
+    $ phpize
+    $ ./configure
+    $ make
+    $ sudo make install
+
+The process can then be repeated as necessary during the development
+process.

Book/php7/pdo/constants.rst

@@ -0,0 +1,77 @@
+Constants
+=========
+
+.. _pdo_attributes:
+
+Database and Statement Attributes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+PDO_ATTR_AUTOCOMMIT
+    BOOL
+
+    TRUE if autocommit is set, FALSE otherwise.
+
+    ``dbh->auto_commit`` contains value. Processed by PDO directly.
+
+PDO_ATTR_PREFETCH
+    LONG
+
+    Value of the prefetch size in drivers that support it.
+
+PDO_ATTR_TIMEOUT
+    LONG
+
+    How long to wait for a db operation before timing out.
+
+PDO_ATTR_ERRMODE
+    LONG
+
+    Processed and handled by PDO
+
+PDO_ATTR_SERVER_VERSION
+    STRING
+
+    The "human-readable" string representing the
+    Server/Version this driver is currently connected to.
+
+PDO_ATTR_CLIENT_VERSION
+    STRING
+
+    The "human-readable" string representing the Client/Version this driver supports.
+
+PDO_ATTR_SERVER_INFO
+    STRING
+
+    The "human-readable" description of the Server.
+
+PDO_ATTR_CONNECTION_STATUS
+    LONG
+
+    Values not yet defined
+
+PDO_ATTR_CASE
+    LONG
+
+    Processed and handled by PDO.
+
+PDO_ATTR_CURSOR_NAME
+    STRING
+
+    String representing the name for a database cursor for use in
+    "where current in <name>" SQL statements.
+
+PDO_ATTR_CURSOR
+    LONG
+
+    PDO_CURSOR_FWDONLY
+        Forward only cursor
+    PDO_CURSOR_SCROLL
+        Scrollable cursor
+
+The values for the attributes above are all defined in terms of the Zend
+API. The Zend API contains macros that can be used to convert a ``*zval`` to a
+value. These macros are defined in the Zend header file, zend_API.h in the
+Zend directory of your PHP build directory. Some of these attributes can be
+used with the statement attribute handlers such as the PDO_ATTR_CURSOR and
+PDO_ATTR_CURSOR_NAME. See the statement attribute handling functions for
+more information.

Book/php7/pdo/error-handling.rst

@@ -0,0 +1,39 @@
+.. _pdo_error_handling:
+
+Error handling
+==============
+
+Error handling is implemented using a hand-shaking protocol between 
+PDO and the database driver code. The database driver code
+signals PDO that an error has occurred via a failure
+(``0``) return from any of the interface functions. If a zero
+is returned, set the field ``error_code`` in the control
+block appropriate to the context (either the pdo_dbh_t or pdo_stmt_t block).
+In practice, it is probably a good idea to set the field in both blocks to
+the same value to ensure the correct one is getting used.
+
+The error_mode field is a six-byte field containing a 5 character ASCIIZ
+SQLSTATE identifier code. This code drives the error message process. The
+SQLSTATE code is used to look up an error message in the internal PDO error
+message table (see pdo_sqlstate.c for a list of error codes and their
+messages). If the code is not known to PDO, a default
+"Unknown Message" value will be used.
+
+In addition to the SQLSTATE code and error message, PDO will
+call the driver-specific fetch_err() routine to obtain supplemental data
+for the particular error condition. This routine is passed an array into
+which the driver may place additional information. This array has slot
+positions assigned to particular types of supplemental info:
+
+#.  A native error code. This will frequently be an error code obtained
+    from the database API.
+
+#.  A descriptive string. This string can contain any additional
+    information related to the failure. Database drivers typically include
+    information such as an error message, code location of the failure, and
+    any additional descriptive information the driver developer feels
+    worthy of inclusion. It is generally a good idea to include all
+    diagnostic information obtainable
+    from the database interface at the time of the failure. For
+    driver-detected errors (such as memory allocation problems), the driver
+    developer can define whatever error information that seems appropriate.