mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-29 23:38:56 +00:00
11055a8ad0
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@202396 c90b9560-bf6c-de11-be94-00142212c4b1
205 lines
7 KiB
XML
205 lines
7 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision: 1.2 $ -->
|
|
<sect1 id="internals.pdo.preparation">
|
|
<title>Preparation and Housekeeping</title>
|
|
<sect2>
|
|
<title>Source directory layout</title>
|
|
|
|
<para>
|
|
The source directory for a typical PDO driver is laid out as follows, where
|
|
<literal>SKEL</literal> represents a shortened form of the name of the
|
|
database that the driver is going to connect to. Even though SKEL is
|
|
presented here in uppercase (for clarity), the convention is to use
|
|
lowercase characters.
|
|
</para>
|
|
<screen>
|
|
pdo_SKEL/
|
|
config.m4 <co id="internals.pdo.layout.co.m4"/>
|
|
config.w32 <co id="internals.pdo.layout.co.w32"/>
|
|
CREDITS
|
|
package.xml <co id="internals.pdo.layout.co.cred"/>
|
|
pdo_SKEL.c <co id="internals.pdo.layout.co.glue"/>
|
|
php_pdo_SKEL.h
|
|
php_pdo_SKEL_int.h <co id="internals.pdo.layout.co.priv"/>
|
|
SKEL_dbh.c <co id="internals.pdo.layout.co.dbh"/>
|
|
SKEL_stmt.c <co id="internals.pdo.layout.co.stmt"/>
|
|
</screen>
|
|
<calloutlist>
|
|
<callout arearefs="internals.pdo.layout.co.m4">
|
|
<para>unix build script</para>
|
|
</callout>
|
|
<callout arearefs="internals.pdo.layout.co.w32">
|
|
<para>win32 build script</para>
|
|
</callout>
|
|
<callout arearefs="internals.pdo.layout.co.cred">
|
|
<para>meta information about the package</para>
|
|
</callout>
|
|
<callout arearefs="internals.pdo.layout.co.glue">
|
|
<para>standard PHP extension glue</para>
|
|
</callout>
|
|
<callout arearefs="internals.pdo.layout.co.priv">
|
|
<para>driver private header</para>
|
|
</callout>
|
|
<callout arearefs="internals.pdo.layout.co.dbh">
|
|
<para>contains the implementation of the PDO driver interface</para>
|
|
</callout>
|
|
<callout arearefs="internals.pdo.layout.co.stmt">
|
|
<para>contains the implementation of the PDO statement interface</para>
|
|
</callout>
|
|
</calloutlist>
|
|
<para>The contents of these files are defined later in this document.</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>Creating a skeleton</title>
|
|
|
|
<para>
|
|
The easiest way to get started is to use the <command>ext_skel</command>
|
|
shell script found in the PHP build tree in the <filename>ext</filename>
|
|
directory. This will build a skeleton directory containing a lot of the
|
|
files listed above. It can be build by executing the following command from
|
|
within the <filename>ext</filename> directory:
|
|
</para>
|
|
<screen>./ext_skel --extname=pdo_SKEL</screen>
|
|
<para>
|
|
This will generate a directory called pdo_SKEL containing the
|
|
skeleton files that you can then modify. This directory should then be
|
|
moved out of the php extension directory . PDO is a PECL extension and
|
|
should not be included in the standard extension directory. As long as you
|
|
have PHP and PDO installed, you should be able to build from any directory.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>Standard Includes</title>
|
|
<sect3>
|
|
<title>Build Specific Headers</title>
|
|
<para>
|
|
The header file config.h is generated by the configure process for the
|
|
platform for the which the driver is being built. If this header is
|
|
present, the HAVE_CONFIG_H compiler variable is set. This variable should
|
|
be tested for and if set, the file config.h should be included in the
|
|
compilation unit.
|
|
</para>
|
|
</sect3>
|
|
<sect3>
|
|
<title>PHP Headers</title>
|
|
<para>
|
|
The following standard public php headers should be included in each
|
|
source module:
|
|
</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>php.h</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>php_ini.h</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>ext/standard/info.h</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</sect3>
|
|
<sect3>
|
|
<title>PDO Interface Headers</title>
|
|
<para>
|
|
The following standard public PDO header files are also included in each
|
|
source module:
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>pdo/php_pdo.h</term>
|
|
<listitem>
|
|
<para>
|
|
This header file contains definitions of the initialization and shutdown
|
|
functions in the main driver as well as definitions of global PDO
|
|
variables.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>pdo/php_pdo_driver.h</term>
|
|
<listitem>
|
|
<para>
|
|
This header contains the types and API contracts that are used to write
|
|
a PDO driver. It also contains method signature for calling back into
|
|
the PDO layer and registering/unregistering your driver with
|
|
PDO. Most importantly, this header file contains the type
|
|
definitions for PDO database handles and statements. The two main
|
|
structures a driver has to deal with, pdo_dbh_t and pdo_stmt_t, are
|
|
described in more detail in Appendix A and B.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</sect3>
|
|
<sect3>
|
|
<title>Driver Specific Headers</title>
|
|
<para>
|
|
The typical PDO driver has two header files that are specific to the
|
|
database implementation. This does not preclude the use of more depending
|
|
on the implementation. The following two headers are, by convention,
|
|
standard:
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>php_pdo_SKEL.h</term>
|
|
<listitem>
|
|
<para>
|
|
This header file is virtually an exact duplicate in functionality
|
|
and content of the previously defined pdo/php_pdo.h that has been
|
|
specifically tailored for your database. If your driver requires
|
|
the use of global variables they should be defined using the
|
|
ZEND_BEGIN_MODULE_GLOBALS and ZEND_END_MODULE_GLOBALS macros.
|
|
Macros are then used to access these variables. This macro is
|
|
usually named PDO_SKEL_G(v) where v is global variable to be
|
|
accessed. Consult the Zend programmer documentation for more
|
|
information.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>php_pdo_SKEL_int.h</term>
|
|
<listitem>
|
|
<para>
|
|
This header file typically contains type definitions and function
|
|
declarations specific to the driver implementation. It also should
|
|
contain the db specific definitions of a pdo_SKEL_handle and
|
|
pdo_SKEL_stmt structures. These are the names of the private
|
|
data structures that are then referenced by the driver_data members
|
|
of the handle and statement structures.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</sect3>
|
|
<sect3>
|
|
<title>Optional Headers</title>
|
|
<para>
|
|
Depending on the implementation details for a particular driver it may be
|
|
necessary to include the following header:
|
|
</para>
|
|
<synopsis>
|
|
#include <zend_exceptions.h>
|
|
</synopsis>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
indent-tabs-mode:nil
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"../../manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|