mirror of
https://github.com/php/php-src.git
synced 2024-09-30 14:26:12 +00:00
115 lines
4.1 KiB
XML
115 lines
4.1 KiB
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="drivers">
|
|
<title>Driver Documentation</title>
|
|
|
|
<para>
|
|
Any PHP extension that is linked against the PDO core module can elect to
|
|
register a PDO driver. A PDO driver is represented by the
|
|
<type>pdo_driver_t</type> type which describes the version of PDO against
|
|
which the driver was built, the name of the driver and a factory method
|
|
that can be used to instantiate a database connection handle. A
|
|
connection handle is represented by the <type>pdo_dbh_t</type> type which
|
|
describes, among other things, how to instantiate a prepared statement
|
|
handle, represented by the <type>pdo_stmt_t</type> type.
|
|
</para>
|
|
|
|
<para>
|
|
These three types are the main interface between the PDO core and a PDO
|
|
driver. In this chapter, we'll refer to an imaginary skeleton driver, and
|
|
use <literal>SKEL</literal> as a placeholder for its various functions or
|
|
types. In practice, a given database vendor will typically choose to use
|
|
a short, lowercase, version of the name of their database or client
|
|
library in place of <literal>SKEL</literal>.
|
|
</para>
|
|
|
|
<section id="drivers.registration">
|
|
<title>Driver Registration</title>
|
|
|
|
<para>
|
|
A driver extension will typically statically define an instance of
|
|
<type>pdo_driver_t</type> and pass the address of it to
|
|
<function>php_pdo_register_driver</function> during its module
|
|
initialization callback (also known as MINIT, for module init), and
|
|
again to <function>php_pdo_unregister_driver</function> during its
|
|
module shutdown callback (also known as MSHUTDOWN).
|
|
</para>
|
|
|
|
<para>
|
|
<filename>php_pdo_driver.h</filename> defines <type>pdo_driver_t</type>,
|
|
<function>php_pdo_register_driver</function> and
|
|
<function>php_pdo_unregister_driver</function> as follows:
|
|
</para>
|
|
|
|
<programlisting role="C"><![CDATA[
|
|
/* This structure is registered with PDO when a PDO driver extension is
|
|
* initialized */
|
|
typedef struct {
|
|
const char *driver_name;
|
|
unsigned long driver_name_len;
|
|
unsigned long api_version; /* needs to be compatible with PDO */
|
|
|
|
#define PDO_DRIVER_HEADER(name) \
|
|
#name, sizeof(#name)-1, \
|
|
PDO_DRIVER_API
|
|
|
|
/* create driver specific portion of the database handle and stash it into
|
|
* the dbh. dbh contains the data source string and flags for this
|
|
* instance. You MUST respect dbh->is_persistent and pass that flag to
|
|
* pemalloc() for all allocations that are stored in the dbh or your instance
|
|
* data in the db, otherwise you will crash PHP when persistent connections
|
|
* are used.
|
|
*/
|
|
int (*db_handle_factory)(pdo_dbh_t *dbh, zval *driver_options TSRMLS_DC);
|
|
} pdo_driver_t;
|
|
|
|
/* call this in MINIT to register your PDO driver */
|
|
PDO_API int php_pdo_register_driver(pdo_driver_t *driver);
|
|
/* call this in MSHUTDOWN to unregister your PDO driver */
|
|
PDO_API void php_pdo_unregister_driver(pdo_driver_t *driver);
|
|
]]></programlisting>
|
|
|
|
<para>
|
|
A driver would typically use code like the following to register a
|
|
driver:
|
|
</para>
|
|
|
|
<programlisting role="C"><![CDATA[
|
|
static pdo_driver_t SKEL_driver = {
|
|
PDO_DRIVER_HEADER(SKEL),
|
|
SKEL_db_handle_factory
|
|
};
|
|
|
|
PHP_MINIT_FUNCTION(pdo_SKEL)
|
|
{
|
|
return php_pdo_register_driver(&SKEL_driver);
|
|
}
|
|
|
|
PHP_MSHUTDOWN_FUNCTION(pdo_SKEL)
|
|
{
|
|
php_pdo_unregister_driver(&SKEL_driver);
|
|
return SUCCESS;
|
|
}
|
|
]]></programlisting>
|
|
|
|
<para>
|
|
The <function>SKEL_db_handle_factory</function> is provided by the
|
|
driver; its operation will be discussed in the next section.
|
|
</para>
|
|
</section>
|
|
|
|
<xi:include href="connect.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
|
|
<xi:include href="dbh_methods.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
|
|
<xi:include href="prepare.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
|
|
<xi:include href="binding.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
|
|
<xi:include href="stmt_methods.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
|
|
|
|
</chapter>
|
|
|
|
<!--
|
|
vim:ts=2:sw=2:et:tw=78:
|
|
-->
|
|
|