芝麻web文件管理V1.00

编辑当前文件:/home/strato/chroot/opt/RZphp80/includes/doc/CodeGen_PECL/docs/manual.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>CodeGen_PECL - the PHP extension generator</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"></HEAD
><BODY
CLASS="book"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="BOOK"
><A
NAME="AEN1"
></A
><DIV
CLASS="TITLEPAGE"
><H1
CLASS="title"
><A
NAME="AEN1"
><TT
CLASS="literal"
>CodeGen_PECL</TT
> - the PHP extension generator</A
></H1
><HR></DIV
><DIV
CLASS="TOC"
><DL
><DT
><B
>Table of Contents</B
></DT
><DT
>1. <A
HREF="#AEN4"
>Introduction</A
></DT
><DD
><DL
><DT
>1.1. <A
HREF="#AEN6"
>What is it?</A
></DT
><DT
>1.2. <A
HREF="#AEN22"
>Features</A
></DT
><DT
>1.3. <A
HREF="#AEN48"
>Installation</A
></DT
><DD
><DL
><DT
>1.3.1. <A
HREF="#AEN53"
>Online installation</A
></DT
><DT
>1.3.2. <A
HREF="#AEN59"
>Installing from package files</A
></DT
><DT
>1.3.3. <A
HREF="#AEN69"
>Installing from PEAR CVS</A
></DT
></DL
></DD
><DT
>1.4. <A
HREF="#AEN74"
>How to use it</A
></DT
></DL
></DD
><DT
>2. <A
HREF="#AEN87"
>The XML description</A
></DT
><DD
><DL
><DT
>2.1. <A
HREF="#AEN89"
>Basics</A
></DT
><DT
>2.2. <A
HREF="#AEN107"
>Grouping</A
></DT
><DT
>2.3. <A
HREF="#AEN112"
>Release information</A
></DT
><DT
>2.4. <A
HREF="#AEN152"
>Dependencies</A
></DT
><DD
><DL
><DT
>2.4.1. <A
HREF="#AEN177"
><TT
CLASS="literal"
>--with...</TT
></A
></DT
><DT
>2.4.2. <A
HREF="#AEN200"
>Header files</A
></DT
><DT
>2.4.3. <A
HREF="#AEN215"
>Libraries</A
></DT
><DT
>2.4.4. <A
HREF="#AEN229"
>Dependencies to other extensions</A
></DT
><DT
>2.4.5. <A
HREF="#AEN267"
>External programs</A
></DT
><DT
>2.4.6. <A
HREF="#AEN270"
>Other files</A
></DT
></DL
></DD
><DT
>2.5. <A
HREF="#AEN273"
>Custom code</A
></DT
><DT
>2.6. <A
HREF="#AEN284"
>Conditional compilation</A
></DT
><DT
>2.7. <A
HREF="#AEN297"
>PHP functions</A
></DT
><DD
><DL
><DT
>2.7.1. <A
HREF="#AEN348"
>Function prototypes</A
></DT
><DT
>2.7.2. <A
HREF="#AEN370"
>Parameter types</A
></DT
><DT
>2.7.3. <A
HREF="#AEN465"
>Optional parameters</A
></DT
><DT
>2.7.4. <A
HREF="#AEN478"
>Varargs</A
></DT
><DT
>2.7.5. <A
HREF="#AEN502"
>Pass by reference</A
></DT
><DT
>2.7.6. <A
HREF="#AEN505"
>Return Values</A
></DT
></DL
></DD
><DT
>2.8. <A
HREF="#AEN573"
>Internal functions</A
></DT
><DT
>2.9. <A
HREF="#AEN635"
>Constants</A
></DT
><DT
>2.10. <A
HREF="#AEN660"
><TT
CLASS="literal"
>php.ini</TT
> parameters and internal variables</A
></DT
><DT
>2.11. <A
HREF="#AEN732"
>Resources</A
></DT
><DD
><DL
><DT
>2.11.1. <A
HREF="#AEN754"
>Resource creation and destruction</A
></DT
></DL
></DD
><DT
>2.12. <A
HREF="#AEN766"
>OO features</A
></DT
><DD
><DL
><DT
>2.12.1. <A
HREF="#AEN770"
>Classes</A
></DT
><DT
>2.12.2. <A
HREF="#AEN788"
>Methods</A
></DT
><DT
>2.12.3. <A
HREF="#AEN812"
>Properties</A
></DT
><DT
>2.12.4. <A
HREF="#AEN832"
>Constants</A
></DT
><DT
>2.12.5. <A
HREF="#AEN836"
>Interfaces</A
></DT
></DL
></DD
><DT
>2.13. <A
HREF="#AEN852"
>Streams</A
></DT
><DT
>2.14. <A
HREF="#AEN855"
>config.m4 fragments</A
></DT
><DT
>2.15. <A
HREF="#AEN862"
>Makefile fragments</A
></DT
><DT
>2.16. <A
HREF="#AEN869"
>Tests</A
></DT
><DD
><DL
><DT
>2.16.1. <A
HREF="#AEN877"
>Global test cases</A
></DT
><DT
>2.16.2. <A
HREF="#AEN912"
>Embedded function test cases</A
></DT
></DL
></DD
></DL
></DD
><DT
>3. <A
HREF="#AEN932"
>XML input parsing</A
></DT
><DD
><DL
><DT
>3.1. <A
HREF="#AEN934"
>Includes</A
></DT
><DD
><DL
><DT
>3.1.1. <A
HREF="#AEN947"
>External entities</A
></DT
><DT
>3.1.2. <A
HREF="#AEN953"
>XInclude</A
></DT
><DT
>3.1.3. <A
HREF="#AEN971"
><TT
CLASS="literal"
><code></TT
> tags</A
></DT
></DL
></DD
><DT
>3.2. <A
HREF="#AEN981"
>Verbatim text data</A
></DT
></DL
></DD
><DT
>4. <A
HREF="#AEN998"
>Usage</A
></DT
><DD
><DL
><DT
>4.1. <A
HREF="#AEN1000"
>Invocation</A
></DT
><DT
>4.2. <A
HREF="#AEN1010"
>Configuration</A
></DT
><DT
>4.3. <A
HREF="#AEN1023"
>Compilation</A
></DT
><DT
>4.4. <A
HREF="#AEN1028"
>Testing</A
></DT
><DT
>4.5. <A
HREF="#AEN1046"
>Installation</A
></DT
><DT
>4.6. <A
HREF="#AEN1056"
>PEAR/PECL integration</A
></DT
></DL
></DD
></DL
></DIV
><DIV
CLASS="LOT"
><DL
CLASS="LOT"
><DT
><B
>List of Examples</B
></DT
><DT
>2-1. <A
HREF="#AEN104"
>Extension basics</A
></DT
><DT
>2-2. <A
HREF="#AEN123"
>Release information</A
></DT
><DT
>2-3. <A
HREF="#AEN137"
>License</A
></DT
><DT
>2-4. <A
HREF="#AEN146"
>Loading a logo image from a file</A
></DT
><DT
>2-5. <A
HREF="#AEN149"
>An inline logo image</A
></DT
><DT
>2-6. <A
HREF="#AEN174"
>Dependencies</A
></DT
><DT
>2-7. <A
HREF="#AEN196"
><TT
CLASS="literal"
>--with...</TT
></A
></DT
><DT
>2-8. <A
HREF="#AEN212"
>Header file dependencies</A
></DT
><DT
>2-9. <A
HREF="#AEN226"
>Library dependencies</A
></DT
><DT
>2-10. <A
HREF="#AEN264"
>Extension dependencies</A
></DT
><DT
>2-11. <A
HREF="#AEN290"
>Conditional compilation</A
></DT
><DT
>2-12. <A
HREF="#AEN367"
>Function prototype examples</A
></DT
><DT
>2-13. <A
HREF="#AEN379"
><SPAN
CLASS="type"
>bool</SPAN
> parameter</A
></DT
><DT
>2-14. <A
HREF="#AEN406"
><SPAN
CLASS="type"
>bool</SPAN
> parameter</A
></DT
><DT
>2-15. <A
HREF="#AEN472"
>Optional parameters</A
></DT
><DT
>2-16. <A
HREF="#AEN496"
>Varargs</A
></DT
><DT
>2-17. <A
HREF="#AEN586"
><TT
CLASS="literal"
>MINIT()</TT
></A
></DT
><DT
>2-18. <A
HREF="#AEN595"
><TT
CLASS="literal"
>MINIT()</TT
></A
></DT
><DT
>2-19. <A
HREF="#AEN605"
><TT
CLASS="literal"
>MINIT()</TT
></A
></DT
><DT
>2-20. <A
HREF="#AEN614"
><TT
CLASS="literal"
>MINIT()</TT
></A
></DT
><DT
>2-21. <A
HREF="#AEN629"
><TT
CLASS="literal"
>MINFO()</TT
></A
></DT
><DT
>2-22. <A
HREF="#AEN657"
>PHP Constants</A
></DT
><DT
>2-23. <A
HREF="#AEN725"
>Defining globals and ini entries</A
></DT
><DT
>2-24. <A
HREF="#AEN729"
>Using globals</A
></DT
><DT
>2-25. <A
HREF="#AEN751"
>Resources</A
></DT
><DT
>2-26. <A
HREF="#AEN758"
>Resource creation</A
></DT
><DT
>2-27. <A
HREF="#AEN763"
>Resource destruction</A
></DT
><DT
>2-28. <A
HREF="#AEN775"
>A minimal class</A
></DT
><DT
>2-29. <A
HREF="#AEN782"
>Simple inheritence</A
></DT
><DT
>2-30. <A
HREF="#AEN859"
>config.m4 additions</A
></DT
><DT
>2-31. <A
HREF="#AEN866"
>Makefile fragments</A
></DT
><DT
>2-32. <A
HREF="#AEN906"
>Minimal test case</A
></DT
><DT
>2-33. <A
HREF="#AEN909"
>Full test case</A
></DT
><DT
>2-34. <A
HREF="#AEN926"
>Minimal function test case</A
></DT
><DT
>2-35. <A
HREF="#AEN929"
>Full function test case</A
></DT
><DT
>3-1. <A
HREF="#AEN950"
>System Entities</A
></DT
><DT
>3-2. <A
HREF="#AEN959"
>XInclude</A
></DT
><DT
>3-3. <A
HREF="#AEN965"
>Verbatim XInclude</A
></DT
><DT
>3-4. <A
HREF="#AEN977"
>Using <TT
CLASS="literal"
><code src="..."></TT
></A
></DT
><DT
>3-5. <A
HREF="#AEN987"
>CDATA sections</A
></DT
><DT
>3-6. <A
HREF="#AEN994"
><TT
CLASS="literal"
><?data</TT
> processing instruction</A
></DT
><DT
>4-1. <A
HREF="#AEN1063"
>Installation using <TT
CLASS="literal"
>pear</TT
></A
></DT
><DT
>4-2. <A
HREF="#AEN1068"
>PEAR/PECL packaging</A
></DT
></DL
></DIV
><DIV
CLASS="chapter"
><HR><H1
><A
NAME="AEN4"
></A
>Chapter 1. Introduction</H1
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="AEN6"
>1.1. What is it?</A
></H2
><P
>    <TT
CLASS="literal"
>CodeGen_PECL</TT
> (formerly known as <TT
CLASS="literal"
>PECL_Gen</TT
>)
    is a tool that can automatically create the basic framework for a PHP extension 
    from a rather simple XML specification file. The actual functionality is provided
    by the script <TT
CLASS="filename"
>pecl-gen</TT
> that is installed by the 
    <TT
CLASS="literal"
>CodeGen_PECL</TT
> package.
   </P
><P
>    It also supports the simpler (but less powerful) prototype file
    format as used by the shell script <TT
CLASS="literal"
>ext_skel</TT
> that
    is distributed togehter with the PHP source code. 
   </P
><P
>    <TT
CLASS="literal"
>pecl-gen</TT
>, unlike the older
    <TT
CLASS="literal"
>ext_skel</TT
> solution, is a 100% PHP 5 based
    solution and does not require any external tools like
    <TT
CLASS="literal"
>awk</TT
> or <TT
CLASS="literal"
>sed</TT
>. It only uses PHP
    functions and PEAR modules that are always enabled in a default 
    build and so it should be usable on any platform that PHP itself runs on.
   </P
><P
>    PHP 5 is only required for the conversion of the XML spec file to C/C++ code. 
    The code generated by <TT
CLASS="literal"
>CodeGen_Pecl</TT
> is designed to work 
    with both the extension APIs of PHP 5 and PHP 4 as long as only procdural
    features are used. Object oriented features are only supported for PHP 5
    as the OO-specific API changed too much between PHP 4 and 5 to generate
    code for both.
   </P
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="AEN22"
>1.2. Features</A
></H2
><P
>    <TT
CLASS="literal"
>CodeGen_PECL</TT
> tries to support as many extension
    writing aspects as possible. This currently includes code and documentation
    generation for:
    <P
></P
><UL
><LI
><P
>functions</P
></LI
><LI
><P
>constants</P
></LI
><LI
><P
><TT
CLASS="literal"
>php.ini</TT
> configuration directives</P
></LI
><LI
><P
>resource types</P
></LI
><LI
><P
>per-thread global variables</P
></LI
><LI
><P
>test cases</P
></LI
></UL
>
   </P
><P
>    <TT
CLASS="literal"
>CodeGen_PECL</TT
> also generates
    <TT
CLASS="filename"
>config.m4</TT
> 
    configuration files for Unix-like build environments,
    VisualStudio <TT
CLASS="filename"
>*.dsp</TT
> project files for Windows
    and the <TT
CLASS="filename"
>package.xml</TT
> files needed for
    PEAR/PECL packaging. Support for the new Windows Scripting Host
    based build system is currently being worked on, <TT
CLASS="filename"
>config.w32</TT
>
    files are already generated but may only work for simple configuration
    setups for now.
   </P
><P
>    DocBook XML documentation templates are created that can either 
    be used to generate stadalone documentation or that can be integrated
    into the PHP manual by simply copying over the generated documentation
    directory.
   </P
><P
>    Test cases are created for each generated function, additional test cases
    may also be specified.
   </P
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="AEN48"
>1.3. Installation</A
></H2
><P
>    <TT
CLASS="literal"
>CodeGen_PECL</TT
> is available in PEAR, the
    PHP Extension and Application Repository: 
    <TT
CLASS="literal"
>http://pear.php.net/CodeGen_PECL</TT
>
   </P
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="AEN53"
>1.3.1. Online installation</A
></H3
><P
>     Online installation using the PEAR installer is the easiest way 
     to install <TT
CLASS="literal"
>CodeGen_PECL</TT
>, just issue the following
     command:
    </P
><PRE
CLASS="programlisting"
>pear install --alldeps CodeGen_PECL
    </PRE
><P
>     The PEAR installer will download and install the package itself
     and all packages that it depends on.
    </P
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="AEN59"
>1.3.2. Installing from package files</A
></H3
><P
>     When installing from package files downloaded from <TT
CLASS="literal"
>pear.php.net</TT
>
     you have to resolve dependencies yourself. Currently <TT
CLASS="literal"
>CodeGen_PECL</TT
>
     depends on two other PEAR packages: <TT
CLASS="literal"
>Console_Getopt</TT
>, which is part
     of the PEAR base installation, and <TT
CLASS="literal"
>CodeGen</TT
>, the code generator
     base package. You need to download both <TT
CLASS="literal"
>CodeGen</TT
> and 
     <TT
CLASS="literal"
>CodeGen_PECL</TT
> packages for installation. The actual installation
     is once again performed by the PEAR installer:
    </P
><PRE
CLASS="programlisting"
>pear install CogeGen-1.0.1.tgz
pear install CogeGen_PECL-1.0.3.tgz
    </PRE
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="AEN69"
>1.3.3. Installing from PEAR CVS</A
></H3
><P
>     You can also install CodeGen_PECL snapshots from PEAR CVS. CVS snapshots may
     include features not yet available in any release package, but the code in
     CVS may not be as well tested as the release packages (or even broken at 
     times). Be warned, your milage may vary. Use the following sequence of 
     commands in your PEAR CVS checkout to install the latest
     <TT
CLASS="literal"
>CodeGen_PECL</TT
> snapshot:
    </P
><PRE
CLASS="programlisting"
>cd pear
cd CodeGen
cvs update
pear install --force package.xml
cd ..
cd CodeGen_PECL
cvs update
pear install --force package.xml
cd ..
    </PRE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="AEN74"
>1.4. How to use it</A
></H2
><P
>    There are three different modes of operation for
    <TT
CLASS="literal"
>pecl-gen</TT
>. In its default mode it can create a complete
    ready-to-compile extension from an XML description (documented in
    the next chapter). In <TT
CLASS="literal"
>ext_skel</TT
> compatibility
    mode it generates the extension from some command line parameters
    and an optional function prototype file and in immediate mode it
    just takes a function prototype from command line and writes a
    C code skeleton for just that function to standard output.
   </P
><P
>    <TT
CLASS="literal"
>ext_skel</TT
> compatibility and immediate mode are 
    not documented here, please refer to the original 
    <TT
CLASS="literal"
>ext_skel</TT
> documentation instead.
   </P
><P
>    A more detailed step by step guide on how to invocate <TT
CLASS="literal"
>pecl-gen</TT
>
    and how to procede to configure, compile, test and install an extension 
    is given in the "Usage" chapter later in this document.
   </P
><P
>    Below you find a hardcopy of the <TT
CLASS="literal"
>pecl-gen
     --help</TT
> output:
   </P
><PRE
CLASS="screen"
>

Usage:

pecl-gen [-h] [--force] [--experimental] [--version]
  [--extname=name] [--proto=file] [--skel=dir] [--stubs=file] 
  [--no-help] [--xml[=file]] [--full-xml] [--function=proto] [specfile.xml]

-h|--help          this message
  -f|--force         overwrite existing directories
  -d|--dir           output directory (defaults to extension name)
  -l|--lint          check syntax only, don't create output
  --linespecs        generate #line specs
  -x|--experimental  deprecated
  --function         create a function skeleton from a proto right away
  --version          show version info

the following options are inherited from ext_skel:
  --extname=module   module is the name of your extension 
  --proto=file       file contains prototypes of functions to create
  --xml              generate xml documentation to be added to phpdoc-cvs

these wait for functionality to be implemented and are ignored for now ...
  --stubs=file       generate only function stubs in file
  --no-help          don't try to be nice and create comments in the code
                     and helper functions to test if the module compiled

these are accepted for backwards compatibility reasons but not used ...
  --full-xml         generate xml documentation for a self-contained extension
                     (this was also a no-op in ext_skel) 
  --skel=dir         path to the skeleton directory
                     (skeleton stuff is now self-contained)

</PRE
></DIV
></DIV
><DIV
CLASS="chapter"
><HR><H1
><A
NAME="AEN87"
></A
>Chapter 2. The XML description</H1
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="AEN89"
>2.1. Basics</A
></H2
><P
>    The top level container tag describing an extension is the
    <TT
CLASS="literal"
><extension></TT
> tag. The name of the extension
    is given in the <TT
CLASS="literal"
>name=...</TT
> attribute. The extension
    name has to be a valid C name as it is used as both the extensions
    directory name and the base name for several C symbols within the
    generated C code.
   </P
><P
>	You can specify which CodeGen_PECL version your specification file
    was written against using the <TT
CLASS="literal"
>version=...</TT
> attribute.
    The <TT
CLASS="filename"
>pecl-gen</TT
> command will not accept specifications
    written for a newer version of CodeGen_PECL than the one installed.
    If the requested version is older then the current one then CodeGen_PECL
    will try to fall back to the older versions behavior for features
    that have changed in incompatible ways.
   </P
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>     So far two such changes have happened: in version 0.9.0 a new
     prototype parser was introduced that might not be 100% backwards
     compatible with the older one and with 1.0.0 the names of some
     of the variables in the generated code changed.
    </P
></TD
></TR
></TABLE
></DIV
><P
>    The tags <TT
CLASS="literal"
><summary></TT
> and
    <TT
CLASS="literal"
><description></TT
> should be added at the very top of
    your extensions. The summary should be a short one-line
    description of the extension while the actually description can be
    as detailed as you like. Both are later used to generate the
    <TT
CLASS="literal"
>package.xml</TT
> file and the documentation for your
    extension. The summary line is also put into the
    <TT
CLASS="literal"
>phpinfo()</TT
> output of your extension.
   </P
><DIV
CLASS="example"
><A
NAME="AEN104"
></A
><P
><B
>Example 2-1. Extension basics</B
></P
><PRE
CLASS="programlisting"
>
<?xml version="1.0" ?>
<!DOCTYPE extension SYSTEM "../extension.dtd"> 
<extension name="sample" version="0.9.0">
 <summary>A sample PHP extension</summary>
 <description>
  This is a sample extension specification
  showing how to use CodeGen_PECL for
  extension generation.
 </description>
 ...

</PRE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="AEN107"
>2.2. Grouping</A
></H2
><P
>    The <group> tag can be used to group tag elements that can
    appear under the top level <extension> tag. <group>
    tags may be nested and can take arbitrary attributes. 
   </P
><P
>    The elements within a group may query the group stack for 
    default values for an attribute supported by the tag but
    not given for the tag itself or to add accumulated values
    from all nested groups surrounding the tag itself.
   </P
><P
>    Currently the only attribute that takes group values in account
    is the 'if' attribute on the following element tags:
    <class>, <constant>, <function>,<global>, 
    <interface>, <phpini>, and <resource>.
   </P
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="AEN112"
>2.3. Release information</A
></H2
><P
>    The release information for your extension should include the
    extension authors and maintainers, the version number, state and
    release date, the chosen license and maybe a change log describing
    previous releases. It is also possible to specify an image file
    to be used as a product logo with the <TT
CLASS="literal"
>phpinfo()</TT
>
    output block for the extension.
   </P
><P
>    The <TT
CLASS="literal"
><maintainers></TT
>, <TT
CLASS="literal"
><release></TT
> and
    <TT
CLASS="literal"
><changelog></TT
> tags specifications are identical to  
    those in  the PEAR <TT
CLASS="literal"
>package.xml</TT
> specification so 
    please refer to the 
    <A
HREF="http://pear.php.net/manual/en/developers.packagedef.php"
TARGET="_top"
>PEAR documentation</A
> 
    here.
   </P
><P
>    If you are going to release the extension using your own channel server instead of pear.php.net
    you have to add a <channel> tag that specifies the channel host you are releasing on, too.
   </P
><DIV
CLASS="example"
><A
NAME="AEN123"
></A
><P
><B
>Example 2-2. Release information</B
></P
><PRE
CLASS="programlisting"
>
...
  <maintainers>
    <maintainer>
      <user>hholzgra</user>
      <name>Hartmut Holzgraefe</name>
      <email>hartmut@php.net</email>
      <role>lead</role>
    </maintainer>
  </maintainers>

<channel>pear.php-baustelle.de</channel>

<release>
    <version>1.0</version>
    <date>2002-07-09</date>
    <state>stable</state>
    <notes>
     The sample extension is now stable
    </notes>
  </release>

<changelog>
    <release>
      <version>0.5</version>
      <date>2002-07-05</date>
      <state>beta</state>
      <notes>First beta version</notes>
    <release>
    <release>
      <version>0.1</version>
      <date>2002-07-01</date>
      <state>alpha</state>
      <notes>First alpha version</notes>
    <release>
  </changelog>
...

</PRE
></DIV
><P
>    The <TT
CLASS="literal"
><license></TT
> tag is a little more restrictive as
    its <TT
CLASS="literal"
>package.xml</TT
> counterpart as it is used to
    decide which license text should actually be written to the
    <TT
CLASS="literal"
>LICENSE</TT
>. For now you have to specify either
    <TT
CLASS="literal"
>PHP</TT
>, <TT
CLASS="literal"
>BSD</TT
> or
    <TT
CLASS="literal"
>LGPL</TT
>, any other value is taken as
    '<SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>unknown</I
></SPAN
>'.
   </P
><DIV
CLASS="warning"
><P
></P
><TABLE
CLASS="warning"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/warning.gif"
HSPACE="5"
ALT="Warning"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>     The GPL is not available as a valid license here due to incompatibilities
     between the GPL and the PHP licese. Please refer to the 
     <A
HREF="http://www.fsf.org/licensing/licenses/index_html"
TARGET="_top"
>FSF license comparison page</A
>
     for further information on this issue.
    </P
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="example"
><A
NAME="AEN137"
></A
><P
><B
>Example 2-3. License</B
></P
><PRE
CLASS="programlisting"
>
...
  <license>PHP</license>
...

</PRE
></DIV
><P
>    A logo to be used within the extensions
    <TT
CLASS="literal"
>phpinfo()</TT
> block can be specified using the
    <TT
CLASS="literal"
><logo></TT
> tag. The actual logo image data
    may be read from a file specified by the <TT
CLASS="literal"
>scr=...</TT
> 
    attribute, or it may be included inline in base64 encoded form
    within the <TT
CLASS="literal"
><logo></TT
> tag.
    Its MIME type may be specified using the
    <TT
CLASS="literal"
>mimetype=...</TT
> attribute. Automatic MIME type
    detection exists for GIF, PNG and JPEG images.
   </P
><DIV
CLASS="example"
><A
NAME="AEN146"
></A
><P
><B
>Example 2-4. Loading a logo image from a file</B
></P
><PRE
CLASS="programlisting"
>
...
  <logo src="sample_logo.gif" mimetype="image/gif" />
...

</PRE
></DIV
><DIV
CLASS="example"
><A
NAME="AEN149"
></A
><P
><B
>Example 2-5. An inline logo image</B
></P
><PRE
CLASS="programlisting"
>...
  <logo>
<![CDATA[
R0lGODdhFQASAOMAAMDEwJCQkLCwsGhoaFhcWLjAuDA0MPj8+FBUUPj4+AAA
AAAAAAAAAAAAAAAAAAAAACwAAAAAFQASAAAEehDISWsNQIhBuv+DphWhABhH
qq5GpgHluc5HK24vmiKGwfeIgdAU0wkSyCQSkAhgQhgdQUlNCAKkq0BaVWqh
29S0i8QRtFyyNXQOhA9jshktVq8F7Xe8O3en5WxXTgEcdn2DAwF2hHiCGoQc
HASSQgRukwiZmpucmwYRADs=
]]>
  </logo>
...
    </PRE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="AEN152"
>2.4. Dependencies</A
></H2
><P
>    Dependencies are specified within the <TT
CLASS="literal"
><deps></TT
>
    environment. Within the <TT
CLASS="literal"
><deps></TT
> section itself it is
    possible to set the programming language and target platforms using
    the <TT
CLASS="literal"
>language=...</TT
> and
    <TT
CLASS="literal"
>platform=...</TT
> attributes.
   </P
><P
>    Supported languages are C (<TT
CLASS="literal"
>lang="c"</TT
>) and C++
    (<TT
CLASS="literal"
>lang="cpp"</TT
>). The language selection 
    does not influence code generation itself
    (<TT
CLASS="literal"
>pecl-gen</TT
> always generates C code as the PHP extension
    API is a pure C API) but the way
    extensions are compiled and linked. C++ should only be selected to
    interface to external C++ libraries.
   </P
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>     I've been thinking about a Delphi backend, too. But as this would require
     a substantial ammount of work (the complete code generation would have
     to become template based) i'm not going to start this unless there's 
     massive interest in something like this or unless someone is willing to
     financially sponsor this kind of work.
    </P
></TD
></TR
></TABLE
></DIV
><P
>    Supported platforms are currently Unix-like systems
    (<TT
CLASS="literal"
>platform="unix"</TT
>), Microsoft Windows
    (<TT
CLASS="literal"
>platform="win32"</TT
>) or both (<TT
CLASS="literal"
>platform="all"</TT
>).
   </P
><P
> 
    <TT
CLASS="literal"
><with></TT
>, <TT
CLASS="literal"
><lib></TT
> and 
    <TT
CLASS="literal"
><header></TT
> tags may be used within the 
    <TT
CLASS="literal"
><deps></TT
> section to add configure switches 
    and library and header file dependencies.
   </P
><DIV
CLASS="example"
><A
NAME="AEN174"
></A
><P
><B
>Example 2-6. Dependencies</B
></P
><PRE
CLASS="programlisting"
>
...
  <deps language="cpp" platform="win32">
  ...
  </deps>
...

</PRE
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="AEN177"
>2.4.1. <TT
CLASS="literal"
>--with...</TT
></A
></H3
><P
>     When building an extension on Unix-like systems or within the
     Cygwin environment under Windows the <TT
CLASS="literal"
>configure</TT
>
     script will try to figure out where external libraries and header
     files needed by an extension are installed on the build system.
     Using a <TT
CLASS="literal"
>--with-...</TT
> option it is possible to specify where to actually
     look for libraries and headers. This way it is possible to
     override search paths if things are not installed in the default
     system paths or to specify the exact version of a package to be
     used if multiple versions are installed on the target system.
    </P
><P
>     The <TT
CLASS="literal"
><with></TT
> tag takes three attributes:
     <TT
CLASS="literal"
>name=...</TT
> for the actual name of the <TT
CLASS="literal"
>--with-...</TT
>
     option, <TT
CLASS="literal"
>testfile</TT
> for the relative path of a
     file to check for while running the <TT
CLASS="literal"
>configure</TT
>
     script and a list of default paths to check if no path is given
     as an argument to the <TT
CLASS="literal"
>--with-...</TT
> option in
     <TT
CLASS="literal"
>defaults</TT
>. 
    </P
><P
>     Name and defaults are set to the extension base name and
     <TT
CLASS="filename"
>/usr:/usr/local</TT
> if no values are given. 
     The testfile attribute is mandatory.
    </P
><P
>     Textual data enclosed by the <TT
CLASS="literal"
><with></TT
> is used to
     describe the "with" option in the output of <TT
CLASS="literal"
>configure
      --help</TT
> calls.
    </P
><DIV
CLASS="example"
><A
NAME="AEN196"
></A
><P
><B
>Example 2-7. <TT
CLASS="literal"
>--with...</TT
></B
></P
><PRE
CLASS="programlisting"
> 
 
... 
  <with name="libz" defaults='/usr:/usr/local:/usr/local/zlib' testfile='include/zlib.h'>
...

</PRE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="AEN200"
>2.4.2. Header files</A
></H3
><P
>     It is possible to specify header files needed by the extension
     using the <TT
CLASS="literal"
><header></TT
>. Any headers specified have
     to exist in the include path set for compiling (see also the
     section on <TT
CLASS="literal"
>--with</TT
>
     above). <TT
CLASS="literal"
>#include</TT
> statements for the specified
     headers are the last ones to be put into the generated code
     unless you set the <TT
CLASS="literal"
>prepend="yes"</TT
> attribute to
     have it put in front of the other <TT
CLASS="literal"
>#include</TT
>s.
    </P
><P
>     By default header files are searched for in the <TT
CLASS="literal"
>include</TT
>
     subdirectory of the path given in <TT
CLASS="literal"
><with></TT
>. If a
     different relative path needs to be used it can be defined using
     the <TT
CLASS="literal"
>path</TT
> attribute.
    </P
><DIV
CLASS="example"
><A
NAME="AEN212"
></A
><P
><B
>Example 2-8. Header file dependencies</B
></P
><PRE
CLASS="programlisting"
>
...
    <header name="include_me_first.h" prepend="yes" />
    <header name="sample.h" />
    <header name="foobar.h" path="include/foo/bar" />    
...

</PRE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="AEN215"
>2.4.3. Libraries</A
></H3
><P
>     Needed external libraries are specified using the
     <TT
CLASS="literal"
><lib></TT
> tag. The <TT
CLASS="literal"
>name=...</TT
>
     attribute is mandatory and takes the library base name. A library
     dependency by the name "sample" is actually referring to a library
     file named <TT
CLASS="filename"
>libsample.a</TT
> for a static or  
     <TT
CLASS="filename"
>libsample.so</TT
> for a dynamic library on
     Unix-like systems or to <TT
CLASS="filename"
>sample.DLL</TT
> on
     Windows.
    </P
><P
>     It is possible to specify the name of a function symbol expected
     to be provided by the library using the
     <TT
CLASS="literal"
>function=...</TT
> attribute. This function symbol
     is being looked for when <TT
CLASS="literal"
>configure</TT
> is run for
     the extension. This way it is possible to verify that the right
     version of a library was found. With VisualStudio on windows it
     is not possible to perform this check, in this case the library
     is just added to the project file.
    </P
><DIV
CLASS="example"
><A
NAME="AEN226"
></A
><P
><B
>Example 2-9. Library dependencies</B
></P
><PRE
CLASS="programlisting"
>
...
    <lib name="sample_u" platform="unix"  function="sample_v2" />
    <lib name="sample_w" platform="win32" />
    <lib name="sample"   platform="all" />
...

</PRE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="AEN229"
>2.4.4. Dependencies to other extensions</A
></H3
><P
>     Starting with PHP 5.1 it is possible to define dependendies 
     between extensions. Dependencies determine the order in which
     extensions are initialized and shut down. They also make sure
     that extensions like <TT
CLASS="literal"
>pdo_mysql</TT
> that require a
     base extension like <TT
CLASS="literal"
>pdo</TT
> are only loaded if 
     that extension is present and that two extensions that would
     conflict whith each other are not loaded at the same time.
    </P
><P
>     A dependency is defined using an <TT
CLASS="literal"
><extension></TT
> 
     tag within <TT
CLASS="literal"
><deps></TT
>.
     Here the <TT
CLASS="literal"
><extension></TT
> takes at least
     a <TT
CLASS="literal"
>name=...</TT
>. 
    </P
><P
>     By default this means that the 
     extension by that name is required by your extension and has
     to be initialized first. This behavior can also explicitly
     be requested by setting the <TT
CLASS="literal"
>type=...</TT
> attribute 
     to <TT
CLASS="literal"
>REQUIRED</TT
>. Other possible values are 
     <TT
CLASS="literal"
>OPTIONAL</TT
> if the other extension should 
     be initialized first if present but is not required by your
     extension and <TT
CLASS="literal"
>CONFLICTS</TT
> if your extension
     and the other one conflict in some way and should not be
     loaded at the same time.
    </P
><P
>     The extension API and CodeGen_PECL also allow to specify
     version checks on dependencies, the actual checks are
     not yet implemented as of PHP 5.1 though. CodeGen_PECL
     allready supports these anyhow, and as soon as the functionality
     is implemented within PHP the generated extensions will
     make use of it.
    </P
><P
>     Version dependencies are defined using 
     the <TT
CLASS="literal"
>version=...</TT
> attribute and the
     optional <TT
CLASS="literal"
>rel=...</TT
> attribute. 
     <TT
CLASS="literal"
>version</TT
> takes a 'PHP-standardized'
     version number string (see http://php.net/version_compare)
     and <TT
CLASS="literal"
>rel</TT
> defines the operator to be
     used to compare the actual extension version with the
     one in <TT
CLASS="literal"
>version</TT
>. The default value
     for <TT
CLASS="literal"
>rel</TT
> is <TT
CLASS="literal"
>>=</TT
>,
     so the extensions version number has to be at least as
     high as specified. Possible <TT
CLASS="literal"
>>=</TT
>
     values are <TT
CLASS="literal"
>>=</TT
>, <TT
CLASS="literal"
>></TT
>, 
     <TT
CLASS="literal"
>=</TT
>, <TT
CLASS="literal"
><</TT
> and 
     <TT
CLASS="literal"
><=</TT
> or their text alternatives 
     <TT
CLASS="literal"
>ge</TT
>, <TT
CLASS="literal"
>gt</TT
>, 
     <TT
CLASS="literal"
>eq</TT
>, <TT
CLASS="literal"
>lt</TT
> and 
     <TT
CLASS="literal"
>le</TT
>.
    </P
><DIV
CLASS="example"
><A
NAME="AEN264"
></A
><P
><B
>Example 2-10. Extension dependencies</B
></P
><PRE
CLASS="programlisting"
>
       <deps>
        <extension name="standard"/>
        <extension name="foobar"      type="OPTIONAL"/>
        <extension name="alternative" type="CONFLICTS"/>
        <extension name="xxx" version="3.2.1" rel="ge"/>
       </deps>

</PRE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="AEN267"
>2.4.5. External programs</A
></H3
><P
>     Not supported yet.
    </P
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="AEN270"
>2.4.6. Other files</A
></H3
><P
>     Not supported yet.
    </P
></DIV
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="AEN273"
>2.5. Custom code</A
></H2
><P
>    Custom code may be added to your extension source files using the
    <TT
CLASS="literal"
><code></TT
> tags. The <TT
CLASS="literal"
>role=...</TT
>
    and <TT
CLASS="literal"
>position=...</TT
> tags specify the actual place
    in there generated source files where your code should be
    inserted.
   </P
><P
>    Possible roles are '<TT
CLASS="literal"
>code</TT
>' (default) for the generated C
    or C++ code file and '<TT
CLASS="literal"
>header</TT
>' header file.
    Possible positions are '<TT
CLASS="literal"
>top</TT
>' and '<TT
CLASS="literal"
>bottom</TT
>'
    (default) for insertion near the beginning or end of the generated file.
   </P
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="AEN284"
>2.6. Conditional compilation</A
></H2
><P
>    For some code elements it is possible to define conditional compilation
    by using the <TT
CLASS="literal"
>if=...</TT
> attribute. The argument to this
    attribute is ment to be a valid C preprocessor expression which can be
    used in an "#if" directive.
   </P
><P
>    To compile in and register a function only if a certain library feature
    is available you may simply use the <TT
CLASS="literal"
>HAVE_...</TT
> macros
    that configure writes into config.h:
   </P
><DIV
CLASS="example"
><A
NAME="AEN290"
></A
><P
><B
>Example 2-11. Conditional compilation</B
></P
><P
>     For a function like this that should only be available if
     configure has detected either the FOO or BAR feature:
    </P
><PRE
CLASS="programlisting"
>
  <function name="foobar" if="HAVE_FOO || HAVE_BAR">
    ...
  </function>

</PRE
><P
>     so all code generated for this function will put into conditional 
     code blocks like this:
    </P
><PRE
CLASS="programlisting"
>#if HAVE_FOO || HAVE_BAR
  ...
#endif
    </PRE
></DIV
><P
>    So far conditional compilation is only available for procedural
    functions but it will be added for other code elements, too, in
    the near future.
   </P
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="AEN297"
>2.7. PHP functions</A
></H2
><P
>     The definition of a PHP function requires 
     <TT
CLASS="literal"
>name=...</TT
> attribute and at least the
     <TT
CLASS="literal"
><proto></TT
> tag to be set.
    </P
><P
>     The function name may be any valid C name. To comply to PHP
     coding conventions a public function provided by an extension
     should always be prefixed by the extension name though.
    </P
><P
>     The function prototype specified using the
     <TT
CLASS="literal"
><proto></TT
> tag is parsed to extract the return
     type, the function name and the argument list. The function name
     in the prototype has to match the name attribute given in the
     <TT
CLASS="literal"
><function></TT
>.
    </P
><P
>     Valid types to be used for arguments and the return type are:
     <P
></P
><UL
><LI
><P
><SPAN
CLASS="type"
>bool</SPAN
></P
></LI
><LI
><P
><SPAN
CLASS="type"
>int</SPAN
></P
></LI
><LI
><P
><SPAN
CLASS="type"
>float</SPAN
></P
></LI
><LI
><P
><SPAN
CLASS="type"
>string</SPAN
></P
></LI
><LI
><P
><SPAN
CLASS="type"
>array</SPAN
></P
></LI
><LI
><P
><SPAN
CLASS="type"
>object</SPAN
></P
></LI
><LI
><P
><SPAN
CLASS="type"
>mixed</SPAN
></P
></LI
><LI
><P
><SPAN
CLASS="type"
>callback</SPAN
></P
></LI
><LI
><P
><SPAN
CLASS="type"
>resource</SPAN
> <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>[typename]</I
></SPAN
></P
></LI
><LI
><P
><SPAN
CLASS="type"
>stream</SPAN
></P
></LI
></UL
>
     Argument names in prototypes are not prepended by a <TT
CLASS="literal"
>$</TT
> 
     sign by convention.
    </P
><P
>     Function documentation should be given using the
     <TT
CLASS="literal"
><summary></TT
> tag for a one line description and the
     <TT
CLASS="literal"
><description></TT
> tag for a more detailed
     description.
     Both are copied to the generated DocBook XML
     documentation for that function. Within <TT
CLASS="literal"
><description></TT
>
     DocBook tags may be used. Be aware though that while <B
CLASS="command"
>pecl-gen</B
>
     accepts this validating XML parsers may complain when reading/validating
     an extension specification file.
    </P
><P
>     Skeleton code for parameter parsing and result passing is
     generated if  no <TT
CLASS="literal"
><code></TT
> fragment is specified
     for a function. A <TT
CLASS="literal"
><code></TT
> section is inserted
     right after the generated parameter parsing code. Setting a
     return value is up to the code fragment if any is given, adding a
     template doesn't make sense in this case.
    </P
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="AEN348"
>2.7.1. Function prototypes</A
></H3
><P
>      A functions parameters and return type are specified by the contents
      of a functions <TT
CLASS="literal"
><proto></TT
> tag. 
      The <TT
CLASS="literal"
><proto></TT
> tag uses the same format as the
      <TT
CLASS="literal"
>proto</TT
> lines within the PHP source code:
      <P
></P
><UL
><LI
><P
>        there is no <TT
CLASS="literal"
>$</TT
> prefix for parameter names
       </P
></LI
><LI
><P
>        types are specified for function parameters and a functions return type
       </P
></LI
><LI
><P
>        optional parameters are enclosed by square brackets
       </P
></LI
><LI
><P
>        optional parameters may be given a default value
       </P
></LI
><LI
><P
>        functions with a variable number of arguments may be defined by
        ading <TT
CLASS="literal"
>...</TT
> as last entry in the parameter list
       </P
></LI
></UL
>
     </P
><DIV
CLASS="example"
><A
NAME="AEN367"
></A
><P
><B
>Example 2-12. Function prototype examples</B
></P
><PRE
CLASS="programlisting"
>
        // no parameter, no return value
        void   funcname(void);

// one int parameter, returning int
        int    funcname(int param);

// returning string, taking one mandatory and two
        // optional parameter
        string funcname(string param1 [[, string param2], string param3]);

// optional parameter with default value
        int funcname([int param = 42]);

// variable argument list
        int funcname(string param1, ...);

// working with objects and resources
        object foo funcname(resource bar param1);

</PRE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="AEN370"
>2.7.2. Parameter types</A
></H3
><P
>       
      </P
><DIV
CLASS="section"
><HR><H4
CLASS="section"
><A
NAME="AEN373"
>2.7.2.1. <SPAN
CLASS="type"
>bool</SPAN
></A
></H4
><P
>        <SPAN
CLASS="type"
>bool</SPAN
> parameters are internally mapped to local 
        <SPAN
CLASS="type"
>zend_bool</SPAN
> variables.
       </P
><DIV
CLASS="example"
><A
NAME="AEN379"
></A
><P
><B
>Example 2-13. <SPAN
CLASS="type"
>bool</SPAN
> parameter</B
></P
><PRE
CLASS="programlisting"
>
<function name="f_bool">
 <proto>void f_bool(bool param)</void>
 <code>
  if (param) {
    ...
  } else {
    ...
  }
 </code>
</function>

</PRE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H4
CLASS="section"
><A
NAME="AEN383"
>2.7.2.2. <SPAN
CLASS="type"
>int</SPAN
></A
></H4
><P
>        <SPAN
CLASS="type"
>int</SPAN
> parameters are internally mapped to local
        <SPAN
CLASS="type"
>long</SPAN
> variables.
       </P
></DIV
><DIV
CLASS="section"
><HR><H4
CLASS="section"
><A
NAME="AEN389"
>2.7.2.3. <SPAN
CLASS="type"
>float</SPAN
></A
></H4
><P
>        <SPAN
CLASS="type"
>float</SPAN
> parameters are internally mapped to local
        <SPAN
CLASS="type"
>double</SPAN
> variables.
       </P
></DIV
><DIV
CLASS="section"
><HR><H4
CLASS="section"
><A
NAME="AEN395"
>2.7.2.4. <SPAN
CLASS="type"
>string</SPAN
></A
></H4
><P
>        For a <SPAN
CLASS="type"
>string</SPAN
> parameter two local variables are
        created: a <SPAN
CLASS="type"
>char*</SPAN
> pointing to the actual string
        data and an <SPAN
CLASS="type"
>int</SPAN
> containing the string length.
       </P
><P
>        The <SPAN
CLASS="type"
>char *</SPAN
> goes by the name of the parameter,
        the <SPAN
CLASS="type"
>int</SPAN
> gets an extra <TT
CLASS="literal"
>_len</TT
>
        postfix appended to the parameter name.
       </P
><DIV
CLASS="example"
><A
NAME="AEN406"
></A
><P
><B
>Example 2-14. <SPAN
CLASS="type"
>bool</SPAN
> parameter</B
></P
><PRE
CLASS="programlisting"
>
<function name="f_string">
 <proto>void f_string(string param)</void>
 <code>
  int i;

for (i = 0; i < param_len; i++) {
    param[i] = toupper(param[i]);
  }
 </code>
</function>

</PRE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H4
CLASS="section"
><A
NAME="AEN410"
>2.7.2.5. <SPAN
CLASS="type"
>array</SPAN
></A
></H4
><P
>        For an <SPAN
CLASS="type"
>array</SPAN
> parameter two local variables are
        created: a <SPAN
CLASS="type"
>zval *</SPAN
> by the name of the parameter
        and a <SPAN
CLASS="type"
>HashTable *</SPAN
> with the postfix 
        <TT
CLASS="literal"
>_hash</TT
> added to the parameter name.
       </P
><P
>        To work with array parameters you have to use Zend API 
        functions like <CODE
CLASS="function"
>zend_hash_num_elements</CODE
>,
        <CODE
CLASS="function"
>zend_hash_internal_pointer_reset</CODE
> and
        <CODE
CLASS="function"
>zend_hash_get_current_data_ex</CODE
>.
       </P
><P
> 
        How to work with Zend <SPAN
CLASS="type"
>HashTable</SPAN
> and the 
        <CODE
CLASS="function"
>zend_hash_...</CODE
> functions is beyond
        the scope of this documentation though.
       </P
></DIV
><DIV
CLASS="section"
><HR><H4
CLASS="section"
><A
NAME="AEN425"
>2.7.2.6. <SPAN
CLASS="type"
>object</SPAN
></A
></H4
><P
>        For PHP objects local <SPAN
CLASS="type"
>zval *</SPAN
> variables
        pointing to the actual object instances are created.
        How to operate on these is beyond the scope of this
        document.
       </P
></DIV
><DIV
CLASS="section"
><HR><H4
CLASS="section"
><A
NAME="AEN430"
>2.7.2.7. <SPAN
CLASS="type"
>resource</SPAN
></A
></H4
><P
>        For <SPAN
CLASS="type"
>resource</SPAN
> parameters three local variables
        are created:
        <P
></P
><UL
><LI
><P
>           A pointer to the resource payload using the parameter name.
          </P
></LI
><LI
><P
>           A <SPAN
CLASS="type"
>zval *</SPAN
> pointer for the actual resource variable
           unsing the parameter name plus a <TT
CLASS="literal"
>_res</TT
> postfix.
           This needs to be used to free a resource using the 
           <CODE
CLASS="function"
>FREE_RESOURCE()</CODE
> macro.
          </P
></LI
><LI
><P
>           A <SPAN
CLASS="type"
>int</SPAN
> storing the numeric resource id using the
           parameter name plus a <TT
CLASS="literal"
>_resid</TT
> postfix.
          </P
></LI
></UL
>
        You'll usually only work on the actual payload data so you'll
        need the <CODE
CLASS="varname"
>name_res</CODE
> variable for calls to
        <CODE
CLASS="function"
>FREE_RESOURCE</CODE
> only and you'll usually 
        never have to touch the <CODE
CLASS="varname"
>var_resid</CODE
> variable
        at all.
       </P
></DIV
><DIV
CLASS="section"
><HR><H4
CLASS="section"
><A
NAME="AEN450"
>2.7.2.8. <SPAN
CLASS="type"
>callback</SPAN
></A
></H4
><P
>        ... not fully implemented yet ...
       </P
></DIV
><DIV
CLASS="section"
><HR><H4
CLASS="section"
><A
NAME="AEN454"
>2.7.2.9. <SPAN
CLASS="type"
>stream</SPAN
></A
></H4
><P
>        ... not fully implemented yet ...
       </P
></DIV
><DIV
CLASS="section"
><HR><H4
CLASS="section"
><A
NAME="AEN458"
>2.7.2.10. <SPAN
CLASS="type"
>mixed</SPAN
></A
></H4
><P
>        <SPAN
CLASS="type"
>mixed</SPAN
> parameters may be of any type so they are
        stored in generic <SPAN
CLASS="type"
>zval *</SPAN
> local variables only.
        How to operate on a <SPAN
CLASS="type"
>zval</SPAN
> using the Zend API
        is beyond the scope of this document.
       </P
></DIV
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="AEN465"
>2.7.3. Optional parameters</A
></H3
><P
>      Parameters at the end of the prototypes parameter list may be
      declared as optional. Each optional parameter needs to be put
      into square brackets. The simple types <SPAN
CLASS="type"
>bool</SPAN
>, 
      <SPAN
CLASS="type"
>int</SPAN
>, <SPAN
CLASS="type"
>float</SPAN
> and <SPAN
CLASS="type"
>string</SPAN
>
      may also be given a default value:
     </P
><DIV
CLASS="example"
><A
NAME="AEN472"
></A
><P
><B
>Example 2-15. Optional parameters</B
></P
><PRE
CLASS="programlisting"
>        // simple optional parameter
        int f1([int p1])

// optional parameter with default value 
        int f2([int p1 = 23])

// mandatory and multiple optional parameters 
        int f3(int p1 [, int p2 [, int p3]])
      </PRE
></DIV
><P
>      Future versions may also support dependant optional 
      parameters like:
      <DIV
CLASS="informalexample"
><P
></P
><A
NAME="AEN476"
></A
><PRE
CLASS="programlisting"
>        int f4(int p1, [int p3, int p3 [,int p4]])
       </PRE
><P
></P
></DIV
>
      This function would exept either one, three or four
      but not two parameters. For now this hasn't been 
      implemented yet though.
     </P
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="AEN478"
>2.7.4. Varargs</A
></H3
><P
>      You may declare functions that accept a variable number of arguments
      (like e.g. PHPs <CODE
CLASS="function"
>max()</CODE
> or <CODE
CLASS="function"
>printf</CODE
>)
      by adding <TT
CLASS="literal"
>'...'</TT
> to the end of your parameter list or as
      the only parameter list entry by itself. You may also additionally prefix
      the <TT
CLASS="literal"
>'...'</TT
> by one of the types <SPAN
CLASS="type"
>bool</SPAN
>, 
      <SPAN
CLASS="type"
>int</SPAN
>, <SPAN
CLASS="type"
>float</SPAN
>, <SPAN
CLASS="type"
>string</SPAN
> or <SPAN
CLASS="type"
>mixed</SPAN
>.
      If no type is given it defaults to <SPAN
CLASS="type"
>mixed</SPAN
>.
     </P
><P
> 
      The number of varargs parameters is stored in the local variable
      <CODE
CLASS="varname"
>varargc</CODE
>. The actual values are stored in an
      array named <CODE
CLASS="varname"
>varargv</CODE
>. The parameter values are
      stored using the associated C data type documented in the 
      'Parameter types' section above. 
      For the <SPAN
CLASS="type"
>string</SPAN
> type an extra array 
      <CODE
CLASS="varname"
>varargv_len</CODE
> containing the string lengthes
      is created.
     </P
><DIV
CLASS="example"
><A
NAME="AEN496"
></A
><P
><B
>Example 2-16. Varargs</B
></P
><PRE
CLASS="programlisting"
>
       <function name="f_vararg1">
        <proto>void f_vararg1(...)</proto>
        <code>...</code>
       </function>

<function name="f_vararg2">
        <proto>void f_vararg2(string format, ...)</proto>
        <code>...</code>
       </function>

<function name="f_vararg3">
        <proto>int f_vararg3(int...)</proto>
        <code>
          int i;
          long sum = 0;

for (i = 0; i < varargc; i++) {
            sum += varargv[i];
          }

RETURN_LONG(sum);
        </code>
       </function>

</PRE
></DIV
><P
>      For more examples see <TT
CLASS="filename"
>varargs.xml</TT
>
      in the <TT
CLASS="filename"
>docs/examples</TT
> directory.
     </P
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="AEN502"
>2.7.5. Pass by reference</A
></H3
><P
>     </P
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="AEN505"
>2.7.6. Return Values</A
></H3
><P
>     </P
><P
></P
><DIV
CLASS="variablelist"
><DL
><DT
><SPAN
CLASS="type"
>bool</SPAN
></DT
><DD
><P
>         Boolean values may be returned using the 
         <CODE
CLASS="function"
>RETURN_BOOL(b)</CODE
>,
         <CODE
CLASS="function"
>RETURN_TRUE</CODE
> and
         <CODE
CLASS="function"
>RETURN_FALSE</CODE
> macros.
        </P
></DD
><DT
><SPAN
CLASS="type"
>int</SPAN
></DT
><DD
><P
>         Integer values are returned using the
         <CODE
CLASS="function"
>RETURN_LONG(l)</CODE
> macro.
        </P
></DD
><DT
><SPAN
CLASS="type"
>float</SPAN
></DT
><DD
><P
>         Float values are returned using the
         <CODE
CLASS="function"
>RETURN_DOUBLE(d)</CODE
> macro.
        </P
></DD
><DT
><SPAN
CLASS="type"
>string</SPAN
></DT
><DD
><P
>         Strings may be returned using the
         <CODE
CLASS="function"
>RETURN_STRING(str, duplicate)</CODE
>,
         <CODE
CLASS="function"
>RETURN_STRINGL(str, len, duplicate)</CODE
>
         or <CODE
CLASS="function"
>RETURN_EMPTY_STRING()</CODE
> macros.
        </P
><P
>         <CODE
CLASS="function"
>RETURN_STRING()</CODE
> only works for zero
         terminated strings, using <CODE
CLASS="function"
>RETURN_STRINGL</CODE
>
         it is also possible to return binary strings containing null
         bytes. Both macros take a <CODE
CLASS="parameter"
>duplicate</CODE
>
         parameter which specifies whether the string data shall be
         duplicated. You'll always set this parameter to 1 unless
         you allocated the <CODE
CLASS="parameter"
>str</CODE
> value using
         e.g. <CODE
CLASS="function"
>emalloc()</CODE
> or 
         <CODE
CLASS="function"
>estrdup()</CODE
> yourself.
        </P
></DD
><DT
><SPAN
CLASS="type"
>resource</SPAN
></DT
><DD
><P
>         For <SPAN
CLASS="type"
>resource</SPAN
> values a special local variable
         <CODE
CLASS="varname"
>return_res</CODE
> is created which is a pointer
         to the resources payload type. Whether you need to allocate
         the payload data yourself or just need to store values in
         preallocated data pointed to by <CODE
CLASS="varname"
>return_res</CODE
>
         depends on the resources <TT
CLASS="literal"
>alloc</TT
> attribute.
        </P
><P
>         If allocation or initialization of the return resource fails
         you may simply <CODE
CLASS="function"
>RETURN_FALSE</CODE
> or 
         <CODE
CLASS="function"
>RETURN_NULL</CODE
> to return an error condition.
        </P
></DD
><DT
><SPAN
CLASS="type"
>array</SPAN
></DT
><DD
><P
>         To return an <SPAN
CLASS="type"
>array</SPAN
> you can add values to the
         <CODE
CLASS="varname"
>return_value</CODE
> variable which has already
         been initialized as an empty array.
        </P
><P
>         Values may be added to the <CODE
CLASS="varname"
>return_value</CODE
>
         result array using the various <CODE
CLASS="function"
>add_assoc_...()</CODE
>,
         <CODE
CLASS="function"
>add_index_...()</CODE
> and 
         <CODE
CLASS="function"
>add_index_next_...()</CODE
> from the Zend API.
        </P
></DD
><DT
><SPAN
CLASS="type"
>object</SPAN
></DT
><DD
><P
>         ...
        </P
></DD
></DL
></DIV
></DIV
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="AEN573"
>2.8. Internal functions</A
></H2
><P
>     Internal functions are called by the PHP extension API to initialize
     and shut down your extension and to retrieve status information for
     <CODE
CLASS="function"
>phpinfo()</CODE
> output.
    </P
><P
>     The definition of an internal function requires the
     <TT
CLASS="literal"
>role="internal"</TT
> and <TT
CLASS="literal"
>name=...</TT
>
     attributes to be set. The name can only be one of the following:
     <P
></P
><DIV
CLASS="variablelist"
><DL
><DT
><TT
CLASS="literal"
>MINIT</TT
></DT
><DD
><P
>         The module initialization function. This is called
         once at startup of a PHP server module or standalone (CLI or
         CGI) binary.
        </P
><DIV
CLASS="example"
><A
NAME="AEN586"
></A
><P
><B
>Example 2-17. <TT
CLASS="literal"
>MINIT()</TT
></B
></P
><PRE
CLASS="programlisting"
>...
    <function role="internal" name="MINIT">
      <code>
<![CDATA[
  library_init();
]]>
      </code>
    </function>
...
         </PRE
></DIV
></DD
><DT
><TT
CLASS="literal"
>MSHUTDOWN</TT
></DT
><DD
><P
>         The module shutdown function. This is called once when the
         PHP server module or standalone binary is properly
         terminated.
         It may not be called on program crashes or other critical errors.
        </P
><DIV
CLASS="example"
><A
NAME="AEN595"
></A
><P
><B
>Example 2-18. <TT
CLASS="literal"
>MINIT()</TT
></B
></P
><PRE
CLASS="programlisting"
>...
    <function role="internal" name="MINIT">
      <code>
<![CDATA[
  library_deinit();
]]>
      </code>
    </function>
...
         </PRE
></DIV
></DD
><DT
><TT
CLASS="literal"
>RINIT</TT
></DT
><DD
><P
>         The request shutdown function. This is called by PHP server
         modules before actually executing a PHP script request or once
         right after <TT
CLASS="literal"
>MINIT()</TT
> for standalone
         binaries (CGI or CLI).
        </P
><DIV
CLASS="example"
><A
NAME="AEN605"
></A
><P
><B
>Example 2-19. <TT
CLASS="literal"
>MINIT()</TT
></B
></P
><PRE
CLASS="programlisting"
>...
    <function role="internal" name="MINIT">
      <code>
<![CDATA[
  global_buffer = malloc(global_buffer_size);
]]>
      </code>
    </function>
...
         </PRE
></DIV
></DD
><DT
><TT
CLASS="literal"
>RSHUTDOWN</TT
></DT
><DD
><P
>         The request shutdown function. This is called by PHP server
         modules after execution of PHP code has been finished or
         terminated.
         Is called even if critical PHP errors occurred but you can not
         rely on it being called on critical errors or crashes on the
         C level.
        </P
><DIV
CLASS="example"
><A
NAME="AEN614"
></A
><P
><B
>Example 2-20. <TT
CLASS="literal"
>MINIT()</TT
></B
></P
><PRE
CLASS="programlisting"
>...
    <function role="internal" name="MINIT">
      <code>
<![CDATA[
  free(global_buffer);
]]>
      </code>
    </function>
...
         </PRE
></DIV
></DD
><DT
><TT
CLASS="literal"
>MINFO</TT
></DT
><DD
><P
>         The <TT
CLASS="literal"
>phpinfo()</TT
> handler for this extension.
         It will be called whenever <TT
CLASS="literal"
>phpinfo()</TT
> is
         invoked or when a standalone PHP binary is called with the
         <TT
CLASS="literal"
>-i</TT
> command line option.
        </P
><P
>         The default code generated when no <TT
CLASS="literal"
><code></TT
>
         section is given includes the extension name, summary line
         and release version and date, the optional logo image if
         specified, and the global and actual values of all
         <TT
CLASS="literal"
>php.ini</TT
> directives specified.
        </P
><DIV
CLASS="example"
><A
NAME="AEN629"
></A
><P
><B
>Example 2-21. <TT
CLASS="literal"
>MINFO()</TT
></B
></P
><PRE
CLASS="programlisting"
>...
    <function role='internal' name='MINFO'>
      <code>
<![CDATA[
  php_info_print_table_start();
  php_info_print_table_header(2, "test", "table");
  php_info_print_table_end();
]]>
      </code>
    </function>
...
         </PRE
></DIV
></DD
></DL
></DIV
>
    </P
><P
>     <TT
CLASS="literal"
><code></TT
> sections for the internal
     functions may be written as if they were C function bodies,
     including local variable definitions.
    </P
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="AEN635"
>2.9. Constants</A
></H2
><P
>    PHP constants are defined using <TT
CLASS="literal"
><constant></TT
>
    tags.
   </P
><P
>    The actual constant name, type and value are specified using the
    <TT
CLASS="literal"
>name=...</TT
>, <TT
CLASS="literal"
>type=...</TT
> and
    <TT
CLASS="literal"
>value=...</TT
> attributes. The constant name has to
    be a valid C name. PHP constant names should use uppercase letters
    only by convention. Possible types are <SPAN
CLASS="type"
>string</SPAN
>, <SPAN
CLASS="type"
>int</SPAN
> and
    <SPAN
CLASS="type"
>float</SPAN
>, the possible values depend on the type. For <SPAN
CLASS="type"
>int</SPAN
> and
    <SPAN
CLASS="type"
>float</SPAN
> you may use either numeric strings or the names of C
    constants (either true ANSI C/C++ constants or values
    <TT
CLASS="literal"
>#define</TT
>d using the C preprocessor. <SPAN
CLASS="type"
>string</SPAN
>
    values are always used "as is", no constants may be used here.
   </P
><P
>    Setting the <TT
CLASS="literal"
>define=...</TT
> attribute to 
    <TT
CLASS="literal"
>yes</TT
> defines not only a PHP constant but
    also adds a C #define with the same name and value to the
    generated header file so that the constant can be used 
    under the same name in both PHP and C code.
   </P
><P
>    It is sufficient on the other hand to specify a constant 
    <TT
CLASS="literal"
>name</TT
> only if a C integer constant should 
    be available under the same name in PHP, too.
   </P
><P
>    A descriptive text may be given as content of the
    <TT
CLASS="literal"
><constant></TT
> tag. This text will be used when
    generation the DocBook XML documentation.
   </P
><DIV
CLASS="example"
><A
NAME="AEN657"
></A
><P
><B
>Example 2-22. PHP Constants</B
></P
><PRE
CLASS="programlisting"
>
...
 <constants>
  <constant name="SAMPLE_INT"   type="int"    value="42">
   A sample integer constant.
  </constant>
  <constant name="SAMPLE_FLOAT" type="float"  value="3.14">
   A sample floating point constant.
  </constant>
  <constant name="SAMPLE_FLOAT" type="float"  value="M_PI">
   A sample floating point constant using a #defined constant
  </constant>
  <constant name="SAMPLE_STRING" type="string" value="Hello World!">
   A sample string constant.
  </constant>
  <constant name="SAMPLE_INT2" type="int" value="23>
   This also adds a <literal>#define SAMPLE_INT2 23</literal>
   definition to the generated header file.
  </constant>
  <constant name="MY_CONST">
   A shortcat for already #defined integer constants
  </constant>
 </constants>
...

</PRE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="AEN660"
>2.10. <TT
CLASS="literal"
>php.ini</TT
> parameters and internal variables</A
></H2
><P
>    An extension may define variables that are global to either the
    complete extension or to a specific request. True globals that are
    global to the complete extensions do not need any registration so
    they can be defined using C code within the global <TT
CLASS="literal"
><code></TT
> 
    tag.
   </P
><P
>    Module globals that are only global to a single request need to
    be managed to ensure thread safety and initialization on request
    initialization. <TT
CLASS="literal"
>php.ini</TT
> directive values are
    also stored as module globals but need some additional definitions.
   </P
><P
>    All global definitions have to be put into a
    <TT
CLASS="literal"
><globals></TT
> environment. Simple module globals are
    defined using the <TT
CLASS="literal"
><global></TT
>
    tag. <TT
CLASS="literal"
>php.ini</TT
> directives are defined using the
    <TT
CLASS="literal"
><phpini></TT
> tag.
   </P
><P
>    A <TT
CLASS="literal"
><global></TT
> definition requires the
    <TT
CLASS="literal"
>name=...</TT
> and <TT
CLASS="literal"
>type=...</TT
>
    attributes to be set as valid C names and types. Which C types are
    allowed depends on what type definitions have been included from
    header files. The available types are not known when
    <TT
CLASS="literal"
>pecl-gen</TT
> parses the XML specification so that
    types are only checked for valid name format here. Specifying a
    type that is not a basic C type or defined in any included file
    will lead to error messages when compiling the generated extension
    code later.
   </P
><P
>    Initial values may be specified using the
    <TT
CLASS="literal"
>value=...</TT
> attribute. This feature should only
    be used for simple numeric values, anything more complex should
    better be initialized within the extensions
    <TT
CLASS="literal"
>RINIT()</TT
> function. 
   </P
><P
>    <TT
CLASS="literal"
>php.ini</TT
> directives may be defined using the
    <TT
CLASS="literal"
><phpini></TT
> within a <TT
CLASS="literal"
><globals></TT
>
    environment. To define a <TT
CLASS="literal"
>php.ini</TT
> directive you
    have to specify its name, type and default value using the
    <TT
CLASS="literal"
>name=...</TT
>, <TT
CLASS="literal"
>type=...</TT
> and
    <TT
CLASS="literal"
>value=...</TT
> attributes.
   </P
><P
>    Valid directive names are C variable names. The actual directive
    name is the extension name followed by a single dot
    '<TT
CLASS="literal"
>.</TT
>' and the specified name. Valid directive
    types are <SPAN
CLASS="type"
>bool</SPAN
>, <SPAN
CLASS="type"
>int</SPAN
>, <SPAN
CLASS="type"
>float</SPAN
>
    and <SPAN
CLASS="type"
>string</SPAN
>.
   </P
><P
>    Directive default values are passed to the engine as strings, so
    you may not use any C constants or preprocessor macros here. The
    default value strings are parsed by the
    <TT
CLASS="literal"
>OnUpdate</TT
> handler registered for that
    directive. No value checking takes place during extension code
    generation or compilation, this is done by the registered
    <TT
CLASS="literal"
>OnUpdate</TT
> handler at runtime during request
    initialization. The <TT
CLASS="literal"
>OnUpdate</TT
> handler defaults
    to the appropriate internal
    <TT
CLASS="literal"
>OnUpdate</TT
><SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>type</I
></SPAN
> handler
    unless you specify a different handler using the
    <TT
CLASS="literal"
>onupdate=...</TT
> attribute.
   </P
><P
>    The directive value may be changed at any time unless you specify
    an <TT
CLASS="literal"
>access=...</TT
> attribute. Possible values are:
    <P
></P
><DIV
CLASS="variablelist"
><DL
><DT
>system</DT
><DD
><P
>        may only be set globally in <TT
CLASS="literal"
>php.ini</TT
> or the
        web server configuration
       </P
></DD
><DT
>perdir</DT
><DD
><P
>        may be changed in local <TT
CLASS="literal"
>.htaccess</TT
> files
       </P
></DD
><DT
>user</DT
><DD
><P
>may be changed by PHP code</P
></DD
><DT
>all</DT
><DD
><P
>may be changed by anyone at any time</P
></DD
></DL
></DIV
>
   </P
><P
>    The content data of <TT
CLASS="literal"
><phpini></TT
> tags is used to
    generate documentation for the defined
    directive. <TT
CLASS="literal"
><global></TT
> definitions may also include
    content data but it is for internal documentation only, it is not
    used in DocBook XML generation (yet).
   </P
><DIV
CLASS="example"
><A
NAME="AEN725"
></A
><P
><B
>Example 2-23. Defining globals and ini entries</B
></P
><PRE
CLASS="programlisting"
>
...
 <globals>
  <global name="sample_int"    type="int"    value="42" />
  <global name="sample_float"  type="float"  value="3.14" />
  <global name="SAMPLE_STRING" type="char *" />

<phpini name="my_int" type="int" value="42" onupdate="OnUpdateLong" access="all">
   Definition for directive "sample.my_int"
  </phpini>
 </globals>
...

</PRE
></DIV
><P
>    Access to the modul globals and ini parameters is provided in a thread safe 
    manner through the EXTNAME_G() macro (replace EXTNAME with the upper cased
    name of your extension).
   </P
><DIV
CLASS="example"
><A
NAME="AEN729"
></A
><P
><B
>Example 2-24. Using globals</B
></P
><PRE
CLASS="programlisting"
>
<extension name="foobar">
 ...
 <globals>
  <global name="sample_int"    type="int"    value="42" />
 </globals>
 ...
 <function ...>
  ...
  <code>
   ...
   int foo = FOOBAR_G(sample_int); // get global value 
   ...
   FOOBAR_G(sample_init) = 42; // set global value
   ...
  </code>
 </function>

</PRE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="AEN732"
>2.11. Resources</A
></H2
><P
>    You may define PHP resource types within a
    <TT
CLASS="literal"
><resources></TT
> environment. For each
    <TT
CLASS="literal"
><resource></TT
> you have to specify the
    <TT
CLASS="literal"
>name=...</TT
> and <TT
CLASS="literal"
>payload=...</TT
>
    attributes. The <TT
CLASS="literal"
>name</TT
> has to be a valid 
    C name and the <TT
CLASS="literal"
>payload</TT
> has to be a valid 
    C type specifier. The payload type can only be checked for 
    the correctness of its form as the actual type definitions 
    from included header files are not known to the extension 
    generator when it generates the extension code.
   </P
><P
>    The actual resource data structure carries a pointer to the
    payload type. You may specify that PHP shall allocate and free
    the actual payload by setting the <TT
CLASS="literal"
>alloc=...</TT
>
    attribute to "<TT
CLASS="literal"
>yes</TT
>". If the payload is allocated
    by a library function or by yourself you should set 
    <TT
CLASS="literal"
>alloc=...</TT
> to "<TT
CLASS="literal"
>no</TT
>" 
    (the default value).
   </P
><P
>    Resources are destructed when the last variable reference refering
    to them is unset or at request shutdown. If your resource
    payload needs to be cleaned up as well you have to add an
    appropriate C code snippet that takes care of this using the
    <TT
CLASS="literal"
><destruct></TT
> tag. Within the destructor snippet you
    may refer to the allocated payload using the
    <TT
CLASS="literal"
>resource</TT
> pointer variable.
   </P
><P
>    You don't need to take care of destruction yourself if  your
    resource payload is allocated by PHP (<TT
CLASS="literal"
>alloc="yes"</TT
>) 
    and needs no further cleanup work besides releasing the allocated memory.
   </P
><DIV
CLASS="example"
><A
NAME="AEN751"
></A
><P
><B
>Example 2-25. Resources</B
></P
><PRE
CLASS="programlisting"
>
...
  <resources>
    <resource name="sample_resource" payload="float" alloc="yes">
      <description>
        A simple floating point resource
      </description>
      
    </resource>

<resource name="sample_struct" payload="struct foobar" alloc="no">
      <description>
        A foobar resource managed by an external foobar lib.
      </description>
      <destruct>
        foobar_release(resource);
      </destruct>
    </resource>
  </resources>
...

</PRE
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="AEN754"
>2.11.1. Resource creation and destruction</A
></H3
><P
>     The creation of resource instances is not defined within
     <TT
CLASS="literal"
><resource></TT
>. This is a task to be handled by
     public PHP functions instead.
    </P
><DIV
CLASS="example"
><A
NAME="AEN758"
></A
><P
><B
>Example 2-26. Resource creation</B
></P
><PRE
CLASS="screen"
>
  <function name="foo_open">
   <proto>resource foo foo_open(string path)</proto>
   <code>
    return_res = foo_open(path);

if (!return_res) RETURN_FALSE;
   </code>
  </function>

</PRE
></DIV
><P
>     Resources are freed using the <TT
CLASS="literal"
>FREE_RESOURCE()</TT
>
     macro. The resources destructor
     function is automaticly called when freeing a resource.
    </P
><DIV
CLASS="example"
><A
NAME="AEN763"
></A
><P
><B
>Example 2-27. Resource destruction</B
></P
><PRE
CLASS="screen"
>
  <function name="foo_close">
   <proto>void foo_close(resource foo foores)</proto>
   <code>
     FREE_RESOURCE(foores);
   </code>
  </function>

</PRE
></DIV
></DIV
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="AEN766"
>2.12. OO features</A
></H2
><DIV
CLASS="warning"
><P
></P
><TABLE
CLASS="warning"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/warning.gif"
HSPACE="5"
ALT="Warning"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>     The OO APIs differ between PHP 4 and 5,  
     CodeGen_PECL only supports the newer PHP 5 API. 
    </P
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="AEN770"
>2.12.1. Classes</A
></H3
><P
>     Classes are declared using the <CODE
CLASS="sgmltag"
>class</CODE
> container.
	 Each class needs to be given a unique class name using the 
     <TT
CLASS="literal"
>name=...</TT
> attribute.
    </P
><DIV
CLASS="example"
><A
NAME="AEN775"
></A
><P
><B
>Example 2-28. A minimal class</B
></P
><PRE
CLASS="programlisting"
>
  <class name="minimal"/>

</PRE
></DIV
><DIV
CLASS="section"
><HR><H4
CLASS="section"
><A
NAME="AEN778"
>2.12.1.1. Inheritance</A
></H4
><P
>      Using the <TT
CLASS="literal"
>extends=...</TT
> attribut it is possible
      to inherit from another internal class. The class inherited from
      does not necessarily have to be defined in the same package so
      the given name is not checked for existance. An attempt to extend
      from a non-existing class will only be caught at PHP runtine.
     </P
><DIV
CLASS="example"
><A
NAME="AEN782"
></A
><P
><B
>Example 2-29. Simple inheritence</B
></P
><PRE
CLASS="programlisting"
>
  <class name="parent">
   <function name="foo">
    <proto>int foo()</proto>
    <code>RETURN_LONG(42);</code>
   </function>

<function name="bar">
    <proto>float bar()</proto>
    <code>RETURN_DOUBLE(3.14);</code>
   </function>
  </class>

<class name="child" extends="parent">
   <function name="foo">
    <proto>int foo()</proto>
    <code>RETURN_LONG(23);</code>
   </function>
  </class>

</PRE
></DIV
><P
> 	  The optional <TT
CLASS="literal"
>abstract=...</TT
> and 
      <TT
CLASS="literal"
>final=...</TT
> attributes can be used to declare
      a class as abstract (can be inherited from but can't be instanciated)
      or final (can't be inherited from anymore).
     </P
></DIV
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="AEN788"
>2.12.2. Methods</A
></H3
><P
>     Class methods (or member functions) are defined similar to regular
     functions using the <CODE
CLASS="sgmltag"
>function</CODE
> tag. In addition 
     to its global counterpart the <CODE
CLASS="sgmltag"
>function</CODE
>.
    </P
><P
>     The <TT
CLASS="literal"
>access=...</TT
> attribute defines the methods
     PPP access rights, possible values are <TT
CLASS="literal"
>public</TT
>,
     <TT
CLASS="literal"
>protected</TT
> and <TT
CLASS="literal"
>private</TT
> 
     (although defining a <TT
CLASS="literal"
>private</TT
> native method
     doesn't really make sense).
    </P
><P
>     The <TT
CLASS="literal"
>abstract</TT
> and <TT
CLASS="literal"
>final</TT
>
     attributes declare a method as abstract or final and have the
     same effect as the PHP keywords of the same name.
    </P
><P
>     The <TT
CLASS="literal"
>procedural=...</TT
> attribute requests the
     registration of a procedural alternative for this method. 
     This is a regular function that takes an instance of the class
     as first argument and allows to call
     <PRE
CLASS="programlisting"
>function($object, ...parameters...)</PRE
>
     instead of 
     <PRE
CLASS="programlisting"
>$object->method(...parameters...)</PRE
>.
    </P
><P
>     This feature is usefull when creating an extension that implements
     something as OO classes that used to be a resource type before,
     see the way <TT
CLASS="literal"
>ext/mysqli</TT
> reimplements the older
     <TT
CLASS="literal"
>ext/mysql</TT
> for example.
    </P
><P
>     The procedural functions name is <TT
CLASS="literal"
>classname_methodname</TT
>
     if you just use  <TT
CLASS="literal"
>procedural='yes'</TT
>, any other attribute
     value will be used as the functions name.
    </P
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="AEN812"
>2.12.3. Properties</A
></H3
><P
>     Class properties are defined using the <CODE
CLASS="sgmltag"
>property</CODE
> tag.
     The property name is given using the <TT
CLASS="literal"
>name=...</TT
> tag and
     is mandatory.
    </P
><P
>     Access to the property is public by default, it can be set to either
     <TT
CLASS="literal"
>public</TT
>, <TT
CLASS="literal"
>protected</TT
> or 
     <TT
CLASS="literal"
>private</TT
> using the optional 
     <TT
CLASS="literal"
>access=...</TT
> attribute.
    </P
><P
>     Property default type and value can be specified using the optional
     <TT
CLASS="literal"
>type=...</TT
> and <TT
CLASS="literal"
>value=...</TT
> attributes.
     Possible types are <TT
CLASS="literal"
>long</TT
>, <TT
CLASS="literal"
>double</TT
>,
     <TT
CLASS="literal"
>string</TT
> and <TT
CLASS="literal"
>NULL</TT
>. The default
     value and type of a property are <TT
CLASS="literal"
>NULL</TT
> if not
     specified using these attributes.
    </P
><P
>     A property can be declared static using the <TT
CLASS="literal"
>static=...</TT
>
     attribute. A static attribute is shared by all instances of the class.
    </P
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="AEN832"
>2.12.4. Constants</A
></H3
><P
>     Class constants are defined like regular constants, just within a 
     <CODE
CLASS="sgmltag"
>class</CODE
> tag. Class constants are always public
     so there is no need for extra attributes.
    </P
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="AEN836"
>2.12.5. Interfaces</A
></H3
><P
>     Interfaces are declared using the <CODE
CLASS="sgmltag"
>interface</CODE
>
     which has two attributes: the mandatory <TT
CLASS="literal"
>name=...</TT
> 
     attribute defines the name of the interface and the optional 
     <TT
CLASS="literal"
>extends=...</TT
> attribute can be used to specify
     that this interface extends another already existing interface.
     If the interface that is to be extended is defined in another
     extension then an extension dependency should be declared, too.
    </P
><P
>     Interface methods are declared using the <CODE
CLASS="sgmltag"
>function</CODE
>
     tag. In this context only the <TT
CLASS="literal"
>name=...</TT
> attribute
     is supported as interface methods are always public and abstract and
     never final anyway. Within the <CODE
CLASS="sgmltag"
>function</CODE
> a 
     <CODE
CLASS="sgmltag"
>proto</CODE
> needs to be defined but there is no support
     for <CODE
CLASS="sgmltag"
>code</CODE
> or <CODE
CLASS="sgmltag"
>test</CODE
> tags within
     interface method declarations.
    </P
><P
>     A class can implement one or more interfaces, the interfaces 
     implemented by a class are declared using the <CODE
CLASS="sgmltag"
>implements</CODE
>
     tag and its <TT
CLASS="literal"
>interface=...</TT
> attribute. The interface
     needs to be defined in the extension specification (see "Interfaces"
     later in this section) or by one of the extensions specified in the
     package dependencies.
    </P
></DIV
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="AEN852"
>2.13. Streams</A
></H2
><P
>    Stream filter and wrapper support is experimental and not yet added
    to the released code base.
   </P
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="AEN855"
>2.14. config.m4 fragments</A
></H2
><P
>    Additional configure checks can be added to the generated config.m4
    file used by Unix/Cygwin builds using the <TT
CLASS="literal"
><configm4></TT
> 
    tag. Using the 'position' attribute it is possible to specify whether
    the additional code is to be added near the top or bottom of the 
    config.m4 file.
   </P
><DIV
CLASS="example"
><A
NAME="AEN859"
></A
><P
><B
>Example 2-30. config.m4 additions</B
></P
><PRE
CLASS="screen"
>
<configm4>
  AC_CHECK_PROG(RE2C, re2c, re2c)
  PHP_SUBST(RE2C)
</configm4>

</PRE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="AEN862"
>2.15. Makefile fragments</A
></H2
><P
>    Makefile rules may be added using the
    <TT
CLASS="literal"
><makefile></TT
> for Unix/Cygwin builds.
    Using this it is possible to add dependencies or build rules in
    addition to the default and auto generated rules.
   </P
><DIV
CLASS="example"
><A
NAME="AEN866"
></A
><P
><B
>Example 2-31. Makefile fragments</B
></P
><PRE
CLASS="screen"
>
<makefile>
$(builddir)/scanner.c: $(srcdir)/scanner.re
  $(RE2C) $(srcdir)/scanner.re > $@
</makefile>

</PRE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="AEN869"
>2.16. Tests</A
></H2
><P
>    Global test cases can be created using the <TT
CLASS="literal"
><test></TT
> tag.
    Test cases for functions are automaticly created. 
   </P
><P
>    Currently you have to make sure your extension is loaded by php.ini
    and have to perform the following steps to run the test suite
    (changing pathes to point to the right files on your system):
   </P
><PRE
CLASS="programlisting"
>
  TEST_PHP_EXECUTABLE="/usr/local/bin/php"   php path/to/run-tests.php tests

</PRE
><P
>    Starting with PHP 5.1 it should be possible to test PECL extensions
    by just typing <TT
CLASS="literal"
>make test</TT
> in the extension source
    dir, the changes needed for this are being reviewed right now and
    should hopefully be ready in time to be included in the PHP 5.1.0
    release.
   </P
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="AEN877"
>2.16.1. Global test cases</A
></H3
><P
>     Global test case scripts can be created using the <TT
CLASS="literal"
><test></TT
> tag.
     The <TT
CLASS="literal"
><test></TT
> has a single attribute <TT
CLASS="literal"
>name</TT
>. 
     As the test name is used as the test file basename <TT
CLASS="literal"
>name</TT
>
     has to be unique and only characters, digits and <TT
CLASS="literal"
>'-'</TT
> and
     <TT
CLASS="literal"
>'_'</TT
> are allowed in test names. A more readable test
     title may be set using the <TT
CLASS="literal"
><title></TT
> tag within 
     <TT
CLASS="literal"
><test></TT
>.
    </P
><P
>     The actual PHP code to run is specified using a <TT
CLASS="literal"
><code></TT
>
     section. The expected output is specified using a <TT
CLASS="literal"
><result></TT
>
     tag, it defaults to <TT
CLASS="literal"
>OK</TT
>. The PHP test suite supports three
     different ways to compare test output with the expected result: plain string
     comparison, comparison using printf style placeholders like %d for numbers
     and regular expresions (for details see the <TT
CLASS="filename"
>README.TESTING*</TT
>
     files in the PHP source). By default the <TT
CLASS="literal"
>plain</TT
> mode is used,
     the other two modes can be selected by setting the <TT
CLASS="literal"
>mode</TT
>
     attribute of <TT
CLASS="literal"
><result></TT
> to <TT
CLASS="literal"
>format</TT
> or
     <TT
CLASS="literal"
>regex</TT
>.
    </P
><P
>     The <TT
CLASS="literal"
>--SKIPIF--</TT
> section of the generated tests checks
     for the generated extension being loaded, the tests will automaticly be
     skiped if it is not available. Additional skip conditions can be added
     using the <TT
CLASS="literal"
><skipif></TT
> tag. The content of the tag may either
     be a PHP expression that evaluates to <TT
CLASS="literal"
>true</TT
> if the test
     should be skipped or a complete code snippet that prints <TT
CLASS="literal"
>skip</TT
>
     if the test is supposed to be skipped. A string describing the reason for
     the test being skipped may be added after the <TT
CLASS="literal"
>skip</TT
> in 
     this case.
    </P
><P
>     Additional php.ini settings to be used for testing may be specified in
     a <TT
CLASS="literal"
><ini></TT
> section.
    </P
><DIV
CLASS="example"
><A
NAME="AEN906"
></A
><P
><B
>Example 2-32. Minimal test case</B
></P
><PRE
CLASS="programlisting"
>
  <test name="echo">
   <code>echo "OK";</code>
  </test>

</PRE
></DIV
><DIV
CLASS="example"
><A
NAME="AEN909"
></A
><P
><B
>Example 2-33. Full test case</B
></P
><PRE
CLASS="programlisting"
>
  <test name="full">
   <title>A full test case using all tags</title>
   <skipif>1==0</skipif>
   <ini>max_execution_time=0</ini>
   <code>echo "Random number: ".rand(1,10);</code>
   <result mode='format'>Random number: %d</result>
  </test>

</PRE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="AEN912"
>2.16.2. Embedded function test cases</A
></H3
><P
>     For each function a default test case is created,
     the name and title for this test are automaticly set
     to the function name. 
    </P
><P
>	
     Test code and the expected result
     can be set using a <TT
CLASS="literal"
><test></TT
>
     section within <TT
CLASS="literal"
><function></TT
>.
     <TT
CLASS="literal"
><code></TT
>,
     <TT
CLASS="literal"
><result></TT
>,
     <TT
CLASS="literal"
><skipif></TT
> and
     <TT
CLASS="literal"
><ini></TT
>
     may be used in there in the same way as in a global
     <TT
CLASS="literal"
><></TT
> section. Use of the 
     <TT
CLASS="literal"
>name</TT
> attribute to 
     <TT
CLASS="literal"
><test></TT
> or the 
     <TT
CLASS="literal"
><title></TT
> tag are not 
     supported within a function test.
    </P
><DIV
CLASS="example"
><A
NAME="AEN926"
></A
><P
><B
>Example 2-34. Minimal function test case</B
></P
><PRE
CLASS="programlisting"
>
  <function name="foobar">
   ...
   <test><code>echo "OK";</code></test>
  </test>

</PRE
></DIV
><DIV
CLASS="example"
><A
NAME="AEN929"
></A
><P
><B
>Example 2-35. Full function test case</B
></P
><PRE
CLASS="programlisting"
>
  <function name="foobar">
   ...
   <test>
    <skipif>1==0</skipif>
    <ini>max_execution_time=0</ini>
    <code>echo "Random number: ".rand(1,10);</code>
    <result mode='format'>Random number: %d</result>
   <test>
  </function>

</PRE
></DIV
></DIV
></DIV
></DIV
><DIV
CLASS="chapter"
><HR><H1
><A
NAME="AEN932"
></A
>Chapter 3. XML input parsing</H1
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="AEN934"
>3.1. Includes</A
></H2
><P
>	The XML parser used by <TT
CLASS="literal"
>CodeGen_PECL</TT
> supports inclusion
    of additional source files using three different ways:
    <P
></P
><UL
><LI
><P
>external entities</P
></LI
><LI
><P
>a subset of XInclude</P
></LI
><LI
><P
>the <TT
CLASS="literal"
>source</TT
> attribute of <TT
CLASS="literal"
><code></TT
> tags</P
></LI
></UL
>
   </P
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="AEN947"
>3.1.1. External entities</A
></H3
><P
>     In SGML and early XML system entites were the only 
     include mechanism availabe. System entities have to
     be defined in the documents DOCTYPE header, later on
     in the document the entity can be used to include 
     the specified file:
    </P
><DIV
CLASS="example"
><A
NAME="AEN950"
></A
><P
><B
>Example 3-1. System Entities</B
></P
><PRE
CLASS="programlisting"
>
<?xml version="1.0" ?>
<!DOCTYPE extension SYSTEM "../extension.dtd" [
<!ENTITY systemEntity SYSTEM "parsing_1.xml">
]>
<extension name="foobar">
...
&systemEntity;
..
</extension>

</PRE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="AEN953"
>3.1.2. XInclude</A
></H3
><P
>     The <TT
CLASS="literal"
>CodeGen</TT
> XML parser supports a simple 
     subset of XInclude, it is possible to include additional
     specification files using the <TT
CLASS="literal"
>href=...</TT
>
     attribute of the <TT
CLASS="literal"
><include></TT
> tag:
    </P
><DIV
CLASS="example"
><A
NAME="AEN959"
></A
><P
><B
>Example 3-2. XInclude</B
></P
><PRE
CLASS="programlisting"
>
  <extension name="foobar" xmlns:xi="http://www.w3.org/2001/XInclude">
   ...
   <xi:include href="foobar_2.xml"/>
   ...
  </extension>

</PRE
></DIV
><P
>     The <TT
CLASS="literal"
>parse=...</TT
> attirbute is also supported, 
     using <TT
CLASS="literal"
><include parse='text' href='...'/></TT
> it is possible to
     include arbitrary data without parsing it as XML.
    </P
><DIV
CLASS="example"
><A
NAME="AEN965"
></A
><P
><B
>Example 3-3. Verbatim XInclude</B
></P
><PRE
CLASS="programlisting"
>
  <extension name="foobar" xmlns:xi="http://www.w3.org/2001/XInclude">
   ...
   <description><xi:include href="README" parse="text"/></description>
   ...
  </extension>

</PRE
></DIV
><P
>     Other <TT
CLASS="literal"
><include></TT
> features and the <TT
CLASS="literal"
><fallback></TT
>
     tag are not supported yet, and most of them won't make sense in this context anyway.
    </P
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="AEN971"
>3.1.3. <TT
CLASS="literal"
><code></TT
> tags</A
></H3
><P
>     In most places the <TT
CLASS="literal"
><code></TT
> tag supports loading of 
     its content using its <TT
CLASS="literal"
>src=...</TT
> attribute:
    </P
><DIV
CLASS="example"
><A
NAME="AEN977"
></A
><P
><B
>Example 3-4. Using <TT
CLASS="literal"
><code src="..."></TT
></B
></P
><PRE
CLASS="programlisting"
>
  <function name="foobar">
   ...
   <code src="func_foobar.c"/>
  </function>

</PRE
></DIV
></DIV
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="AEN981"
>3.2. Verbatim text data</A
></H2
><P
>    C code usually contains quite a few <TT
CLASS="literal"
>></TT
>, 
    <TT
CLASS="literal"
><</TT
> and <TT
CLASS="literal"
>&</TT
> characters
    all of which need to be escaped in XML. This can be done by either
    converting them into entities all over the place or by embedding
    the code into CDATA sections:
   </P
><DIV
CLASS="example"
><A
NAME="AEN987"
></A
><P
><B
>Example 3-5. CDATA sections</B
></P
><PRE
CLASS="programlisting"
><code>
<![CDATA[
  foo->bar = 42;
]]>
</code>
    </PRE
></DIV
><P
>    Typing <TT
CLASS="literal"
><![CDATA[</TT
> can become rather annoying
    over time (esp. on a german keyboard), so i introduced the 
    <TT
CLASS="literal"
><?data</TT
> processing instruction into the
    <TT
CLASS="literal"
>CodeGen</TT
> XML parser as an alternative to CDATA:
   </P
><DIV
CLASS="example"
><A
NAME="AEN994"
></A
><P
><B
>Example 3-6. <TT
CLASS="literal"
><?data</TT
> processing instruction</B
></P
><PRE
CLASS="programlisting"
>
<?data
  foo->bar = 42;
?>

</PRE
></DIV
></DIV
></DIV
><DIV
CLASS="chapter"
><HR><H1
><A
NAME="AEN998"
></A
>Chapter 4. Usage</H1
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="AEN1000"
>4.1. Invocation</A
></H2
><P
>    The transformation of a XMP specification file into 
    an extension directory is done by simply calling the
    <TT
CLASS="filename"
>pecl-gen</TT
> command with the XML
    filename as argument:
   </P
><PRE
CLASS="programlisting"
>pecl-gen my_extension.xml
   </PRE
><P
>    <TT
CLASS="filename"
>pecl-gen</TT
> will refuse to overwrite
    an existing extension directory (as changes made in there
    may be lost) unless you call it with the <TT
CLASS="literal"
>-f</TT
>
    or <TT
CLASS="literal"
>--force</TT
> option:
   </P
><PRE
CLASS="programlisting"
>pecl-gen -f my_extension.xml
   </PRE
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="AEN1010"
>4.2. Configuration</A
></H2
><P
>    You need to configure an extension for your actual build
    system before compiling it. Configuring a PECL extension
    consists of two steps:
   </P
><P
>    First you need to copy some files from your PHP installation
    into the extension directory and run the autotools to create
    a <TT
CLASS="filename"
>configure</TT
>. All this is taken care of by the
    <TT
CLASS="filename"
>phpize</TT
> command that is part of your PHP
    installation:
   </P
><PRE
CLASS="programlisting"
>cd my_extension
phpize
   </PRE
><P
>    Next you need to run <TT
CLASS="filename"
>configure</TT
> to configure
    your extension for your system installation. Most of the time just
    running <TT
CLASS="filename"
>configure</TT
> will be sufficient as 
    appropriate defaults should be picked by the script. If your 
    extension relies on external libraries installed in non-standard
    places you may want to run <TT
CLASS="filename"
>configure</TT
> with
    the appropriate <TT
CLASS="literal"
>--with-...</TT
> options.
   </P
><PRE
CLASS="programlisting"
>configure
   </PRE
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="AEN1023"
>4.3. Compilation</A
></H2
><P
>    After configuring your extension the actual compilation is
    done by the <TT
CLASS="filename"
>make</TT
> command. No further
    parameters are needed at this point:
   </P
><PRE
CLASS="programlisting"
>make
   </PRE
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="AEN1028"
>4.4. Testing</A
></H2
><P
>    Starting with PHP 5.1 it should be possible to run the generated 
    test cases by simply typing <TT
CLASS="literal"
>make test</TT
>. For older
    PHP versions a few more steps are needed:
    <P
></P
><UL
><LI
><P
>you have to specify the PHP binary to be used for testing</P
></LI
><LI
><P
>you have to set up a <TT
CLASS="filename"
>php.ini</TT
> that loags the extension for testing</P
></LI
><LI
><P
>you have to manually run the <TT
CLASS="filename"
>run-tests.php</TT
> that comes with the PHP source</P
></LI
></UL
>
    After adding the extension to your <TT
CLASS="filename"
>php.ini</TT
> a typical 
    test invocation may look like this:
   </P
><PRE
CLASS="programlisting"
>
  TEST_PHP_EXECUTABLE="/usr/local/bin/php"   php ../php-src/run-tests.php tests

</PRE
><P
>    (your <TT
CLASS="filename"
>php</TT
> binary and <TT
CLASS="filename"
>run-tests.php</TT
>
    script may obviously be in different locations)
   </P
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="AEN1046"
>4.5. Installation</A
></H2
><P
>    You can copy your newly created extension to your installations 
    default extension directory by simply running <TT
CLASS="literal"
>make install</TT
>.
    If you've set a different <TT
CLASS="literal"
>extension_dir</TT
> in your
    <TT
CLASS="filename"
>php.ini</TT
> you have to manually copy the extensions 
    <TT
CLASS="literal"
>.so</TT
> file to this directory.
   </P
><P
>    Please note that in both cases your regular user permissions may
    not be sufficient to install the extension file, you may need to
    run the commands as a different user, e.g. by using the <TT
CLASS="literal"
>sudo</TT
>
    command.
   </P
><PRE
CLASS="programlisting"
>sudo make install
   </PRE
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="AEN1056"
>4.6. PEAR/PECL integration</A
></H2
><P
>    <TT
CLASS="literal"
>pecl-gen</TT
> generates PEAR package description files a
    along with the other output files. Both the old <TT
CLASS="filename"
>package.xml</TT
>
    and the new <TT
CLASS="filename"
>package2.xml</TT
> package formats are supported.
   </P
><P
>    An extension may be configured,
    compiled and installed in a single operation using the PEAR installer:
   </P
><DIV
CLASS="example"
><A
NAME="AEN1063"
></A
><P
><B
>Example 4-1. Installation using <TT
CLASS="literal"
>pear</TT
></B
></P
><PRE
CLASS="programlisting"
>cd my_extension
pear install package2.xml
    </PRE
></DIV
><P
>    The above will perform all necessary configuration, compilation and 
    installation steps for you. You can also create packages ready
    to be submitted to the PECL repository or any other compatible 
    distribution channel using:
   </P
><DIV
CLASS="example"
><A
NAME="AEN1068"
></A
><P
><B
>Example 4-2. PEAR/PECL packaging</B
></P
><PRE
CLASS="programlisting"
>cd my_extension
pear package package2.xml
    </PRE
></DIV
><P
>    If you want to release your package on a different channel then
    <TT
CLASS="literal"
>pecl.php.net</TT
> you need to add a 
    <TT
CLASS="literal"
><channel></TT
> tag containing the channel
    name to your description file.
   </P
></DIV
></DIV
></DIV
></BODY
></HTML
>