Sophie: php-manual-en-4.3.0-2mdk noarch

php-manual-en-4.3.0-2mdk.noarch.rpm

<HTML
><HEAD
><TITLE
>Creating Extensions</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
REL="HOME"
TITLE="PHP Manual"
HREF="index.html"><LINK
REL="UP"
TITLE="Extending PHP 4.0"
HREF="zend.html"><LINK
REL="PREVIOUS"
TITLE="PHP's Automatic Build System"
HREF="zend.build.html"><LINK
REL="NEXT"
TITLE="Using Extensions"
HREF="zend.using.html"><META
HTTP-EQUIV="Content-type"
CONTENT="text/html; charset=ISO-8859-1"></HEAD
><BODY
CLASS="chapter"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>PHP Manual</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="zend.build.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="zend.using.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="chapter"
><H1
><A
NAME="zend.creating"
>Chapter 28. Creating Extensions</A
></H1
><DIV
CLASS="TOC"
><DL
><DT
><B
>Table of Contents</B
></DT
><DT
><A
HREF="zend.creating.html#zend.creating.compiling"
>Compiling Modules</A
></DT
></DL
></DIV
><P
>&#13;   We'll start with the creation of a very simple extension at first, which
   basically does nothing more than implement a function that returns the
   integer it receives as parameter. <A
HREF="zend.creating.html#example.simple"
>Example 28-1</A
> shows the source.
  </P
><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="example.simple"
></A
><P
><B
>Example 28-1. A simple extension.</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="C"
>/* include standard header */
#include "php.h"

/* declaration of functions to be exported */
ZEND_FUNCTION(first_module);

/* compiled function list so Zend knows what's in this module */
zend_function_entry firstmod_functions[] =
{
    ZEND_FE(first_module, NULL)
    {NULL, NULL, NULL}
};

/* compiled module information */
zend_module_entry firstmod_module_entry =
{
    STANDARD_MODULE_HEADER,
    "First Module",
    firstmod_functions,
    NULL, 
    NULL, 
    NULL, 
    NULL, 
    NULL,
    NO_VERSION_YET,
    STANDARD_MODULE_PROPERTIES
};

/* implement standard "stub" routine to introduce ourselves to Zend */
#if COMPILE_DL_FIRST_MODULE
ZEND_GET_MODULE(firstmod)
#endif

/* implement function that is meant to be made available to PHP */
ZEND_FUNCTION(first_module)
{
    long parameter;

    if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "l", &#38;parameter) == FAILURE) {
        return;
    }

    RETURN_LONG(parameter);
}</PRE
></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
><P
>&#13;   This code contains a complete PHP module. We'll explain the source
   code in detail shortly, but first we'd like to discuss the build
   process. (This will allow the impatient to experiment before we
   dive into API discussions.)
  </P
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>Note: </B
>
    The example source makes use of some features introduced with the Zend version
    used in PHP 4.1.0 and above, it won't compile with older PHP 4.0.x versions.
   </P
></BLOCKQUOTE
></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="zend.creating.compiling"
></A
>Compiling Modules</H1
><P
>&#13;    There are basically two ways to compile modules: 
    <P
></P
><UL
><LI
><P
>&#13;       Use the provided "make" mechanism in the
       <TT
CLASS="filename"
>ext</TT
> directory, which also allows building
       of dynamic loadable modules.
      </P
></LI
><LI
><P
>Compile the sources manually.</P
></LI
></UL
> 
    The first method should definitely be favored,
    since, as of PHP 4.0, this has been standardized into a
    sophisticated build process. The fact that it is so sophisticated
    is also its drawback, unfortunately - it's hard to understand at
    first. We'll provide a more detailed introduction to this later in
    the chapter, but first let's work with the default files.
   </P
><P
>&#13;    The second method is good for those who (for some reason) don't
    have the full PHP source tree available, don't have access to all
    files, or just like to juggle with their keyboard. These cases
    should be extremely rare, but for the sake of completeness we'll
    also describe this method.
   </P
><DIV
CLASS="formalpara"
><P
><B
>Compiling Using Make. </B
>
     To compile the sample sources using the standard mechanism, copy
     all their subdirectories to the <TT
CLASS="filename"
>ext</TT
>
     directory of your PHP source tree. Then run
     <TT
CLASS="filename"
>buildconf</TT
>, which will create an updated
     <TT
CLASS="filename"
>configure</TT
> script containing appropriate
     options for the new extension. By default, all the sample sources
     are disabled, so you don't have to fear breaking your build
     process.
    </P
></DIV
><P
>&#13;    After you run <TT
CLASS="filename"
>buildconf</TT
>, <TT
CLASS="filename"
>configure
     --help</TT
> shows the following additional modules: 
   </P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="screen"
>--enable-array_experiments   BOOK: Enables array experiments
  --enable-call_userland       BOOK: Enables userland module
  --enable-cross_conversion    BOOK: Enables cross-conversion module
  --enable-first_module        BOOK: Enables first module
  --enable-infoprint           BOOK: Enables infoprint module
  --enable-reference_test      BOOK: Enables reference test module
  --enable-resource_test       BOOK: Enables resource test module
  --enable-variable_creation   BOOK: Enables variable-creation module</PRE
></TD
></TR
></TABLE
><P
>&#13;    The module shown earlier in <A
HREF="zend.creating.html#example.simple"
>Example 28-1</A
>  
    can be enabled with
    <TT
CLASS="literal"
>--enable-first_module</TT
> or
    <TT
CLASS="literal"
>--enable-first_module=yes</TT
>.
   </P
><DIV
CLASS="formalpara"
><P
><B
>Compiling Manually. </B
>
     To compile your modules manually, you need the following commands:
     <DIV
CLASS="informaltable"
><A
NAME="AEN99794"
></A
><P
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><TBODY
><TR
><TD
WIDTH="20%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>Action</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>Command</TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>Compiling</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>cc -fpic -DCOMPILE_DL=1 -I/usr/local/include -I.
     -I.. -I../Zend -c -o <TT
CLASS="filename"
>&#60;your_object_file&#62;</TT
>
     <TT
CLASS="filename"
>&#60;your_c_file&#62;</TT
></TD
></TR
><TR
><TD
WIDTH="20%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>Linking</TD
><TD
WIDTH="80%"
ALIGN="LEFT"
VALIGN="MIDDLE"
>cc -shared -L/usr/local/lib -rdynamic -o
			 <TT
CLASS="filename"
>&#60;your_module_file&#62;</TT
>
			 <TT
CLASS="filename"
>&#60;your_object_file(s)&#62;</TT
></TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
>
     The command to compile the module simply instructs the compiler
     to generate position-independent code (<TT
CLASS="literal"
>-fpic</TT
> shouldn't be
     omitted) and additionally defines the constant <TT
CLASS="literal"
>COMPILE_DL</TT
> to
     tell the module code that it's compiled as a dynamically loadable module (the
     test module above checks for this; we'll discuss it shortly). After these
     options, it specifies a number of standard include paths that should be used
     as the minimal set to compile the source files. 
    </P
></DIV
><P
>&#13;    <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>Note:</I
></SPAN
> All include paths in the example are
    relative to the directory <TT
CLASS="filename"
>ext</TT
>. If you're
    compiling from another directory, change the pathnames
    accordingly. Required items are the PHP directory, the
    <TT
CLASS="filename"
>Zend</TT
> directory, and (if necessary), the
    directory in which your module resides.
   </P
><P
>&#13;    The link command is also a plain vanilla command instructing linkage as a dynamic module.
   </P
><P
>&#13;    You can include optimization options in the compilation
    command, although these have been omitted in this example (but some are included in the makefile
    template described in an earlier section).
   </P
><P
>&#13;    <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>Note:</I
></SPAN
> Compiling and linking manually as a
    static module into the PHP binary involves very long instructions
    and thus is not discussed here. (It's not very efficient to type
    all those commands.)
   </P
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="zend.build.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="zend.using.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>PHP's Automatic Build System</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="zend.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Using Extensions</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>