php-src/ext/pdo/specs/overview.xml

<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

<chapter id="overview">
  <title>Overview</title>

<para>
  PDO is structured as depicted below; a core PDO module provides a framework
  for loading driver extensions and calling into them, similar in some ways to
  ODBC, although PDO is a very lightweight bridge when compared to ODBC.  The
  core module is responsible for managing the user-space portions of the the
  PHP/Database interaction, delegating the database/vendor specific portions to
  the appropriate driver extension module.  It is typical for a driver
  extension to delegate, in turn, to a pre-existing database client library to
  carry out its duties.
</para>

<para>
<screen>
+---------------------------------------------+
|                  PDO Core                   |
+---------------------------------------------+
+--------------------+   +--------------------+
|PDO Driver Extension|   |PDO Driver Extension|
+--------------------+   +--------------------+
+--------------------+   +--------------------+
| DB Client Library  |   | DB Client Library  |
+--------------------+   +--------------------+
</screen>
</para>

<section id="overview.design">
  <title>Design Principles</title>

<para>
  PDO was built around the ideal of being able to provide a common data access
  paradigm across a variety of data providers.  The goal was to provide the
  lowest common denominator of features using a common API, while still
  being able to provide access to database/vendor specific features.
  There are some important behavior traits in PDO; most are general behaviors
  that most drivers exhibit; some deviation is allowed if it the net effect of
  the deviation is not a big problem (for instance, type juggling).  There are
  a couple of hard rules that must be adhered to for conformance, however.
</para>

<section id="overview.design.connection">
<title>Connection Management</title>

<para>
  While an instance of the PDO class exists, it represents an open connection
  to the database.
</para>
</section>

<section id="overview.design.typing">
<title>Data typing</title>

<para>
  As a "typeless" environment, PHP doesn't mind whether data is returned as
  integer, floating point or string; it can convert to the appropriate type as
  needed.  This conversion process may cause loss in data fidelity in some
  cases, in particular when it comes to floating point numbers.  The type of
  choice for PDO when binding or requesting data is to use the string type, as
  this has the best data fidelity.
</para>
<para>
  Note that some database client library implementations don't provide the
  application with a means to specify their preferred data type, returning it
  in their own perception of the best native data type.  For those drivers it
  would typically be wasted effort to convert to a string in the PDO driver
  layer, so the native type is passed up and returned to the script in that
  form.
</para>
<para>
  The net result of this is that data is usually, but not always, returned as
  strings unless otherwise specified by the PHP script.
</para>

</section>

<section id="overview.design.xact">
<title>Transaction Support</title>

<para>
  Many, but not all, database implementations support the notion of
  transactions.  The transaction reflects a block of database operations
  that can be either committed or rolled back.  Some database implementations
  support nesting transactions, or transactions across multiple connection
  handles.  Most databases that support transactions start out in a mode known
  as "auto-commit", which emulates non-transactional behavior.
</para>

<para>
  PDO, as an abstraction layer, is responsible for making sure that the
  behavior of two freshly opened connections to different databases don't
  exhibit drastically different behavior.  The principle of least surprise is
  particularly important when it comes to transactions, so PDO requires that
  its driver extensions observe the following rules, since an application that
  assumes that transactions are available when they are not could proceed and
  cause damage to the data in the database when it attempts to rollback its
  changes.
</para>

<para>
  Freshly created connections must start in auto-commit mode.  This allows
  non-transactional scripts to operate without having to do anything special
  to get auto-commit enabled.
</para>

<para>
  Attempting to use transactions when the underlying database doesn't support
  them must return an error to the PDO core layer.  PDO itself will generate a
  runtime exception which will cause the script to terminate unless handled by
  the script.  Note that PDO will not normally generate exceptions unless
  explicitly told to do so by the script.  Forcing an exception in this case
  helps to reinforce that something is seriously wrong.
</para>

<para>
  PDO only supports the notion of being in a transaction or not.  It does not
  support nested transactions, it is an error to start a new transaction while
  a transaction is active.
</para>

<para>
  Ad-hoc SQL executed by the script that affects the transactional state of
  the connection as seen by the database is allowed, but its effect on the
  PDO-core notion of the transactional state is undefined.  A driver must not
  attempt to reconcile the effect of ad-hoc SQL with the PDO-core
  transactional state.
</para>

</section>

<section id="overview.design.err">
<title>Error Handling</title>

<para>
  The behavior of PDO in the face of errors varies based on application
  preference.  The default is to silently return error codes back to the
  script, but also allows the option of emitting a warning in addition to
  returning the error code, or to throw an exception object containing the
  error state.
</para>

<para>
  In the interests of portability and fidelity of information, PDO requires
  its drivers to record the ANSI SQL 92 SQLSTATE error code along with their
  native and human readable error codes when an error is encountered.  This
  allows portable scripts the ability to use vendor-independent error handling
  logic as well as the freedom to also use vendor-dependent logic if required.
</para>

</section>

</section>
</chapter>

<!--
vim:ts=2:sw=2:et:fileencoding=utf-8:encoding=utf-8:
-->