cvs: phpdoc /en/internals2/pdo implementing.xml packaging.xml preparation.xml /en/language types.xml /en/language/oop5 interfaces.xml

gwynne Mon Jun 25 17:59:35 2007 UTC Modified files: /phpdoc/en/internals2/pdo implementing.xml packaging.xml preparation.xml /phpdoc/en/language types.xml /phpdoc/en/language/oop5 interfaces.xml Log: Add some missing IDs

http://cvs.php.net/viewvc.cgi/phpdoc/en/internals2/pdo/implementing.xml?r1=1.2&r2=1.3&diff_format=u Index: phpdoc/en/internals2/pdo/implementing.xml diff -u phpdoc/en/internals2/pdo/implementing.xml:1.2 phpdoc/en/internals2/pdo/implementing.xml:1.3 --- phpdoc/en/internals2/pdo/implementing.xml:1.2 Wed Jun 20 22:39:08 2007 +++ phpdoc/en/internals2/pdo/implementing.xml Mon Jun 25 17:59:34 2007 @@ -1,8 +1,8 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.2 $ --> +<!-- $Revision: 1.3 $ --> <sect1 xml:id="internals2.pdo.implementing" xmlns="http://docbook.org/ns/docbook"> <title>Fleshing out your skeleton</title> - <sect2> + <sect2 xml:id="internals2.pdo.implementing.structures"> <title>Major Structures and Attributes</title> <para> The major structures, pdo_dbh_t and pdo_stmt_t are defined and explained in @@ -11,9 +11,9 @@ </para> </sect2> - <sect2> + <sect2 xml:id="internals2.pdo.implementing.skel"> <title>pdo_SKEL.c: PHP extension glue</title> - <sect3> + <sect3 xml:id="internals2.pdo.implementing.skel.entries"> <title>function entries</title> <synopsis><![CDATA[ static function_entry pdo_SKEL_functions[] = { @@ -26,7 +26,7 @@ the synopsis above. </para> </sect3> - <sect3> + <sect3 xml:id="internals2.pdo.implementing.skel.module"> <title>Module entry</title> <synopsis><![CDATA[ /* {{{ pdo_SKEL_module_entry */ @@ -67,9 +67,9 @@ </para> </sect3> - <sect3> + <sect3 xml:id="internals2.pdo.implementing.skel.functions"> <title>Standard PHP Module Extension Functions</title> - <sect4> + <sect4 xml:id="internals2.pdo.implementing.skel.functions.minit"> <title>PHP_MINIT_FUNCTION</title> <synopsis><![CDATA[ /* {{{ PHP_MINIT_FUNCTION */ @@ -92,7 +92,7 @@ </para> </sect4> - <sect4> + <sect4 xml:id="internals2.pdo.implementing.skel.functions.mshutdown"> <title>PHP_MSHUTDOWN_FUNCTION</title> <synopsis><![CDATA[ /* {{{ PHP_MSHUTDOWN_FUNCTION */ @@ -110,7 +110,7 @@ init function above. </para> </sect4> - <sect4> + <sect4 xml:id="internals2.pdo.implementing.skel.functions.minfo"> <title>PHP_MINFO_FUNCTION</title> <para> This is again a standard PHP extension function. Its purpose is to @@ -123,7 +123,7 @@ </sect4> </sect3> </sect2> - <sect2> + <sect2 xml:id="internals2.pdo.implementing.driver"> <title>SKEL_driver.c: Driver implementation</title> <para> @@ -135,7 +135,7 @@ documentation for more information on this macro. </para> - <sect3> + <sect3 xml:id="internals2.pdo.implementing.driver.error"> <title>pdo_SKEL_error</title> <synopsis><![CDATA[static int pdo_SKEL_error(pdo_dbh_t *dbh, @@ -191,7 +191,7 @@ handling errors. </para> - <example> + <example xml:id="internals2.pdo.implementing.driver.error.ex-macros"> <title>Example macros for invoking pdo_SKEL_error</title> <programlisting role="c"><![CDATA[ #define pdo_SKEL_drv_error(what) \ @@ -214,7 +214,7 @@ </para> </note> </sect3> - <sect3> + <sect3 xml:id="internals2.pdo.implementing.driver.fetch-err"> <title>pdo_SKEL_fetch_error_func</title> <synopsis><![CDATA[static int pdo_SKEL_fetch_error_func(pdo_dbh_t *dbh, pdo_stmt_t *stmt, zval *info TSRMLS_DC)]]></synopsis> @@ -272,7 +272,7 @@ does not have additional info. </para> </sect3> - <sect3> + <sect3 xml:id="internals2.pdo.implementing.driver.handle-closer"> <title>SKEL_handle_closer</title> <synopsis><![CDATA[static int SKEL_handle_closer(pdo_dbh_t *dbh TSRMLS_DC)]]></synopsis> @@ -368,7 +368,7 @@ <function>pdo_parse_params</function> API to have PDO rewrite the query to take advantage of the support provided by your database. </para> - <example> + <example xml:id="internals2.pdo.implementing.preparer.ex-parse-params"> <title>Using pdo_parse_params</title> <programlisting role="c"><![CDATA[ int ret; @@ -398,7 +398,7 @@ <constant>PDO_PLACEHOLDER_POSITIONAL</constant> and <constant>PDO_PLACEHOLDER_NONE</constant>. If the driver doesn't support prepare statements at all, then this function should simply allocate any state that it might need, and then return: </para> - <example> + <example xml:id="internals2.pdo.implementing.preparer.ex-no-native-prep"> <title>Implementing preparer for drivers that don't support native prepared statements</title> <programlisting role="c"><![CDATA[ static int SKEL_handle_preparer(pdo_dbh_t *dbh, const char *sql, @@ -419,7 +419,7 @@ <para>This function returns 1 on success or 0 on failure.</para> </sect3> - <sect3> + <sect3 xml:id="internals2.pdo.implementing.driver.handle-doer"> <title>SKEL_handle_doer</title> <synopsis><![CDATA[static long SKEL_handle_doer(pdo_dbh_t *dbh, const char *sql, long sql_len TSRMLS_DC)]]></synopsis> @@ -454,7 +454,7 @@ </para> </sect3> - <sect3> + <sect3 xml:id="internals2.pdo.implementing.driver.handle-quoter"> <title>SKEL_handle_quoter</title> <synopsis><![CDATA[static int SKEL_handle_quoter(pdo_dbh_t *dbh, const char *unquoted, int unquoted_len, char **quoted, int quoted_len, enum pdo_param_type param_type TSRMLS_DC)]]></synopsis> @@ -519,7 +519,7 @@ used unchanged with a 0 return. </para> </sect3> - <sect3> + <sect3 xml:id="internals2.pdo.implementing.driver.handle-begin"> <title>SKEL_handle_begin</title> <synopsis><![CDATA[static int SKEL_handle_begin(pdo_dbh_t *dbh TSRMLS_DC)]]></synopsis> @@ -540,7 +540,7 @@ 0 if an error occurred. </para> </sect3> - <sect3> + <sect3 xml:id="internals2.pdo.implementing.driver.handle-commit"> <title>SKEL_handle_commit</title> <synopsis><![CDATA[static int SKEL_handle_commit(pdo_dbh_t *dbh TSRMLS_DC)]]></synopsis> <para> @@ -562,7 +562,7 @@ accomplished to commit a transaction. This function returns 1 for success or 0 if an error occurred. </para> </sect3> - <sect3> + <sect3 xml:id="internals2.pdo.implementing.driver.handle-rollback"> <title>SKEL_handle_rollback</title> <synopsis><![CDATA[static int SKEL_handle_rollback( pdo_dbh_t *dbh TSRMLS_DC)]]></synopsis> <para>This function will be called by PDO to rollback a database transaction.</para> @@ -580,7 +580,7 @@ success or 0 if an error occurred. </para> </sect3> - <sect3> + <sect3 xml:id="internals2.pdo.implementing.driver.get-attr"> <title>SKEL_handle_get_attribute</title> <synopsis><![CDATA[static int SKEL_handle_get_attribute(pdo_dbh_t *dbh, long attr, zval *return_value TSRMLS_DC)]]></synopsis> <para>This function will be called by PDO to retrieve a database attribute.</para> @@ -618,7 +618,7 @@ This function returns 1 on success or 0 on failure. </para> </sect3> - <sect3> + <sect3 xml:id="internals2.pdo.implementing.driver.set-attr"> <title>SKEL_handle_set_attribute</title> <synopsis>static int SKEL_handle_set_attribute(pdo_dbh_t *dbh, long attr, zval *val TSRMLS_DC)</synopsis> <para> @@ -662,7 +662,7 @@ </para> </sect3> - <sect3> + <sect3 xml:id="internals2.pdo.implementing.driver.last-id"> <title>SKEL_handle_last_id</title> <synopsis><![CDATA[static char * SKEL_handle_last_id(pdo_dbh_t *dbh, const char *name, unsigned int len TSRMLS_DC)]]></synopsis> <para> @@ -699,7 +699,7 @@ </para> </sect3> - <sect3> + <sect3 xml:id="internals2.pdo.implementing.driver.check-live"> <title>SKEL_check_liveness</title> <synopsis><![CDATA[static int SKEL_check_liveness(pdo_dbh_t *dbh TSRMLS_DC)]]></synopsis> @@ -732,7 +732,7 @@ </sect3> - <sect3> + <sect3 xml:id="internals2.pdo.implementing.driver.get-methods"> <title>SKEL_get_driver_methods</title> <synopsis><![CDATA[static function_entry *SKEL_get_driver_methods(pdo_dbh_t *dbh, int kind TSRMLS_DC)]]></synopsis> <para> @@ -787,7 +787,7 @@ </para> </sect3> - <sect3> + <sect3 xml:id="internals2.pdo.implementing.driver.handle-factory"> <title>SKEL_handle_factory</title> <synopsis><![CDATA[static int SKEL_handle_factory(pdo_dbh_t *dbh, zval *driver_options TSRMLS_DC)]]></synopsis> <para> @@ -828,7 +828,7 @@ </para> </sect3> - <sect3> + <sect3 xml:id="internals2.pdo.implementing.driver.method-table"> <title>Driver method table</title> <para> A static structure of type pdo_dbh_methods named SKEL_methods must be @@ -838,7 +838,7 @@ </para> </sect3> - <sect3> + <sect3 xml:id="internals2.pdo.implementing.driver.skeldriver"> <title>pdo_SKEL_driver</title> <para> A structure of type pdo_driver_t named pdo_SKEL_driver should be declared. @@ -847,13 +847,13 @@ </para> </sect3> </sect2> - <sect2> + <sect2 xml:id="internals2.pdo.implementing.statement"> <title>SKEL_statement.c: Statement implementation</title> <para> This unit implements all of the database statement handling methods that support the PDO statement object. </para> - <sect3> + <sect3 xml:id="internals2.pdo.implementing.statement.dtor"> <title>SKEL_stmt_dtor</title> <synopsis><![CDATA[static int SKEL_stmt_dtor(pdo_stmt_t *stmt TSRMLS_DC)]]></synopsis> @@ -876,7 +876,7 @@ </para> </sect3> - <sect3> + <sect3 xml:id="internals2.pdo.implementing.statement.exec"> <title>SKEL_stmt_execute</title> <synopsis><![CDATA[static int SKEL_stmt_execute(pdo_stmt_t *stmt TSRMLS_DC)]]></synopsis> <para> @@ -896,7 +896,7 @@ This function returns 1 for success or 0 in the event of failure. </para> </sect3> - <sect3> + <sect3 xml:id="internals2.pdo.implementing.statement.fetch"> <title>SKEL_stmt_fetch</title> <synopsis>static int SKEL_stmt_fetch(pdo_stmt_t *stmt, enum pdo_fetch_orientation ori, long offset TSRMLS_DC)</synopsis> @@ -941,7 +941,7 @@ failure. </para> </sect3> - <sect3> + <sect3 xml:id="internals2.pdo.implementing.statement.param-hook"> <title>SKEL_stmt_param_hook</title> <synopsis><![CDATA[static int SKEL_stmt_param_hook(pdo_stmt_t *stmt, struct pdo_bound_param_data *param, enum pdo_param_event event_type TSRMLS_DC)]]></synopsis> @@ -1056,7 +1056,7 @@ </para> </sect3> - <sect3> + <sect3 xml:id="internals2.pdo.implementing.statement.desc-col"> <title>SKEL_stmt_describe_col</title> <synopsis><![CDATA[static int SKEL_stmt_describe_col(pdo_stmt_t *stmt, int colno TSRMLS_DC)]]></synopsis> @@ -1086,7 +1086,7 @@ </para> </sect3> - <sect3> + <sect3 xml:id="internals2.pdo.implementing.statement.get-col-data"> <title>SKEL_stmt_get_col_data</title> <synopsis><![CDATA[static int SKEL_stmt_get_col_data(pdo_stmt_t *stmt, int colno, char **ptr, unsigned long *len, int *caller_frees TSRMLS_DC)]]></synopsis> @@ -1132,7 +1132,7 @@ returns 1 for success or 0 in the event of failure. </para> </sect3> - <sect3> + <sect3 xml:id="internals2.pdo.implementing.statement.set-attr"> <title>SKEL_stmt_set_attr</title> <synopsis>static int SKEL_stmt_set_attr(pdo_stmt_t *stmt, long attr, zval *val TSRMLS_DC)</synopsis> @@ -1175,7 +1175,7 @@ attributes on the database driver's behalf. </para> </sect3> - <sect3> + <sect3 xml:id="internals2.pdo.implementing.statement.get-attr"> <title>SKEL_stmt_get_attr</title> <synopsis><![CDATA[static int SKEL_stmt_get_attr(pdo_stmt_t *stmt, long attr, zval *return_value TSRMLS_DC)]]></synopsis> @@ -1217,7 +1217,7 @@ handle any settable attributes on the database driver's behalf. </para> </sect3> - <sect3> + <sect3 xml:id="internals2.pdo.implementing.statement.get-col-meta"> <title>SKEL_stmt_get_col_meta</title> <synopsis><![CDATA[static int SKEL_stmt_get_col_meta(pdo_stmt_t *stmt, int colno, zval *return_value TSRMLS_DC)]]></synopsis> @@ -1260,7 +1260,7 @@ </para> </sect3> - <sect3> + <sect3 xml:id="internals2.pdo.implementing.statement.method-table"> <title>Statement handling method table</title> <para> A static structure of type pdo_stmt_methods named SKEL_stmt_methods should http://cvs.php.net/viewvc.cgi/phpdoc/en/internals2/pdo/packaging.xml?r1=1.2&r2=1.3&diff_format=u Index: phpdoc/en/internals2/pdo/packaging.xml diff -u phpdoc/en/internals2/pdo/packaging.xml:1.2 phpdoc/en/internals2/pdo/packaging.xml:1.3 --- phpdoc/en/internals2/pdo/packaging.xml:1.2 Wed Jun 20 22:39:08 2007 +++ phpdoc/en/internals2/pdo/packaging.xml Mon Jun 25 17:59:34 2007 @@ -1,20 +1,25 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.2 $ --> +<!-- $Revision: 1.3 $ --> <sect1 xml:id="internals2.pdo.packaging" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> <title>Packaging and distribution</title> - <sect2> + <sect2 xml:id="internals2.pdo.packaging.creating"> <title>Creating a package</title> <para> PDO drivers are released via PECL; all the usual rules for PECL extensions apply. Packaging is accomplished by creating a valid <filename>package.xml</filename> file and then running: </para> - <screen><![CDATA[ + + <screen> +<![CDATA[ $ pecl package -]]></screen> +]]> + </screen> + <para> This will create a tarball named <filename>PDO_SKEL-X.Y.Z.tgz</filename>. </para> + <para> Before releasing the package, you should test that it builds correctly; if you've made a mistake in your <filename>config.m4</filename> or @@ -22,23 +27,29 @@ correctly. You can test the build, without installing anything, using the following invocation: </para> - <screen><![CDATA[ + + <screen> +<![CDATA[ $ pecl build package.xml -]]></screen> +]]> + </screen> <para> Once this is proven to work, you can test installation: </para> - <screen><![CDATA[ + <screen> +<![CDATA[ $ pecl package $ sudo pecl install PDO_SKEL-X.Y.X.tgz -]]></screen> +]]> + </screen> <para> Full details about <filename>package.xml</filename> can be found in the PEAR Programmer's documentation (<link xlink:href="&url.php.pear.manual;"/>). </para> </sect2> - <sect2> + + <sect2 xml:id="internals2.pdo.packaging.creating.releasing"> <title>Releasing the package</title> <para> A PDO driver is released via the PHP Extension Community Library (PECL). http://cvs.php.net/viewvc.cgi/phpdoc/en/internals2/pdo/preparation.xml?r1=1.2&r2=1.3&diff_format=u Index: phpdoc/en/internals2/pdo/preparation.xml diff -u phpdoc/en/internals2/pdo/preparation.xml:1.2 phpdoc/en/internals2/pdo/preparation.xml:1.3 --- phpdoc/en/internals2/pdo/preparation.xml:1.2 Wed Jun 20 22:39:08 2007 +++ phpdoc/en/internals2/pdo/preparation.xml Mon Jun 25 17:59:34 2007 @@ -1,8 +1,8 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.2 $ --> +<!-- $Revision: 1.3 $ --> <sect1 xml:id="internals2.pdo.preparation" xmlns="http://docbook.org/ns/docbook"> <title>Preparation and Housekeeping</title> - <sect2> + <sect2 xml:id="internals2.pdo.preparation.layout"> <title>Source directory layout</title> <para> @@ -13,6 +13,7 @@ lowercase characters. </para> <screen> +<![CDATA[ pdo_SKEL/ config.m4 <co xml:id="internals2.pdo.layout.co.m4"/> config.w32 <co xml:id="internals2.pdo.layout.co.w32"/> @@ -24,6 +25,7 @@ SKEL_dbh.c <co xml:id="internals2.pdo.layout.co.dbh"/> SKEL_stmt.c <co xml:id="internals2.pdo.layout.co.stmt"/> tests/ +]]> </screen> <calloutlist> <callout arearefs="internals2.pdo.layout.co.m4"> @@ -50,7 +52,7 @@ </calloutlist> <para>The contents of these files are defined later in this document.</para> </sect2> - <sect2> + <sect2 xml:id="internals2.pdo.preparation.create-skel"> <title>Creating a skeleton</title> <para> @@ -60,7 +62,11 @@ 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> + <screen> +<![CDATA[ +./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 @@ -69,9 +75,9 @@ have PHP and PDO installed, you should be able to build from any directory. </para> </sect2> - <sect2> + <sect2 xml:id="internals2.pdo.preparation.std-includes"> <title>Standard Includes</title> - <sect3> + <sect3 xml:id="internals2.pdo.preparation.std-includes.build-specific"> <title>Build Specific Headers</title> <para> The header file config.h is generated by the configure process for the @@ -81,7 +87,7 @@ compilation unit. </para> </sect3> - <sect3> + <sect3 xml:id="internals2.pdo.preparation.std-includes.php"> <title>PHP Headers</title> <para> The following standard public php headers should be included in each @@ -99,7 +105,7 @@ </listitem> </orderedlist> </sect3> - <sect3> + <sect3 xml:id="internals2.pdo.preparation.std-includes.pdo"> <title>PDO Interface Headers</title> <para> The following standard public PDO header files are also included in each @@ -132,7 +138,7 @@ </varlistentry> </variablelist> </sect3> - <sect3> + <sect3 xml:id="internals2.pdo.preparation.std-headers.driver-spec"> <title>Driver Specific Headers</title> <para> The typical PDO driver has two header files that are specific to the @@ -172,15 +178,17 @@ </varlistentry> </variablelist> </sect3> - <sect3> + <sect3 xml:id="internals2.pdo.preparation.std-headers.optional"> <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 &lt;zend_exceptions.h&gt; - </synopsis> + <programlisting role="c"> +<![CDATA[ +#include <zend_exceptions.h> +]]> + </programlisting> </sect3> </sect2> </sect1> http://cvs.php.net/viewvc.cgi/phpdoc/en/language/types.xml?r1=1.181&r2=1.182&diff_format=u Index: phpdoc/en/language/types.xml diff -u phpdoc/en/language/types.xml:1.181 phpdoc/en/language/types.xml:1.182 --- phpdoc/en/language/types.xml:1.181 Wed Jun 20 22:24:12 2007 +++ phpdoc/en/language/types.xml Mon Jun 25 17:59:35 2007 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.181 $ --> +<!-- $Revision: 1.182 $ --> <chapter xml:id="language.types" xmlns="http://docbook.org/ns/docbook"> <title>Types</title> @@ -1806,7 +1806,7 @@ as the string <literal>"bar"</literal>, but that you forgot to write the quotes. </para> - <sect4> + <sect4 xml:id="language.types.array.foo-bar.why"> <title>So why is it bad then?</title> <para> At some point in the future, the PHP team might want to add another http://cvs.php.net/viewvc.cgi/phpdoc/en/language/oop5/interfaces.xml?r1=1.9&r2=1.10&diff_format=u Index: phpdoc/en/language/oop5/interfaces.xml diff -u phpdoc/en/language/oop5/interfaces.xml:1.9 phpdoc/en/language/oop5/interfaces.xml:1.10 --- phpdoc/en/language/oop5/interfaces.xml:1.9 Wed Jun 20 22:24:13 2007 +++ phpdoc/en/language/oop5/interfaces.xml Mon Jun 25 17:59:35 2007 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.9 $ --> +<!-- $Revision: 1.10 $ --> <sect1 xml:id="language.oop5.interfaces" xmlns="http://docbook.org/ns/docbook"> <title>Object Interfaces</title> <para> @@ -16,7 +16,7 @@ All methods declared in an interface must be public, this is the nature of an interface. </para> - <sect2> + <sect2 xml:id="language.oop5.interfaces.implements"> <title><literal>implements</literal></title> <para> To implement an interface, the <literal>implements</literal> operator is used. @@ -31,9 +31,9 @@ </para> </note> </sect2> - <sect2> + <sect2 xml:id="language.oop5.interfaces.examples"> &reftitle.examples; - <example> + <example xml:id="language.oop5.interfaces.examples.ex1"> <title>Interface example</title> <programlisting role="php"> <![CDATA[