Writing Functions

Functions and Methods in PHP take much the same form, a method is simply a function with a specific scope; the scope of their class entry. The Hacker will read about class entries in other sections of the Hacker's guide. The purpose of this section is to introduce the Hacker to the anatomy of a function or method; the Hacker will learn how to define functions, how to accept variables and how to return variables to the programmer of PHP.

The anatomy of a function could not be simpler:

PHP_FUNCTION(hackers_function) {
  /* your accepted arguments here */
  long number;
  
  /* accepting arguments */
  if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "l", &number) != SUCCESS) {
      return;
  }
  
  /* do some work on the input */
  number *= 2;
  
  /* set return value */
  RETURN_LONG(number);
}

The PHP_FUNCTION(hackers_function) preprocessor instruction will result in the following declaration:

void zif_hackers_function(INTERNAL_FUNCTION_PARAMETERS)

INTERNAL_FUNCTION_PARAMETERS is defined as a macro and explained in the following table:

**INTERNAL_FUNCTION_PARAMETERS**
Name and type	Description	Access macros
`int ht`	Number of actual parameters passed by user	`ZEND_NUM_ARGS()`
`zval *return_value`	Pointer to a PHP variable that can be filled with the return value passed to the user. The default type is `IS_NULL`.	`RETVAL_`, `RETURN_`
`zval **return_value_ptr`	When returning references to PHP set this to a pointer to your variable. It is not suggested to return references.
`zval *this_ptr`	If this is a method call, points to the PHP variable holding the `$this` object.	`getThis()`
`int return_value_used`	Flag indicating whether the returned value will be used by the caller.

For clarity, the fully expanded declaration for PHP_FUNCTION(hackers_function) looks like:

void zif_hackers_function(int ht, zval* return_value, zval** return_value_ptr, zval* this_ptr, int return_value_used)

The precense of this_ptr may be confusing, classes are covered in detail in later sections, suffice to say that PHP_METHOD(MyClass, hackersFunction) would result in the following declaration:

void zim_MyClass_hackersFunction(INTERNAL_FUNCTION_PARAMETERS)

hackers_function doesn't do anything useful, it accepts a number using the zend_parse_parameters API, doubles it, and returns it to the engine. It is obvious that a normal function would have to do something more complex than double the input, for the purposes of education we are keeping it simple. On entry to the function return_value is allocated and initialized to null, making null the default return value of any function in PHP.

If zend_parse_parameters does not recieve what is specified by the Hacker as the correct arguments, and the arguments recieved cannot be converted to conform with type_spec an error will be raised, and by convention, the Hacker should return immediately.

Note:
Arrays, Objects, and Resources cannot be converted.

**Parsing Parameters Prototypes**
`int zend_parse_parameters(int num_args TSRMLS_DC, char *type_spec, ...)`
`int zend_parse_parameters_ex(int flags, int num_args TSRMLS_DC, char *type_spec, ...)`
`int zend_parse_parameter(int flags, int arg_num TSRMLS_DC, zval *arg, const char spec, ...)`

Note:
zend_parse_parameter is available from version 5.5, it behaves like zend_parse_parameters_ex except that instead of reading the arguments from the stack, it receives a single zval to convert, which may be changed in place.

Note:
flags is intended to be a mask, currently only ZEND_PARSE_PARAMS_QUIET will have any impact (supress warnings)

The variable arguments recieved by these API functions are expected to be the address of C variables, and should be considered the output of the zend_parse_parameters API functions.

**Type Specifiers**
Spec	Type	Locals
a	`array`	`zval*`
A	`array` or `object`	`zval*`
b	`boolean`	`zend_bool`
C	`class`	`zend_class_entry*`
d	`double`	`double`
f	`function`	`zend_fcall_info`, `zend_fcall_info_cache`
h	`array`	`HashTable*`
H	`array` or `object`	`HashTable*`
l	`long`	`long`
L	`long` (limits out-of-range LONG_MAX/LONG_MIN)	`long`
o	`object`	`zval*`
O	`object` (of specified `zend_class_entry`)	`zval`, `zend_class_entry`
p	`string` (a valid path)	`char*`, `int`
r	`resource`	`char*`
s	`string`	`char*`, `int`
z	`mixed`	`zval*`
Z	`mixed`	`zval**`

Note:
Where the type specifier is O, the local zend_class_entry* is to be considered input (part of the type spec) to zend_parse_parameter

**Advanced Type Specifiers**
Spec	Description
*	a variable number of argument of the preceeding type, 0 or more
+	a variable number of argument of the preceeding type, 1 or more
\|	indicates that the remaining parameters are optional
/	`SEPARATE_ZVAL_IF_NOT_REF` on the parameter it follows
!	the preceeding parameter can be of the specified type or `null` For 'b', 'l' and 'd', an extra argument of type zend_bool* must be passed after the corresponding `bool`, `long` or `double*` addresses which will be set `true` if `null` is recieved.

Note:
Consult README.PARAMETER_PARSING_API included in source distributions for more information on parsing parameters

Once the Hacker's function has executed whatever it was implemented to execute, it is time to set the return_value for the engine. The RETURN_ and RETVAL_ macros are just wrappers around Z_*_P macros that work with return_value.

Note:
RETURN_ macros cause execution to leave the function immediately (ie: return;), while RETVAL_ macros allow execution to continue after return_value has been set.

The Hacker should now have a reasonable understanding of the anatomy of a function, and to some degree, the anatomy of a method.