PDO Specification

While an instance of the PDO class exists, it represents an open connection to the database.

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.

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.

The net result of this is that data is usually, but not always, returned as strings unless otherwise specified by the PHP script.

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.

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.

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.

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.

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.

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.

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.

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.

The PDO core initializes various pieces of a pdo_dbh_t (we'll refer to it as dbh from now on). The portions of the structure that are relevant as inputs to the factory method are:

struct _pdo_dbh_t {
/* credentials */
char *username, *password;
/* data source string used to open this handle */
const char *data_source;
unsigned long data_source_len;

/* if true, then data stored and pointed at by this handle must all be
 * persistently allocated */
unsigned is_persistent:1;

/* if true, driver should act as though a COMMIT were executed between
 * each executed statement; otherwise, COMMIT must be carried out manually
 * */
unsigned auto_commit:1;
};

In addition to the dbh, the factory method is also passed a PHP zval pointer that may be NULL. If it is not NULL, it will reference a PHP array type keyed by integer attribute identifiers. The driver should use pdo_attr_lval and/or pdo_attr_strval to determine if any parameters that affect how it will establish the connection are present.

The PDO core will iterate all the options and inform the driver of them immediately after the connection has been successfully established, so the factory method should only process those parameters that are needed to establish the connection.

The primary purpose of the factory method is to establish a connection to a data source. It must also set certain fields of the dbh so that the PDO core knows how best to interact with it.

The portions of the dbh that are relevant as outputs of the factory method are:

struct _pdo_dbh_t {
  /* driver specific methods */
  struct pdo_dbh_methods *methods;
  /* driver specific data */
  void *driver_data;
  /* if true, the driver requires that memory be allocated explicitly for
   * the columns that are returned */
  unsigned alloc_own_columns:1;
  /* max length a single character can become after correct quoting */
  unsigned max_escaped_char_length:3;
};

On success, the methods and driver_data fields of dbh must be set to non-NULL values. The other fields described above should be set as appropriate. The factory method must return 1 to indicate success.

On failure, the methods field of dbh must be set to a non-NULL value, The other fields described above may have been modified by the driver. The PDO core will free all resources by calling the closer method provided by the driver. The driver must trigger an exception and return 0 to indicate failure.

The connection failure case might look something like this:

zend_throw_exception_ex(php_pdo_get_exception(), 0 TSRMLS_CC,
  "SQLSTATE[%s] connection failed", sqlstate);
return 0;

When a driver encounters an error, it must update the error_code field of the dbh to hold an appropriate SQLSTATE error code, and take some action to record the driver specific error code and human readable message, if necessary.

The method descriptions below describe how to indicate an error status. The PDO core may invoke the SKEL_fetch_error_func to obtain the driver specific error code and human readable message.

The driver should not unilaterally raise an exception in reponse to an error. Instead, it should be left to the PDO core to handle reporting the error to the script, based on the application preferences for error handling.

int SKEL_close_func(pdo_dbh_t *dbh TSRMLS_DC);

This function is called by the PDO core when freeing resources associated with the dbh. It should release any resources allocated by the driver.

Returns 0. An implementation bug means that the return value is not checked.

int SKEL_prepare_func(pdo_dbh_t *dbh, const char *sql,
      long sql_len, pdo_stmt_t *stmt, zval *driver_options TSRMLS_DC);

This function is called when creating a statement handle. It is described in more detail in Section 2.4, “Preparing Statements”.

Returns 1 on success, 0 on failure.

int SKEL_do_func(pdo_dbh_t *dbh, const char *sql,
      long sql_len TSRMLS_DC);

Execute a statement that does not return a result set.

Returns -1 on failure, or the number of affected rows otherwise.

int SKEL_quote_func(pdo_dbh_t *dbh, const char *unquoted,
      int unquoted_len, char **quoted, int *quotedlen,
      enum pdo_param_type paramtype TSRMLS_DC);

Quote a parameter, escaping SQL meta-characters as appropriate and enclosing the parameter in appropriate quotation marks. This function will allocate an appropriately sized buffer using emalloc and return it to the caller by setting quoted and quotedlen to the buffer and its length.

The return value should be 1 if the function generated a quoted string, or 0 otherwise.

int SKEL_begin_func(pdo_dbh_t *dbh TSRMLS_DC);

This function begins a transaction on the connection. If the driver does not support transactions, it should not provide this method.

Returns 1 to indicate that a new transaction has begun, 0 to indicate error. The PDO core maintains its own idea of whether a transaction is in progress, so the driver should not maintain its own.

int SKEL_commit_func(pdo_dbh_t *dbh TSRMLS_DC);

This function commits a transaction on the connection. If the driver does not support transactions, it should not provide this method.

Returns 1 to indicate that the transaction was committed, 0 otherwise. Once committed, PDO assumes that a transaction is no longer active.

int SKEL_rollback_func(pdo_dbh_t *dbh TSRMLS_DC);

This function rolls back a transaction on the connection. If the driver does not support transactions, it should not provide this method.

Returns 1 to indicate a successful rollback, 0 otherwise. Once rolled back, PDO assumes that a transaction is no longer active.

int SKEL_set_attr_func(pdo_dbh_t *dbh, long attr, zval *val TSRMLS_DC);

Sets an attribute on the database handle. Returns 1 if the attribute was set successfully, 0 otherwise. There are a number of attributes that can be set, and these are discussed in ???.

char *SKEL_last_id_func(pdo_dbh_t *dbh, const char *name,
      unsigned int *len TSRMLS_DC);

Returns the last insert id. A NULL return value indicates an error condition, otherwise the return value must be a NUL terminated string allocated using emalloc.

int SKEL_fetch_error_func(pdo_dbh_t *dbh, pdo_stmt *stmt,
      zval *info TSRMLS_DC);

Fetch error information. If stmt is not NULL, fetch information pertaining to the statement, otherwise fetch the connection level error information. The driver should add the following information to the array "info" in this order: a) the native error code and b) a string representation of the error code.

A driver may optionally append any other arbitrary, useful, information to the info array.

Returns 1 to indicate that it populated info, 0 otherwise.

int SKEL_get_attr_func(pdo_dbh_t *dbh, long attr, zval *val TSRMLS_DC);

Retrieves an attribute from a database handle. Returns 0 if the driver doesn't support the attribute. Returns -1 if the driver encountered an error. Returns 1 on success. There are a number of attributes that can be fetched, and these are discussed in ???.

int SKEL_check_liveness_func(pdo_dbh_t *dbh TSRMLS_DC);

Performs some driver dependent action to determine if a connection is still valid for use, typically a low overhead ping. Returns SUCCESS if the connection is still alive and ready to be used, FAILURE if the connection is no longer alive (perhaps it timed out). If this function is not provided, it is equivalent to defining a function that always returns SUCCESS.

zend_function_entry *SKEL_get_driver_methods_func(
      pdo_dbh_t *dbh, int kind TSRMLS_DC);

When a PHP script attempts to call a method on a PDO or PDOStatement object that is not covered by either this specification or by a user defined class that extends either PDO or a PDOStatement, then SKEL_get_driver_methods_func is called to determine the driver extension methods that are present.

When kind is PDO_DBH_DRIVER_METHOD_KIND_DBH, the driver extension method table for the connection handle must be returned. When kind is PDO_DBH_DRIVER_METHOD_KIND_STMT, the driver extension method table for the statement handle must be returned.

The return value is either a zend_function_entry pointer referencing a table of methods, or NULL to indicate that there are no extension methods available.

Driver extension methods must be prefixed with the driver name used to register the driver so that they are less likely to collide with either future PDO methods or user defined functions in derived classes.

void SKEL_request_shutdown_func(pdo_dbh_t *dbh TSRMLS_DC);

Called when a script terminates (request shutdown) for a persistent connection handle. This provides the opportunity to safely releases resources that only have per-request scope.

struct _pdo_stmt_t {
  /* driver specific methods */
  struct pdo_stmt_methods *methods;
  /* driver specific data */
  void *driver_data;

  unsigned supports_placeholders:2;

  const char *named_rewrite_template;
};

PDO_API int pdo_parse_params(pdo_stmt_t *stmt, char *inquery,
      int inquery_len, char **outquery, int *outquery_len TSRMLS_DC);

Given an input inquery and its length, inquery_len, analyzes the SQL and potentially rewrites it to an appropriate native form based on the supports_placeholders field in stmt.

Returns 0 if the input query is in a suitable native form that the driver understands.

Returns 1 if the query was rewritten; outquery and outquery_len will be updated to reference the rewritten query string and its length. If outquery is not NULL, the caller is responsible for freeing it via efree when it is no longer required.

Returns -1 if an error ocurred. The error_code field of stmt will have been set to an appropriate SQLSTATE error code. A driver will usually copy this code into the equivalent field of the dbh.

When a driver encounters an error on a prepared statement handle, it must update the error_code field of the stmt to hold an appropriate SQLSTATE error code, and take some action to record the driver specific error code and human readable message, if necessary.

The method descriptions below describe how to indicate an error status. The PDO core may invoke the SKEL_fetch_error_func to obtain the driver specific error code and human readable message.

The driver should not unilaterally raise an exception in reponse to an error. Instead, it should be left to the PDO core to handle reporting the error to the script, based on the application preferences for error handling.

int SKEL_stmt_dtor_func(pdo_stmt_t *stmt TSRMLS_DC);

This function is called by the PDO core when freeing resources associated with the stmt. It should release any resources allocated by the driver.

Returns 0. An implementation bug means that the return value is not checked.

int SKEL_stmt_execute_func(pdo_stmt_t *stmt TSRMLS_DC);

Starts the query. This is typically implemented as a call to the database specific prepared statement execute function. Prior to calling this function, the PDO core will trigger a PDO_PARAM_EVT_EXEC_PRE event for each parameter, offering the driver an opportunity to perform some final binding or allocation actions prior to executing the statement.

active_query_string and active_query_stringlen will be set by the PDO core to reflect the query being executed. This is largely for the convenience of drivers that don't natively support parameterized queries; the query rewriter will have synthesized a query string with the parameters expanded, if the supports_placeholders indicates that it should have. For drivers that do support parameterized queries, it is anticipated that they will have already prepared their statement handles and associated the parameters with it during the PDO_PARAM_EVT_EXEC_PRE notification.

Immediately after executing, the PDO core will trigger a PDO_PARAM_EVT_EXEC_POST event for each parameter, offering the driver an opportunity to take some action, for example, with parameters bound as OUT parameters.

Returns 1 on success, 0 on failure.

int SKEL_stmt_fetch_func(pdo_stmt_t *stmt,
      enum pdo_fetch_orientation ori, long offset TSRMLS_DC);

Requests that the driver fetch the next row into driver storage. Prior to calling this function the PDO core will trigger a PDO_PARAM_EVT_FETCH_PRE event for each column, offering the driver an opportunity to perform per-column allocations or binding.

After calling this function, the PDO core will trigger a describe of the columns if they haven't already been queried, and will then trigger a PDO_PARAM_EVT_FETCH_POST event.

The orientation and offset parameters allow scrolling cursor operation.

Returns 1 if data was returned, 0 otherwise.

int SKEL_stmt_describe_col_func(pdo_stmt_t *stmt,
      int colno TSRMLS_DC);

Requests that the driver populate the columns field of stmt with information about a given column. Columns are numbered zero-based in this function.

Returns 1 if successful, 0 otherwise.

int SKEL_stmt_get_col_data_func(pdo_stmt_t *stmt,
      int colno, char **ptr, unsigned long *len, int *caller_frees TSRMLS_DC);

Requests that the driver return a pointer and size of the data for a particular column. PDO prefers that the driver manage the lifetime of this data (it can often reuse the same memory block for repeated fetches). The PDO core will translate this memory, copying it if necessary. If the driver must allocate transient memory for a column, then it should do so using emalloc() and set caller_frees to a non-zero value. This informs PDO that it is responsible for freeing the column data when it is no longer required.

The type of pointer is specified by the column description prepared by SKEL_stmt_describe_col_func.

Returns 1 if successful, 0 otherwise.

int SKEL_stmt_param_hook_func(pdo_stmt_t *stmt,
      struct pdo_bound_param_data *param, enum pdo_param_event event_type
      TSRMLS_DC);

The param hook function is called by the PDO core at certain key points in the setup of a statement handle, per parameter or column, to notify the driver, so that it can perform some driver specific function.

The PDO core has no expectations for the hook function, except that it should return 0 if there was an error, 1 otherwise.

The events that are possible are:

PDO_PARAM_EVT_NORMALIZE

Triggered before PDO_PARAM_EVT_ALLOC to normalize the parameter name. This is not typically used by most drivers. The pgsql driver uses this opportunity to fixup the parameter name and ordinal position before the core registers its parameter state.

PDO_PARAM_EVT_ALLOC

Triggered in response to binding a parameter or column. This is the drivers opportunity to allocate its driver-specific state for the parameter.

Some drivers will take this opportunity to set up bind descriptors if enough information is present in the param data. Note that this stage is too early to be sure of the value (it may change between the bind call and statement execution), so drivers must not snapshot the value of the parameter at this point.

PDO_PARAM_EVT_FREE

Triggered when the core is done with a parameter, typically at statement handle tear-down time. The driver must release any resources it may have allocated for the parameter.

PDO_PARAM_EVT_EXEC_PRE

Triggered for each parameter immediately before invoking the SKEL_stmt_execute_func. This is the correct time to capture or reference the parameter value and finalize the binding of the parameter.

PDO_PARAM_EVT_EXEC_POST

Triggered for each parameter immediately after invoking the SKEL_stmt_execute_func. This allows a driver to fixup or reconcile state, in particular for OUT parameters that have been bound to a zval.

PDO_PARAM_EVT_FETCH_PRE

Triggered for each bound column immediately before invoking the SKEL_stmt_fetch_func. This has similar semantics to PDO_PARAM_EVT_EXEC_PRE, except that it applies to binding columns in a result set to zvals rather than parameters in a prepared statement.

PDO_PARAM_EVT_FETCH_POST

Triggered for each bound column immediately after invoking the SKEL_stmt_fetch_func. This has similar semantics to PDO_PARAM_EVT_EXEC_POST, except that it applies to binding columns in a result set to zvals rather than parameters in a prepared statement.