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

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

<HTML
><HEAD
><TITLE
>Retrieving Arguments</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="Accepting Arguments"
HREF="zend.arguments.html"><LINK
REL="PREVIOUS"
TITLE="Accepting Arguments"
HREF="zend.arguments.html"><LINK
REL="NEXT"
TITLE="Old way of retrieving arguments (deprecated)"
HREF="zend.arguments.deprecated-retrieval.html"><META
HTTP-EQUIV="Content-type"
CONTENT="text/html; charset=ISO-8859-1"></HEAD
><BODY
CLASS="section"
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.arguments.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Chapter 32. Accepting Arguments</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="zend.arguments.deprecated-retrieval.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="zend.arguments.retrieval"
></A
>Retrieving Arguments</H1
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>New parameter parsing API: </B
>
     This chapter documents the new Zend parameter parsing API
     introduced by Andrei Zmievski. It was introduced in the
     development stage between PHP 4.0.6 and 4.1.0 .
    </P
></BLOCKQUOTE
></DIV
><P
>&#13;    Parsing parameters is a very common operation and it may get a bit
    tedious. It would also be nice to have standardized error checking
    and error messages. Since PHP 4.1.0, there is a way to do just
    that by using the new parameter parsing API. It greatly simplifies
    the process of receiving parameteres, but it has a drawback in
    that it can't be used for functions that expect variable number of
    parameters. But since the vast majority of functions do not fall
    into those categories, this parsing API is recommended as the new
    standard way.
   </P
><P
>&#13;    The prototype for parameter parsing function looks like this:
    <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>int zend_parse_parameters(int num_args TSRMLS_DC, char *type_spec, ...);</PRE
></TD
></TR
></TABLE
>
    The first argument to this function is supposed to be the number
    of actual parameters passed to your function, so
    <TT
CLASS="literal"
>ZEND_NUM_ARGS()</TT
> can be used for that. The
    second parameter should always be <TT
CLASS="literal"
>TSRMLS_CC</TT
>
    macro. The third argument is a string that specifies the number
    and types of arguments your function is expecting, similar to how
    printf format string specifies the number and format of the output
    values it should operate on. And finally the rest of the arguments
    are pointers to variables which should receive the values from the
    parameters.
   </P
><P
>&#13;    <B
CLASS="function"
>zend_parse_parameters()</B
> also performs type
    conversions whenever possible, so that you always receive the data
    in the format you asked for. Any type of scalar can be converted
    to another one, but conversions between complex types (arrays,
    objects, and resources) and scalar types are not allowed.
   </P
><P
>&#13;    If the parameters could be obtained successfully and there were no
    errors during type conversion, the function will return
    <TT
CLASS="literal"
>SUCCESS</TT
>, otherwise it will return
    <TT
CLASS="literal"
>FAILURE</TT
>.  The function will output informative
    error messages, if the number of received parameters does not
    match the requested number, or if type conversion could not be
    performed.
   </P
><P
>&#13;    Here are some sample error messages:
    <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="screen"
>Warning - ini_get_all() requires at most 1 parameter, 2 given
     Warning - wddx_deserialize() expects parameter 1 to be string, array given</PRE
></TD
></TR
></TABLE
>
    Of course each error message is accompanied by the filename and
    line number on which it occurs.
   </P
><P
>&#13;    Here is the full list of type specifiers:
    <P
></P
><UL
><LI
><P
><TT
CLASS="literal"
>l - </TT
>long</P
></LI
><LI
><P
><TT
CLASS="literal"
>d - </TT
>double</P
></LI
><LI
><P
><TT
CLASS="literal"
>s - </TT
>string (with possible null bytes) and its length</P
></LI
><LI
><P
><TT
CLASS="literal"
>b - </TT
>boolean</P
></LI
><LI
><P
><TT
CLASS="literal"
>r - </TT
>resource, stored in <TT
CLASS="literal"
>zval*</TT
></P
></LI
><LI
><P
><TT
CLASS="literal"
>a - </TT
>array, stored in <TT
CLASS="literal"
>zval*</TT
></P
></LI
><LI
><P
><TT
CLASS="literal"
>o - </TT
>object (of any class), stored in <TT
CLASS="literal"
>zval*</TT
></P
></LI
><LI
><P
><TT
CLASS="literal"
>O - </TT
>object (of class specified by class entry), stored in <TT
CLASS="literal"
>zval*</TT
></P
></LI
><LI
><P
><TT
CLASS="literal"
>z - </TT
>the actual <TT
CLASS="literal"
>zval*</TT
></P
></LI
></UL
>
    The following characters also have a meaning in the specifier
    string:
    <P
></P
><UL
><LI
><P
>&#13;       <TT
CLASS="literal"
>| - </TT
>indicates that the remaining
       parameters are optional. The storage variables
       corresponding to these parameters should be initialized to
       default values by the extension, since they will not be
       touched by the parsing function if the parameters are not
       passed.
      </P
></LI
><LI
><P
>&#13;       <TT
CLASS="literal"
>/ - </TT
>the parsing function will
       call <B
CLASS="function"
>SEPARATE_ZVAL_IF_NOT_REF()</B
> on
       the parameter it follows, to provide a copy of the
       parameter, unless it's a reference.  
      </P
></LI
><LI
><P
>&#13;       <TT
CLASS="literal"
>! - </TT
>the parameter it follows can
       be of specified type or <TT
CLASS="literal"
>NULL</TT
> (only
       applies to a, o, O, r, and z). If <TT
CLASS="literal"
>NULL</TT
>
       value is passed by the user, the storage pointer will be
       set to <TT
CLASS="literal"
>NULL</TT
>.
      </P
></LI
></UL
>
   </P
><P
>&#13;    The best way to illustrate the usage of this function is through
    examples:
    <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>/* Gets a long, a string and its length, and a zval. */
long l;
char *s;
int s_len;
zval *param;
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC,
                          "lsz", &#38;l, &#38;s, &#38;s_len, &#38;param) == FAILURE) {
    return;
}

/* Gets an object of class specified by my_ce, and an optional double. */
zval *obj;
double d = 0.5;
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC,
                          "O|d", &#38;obj, my_ce, &#38;d) == FAILURE) {
    return;
}

/* Gets an object or null, and an array.
   If null is passed for object, obj will be set to NULL. */
zval *obj;
zval *arr;
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "O!a", &#38;obj, &#38;arr) == FAILURE) {
    return;
}

/* Gets a separated array. */
zval *arr;
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "a/", &#38;arr) == FAILURE) {
    return;
}

/* Get only the first three parameters (useful for varargs functions). */
zval *z;
zend_bool b;
zval *r;
if (zend_parse_parameters(3, "zbr!", &#38;z, &#38;b, &#38;r) == FAILURE) {
    return;
}</PRE
></TD
></TR
></TABLE
>
   </P
><P
>&#13;    Note that in the last example we pass 3 for the number of received
    parameters, instead of <B
CLASS="function"
>ZEND_NUM_ARGS()</B
>. What
    this lets us do is receive the least number of parameters if our
    function expects a variable number of them. Of course, if you want
    to operate on the rest of the parameters, you will have to use
    <B
CLASS="function"
>zend_get_parameters_array_ex()</B
> to obtain
    them.
   </P
><P
>&#13;    The parsing function has an extended version that allows for an
    additional flags argument that controls its actions.
    <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>int zend_parse_parameters_ex(int flags, int num_args TSRMLS_DC, char *type_spec, ...);</PRE
></TD
></TR
></TABLE
>
   </P
><P
>&#13;    The only flag you can pass currently is <TT
CLASS="literal"
>ZEND_PARSE_PARAMS_QUIET</TT
>,
    which instructs the function to not output any error messages
    during its operation. This is useful for functions that expect
    several sets of completely different arguments, but you will have
    to output your own error messages.
   </P
><P
>&#13;    For example, here is how you would get either a set of three longs
    or a string:
    <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>long l1, l2, l3;
char *s;
if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET,
                             ZEND_NUM_ARGS() TSRMLS_CC,
                             "lll", &#38;l1, &#38;l2, &#38;l3) == SUCCESS) {
    /* manipulate longs */
} else if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET,
                                    ZEND_NUM_ARGS(), "s", &#38;s, &#38;s_len) == SUCCESS) {
    /* manipulate string */
} else {
    php_error(E_WARNING, "%s() takes either three long values or a string as argument",
              get_active_function_name(TSRMLS_C));
    return;
}</PRE
></TD
></TR
></TABLE
>
   </P
><P
>&#13;    With all the abovementioned ways of receiving function parameters
    you should have a good handle on this process.  For even more
    example, look through the source code for extensions that are
    shipped with PHP - they illustrate every conceivable situation.
   </P
></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.arguments.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.arguments.deprecated-retrieval.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Accepting Arguments</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="zend.arguments.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Old way of retrieving arguments (deprecated)</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>