If you want to add additional extensions to php, the best way to
do this is using 'phpize'. You do not need to rebuild PHP itself.

Building php is a complicated affair. It requires that several libraries
be built first and in a specific order in some cases.
It has taken us a lot of time and trial-and-error to figure out the right
build order and libraries. So please DO NOT change anything in the
'make_solaris.sh' or 'make_fastcgi.sh' script. The former is for using
PHP with apache (via mod_php) and the latter is for using PHP with any
other webserver via fastcgi.

If you are not rebuilding any libraries but only PHP itself, then go
ahead and install the CSKphplibs package and use that as is.
All you then have to do is to run the 'make_solaris.sh' script here.

If you do want to rebuild everything, here is the order in which 
we build :
imap, libiconv, libxml2, mysql, curl, readline, gettext, ncurses,
freetype, gd, gdbm, tidy, unixODBC, freetds, cyrus-sasl, openldap,
httpd, php

If PHP is rebuilt, you also need to rebuid APC and suhosin extensions.

This is the first file you should be reading after you get your CVS account.
We'll assume you're basically familiar with CVS, but feel free to post
your questions on the mailing list. Please have a look at 
http://cvsbook.red-bean.com/ for more detailed information on CVS.

PHP is developed through the efforts of a large number of people.
Collaboration is a Good Thing(tm), and CVS lets us do this. Thus, following
some basic rules with regards to CVS usage will:

   a. Make everybody happier, especially those responsible for maintaining
      the CVS itself.
   b. Keep the changes consistently well documented and easily trackable.
   c. Prevent some of those 'Oops' moments.
   d. Increase the general level of good will on planet Earth.


Having said that, here are the organizational rules:

   1. Respect other people working on the project.

   2. Discuss any significant changes on the list before committing. 

   3. Look at EXTENSIONS file to see who is the primary maintainer of
      the code you want to contribute to.

   4. If you "strongly disagree" about something another person did, don't
      start fighting publicly - take it up in private email.

   5. If you don't know how to do something, ask first!

   6. Test your changes before committing them. We mean it. Really.
      To do so use "make test".
   
   7. For development use the --enable-maintainer-zts switch to ensure your
      code handles TSRM correctly and doesn't break for thos who need that.

Currently we have the following branches in use:
HEAD     Will become PHP 6.0. This CVS branch is for active development.
PHP_5_2  Is used to release the PHP 5.2.x series. Only minor feature
         enhancements may go in here, but please keep that as infrequent as
         possible.
PHP_5_1  Is used to release the PHP 5.1.x series. Only bugfixes are permitted
         on this branch (Consult the releasemaster prior to commit).
PHP_5_0  This branch is closed.
PHP_4_4  Is used to release the PHP 4.4.x series. Only bugfixes are permitted
         on this branch (Consult the releasemaster prior to commit).
PHP_4_3  This branch is closed.

The next few rules are more of a technical nature.

   1. DO NOT TOUCH ChangeLog! It is automagically updated from the commit
      messages every day. Woe be to those who attempt to mess with it.

   2. All news updates intended for public viewing, such as new features,
      bug fixes, improvements, etc., should go into the NEWS file. 
	  
      NB! Lines, starting with @ will go automagically into NEWS file, but
      this is NOT recommended, though. Please, add news entries directly to 
      NEWS file and don't forget to keep them adjusted and sorted.

   3. Do not commit multiple file and dump all messages in one commit. If you
      modified several unrelated files, commit each group separately and
      provide a nice commit message for each one. See example below.

   4. Do write your commit message in such a way that it makes sense even
      without the corresponding diff. One should be able to look at it, and
      immediately know what was modified. Definitely include the function name
      in the message as shown below.

   5. In your commit messages, keep each line shorter than 80 characters. And
      try to align your lines vertically, if they wrap. It looks bad otherwise.

   6. If you modified a function that is callable from PHP, prepend PHP to
      the function name as shown below.


The format of the commit messages is pretty simple.

Use a - to start a new item in your commit message.

If a line begins with #, it is taken to be a comment and will not appear
in the ChangeLog. Everything else goes into the ChangeLog.

It is important to note that if your comment or news logline spans multiple
lines, you have to put # at the beginning of _every_ such line. 

Example. Say you modified two files, datetime.c and string.c. In datetime.c you
added a new format option for the date() function, and in string.c you fixed a
memory leak in php_trim(). Don't commit both of these at once. Commit them
separately and try to make sure your commit messages look something like the
following.

For datetime.c:
- Added new 'K' format modifier to date() for printing out number of days until
  New Year's Eve.

For string.c:
- Fixed a memory leak in php_trim() resulting from improper use of zval_dtor().
#- Man, that thing was leaking all over the place!

The # lines will be omitted from the ChangeLog automagically.

If you fix some bugs, you should note the bug ID numbers in your
commit message. Bug ID should be prefixed by "#" for easier access to
bug report when developers are browsing CVS via. LXR or Bonsai.

Example:

Fixed bug #14016 (pgsql notice handler double free crash bug.)

If you don't see your messages in ChangeLog right away, don't worry!
These files are updated once a day, so your stuff will not show up until
somewhat later. 

You can use LXR (http://lxr.php.net/) and Bonsai (http://bonsai.php.net/)
to look at PHP CVS repository in various ways.

To receive daily updates to ChangeLog and NEWS, send an empty message to
php-cvs-daily-subscribe (a] lists.php.net.

Happy hacking,

PHP Team

(NOTE: you may also want to take a look at the pear package
	     PECL_Gen, a PHP-only alternative for this script that
			 supports way more extension writing tasks and is 
			 supposed to replace ext_skel completely in the long run ...)

WHAT IT IS

  It's a tool for automatically creating the basic framework for a PHP module
  and writing C code handling arguments passed to your functions from a simple
  configuration file. See an example at the end of this file.

HOW TO USE IT

  Very simple. First, change to the ext/ directory of the PHP 4 sources. If
  you just need the basic framework and will be writing all the code in your
  functions yourself, you can now do

   ./ext_skel --extname=module_name

  and everything you need is placed in directory module_name. 

  [ Note that GNU awk is likely required for this script to work.  Debian 
    systems seem to default to using mawk, so you may need to change the 
    #! line in skeleton/create_stubs and the cat $proto | awk line in
    ext_skel to use gawk explicitly. ]

  If you don't need to test the existence of any external header files, 
  libraries or functions in them, the module is already almost ready to be 
  compiled in PHP.  Just remove 3 comments in your_module_name/config.m4, 
  change back up to PHP sources top directory, and do

    ./buildconf; ./configure --enable-module_name; make

  But if you already have planned the overall scheme of your module, what
  functions it will contain, their return types and the arguments they take
  (a very good idea) and don't want to bother yourself with creating function
  definitions and handling arguments passed yourself, it's time to create a
  function definitions file, which you will give as an argument to ext_skel
  with option

    --proto=filename.

FORMAT OF FUNCTION DEFINITIONS FILE

  All the definitions must be on one line. In it's simplest form, it's just
  the function name, e.g.

    my_function

  but then you'll be left with an almost empty function body without any
  argument handling.

  Arguments are given in parenthesis after the function name, and are of
  the form 'argument_type argument_name'. Arguments are separated from each
  other with a comma and optional space. Argument_type can be one of int,
  bool, double, float, string, array, object or mixed.

  An optional argument is separated from the previous by an optional space,
  then '[' and of course comma and optional space, like all the other
  arguments. You should close a row of optional arguments with same amount of
  ']'s as there where '['s. Currently, it does not harm if you forget to do it
  or there is a wrong amount of ']'s, but this may change in the future.

	An additional short description may be added after the parameters. 
  If present it will be filled into the 'proto' header comments in the stubs
  code and the <refpurpose> tag in the XML documentation.

  An example:

    my_function(int arg1, int arg2 [, int arg3 [, int arg4]]) this is my 1st

  Arguments arg3 and arg4 are optional.

  If possible, the function definition should also contain it's return type
  in front of the definition. It's not actually used for any C code generating
  purposes but PHP in-source documentation instead, and as such, very useful.
  It can be any of int, double, string, bool, array, object, resource, mixed
  or void.

  The file must contain nothing else but function definitions, no comments or
  empty lines.

OTHER OPTIONS

    --no-help

  By default, ext_skel creates both comments in the source code and a test
  function to help first time module writers to get started and testing
  configuring and compiling their module. This option turns off all such things
  which may just annoy experienced PHP module coders. Especially useful with

    --stubs=file

  which will leave out also all module specific stuff and write just function
  stubs with function value declarations and passed argument handling, and
  function entries and definitions at the end of the file, for copying and
  pasting into an already existing module.

    --assign-params
    --string-lens

  By default, function proto 'void foo(string bar)' creates the following:
     ...
     zval **bar;
     ... (zend_get_parameters_ex() called in the middle...)
     convert_to_string_ex(bar);

  Specifying both of these options changes the generated code to:
     ...
     zval **bar_arg;
     int bar_len;
     char *bar = NULL;
     ... (zend_get_parameters_ex() called in the middle...)
     convert_to_string_ex(bar_arg);
     bar = Z_STRVAL_PP(bar_arg);
     bar_len = Z_STRLEN_PP(bar_arg);

  You shouldn't have to ask what happens if you leave --string-lens out. If you
  have to, it's questionable whether you should be reading this document.

    --with-xml[=file]

  Creates the basics for phpdoc .xml file.

    --full-xml

  Not implemented yet. When or if there will ever be created a framework for
  self-contained extensions to use phpdoc system for their documentation, this
  option enables it on the created xml file.

CURRENT LIMITATIONS, BUGS AND OTHER ODDITIES

  Only arguments of types int, bool, double, float, string and array are
  handled. For other types you must write the code yourself. And for type
  mixed, it wouldn't even be possible to write anything, because only you
  know what to expect.
  
  It can't handle correctly, and probably never will, variable list of
  of arguments. (void foo(int bar [, ...])

  Don't trust the generated code too much. It tries to be useful in most of
  the situations you might encounter, but automatic code generation will never
  beat a programmer who knows the real situation at hand. ext_skel is generally
  best suited for quickly generating a wrapper for c-library functions you
  might want to have available in PHP too.

  This program doesn't have a --help option. It has --no-help instead.

EXAMPLE

  The following _one_ line

  bool my_drawtext(resource image, string text, resource font, int x, int y [, int color])

  will create this function definition for you (note that there are a few
  question marks to be replaced by you, and you must of course add your own
  value definitions too):

/* {{{ proto bool my_drawtext(resource image, string text, resource font, int x, int y[, int color])
    */
PHP_FUNCTION(my_drawtext)
{
	zval **image, **text, **font, **x, **y, **color;
	int argc;
	int image_id = -1;
	int font_id = -1;

	argc = ZEND_NUM_ARGS();
	if (argc < 5 || argc > 6 || zend_get_parameters_ex(argc, &image, &text, &font, &x, &y, &color) == FAILURE) {
		WRONG_PARAM_COUNT;
	}

	ZEND_FETCH_RESOURCE(???, ???, image, image_id, "???", ???_rsrc_id);
	ZEND_FETCH_RESOURCE(???, ???, font, font_id, "???", ???_rsrc_id);

	switch (argc) {
		case 6:
			convert_to_long_ex(color);
			/* Fall-through. */
		case 5:
			convert_to_long_ex(y);
			convert_to_long_ex(x);
			/* font: fetching resources already handled. */
			convert_to_string_ex(text);
			/* image: fetching resources already handled. */
			break;
		default:
			WRONG_PARAM_COUNT;
	}

	php_error(E_WARNING, "my_drawtext: not yet implemented");
}
/* }}} */

Between PHP 4.0.6 and 4.1.0, the Zend module struct changed in a way
that broke both source and binary compatibility.  If you are
maintaining a third party extension, here's how to update it:

If this was your old module entry:

zend_module_entry foo_module_entry = {
    "foo",                /* extension name */
    foo_functions,        /* extension function list */
    NULL,                 /* extension-wide startup function */
    NULL,                 /* extension-wide shutdown function */
    PHP_RINIT(foo),       /* per-request startup function */
    PHP_RSHUTDOWN(foo),   /* per-request shutdown function */
    PHP_MINFO(foo),       /* information function */
    STANDARD_MODULE_PROPERTIES
};

Here's how it should look if you want your code to build with PHP
4.1.0 and up:

zend_module_entry foo_module_entry = {
#if ZEND_MODULE_API_NO >= 20010901
    STANDARD_MODULE_HEADER,
#endif
    "foo",                /* extension name */
    foo_functions,        /* extension function list */
    NULL,                 /* extension-wide startup function */
    NULL,                 /* extension-wide shutdown function */
    PHP_RINIT(foo),       /* per-request startup function */
    PHP_RSHUTDOWN(foo),   /* per-request shutdown function */
    PHP_MINFO(foo),       /* information function */
#if ZEND_MODULE_API_NO >= 20010901
    FOO_VERSION,          /* extension version number (string) */
#endif
    STANDARD_MODULE_PROPERTIES
};

If you don't care about source compatibility with earlier PHP releases
than 4.1.0, you can drop the #if/#endif lines.

Input Filter Support in PHP 5
-----------------------------

XSS (Cross Site Scripting) hacks are becoming more and more prevalent,
and can be quite difficult to prevent.  Whenever you accept user data
and somehow display this data back to users, you are likely vulnerable
to XSS hacks.

The Input Filter support in PHP 5 is aimed at providing the framework
through which a company-wide or site-wide security policy can be
enforced.  It is implemented as a SAPI hook and is called from the
treat_data and post handler functions.  To implement your own security
policy you will need to write a standard PHP extension.  There is also
a powerful standard implementation in ext/filter that should suit most
peoples' needs.  However, if you want to implement your own security 
policy, read on.

A simple implementation might look like the following.  This stores the
original raw user data and adds a my_get_raw() function while the normal
$_POST, $_GET and $_COOKIE arrays are only populated with stripped
data.  In this simple example all I am doing is calling strip_tags() on
the data.  If register_globals is turned on, the default globals that
are created will be stripped ($foo) while a $RAW_foo is created with the
original user input.

ZEND_BEGIN_MODULE_GLOBALS(my_input_filter)
        zval *post_array;
        zval *get_array;
        zval *cookie_array;
ZEND_END_MODULE_GLOBALS(my_input_filter)

#ifdef ZTS
#define IF_G(v) TSRMG(my_input_filter_globals_id, zend_my_input_filter_globals *, v)
#else
#define IF_G(v) (my_input_filter_globals.v)
#endif

ZEND_DECLARE_MODULE_GLOBALS(my_input_filter)

zend_function_entry my_input_filter_functions[] = {
    PHP_FE(my_get_raw,   NULL)
    {NULL, NULL, NULL}
};

zend_module_entry my_input_filter_module_entry = {
    STANDARD_MODULE_HEADER,
    "my_input_filter",
    my_input_filter_functions,
    PHP_MINIT(my_input_filter),
    PHP_MSHUTDOWN(my_input_filter),
    NULL,
    PHP_RSHUTDOWN(my_input_filter),
    PHP_MINFO(my_input_filter),
    "0.1",
    STANDARD_MODULE_PROPERTIES
};

PHP_MINIT_FUNCTION(my_input_filter)
{
    ZEND_INIT_MODULE_GLOBALS(my_input_filter, php_my_input_filter_init_globals, NULL);

    REGISTER_LONG_CONSTANT("POST", PARSE_POST, CONST_CS | CONST_PERSISTENT);
    REGISTER_LONG_CONSTANT("GET", PARSE_GET, CONST_CS | CONST_PERSISTENT);
    REGISTER_LONG_CONSTANT("COOKIE", PARSE_COOKIE, CONST_CS | CONST_PERSISTENT);

    sapi_register_input_filter(my_sapi_input_filter);
    return SUCCESS;
}

PHP_RSHUTDOWN_FUNCTION(my_input_filter)
{
    if(IF_G(get_array)) {
        zval_ptr_dtor(&IF_G(get_array));
        IF_G(get_array) = NULL;
    }
    if(IF_G(post_array)) {
        zval_ptr_dtor(&IF_G(post_array));
        IF_G(post_array) = NULL;
    }
    if(IF_G(cookie_array)) {
        zval_ptr_dtor(&IF_G(cookie_array));
        IF_G(cookie_array) = NULL;
    }
    return SUCCESS;
}

PHP_MINFO_FUNCTION(my_input_filter)
{
    php_info_print_table_start();
    php_info_print_table_row( 2, "My Input Filter Support", "enabled" );
    php_info_print_table_row( 2, "Revision", "$Revision: 1.7.4.1.2.1 $");
    php_info_print_table_end();
}

/* The filter handler. If you return 1 from it, then PHP also registers the
 * (modified) variable. Returning 0 prevents PHP from registering the variable;
 * you can use this if your filter already registers the variable under a
 * different name, or if you just don't want the variable registered at all. */
SAPI_INPUT_FILTER_FUNC(my_sapi_input_filter)
{
    zval new_var;
    zval *array_ptr = NULL;
    char *raw_var;
    int var_len;

    assert(*val != NULL);

    switch(arg) {
        case PARSE_GET:
            if(!IF_G(get_array)) {
                ALLOC_ZVAL(array_ptr);
                array_init(array_ptr);
                INIT_PZVAL(array_ptr);
            }
            IF_G(get_array) = array_ptr;
            break;
        case PARSE_POST:
            if(!IF_G(post_array)) {
                ALLOC_ZVAL(array_ptr);
                array_init(array_ptr);
                INIT_PZVAL(array_ptr);
            }
            IF_G(post_array) = array_ptr;
            break;
        case PARSE_COOKIE:
            if(!IF_G(cookie_array)) {
                ALLOC_ZVAL(array_ptr);
                array_init(array_ptr);
                INIT_PZVAL(array_ptr);
            }
            IF_G(cookie_array) = array_ptr;
            break;
    }
    Z_STRLEN(new_var) = val_len;
    Z_STRVAL(new_var) = estrndup(*val, val_len);
    Z_TYPE(new_var) = IS_STRING;

    var_len = strlen(var);
    raw_var = emalloc(var_len+5);  /* RAW_ and a \0 */
    strcpy(raw_var, "RAW_");
    strlcat(raw_var,var,var_len+5);

    php_register_variable_ex(raw_var, &new_var, array_ptr TSRMLS_DC);

    php_strip_tags(*val, val_len, NULL, NULL, 0);

    *new_val_len = strlen(*val);
    return 1;
}

PHP_FUNCTION(my_get_raw)
{
    long arg;
    char *var;
    int var_len;
    zval **tmp;
    zval *array_ptr = NULL;
    HashTable *hash_ptr;
    char *raw_var;

    if(zend_parse_parameters(2 TSRMLS_CC, "ls", &arg, &var, &var_len) == FAILURE) {
        return;
    }

    switch(arg) {
        case PARSE_GET:
            array_ptr = IF_G(get_array);
            break;
        case PARSE_POST:
            array_ptr = IF_G(post_array);
            break;
        case PARSE_COOKIE:
            array_ptr = IF_G(post_array);
            break;
    }

    if(!array_ptr) RETURN_FALSE;

    /*
     * I'm changing the variable name here because when running with register_globals on,
     * the variable will end up in the global symbol table
     */
    raw_var = emalloc(var_len+5);  /* RAW_ and a \0 */
    strcpy(raw_var, "RAW_");
    strlcat(raw_var,var,var_len+5);
    hash_ptr = HASH_OF(array_ptr);

    if(zend_hash_find(hash_ptr, raw_var, var_len+5, (void **)&tmp) == SUCCESS) {
        *return_value = **tmp;
        zval_copy_ctor(return_value);
    } else {
        RETVAL_FALSE;
    }
    efree(raw_var);
}

New parameter parsing functions
===============================

It should be easier to parse input parameters to an extension function.
Hence, borrowing from Python's example, there are now a set of functions
that given the string of type specifiers, can parse the input parameters
and store the results in the user specified variables. This avoids most
of the IS_* checks and convert_to_* conversions. The functions also
check for the appropriate number of parameters, and try to output
meaningful error messages.


Prototypes
----------
/* Implemented. */
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, ...);

The zend_parse_parameters() function takes the number of parameters
passed to the extension function, the type specifier string, and the
list of pointers to variables to store the results in. The _ex() version
also takes 'flags' argument -- current only ZEND_PARSE_PARAMS_QUIET can
be used as 'flags' to specify that the function should operate quietly
and not output any error messages.

Both functions return SUCCESS or FAILURE depending on the result.

The auto-conversions are performed as necessary. Arrays, objects, and
resources cannot be auto-converted.


Type specifiers
---------------
 a	- array
 b	- boolean, stored in zend_bool
 d	- double
 f	- function or array containing php method call info (returned as 
	  zend_fcall_info* and zend_fcall_info_cache*)
 h	- array (returned as HashTable*)
 l	- long
 o	- object (of any type)
 O	- object (of specific type, specified by class entry)
 r	- resource (stored in zval)
 s	- string (with possible null bytes) and its length
 z	- the actual zval

 The following characters also have a meaning in the specifier string:
	| - indicates that the remaining parameters are optional, they
	    should be initialized to default values by the extension since they
	    will not be touched by the parsing function if they are not
	    passed to it.
	/ - use SEPARATE_ZVAL_IF_NOT_REF() on the parameter it follows
	! - the parameter it follows can be of specified type or NULL (only applies
	    to 'a', 'o', 'O', 'r', and 'z'). If NULL is passed, the results
	    pointer is set to NULL as well.

Examples
--------
/* 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",
						  &l, &s, &s_len, &param) == FAILURE) {
	return;
}


/* Gets an object of class specified by my_ce, and an optional double. */
zval *obj;
double d = 0.5;
zend_class_entry my_ce;
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "O|d",
						  &obj, my_ce, &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",
						  &obj, &arr) == FAILURE) {
	return;
}


/* Gets a separated array which can also be null. */
zval *arr;
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "a/!",
						  &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 TSRMLS_CC, "zbr!",
						  &z, &b, &r) == FAILURE) {
	return;
}


/* Get either a set of 3 longs or a string. */
long l1, l2, l3;
char *s;
/* 
 * The function expects a pointer to a integer in this case, not a long
 * or any other type.  If you specify a type which is larger
 * than a 'int', the upper bits might not be initialized
 * properly, leading to random crashes on platforms like
 * Tru64 or Linux/Alpha.
 */
int length;

if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS() TSRMLS_CC,
							 "lll", &l1, &l2, &l3) == SUCCESS) {
	/* manipulate longs */
} else if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS() TSRMLS_CC,
									"s", &s, &length) == SUCCESS) {
	/* manipulate string */
} else {
	/* output error */

	return;
}

1. strrpos() and strripos() now use the entire string as a needle.  Be aware
   that the existing scripts may no longer work as you expect.

   EX :
   <?php
   var_dump(strrpos("ABCDEF","DEF"));
   var_dump(strrpos("ABCDEF","DAF"));
   ?>

   Will give you different results. The former returns 3 while the latter
   returns false rather than the position of the last occurrence of 'D'.
   The same applies to strripos().

2. Illegal use of string offsets causes E_ERROR instead of E_WARNING.

   EX :
   <?php
   $a = "foo";
   unset($a[0][1][2]);
   ?>

   Fatal error: Cannot use string offset as an array in ... on line 1

3. array_merge() was changed to accept only arrays. If a non-array variable is
   passed, a E_WARNING will be thrown for every such parameter. Be careful
   because your code may start emitting E_WARNING out of the blue.

4. Be careful when porting from ext/mysql to ext/mysqli. The following
   functions return NULL when no more data is available in the result set
   (ext/mysql's functions return FALSE).

    - mysqli_fetch_row()
    - mysqli_fetch_array()
    - mysqli_fetch_assoc()

5. PATH_TRANSLATED server variable is no longer set implicitly under
   Apache2 SAPI in contrast to the situation in PHP 4, where it is set to the
   same value as the SCRIPT_FILENAME server variable when it is not populated
   by Apache.  This change was made to comply with the CGI specification.
   Please refer to bug #23610 for further information.

6. Starting PHP 5.0.0 the T_ML_CONSTANT constant is no longer defined by the
   ext/tokenizer extension. If error_reporting is set to E_ALL notices will
   be produced. Instead of T_ML_CONSTANT for /* */ the T_COMMENT constant 
   is used, thus both // and /* */ are resolved as the T_COMMENT constant.
   However the PHPDoc style comments /** */ ,which starting PHP 5 are parsed
   by PHP, are recongnized as T_DOC_COMMENT.

7. $_SERVER should be populated with argc and argv if variables_order
   includes "S".  If you have specifically configured your system to not
   create $_SERVER, then of course it shouldn't be there.  The change was to
   always make argc and argv available in the CLI version regardless of the
   variables_order setting.  As in, the CLI version will now always populate
   the global $argc and $argv variables.

8. In some cases classes must be declared before used. It only happens only
   if some of the new features of PHP 5 are used. Otherwise the behaviour is
   the old.
   Example 1 (works with no errors):
   <?php
   $a = new a();
   class a {
   }
   ?>
 
   Example 2 (throws an error):
   <?php 
   $a = new a();
   interface b{
   }
   class a implements b {
   } 
   ?>

   Output (example 2) :
   Fatal error: Class 'a' not found in /tmp/cl.php on line 2

9. get_class() starting PHP 5 returns the name of the class as it was
   declared which may lead to problems in older scripts that rely on
   the previous behaviour - the class name is lowercased. Expect the
   same behaviour from get_parent_class() when applicable.
   Example :
   <?php
   class FooBar {
   }
   class ExtFooBar extends FooBar{}
   $a = new FooBar();
   var_dump(get_class($a), get_parent_class($a));
   ?>

   Output (PHP 4):
   string(6) "foobar"
   string(9) "extfoobar"

   Output (PHP 5):
   string(6) "FooBar"
   string(9) "ExtFooBar"
   ----------------------------------------------------------------------
   Example code that will break :
   //....
   function someMethod($p) {
     if (get_class($p) != 'helpingclass') {
       return FALSE;
     }
     //...
   }
   //...
   Possible solution is to search for get_class() and get_parent_class() in
   all your scripts and use strtolower().

10. get_class_methods() returns the names of the methods of a class as they
   declared. In PHP4 the names are all lowercased.
   Example code :
   <?php
   class Foo{
     function doFoo(){}
     function hasFoo(){}
   }
   var_dump(get_class_methods("Foo")); 
   ?>
   Output (PHP4):
   array(2) {
     [0]=>
     string(5) "dofoo"
     [1]=>
     string(6) "hasfoo"
   }
   Output (PHP5):
   array(2) {
     [0]=>
     string(5) "doFoo"
     [1]=>
     string(6) "hasFoo"
   }

11. Assignment $this is impossible. Starting PHP 5.0.0 $this has special
    meaning in class methods and is recognized by the PHP parser. The latter
    will generate a parse error when assignment to $this is found
    Example code :
    <?php
    class Foo {
      function assignNew($obj) {
        $this = $obj;
      }
    }
    $a = new Foo();
    $b = new Foo();
    $a->assignNew($b);
    echo "I was executed\n";
    ?>
    Output (PHP 4):
    I was executed
    Output (PHP 5):
    PHP Fatal error:  Cannot re-assign $this in /tmp/this_ex.php on line 4

QNX4 Installation Notes
-----------------------

NOTE: General installation instructions are in the INSTALL file 


1. To compile and test PHP3 you have to grab, compile and install:
	- GNU dbm library or another db library;
	- GNU bison (1.25 or later; 1.25 tested);
	- GNU flex (any version supporting -o and -P options; 2.5.4 tested);
	- GNU diffutils (any version supporting -w option; 2.7 tested);

2. To use CVS version you may need also:
	- GNU CVS (1.9 tested);
	- GNU autoconf (2.12 tested);
	- GNU m4 (1.3 or later preferable; 1.4 tested);

3. To run configure define -lunix in command line:
	LDFLAGS=-lunix ./configure

4. To use Sybase SQL Anywhere define ODBC_QNX and CUSTOM_ODBC_LIBS in
	command line and run configure with --with-custom-odbc:
	CFLAGS=-DODBC_QNX LDFLAGS=-lunix CUSTOM_ODBC_LIBS="-ldblib -lodbc" ./configure --with-custom-odbc=/usr/lib/sqlany50
   If you have SQL Anywhere version 5.5.00, then you have to add 
	CFLAGS=-DSQLANY_BUG
   to workaround its SQLFreeEnv() bug. Other versions has not been tested,
   so try without this flag first.

5. To build the Apache module, you may have to hardcode an include path for 
   alloc.h in your Apache base directory:
	- APACHE_DIRECTORY/src/httpd.h: 
		change	#include "alloc.h"
		to 		#include "APACHE_DIRECTORY/src/alloc.h"
   Unless you want to use system regex library, you have to hardcode also
   a path to regex.h:
	- APACHE_DIRECTORY/src/conf.h:  
		change  #include <regex.h>
		to		#include "APACHE_DIRECTORY/src/regex/regex.h"
   I don't know so far why this required for QNX, may be it is Watcom 
   compiler problem.

  If you building Apache module with SQL Anywhere support, you'll get
  symbol conflict with BOOL. It is defined in Apache (httpd.h) and in 
  SQL Anywhere (odbc.h). This has nothing to do with PHP, so you have to 
  fix it yourself someway.

6. With above precautions, it should compile as is and pass regression
	tests completely:
		make
		make check
		make install

	Don't bother me unless you really sure you made	that all but it 
	still doesn't work.

June 28, 1998
Igor Kovalenko -- owl (a] infomarket.ru

$Id: README.SELF-CONTAINED-EXTENSIONS,v 1.12 2002/10/23 21:35:17 jon Exp $
=============================================================================

HOW TO CREATE A SELF-CONTAINED PHP EXTENSION

  A self-contained extension can be distributed independently of
  the PHP source. To create such an extension, two things are
  required:

  - Configuration file (config.m4)
  - Source code for your module

  We will describe now how to create these and how to put things
  together.

PREPARING YOUR SYSTEM

  While the result will run on any system, a developer's setup needs these
  tools:

    GNU autoconf
    GNU automake
    GNU libtool
    GNU m4

  All of these are available from 

    ftp://ftp.gnu.org/pub/gnu/

CONVERTING AN EXISTING EXTENSION

  Just to show you how easy it is to create a self-contained
  extension, we will convert an embedded extension into a
  self-contained one. Install PHP and execute the following
  commands.
  
     $ mkdir /tmp/newext
     $ cd /tmp/newext

  You now have an empty directory. We will copy the files from
  the mysql extension:

     $ cp -rp php-4.0.X/ext/mysql/* .

  It is time to finish the module. Run:

     $ phpize

  You can now ship the contents of the directory - the extension
  can live completely on its own.

  The user instructions boil down to

     $ ./configure \
            [--with-php-config=/path/to/php-config] \
            [--with-mysql=MYSQL-DIR]
     $ make install

  The MySQL module will either use the embedded MySQL client 
  library or the MySQL installation in MYSQL-DIR.


DEFINING THE NEW EXTENSION

  Our demo extension is called "foobar".

  It consists of two source files "foo.c" and "bar.c"
  (and any arbitrary amount of header files, but that is not
  important here).
  
  The demo extension does not reference any external 
  libraries (that is important, because the user does not
  need to specify anything).


  LTLIBRARY_SOURCES specifies the names of the sources files. You can
  name an arbitrary number of source files here.

CREATING THE M4 CONFIGURATION FILE

  The m4 configuration can perform additional checks. For a 
  self-contained extension, you do not need more than a few
  macro calls.

------------------------------------------------------------------------------
PHP_ARG_ENABLE(foobar,whether to enable foobar,
[  --enable-foobar            Enable foobar])

if test "$PHP_FOOBAR" != "no"; then
  PHP_NEW_EXTENSION(foobar, foo.c bar.c, $ext_shared)
fi
------------------------------------------------------------------------------

  PHP_ARG_ENABLE will automatically set the correct variables, so
  that the extension will be enabled by PHP_NEW_EXTENSION in shared mode.

  The first argument of PHP_NEW_EXTENSION describes the name of the
  extension.  The second names the source-code files.  The third passes
  $ext_shared which is set by PHP_ARG_ENABLE/WITH to PHP_NEW_EXTENSION.
  
  Please use always PHP_ARG_ENABLE or PHP_ARG_WITH. Even if you do not
  plan to distribute your module with PHP, these facilities allow you
  to integrate your module easily into the main PHP module framework.

CREATING SOURCE FILES

  ext_skel can be of great help when creating the common code for all modules
  in PHP for you and also writing basic function definitions and C code for
  handling arguments passed to your functions. See README.EXT_SKEL for further
  information.

  As for the rest, you are currently alone here. There are a lot of existing
  modules, use a simple module as a starting point and add your own code.


CREATING THE SELF-CONTAINED EXTENSION

  Put config.m4 and the source files into one directory. Then, run phpize
  (this is installed during make install by PHP 4.0).

  For example, if you configured PHP with --prefix=/php, you would run

     $ /php/bin/phpize

  This will automatically copy the necessary build files and create
  configure from your config.m4.

  And that's it. You now have a self-contained extension.

INSTALLING A SELF-CONTAINED EXTENSION

  An extension can be installed by running:

     $ ./configure \
            [--with-php-config=/path/to/php-config]
     $ make install

ADDING SHARED MODULE SUPPORT TO A MODULE

  In order to be useful, a self-contained extension must be loadable
  as a shared module. I will explain now how you can add shared module 
  support to an existing module called foo.

  1. In config.m4, use PHP_ARG_WITH/PHP_ARG_ENABLE. Then you will
     automatically be able to use --with-foo=shared[,..] or
     --enable-foo=shared[,..].

  2. In config.m4, use PHP_NEW_EXTENSION(foo,.., $ext_shared) to enable
     building the extension.

  3. Add the following lines to your C source file:

        #ifdef COMPILE_DL_FOO
        ZEND_GET_MODULE(foo)
        #endif

An Overview of the PHP Streams abstraction
==========================================
$Id: README.STREAMS,v 1.11 2003/03/04 21:46:33 iliaa Exp $

WARNING: some prototypes in this file are out of date.
The information contained here is being integrated into
the PHP manual - stay tuned...

Please send comments to: Wez Furlong <wez (a] thebrainroom.com>

Why Streams?
============
You may have noticed a shed-load of issock parameters flying around the PHP
code; we don't want them - they are ugly and cumbersome and force you to
special case sockets and files every time you need to work with a "user-level"
PHP file pointer.
Streams take care of that and present the PHP extension coder with an ANSI
stdio-alike API that looks much nicer and can be extended to support non file
based data sources.

Using Streams
=============
Streams use a php_stream* parameter just as ANSI stdio (fread etc.) use a
FILE* parameter.

The main functions are:

PHPAPI size_t php_stream_read(php_stream * stream, char * buf, size_t count);
PHPAPI size_t php_stream_write(php_stream * stream, const char * buf, size_t
        count);
PHPAPI size_t php_stream_printf(php_stream * stream TSRMLS_DC, 
        const char * fmt, ...);
PHPAPI int php_stream_eof(php_stream * stream);
PHPAPI int php_stream_getc(php_stream * stream);
PHPAPI char *php_stream_gets(php_stream * stream, char *buf, size_t maxlen);
PHPAPI int php_stream_close(php_stream * stream);
PHPAPI int php_stream_flush(php_stream * stream);
PHPAPI int php_stream_seek(php_stream * stream, off_t offset, int whence);
PHPAPI off_t php_stream_tell(php_stream * stream);
PHPAPI int php_stream_lock(php_stream * stream, int mode);

These (should) behave in the same way as the ANSI stdio functions with similar
names: fread, fwrite, fprintf, feof, fgetc, fgets, fclose, fflush, fseek, ftell, flock.

Opening Streams
===============
In most cases, you should use this API:

PHPAPI php_stream *php_stream_open_wrapper(char *path, char *mode,
    int options, char **opened_path TSRMLS_DC);

Where:
    path is the file or resource to open.
    mode is the stdio compatible mode eg: "wb", "rb" etc.
    options is a combination of the following values:
        IGNORE_PATH  (default) - don't use include path to search for the file
        USE_PATH        - use include path to search for the file
        IGNORE_URL      - do not use plugin wrappers
        REPORT_ERRORS   - show errors in a standard format if something
                          goes wrong.
        STREAM_MUST_SEEK - If you really need to be able to seek the stream
                           and don't need to be able to write to the original
                           file/URL, use this option to arrange for the stream
                           to be copied (if needed) into a stream that can
                           be seek()ed.
                           
    opened_path is used to return the path of the actual file opened,
    but if you used STREAM_MUST_SEEK, may not be valid.  You are
    responsible for efree()ing opened_path.  opened_path may be (and usually
    is) NULL.

If you need to open a specific stream, or convert standard resources into
streams there are a range of functions to do this defined in php_streams.h.
A brief list of the most commonly used functions:

PHPAPI php_stream *php_stream_fopen_from_file(FILE *file, const char *mode);
    Convert a FILE * into a stream.

PHPAPI php_stream *php_stream_fopen_tmpfile(void);
    Open a FILE * with tmpfile() and convert into a stream.

PHPAPI php_stream *php_stream_fopen_temporary_file(const char *dir,
    const char *pfx, char **opened_path TSRMLS_DC);
    Generate a temporary file name and open it.

There are some network enabled relatives in php_network.h:

PHPAPI php_stream *php_stream_sock_open_from_socket(int socket, int persistent);
    Convert a socket into a stream.

PHPAPI php_stream *php_stream_sock_open_host(const char *host, unsigned short port,
		int socktype, int timeout, int persistent);
    Open a connection to a host and return a stream.

PHPAPI php_stream *php_stream_sock_open_unix(const char *path, int persistent,
    struct timeval *timeout);
    Open a UNIX domain socket.
   

Stream Utilities
================

If you need to copy some data from one stream to another, you will be please
to know that the streams API provides a standard way to do this:

PHPAPI size_t php_stream_copy_to_stream(php_stream *src,
    php_stream *dest, size_t maxlen);

If you want to copy all remaining data from the src stream, pass
PHP_STREAM_COPY_ALL as the maxlen parameter, otherwise maxlen indicates the
number of bytes to copy.
This function will try to use mmap where available to make the copying more
efficient.

If you want to read the contents of a stream into an allocated memory buffer,
you should use:

PHPAPI size_t php_stream_copy_to_mem(php_stream *src, char **buf,
    size_t maxlen, int persistent);

This function will set buf to the address of the buffer that it allocated,
which will be maxlen bytes in length, or will be the entire length of the
data remaining on the stream if you set maxlen to PHP_STREAM_COPY_ALL.
The buffer is allocated using pemalloc(); you need to call pefree() to
release the memory when you are done.
As with copy_to_stream, this function will try use mmap where it can.

If you have an existing stream and need to be able to seek() it, you
can use this function to copy the contents into a new stream that can
be seek()ed:

PHPAPI int php_stream_make_seekable(php_stream *origstream, php_stream **newstream);

It returns one of the following values:
#define PHP_STREAM_UNCHANGED	0 /* orig stream was seekable anyway */
#define PHP_STREAM_RELEASED		1 /* newstream should be used; origstream is no longer valid */
#define PHP_STREAM_FAILED		2 /* an error occurred while attempting conversion */
#define PHP_STREAM_CRITICAL		3 /* an error occurred; origstream is in an unknown state; you should close origstream */

make_seekable will always set newstream to be the stream that is valid
if the function succeeds.
When you have finished, remember to close the stream.

NOTE: If you only need to seek forward, there is no need to call this
function, as the php_stream_seek can emulate forward seeking when the
whence parameter is SEEK_CUR.

NOTE: Writing to the stream may not affect the original source, so it
only makes sense to use this for read-only use.

NOTE: If the origstream is network based, this function will block
until the whole contents have been downloaded.

NOTE: Never call this function with an origstream that is referenced
as a resource! It will close the origstream on success, and this
can lead to a crash when the resource is later used/released.

NOTE: If you are opening a stream and need it to be seekable, use the
STREAM_MUST_SEEK option to php_stream_open_wrapper();

PHPAPI int php_stream_supports_lock(php_stream * stream);

This function will return either 1 (success) or 0 (failure) indicating whether or
not a lock can be set on this stream. Typically you can only set locks on stdio streams.

Casting Streams
===============
What if your extension needs to access the FILE* of a user level file pointer?
You need to "cast" the stream into a FILE*, and this is how you do it:

FILE * fp;
php_stream * stream; /* already opened */

if (php_stream_cast(stream, PHP_STREAM_AS_STDIO, (void*)&fp, REPORT_ERRORS) == FAILURE)    {
    RETURN_FALSE;
}

The prototype is:

PHPAPI int php_stream_cast(php_stream * stream, int castas, void ** ret, int
        show_err);

The show_err parameter, if non-zero, will cause the function to display an
appropriate error message of type E_WARNING if the cast fails.

castas can be one of the following values:
PHP_STREAM_AS_STDIO - a stdio FILE*
PHP_STREAM_AS_FD - a generic file descriptor
PHP_STREAM_AS_SOCKETD - a socket descriptor

If you ask a socket stream for a FILE*, the abstraction will use fdopen to
create it for you.  Be warned that doing so may cause buffered data to be lost
if you mix ANSI stdio calls on the FILE* with php stream calls on the stream.

If your system has the fopencookie function, php streams can synthesize a
FILE* on top of any stream, which is useful for SSL sockets, memory based
streams, data base streams etc. etc.

In situations where this is not desirable, you should query the stream
to see if it naturally supports FILE *.  You can use this code snippet
for this purpose:

    if (php_stream_is(stream, PHP_STREAM_IS_STDIO)) {
        /* can safely cast to FILE* with no adverse side effects */
    }

You can use:

PHPAPI int php_stream_can_cast(php_stream * stream, int castas)

to find out if a stream can be cast, without actually performing the cast, so
to check if a stream is a socket you might use:

if (php_stream_can_cast(stream, PHP_STREAM_AS_SOCKETD) == SUCCESS)  {
    /* it can be a socket */
}

Please note the difference between php_stream_is and php_stream_can_cast;
stream_is tells you if the stream is a particular type of stream, whereas
can_cast tells you if the stream can be forced into the form you request.
The former doesn't change anything, while the later *might* change some
state in the stream.

Stream Internals
================

There are two main structures associated with a stream - the php_stream
itself, which holds some state information (and possibly a buffer) and a
php_stream_ops structure, which holds the "virtual method table" for the
underlying implementation.

The php_streams ops struct consists of pointers to methods that implement
read, write, close, flush, seek, gets and cast operations.  Of these, an
implementation need only implement write, read, close and flush.  The gets
method is intended to be used for streams if there is an underlying method
that can efficiently behave as fgets.  The ops struct also contains a label
for the implementation that will be used when printing error messages - the
stdio implementation has a label of "STDIO" for example.

The idea is that a stream implementation defines a php_stream_ops struct, and
associates it with a php_stream using php_stream_alloc.

As an example, the php_stream_fopen() function looks like this:

PHPAPI php_stream * php_stream_fopen(const char * filename, const char * mode)
{
    FILE * fp = fopen(filename, mode);
    php_stream * ret;
    
    if (fp) {
        ret = php_stream_alloc(&php_stream_stdio_ops, fp, 0, 0, mode);
        if (ret)
            return ret;

        fclose(fp);
    }
    return NULL;
}

php_stream_stdio_ops is a php_stream_ops structure that can be used to handle
FILE* based streams.

A socket based stream would use code similar to that above to create a stream
to be passed back to fopen_wrapper (or it's yet to be implemented successor).

The prototype for php_stream_alloc is this:

PHPAPI php_stream * php_stream_alloc(php_stream_ops * ops, void * abstract,
        size_t bufsize, int persistent, const char * mode)

ops is a pointer to the implementation,
abstract holds implementation specific data that is relevant to this instance
of the stream,
bufsize is the size of the buffer to use - if 0, then buffering at the stream
level will be disabled (recommended for underlying sources that implement
their own buffering - such a FILE*),
persistent controls how the memory is to be allocated - persistently so that
it lasts across requests, or non-persistently so that it is freed at the end
of a request (it uses pemalloc),
mode is the stdio-like mode of operation - php streams places no real meaning
in the mode parameter, except that it checks for a 'w' in the string when
attempting to write (this may change).

The mode parameter is passed on to fdopen/fopencookie when the stream is cast
into a FILE*, so it should be compatible with the mode parameter of fopen().

Writing your own stream implementation
======================================

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
RULE #1: when writing your own streams: make sure you have configured PHP with
--enable-debug.
I've taken some great pains to hook into the Zend memory manager to help track
down allocation problems.  It will also help you spot incorrect use of the
STREAMS_DC, STREAMS_CC and the semi-private STREAMS_REL_CC macros for function
definitions.
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

RULE #2: Please use the stdio stream as a reference; it will help you
understand the semantics of the stream operations, and it will always
be more up to date than these docs :-)

First, you need to figure out what data you need to associate with the
php_stream.  For example, you might need a pointer to some memory for memory
based streams, or if you were making a stream to read data from an RDBMS like
MySQL, you might want to store the connection and rowset handles.

The stream has a field called abstract that you can use to hold this data.
If you need to store more than a single field of data, define a structure to
hold it, allocate it (use pemalloc with the persistent flag set
appropriately), and use the abstract pointer to refer to it.

For structured state you might have this:

struct my_state {
    MYSQL conn;
    MYSQL_RES * result;
};

struct my_state * state = pemalloc(sizeof(struct my_state), persistent);

/* initialize the connection, and run a query, using the fields in state to
 * hold the results */

state->result = mysql_use_result(&state->conn);

/* now allocate the stream itself */
stream = php_stream_alloc(&my_ops, state, 0, persistent, "r");

/* now stream->abstract == state */

Once you have that part figured out, you can write your implementation and
define the your own php_stream_ops struct (we called it my_ops in the above
example).

For example, for reading from this weird MySQL stream:

static size_t php_mysqlop_read(php_stream * stream, char * buf, size_t count)
{
    struct my_state * state = (struct my_state*)stream->abstract;

    if (buf == NULL && count == 0)  {
        /* in this special case, php_streams is asking if we have reached the
         * end of file */
        if (... at end of file ...)
            return EOF;
        else
            return 0;
    }
    
    /* pull out some data from the stream and put it in buf */
    ... mysql_fetch_row(state->result) ...
    /* we could do something strange, like format the data as XML here,
        and place that in the buf, but that brings in some complexities,
        such as coping with a buffer size too small to hold the data,
        so I won't even go in to how to do that here */
}

Implement the other operations - remember that write, read, close and flush
are all mandatory.  The rest are optional.  Declare your stream ops struct:

php_stream_ops my_ops = {
    php_mysqlop_write, php_mysqlop_read, php_mysqlop_close,
    php_mysqlop_flush, NULL, NULL, NULL,
    "Strange MySQL example"
}

Thats it!

Take a look at the STDIO implementation in streams.c for more information
about how these operations work.
The main thing to remember is that in your close operation you need to release
and free the resources you allocated for the abstract field.  In the case of
the example above, you need to use mysql_free_result on the rowset, close the
connection and then use pefree to dispose of the struct you allocated.
You may read the stream->persistent field to determine if your struct was
allocated in persistent mode or not.

vim:tw=78:et

Submitting Patch for PHP
========================

This document describes how to submit a patch for PHP. Since you are
reading this document, you are willing to submit a patch for PHP.
Please keep reading! Submitting a patch for PHP is easy. The hard
part is making it acceptable for inclusion into our repository. :-)

How to create patch?  
-------------------- 
We are working with CVS. You need to get CVS source to create a patch
that we accept.  Visit http://www.php.net/anoncvs.php to get CVS
source. You can check out older versions, but make sure you get
the default branch (i.e. Do not use -r option when you check out the 
CVS source)

Read CODING_STANDARDS file before you start working.

Now you are ready to create a patch. Modify source to fix a bug in PHP or
add a new feature to PHP. After you finished editing, please test your
patch. Read README.TESTING for testing.

After you finish testing your patch, take diff file using 
"cvs diff > your.patch" command.

Read README.TESTING for submitting a test script for your patch. This is
not strictly required, but it is preferred to submit a test script along
with your patch. Making new test script is very easy. It also helps us
to understand what you have been fixed or added to PHP.


Tips for creating patch 
----------------------- 
If you would like to fix multiple bugs. It is easier for us if you
could create 1 patch for 1 bug, but this is not strictly required.
Note though that you might get little response, if your patch is
too hard to review.

If you would like change/add many lines, it is better to ask module
maintainer and/or internals (a] lists.php.net, or pear-dev (a] lists.php.net if
you are patching PEAR. Official module maintainers can be found in
EXTENSIONS file in PHP source.

If you are new to CVS (Concurrent Versions System), visit 
http://cvshome.org/ for details.


Recommended CVS client settings for creating patch file
------------------------------------------------------
Recommended ~/.cvsrc file setting is:
------
cvs -z3
update -d -P
checkout -P
diff -u

------
diff -u means:
 -u     Use the unified output format.

With this CVS setting, you don't have to worry about adding/deleting
newlines and spaces.


Check list for submitting patch
-------------------------------
 - Did you run "make test" to check if your patch didn't break
   other features?
 - Did you compile PHP with --enable-debug and check the PHP and
   web server error logs when you test your patch?
 - Did you build PHP for multi-threaded web servers. (Optional)
 - Did you create test script for "make test"? (Recommended)
 - Did you check your patch is unified format and it does not 
   contain white space changes? (If you are not using recommended 
   cvs setting)
 - Did you update CVS source before you take final patch?
 - Did you read the patch again?


Where to send your patch?
-------------------------
If you are patching C source, send the patch to internals (a] lists.php.net. 
If you are patching a module, you should also send the patch to the 
maintainer. Official module maintainers are listed in EXTENSION file 
in source.

If you are patching PEAR, send the patch to pear-dev (a] lists.php.net.

Please add the prefix "[PATCH]" to your email subject and make sure
to include the patch as a MIME attachment even if it is short. 

NOTE: only MIME attachments of type 'text/*' are accepted. The
      easiest way to accomplish this, is to make the extension
      '.txt'.

Test scripts should be included in the same email.
Explain what has been fixed/added/changed by your patch.

Finally, add the bug Id(s) which can be closed by your patch, if any.


What happens after you submit your patch
---------------------------------------- 
If your patch is easy to review and has obviously no side-effects,
it might take up to a few hours until someone commits it.

Because this is a volunteer-driven effort, more complex patches will
require more patience on your side. 

If you did not receive any feedback in a few days, please consider
resubmitting the description of your patch, along-side with
these questions:

- Is my patch too hard to review? Because of which factors?
- Should I split it up in multiple parts?
- Are there any unwanted whitespace changes?


What happens when your patch is applied?
---------------------------------------- 
Your name will be included together with your email address in the CVS 
commit log. If your patch affects end-users, a brief description
and your name might be added to the NEWS file.


Thank you for submitting patch for PHP!

[IMPORTANT NOTICE]
------------------
 Failed tests usualy indicate a problem with your local system setup
and not within PHP itself (at least for official PHP release versions).
You may decide to automaticaly submit a test summary to our QA workflow
at the end of a test run.
 Please do *not* submit a failed test as a bug or ask for help on why
it failed on your system without providing substantial backup information
on *why* the test failed on your special setup. Thank you :-)


[Testing Basics] 
----------------
 The easiest way to test your PHP build is to run "make test" from the
command line after successfully compiling. This will run the complete
tests for all enabled functionalities and extensions using the PHP
CLI binary.
 To execute test scripts, you must build PHP with some SAPI, then you
type "make test" to execute all or some test scripts saved under
"tests" directory under source root directory.

Usage:
make test

 "make test" basically executes "run-tests.php" script
under the source root (parallel builds will not work). Therefore you
can execute the script as follows:

TEST_PHP_EXECUTABLE=sapi/cli/php \
sapi/cli/php [-c /path/to/php.ini] run-tests.php [ext/foo/tests/GLOB]


[Which "php" executable "make test" look for]
---------------------------------------------
 You must use TEST_PHP_EXECUTABLE environment variable to explicitly
select the php executable to be used to run the tests. That can either
be the CLI or CGI executable.

 "make test" executes "run-tests.php" script with "php" binary.  Some
test scripts such as session must be executed by CGI SAPI. Therefore,
you must build PHP with CGI SAPI to perform all tests.

NOTE: PHP binary executing "run-tests.php" and php binary used for
executing test scripts may differ. If you use different PHP binary for
executing "run-tests.php" script, you may get errors.


[Which php.ini is used]
-----------------------
 "make test" uses the same php.ini file as it would once installed.
The tests have been written to be independent of that php.ini file,
so if you find a test that is affected by a setting, please report
this, so we can address the issue.


[Which test scripts are executed]
---------------------------------
 "run-tests.php" ("make test"), without any arguments executes all
test scripts by extracting all directories named "tests"
from the source root and any subdirectories below. If there are files,
which have a "phpt" extension, "run-tests.php" looks at the sections
in these files, determines whether it should run it, by evaluating
the 'SKIP' section. If the test is eligible for execution, the 'FILE'
section is extracted into a ".php" file (with the same name besides 
the extension) and gets executed.
When an argument is given or TESTS environment variable is set, the
GLOB is expanded by the shell and any file with extension "*.phpt" is
regarded as a test file.

 Tester can easily execute tests selectively with as follows.

Examples:
./sapi/cli/php run-tests.php ext/mbstring/*
./sapi/cli/php run-tests.php ext/mbstring/020.phpt


[Test results]
--------------
 Test results are printed to standard output. If there is a failed test, 
the "run-tests.php" script saves the result, the expected result and the
code executed to the test script directory. For example, if 
ext/myext/tests/myext.phpt fails to pass, the following files are created:

ext/myext/tests/myext.php   - actual test file executed
ext/myext/tests/myext.log   - log of test execution (L)
ext/myext/tests/myext.exp   - expected output (E)
ext/myext/tests/myext.out   - output from test script (O)
ext/myext/tests/myext.diff  - diff of .out and .exp (D)

 Failed tests are always bugs. Either the test is bugged or not considering
factors applying to the tester's environment, or there is a bug in PHP.
If this is a known bug, we strive to provide bug numbers, in either the
test name or the file name. You can check the status of such a bug, by
going to: http://bugs.php.net/12345 where 12345 is the bug number.
For clarity and automated processing, bug numbers are prefixed by a hash
sign '#' in test names and/or test cases are named bug12345.phpt.

NOTE: The files generated by tests can be selected by setting the
environment variable TEST_PHP_LOG_FORMAT. For each file you want to be
generated use the character in brackets as shown above (default is LEOD).
The php file will be generated always.

NOTE: You can set environment variable TEST_PHP_DETAILED to enable
detailed test information.

[Automated testing]
 If you like to keep up to speed, with latest developments and quality
assurance, setting the environment variable NO_INTERACTION to 1, will not
prompt the tester for any user input.

Normally, the exit status of "make test" is zero, regardless of the results
of independent tests. Set the environment variable REPORT_EXIT_STATUS to 1,
and "make test" will set the exit status ("$?") to non-zero, when an
individual test has failed.

Example script to be run by cron(1):
========== qa-test.sh =============
#!/bin/sh

CO_DIR=$HOME/cvs/php5
MYMAIL=qa-test (a] domain.com
TMPDIR=/var/tmp
TODAY=`date +"%Y%m%d"`

# Make sure compilation enviroment is correct
CONFIGURE_OPTS='--disable-all --enable-cli --with-pcre'
export MAKE=gmake
export CC=gcc

# Set test environment
export NO_INTERACTION=1
export REPORT_EXIT_STATUS=1

cd $CO_DIR
cvs update . >>$TMPDIR/phpqatest.$TODAY
./cvsclean ; ./buildconf ; ./configure $CONFIGURE_OPTS ; $MAKE
$MAKE test >>$TMPDIR/phpqatest.$TODAY 2>&1
if test $? -gt 0
then
        cat $TMPDIR/phpqatest.$TODAY | mail -s"PHP-QA Test Failed for $TODAY" $MYMAIL
fi
========== end of qa-test.sh =============

NOTE: the exit status of run-tests.php will be 1 when
REPORT_EXIT_STATUS is set. The result of "make test" may be higher
than that. At present, gmake 3.79.1 returns 2, so it is
advised to test for non-zero, rather then a specific value.


[Creating new test files]
-------------------------
 Writing test file is very easy if you are used to PHP. 
See the HOWTO at http://qa.php.net/write-test.php


[How to help us]
----------------
 If you find bug in PHP, you can submit bug report AND test script 
for us. You don't have to write complete script, just give us test
script with following format. Please test the script and make sure
you write the correct ACTUAL OUTPUT and EXPECTED OUTPUT before you
submit.

<?php
/* 
Bug #12345
substr() bug. Do not return expected string.

ACTUAL OUTPUT
XYXA

EXPECTED OUTPUT
ABCD
*/

$str = "XYZABCD";
echo substr($str,3,7);

?>

[IMPORTANT NOTICE]
------------------
This is an addendum to README.TESTING with additional information 
specific to run-tests2.php.

run-tests2.php is backward compatible with tests developed for
the original run-tests.php script.  run-tests2 is *not* used by
'make test'.  run-tests2 was developed to provide support for
testing PHP under it's primary environment, HTTP, and can run the
PHP tests under any of the SAPI modules that are direct executables, 
or are accessable via HTTP.

[New features]
----------------
* Command line interface:
  You can run 'php run-tests2.php -h' to get all the possible options.
* Configuration file:
  the -c argument will allow you to use a configuration file.  This is
  handy if you are testing multiple environments and need various options
  depending on the environment.
  see run-tests-config.php for details.
* CGI Emulation:
  Will emulate a CGI environment when testing with the cgi sapi executable.
* HTTP testing:
  can be configured to run test scripts through an HTTP server running
  on localhost.  localhost is required since either the web server must
  alias a directory to the php source directory, or the test scripts
  must be copied to a directory under the web server 
  (see config options TEST_WEB_BASE_URL, TEST_BASE_PATH, and TEST_WEB_EXT)
* New sections supported for test files (see below)

When running tests over http, tests that require ini settings different that what
the web server runs under will be skipped.  Since the test harness defines a number
of ini settings by default, the web server may require special configuration to
make testing work.

[Example Usage]
----------------
Some (but not all!) examples of usage:

1. run tests from the php source directory
    php run-tests2.php -p /path/to/php-cli

2. run tests using cgi emulation
    php run-tests2.php -p /path/to/php-cgi

3. run tests over http, copying test files into document root
    php run-tests2.php -w -u http://localhost/test -m /path/to/htdocs/test

4. run tests over http, php sources have been aliased in web server
    php run-tests2.php -w -u http://localhost/test
    
5. run tests using configuration file
    php run-tests2.php -c /path/to/run-tests-config.php

6. run tests using configuration file, but overriding some settings:
   (config file must be first)
    php run-tests2.php -c /path/to/run-tests-config.php -w -t 3 -d /path/to/testdir

NOTE: configuration as described in README.TESTING still works.

[New Test Sections] 
----------------
In addition to the traditional test sections 
(see http://qa.php.net/write-test.php), several new sections are available 
under run-tests2.

--POST--
This is not a new section, but not multipart posts are supported for testing
file uploads, or other types of POST data.

--CGI--
This section takes no value.  It merely provides a simple marker for tests
that MUST be run as CGI, even if there is no --POST-- or --GET-- sections
in the test file.

--DESCRIPTION--
Not used for anything, just a section for documenting the test

--ENV--
This section get's eval()'d to help build an environment for the 
execution of the test.  This can be used to change environment
vars that are used for CGI emulation, or simply to set env vars
for cli testing.  A full example looks like:

  --ENV--
  return <<<END
  PATH_TRANSLATED=$filename
  PATH_INFO=$scriptname
  SCRIPT_NAME=$scriptname
  END;

Some variables are made easily available for use in this section, they
include:
  $filename     full native path to file, will become PATH_TRANSLATED
  $filepath     =dirname($filename)
  $scriptname   this is what will become SCRIPT_NAME unless you override it
  $docroot      the equivelant of DOCUMENT_ROOT under Apache
  $cwd          the directory that the test is being initiated from
  $this->conf   all run-tests2 configuration vars
  $this->env    all environment variables that will get passed to the test


--REQUEST--
This section is also eval'd, and is similar in nature to --ENV--.  However,
this section is used to build the url used in an HTTP request.  Valid values
to set in this section would include:
  SCRIPT_NAME   The inital part of the request url
  PATH_INFO     The pathinfo part of a request url
  FRAGMENT      The fragment section of a url (after #)
  QUERY_STRING  The query part of a url (after ?)

  --REQUEST--
  return <<<END
  PATH_INFO=/path/info
  END;

--HEADERS--
This section is also eval'd.  It is used to provide additional headers sent
in an HTTP request, such as content type for multipart posts, cookies, etc.

  --HEADERS--
  return <<<END
  Content-Type=multipart/form-data; boundary=---------------------------240723202011929
  Content-Length=100
  END;

--EXPECTHEADERS--
This section can be used to define what headers are required to be
received back from a request, and is checked in addition to the
regular expect sections.  For example:

  --EXPECTHEADERS--
  Status: 404

PHP Build System V5 Overview

- supports Makefile.ins during transition phase
- not-really-portable Makefile includes have been eliminated
- supports separate build directories without VPATH by using
  explicit rules only
- does not waste disk-space/CPU-time for building temporary libraries
  => especially noticeable on slower systems
- slow recursive make replaced with one global Makefile
- eases integration of proper dependencies
- adds PHP_DEFINE(what[, value]) which creates a single include-file
  per what.  This will allow more fine-grained dependencies.
- abandoning the "one library per directory" concept
- improved integration of the CLI
- several new targets
  build-modules: builds and copies dynamic modules into modules/
  install-cli: installs the CLI only, so that the install-sapi
               target does only what its name says
- finally abandoned automake (still requires aclocal at this time)
- changed some configure-time constructs to run at buildconf-time
- upgraded shtool to 1.5.4
- removed $(moduledir) (use EXTENSION_DIR)

The Reason For a New System

It became more and more apparent that there is a severe need
for addressing the portability concerns and improving the chance
that your build is correct (how often have you been told to
"make clean"? When this is done, you won't need to anymore).


If You Build PHP on a Unix System


You, as a user of PHP, will notice no changes.  Of course, the build
system will be faster, look better and work smarter.



If You Are Developing PHP




Extension developers:

Makefile.ins are abandoned.  The files which are to be compiled
are specified in the config.m4 now using the following macro:

PHP_NEW_EXTENSION(foo, foo.c bar.c baz.cpp, $ext_shared)

E.g. this enables the extension foo which consists of three source-code
modules, two in C and one in C++.  And, depending on the user's wishes,
the extension will even be built as a dynamic module.

The full syntax:

PHP_NEW_EXTENSION(extname, sources [, shared [,sapi_class[, extra-cflags]]])

Please have a look at acinclude.m4 for the gory details and meanings
of the other parameters.

And that's basically it for the extension side.

If you previously built sub-libraries for this module, add
the source-code files here as well.  If you need to specify
separate include directories, do it this way:

PHP_NEW_EXTENSION(foo, foo.c mylib/bar.c mylib/gregor.c,,,-I@ext_srcdir@/lib)

E.g. this builds the three files which are located relative to the
extension source directory and compiles all three files with the
special include directive (@ext_srcdir@ is automatically replaced).

Now, you need to tell the build system that you want to build files
in a directory called $ext_builddir/lib:

PHP_ADD_BUILD_DIR($ext_builddir/lib)

Make sure to call this after PHP_NEW_EXTENSION, because $ext_builddir
is only set by the latter.

If you have a complex extension, you might to need add special
Make rules.  You can do this by calling PHP_ADD_MAKEFILE_FRAGMENT
in your config.m4 after PHP_NEW_EXTENSION.

This will read a file in the source-dir of your extension called
Makefile.frag.  In this file, $(builddir) and $(srcdir) will be
replaced by the values which are correct for your extension
and which are again determined by the PHP_NEW_EXTENSION macro.

Make sure to prefix *all* relative paths correctly with either
$(builddir) or $(srcdir).  Because the build system does not
change the working directory anymore, we must use either
absolute paths or relative ones to the top build-directory.
Correct prefixing ensures that.


SAPI developers:

Instead of using PHP_SAPI=foo/PHP_BUILD_XYZ, you will need to type

PHP_SELECT_SAPI(name, type, sources.c)

I.e. specify the source-code files as above and also pass the
information regarding how PHP is supposed to be built (shared
module, program, etc).

For example for APXS:

PHP_SELECT_SAPI(apache, shared, sapi_apache.c mod_php5.c php_apache.c)



General info

The foundation for the new system is the flexible handling of
sources and their contexts.  With the help of macros you
can define special flags for each source-file, where it is
located, in which target context it can work, etc.

Have a look at the well documented macros
PHP_ADD_SOURCES(_X) in acinclude.m4.

PHP 5.2 UPDATE INFO

===============================
Changes in PHP datetime support
===============================

Since PHP 5.1, there has been an extension named 'date' in the PHP core. This
is the new implementation of PHP's datetime support. Although it will attempt
to guess your system's timezone setting, you should set the timezone manually.
You can do this in any of three ways:

1) in your php.ini using the date.timezone INI directive
2) on your system using the TZ environmental variable
3) from your script using the convenience function date_default_timezone_set()

All supported timezones are listed in the PHP Manual at
http://www.php.net/manual/timezones.php.

With the advent of PHP 5.2, there are object representations of the date and
timezone, named DateTime and DateTimeZone respectively. You can see the methods
and constants available to the new classes by running

php --rc DateTime
php --rc DateTimeZone

under PHP CLI - or see the PHP Manual under Date/Time functions, or the 'NEW
FEATURES' section below. All methods map to existing procedural date functions.

==================================
Items from the NEWS file explained
==================================

- Added new error mode E_RECOVERABLE_ERROR. (Derick, Marcus, Tony)

  Some of the existing E_ERROR conditions have been converted to something that
  you can catch with a user-defined error handler. If an E_RECOVERABLE_ERROR is
  not handled, it will behave in the same way as E_ERROR behaves in all versions
  of PHP. Errors of this type are logged as 'Catchable fatal error'.


- Changed E_ALL error reporting mode to include E_RECOVERABLE_ERROR. (Marcus)

  This change means that the value of the E_ALL error_reporting constant is now
  6143, where the previous value was 2047. If you are setting the error_reporting
  mode from either the Apache config file or the .htaccess files, you will need
  to adjust the value accordingly. The same applies if you use the numeric value
  rather than the constant in your PHP scripts.


- Added support for constructors in interfaces to force constructor signature
  checks in implementations. (Marcus)

  Starting with PHP 5.2, interfaces can have constructors. However, if you choose
  to declare a constructor in an interface, each class implementing that interface
  MUST include a constructor with a signature matching that of the base interface
  constructor. By 'signature' we mean the parameter and return type definitions,
  including any type hints and including whether the data is passed by reference
  or by value.


- Changed __toString to be called wherever applicable. (Marcus)

  The magic method __toString() will now be called in a string context, that
  is, anywhere an object is used as a string. When implementing your __toString()
  method in a class, you should be aware that the script will terminate if
  your function throws an exception.

  The PHP 5.0/5.1 fallback - returning a string that contains the object
  identifier - has been dropped in PHP 5.2. It became problematic because
  an object identifier cannot be considered unique. This change will mean
  that your application is flawed if you have relied on the object identifier
  as a return value. An attempt to use that value as a string will now result
  in a catchable fatal error (see above).

  Even with __toString(), objects cannot be used as array indices or keys. We
  may add built-in hash support for this at a later date, but for PHP 5.2 you
  will need to either provide your own hashing or use the new SPL function
  spl_object_hash().


- Added RFC2397 (data: stream) support. (Marcus)

  The introduction of the 'data' URL scheme has the potential to lead to a
  change of behaviour under Windows. If you are working with an NTFS
  file system and making use of meta streams in your application, and if you
  just happen to be using a file with the name 'data:' that is accessed without
  any path information - it won't work any more. The fix is to use the 'file:'
  protocol when accessing it.

  There is information about the RFC at http://www.faqs.org/rfcs/rfc2397.html.


- Added allow_url_include ini directive to complement allow_url_fopen. (Rasmus)

  This useful option makes it possible to differentiate between standard
  file operations on remote files, and the inclusion of remote files. While the
  former is usually desirable, the latter can be a security risk if used naively.
  Starting with PHP 5.2, you can allow remote file operations while
  disallowing the inclusion of remote files in local scripts. In fact, this
  is the default configuration.


- Dropped abstract static class functions. (Marcus)

  Due to an oversight, PHP 5.0 and 5.1 allowed abstract static functions in
  classes. In PHP 5.2, only interfaces can have them.


- Removed extensions (Derick, Tony)

  The filepro and hwapi extensions have been moved to PECL and are no longer
  part of the PHP distribution. The PECL package version of these extensions
  will be created according to user demand.


- Added extensions (Rasmus, Derick, Pierre)

  The JSON extension implements the JavaScript Object Notation (JSON)
  data interchange format. This extension is enabled by default.

  The Filter extension validates and filters data, and is designed for
  use with insecure data such as user input. This extension is enabled
  by default; the default mode RAW does not impact input data in any way.

  The Zip extension enables you to transparently read or write ZIP
  compressed archives and the files inside them.

  Please refer to the NEW FEATURES section below or to the PHP Manual
  for details.


- Improved memory manager and increased default memory limit (Dmitry)

  The new memory manager allocates less memory and works faster than the
  previous incarnation. It allocates memory from the system in large blocks,
  and then manages the heap by itself. The memory_limit value in php.ini is
  checked, not for each emalloc() call (as before), but for actual blocks
  requested from the system. This means that memory_limit is far more
  accurate than it used to be, since the old memory manager didn't calculate
  all the memory overhead used by the malloc library.

  Thanks to this new-found accuracy memory usage may appear to have increased,
  although actually it has not. To accommodate this apparent increase, the
  default memory_limit setting was also increased - from 8 to 16 megabytes.


- Changed priority of PHPRC environment variable on win32 (Dmitry)

  The PHPRC environment variable now takes priority over the path stored
  in the Windows registry.


- CLI SAPI no longer checks cwd for php.ini or the php-cli.ini file (Edin)

  In PHP 5.1 an undocumented feature was added that made the CLI binary check
  the current working directory for a PHP configuration file, potentially
  leading to unpredictable behavior if an unexpected configuration file were
  read. This functionality was removed in 5.2, and PHP will no longer search
  CWD for the presence of php.ini or php-cli.ini files.


- Added a notice when performing modulus 0 operation (Tony)

  In earlier versions of PHP, performing integer % 0 did not emit any
  warning messages, instead returning an unexpected return value of FALSE.
  As of PHP 5.2 this operation will emit an E_WARNING, as is the case in all
  other instances where division by zero is performed.


- As a side-effect of a change made to prevent duplicate error messages
  when error_tracking is On [Ilia], it is now necessary to return FALSE
  from your error handler in order to populate $php_errormsg. This allows
  you to fine-grain the levels of the messages stored.


==================
NEW ERROR MESSAGES
==================

In the PHP core
===============

<?php

print 10%0;
/* Warning:  Division by zero in filename on line n */

echo " ";
session_regenerate_id();
/*  Warning:  session_regenerate_id(): Cannot regenerate session id - headers already sent in filename on line n */

str_word_count("string", 4);
/* Warning:  str_word_count(): Invalid format value 4 in filename on line n */

strripos("foo", "f", 4);
/* Notice:  strripos(): Offset is greater than the length of haystack string in filename on line n */

strrpos("foo", "f", 4);
/* Notice:  strrpos(): Offset is greater than the length of haystack string in filename on line n */

?>

OO related in the PHP core
==========================

<?php

interface foo {
}
class bar implements foo, foo {
}
/* Fatal error: Class bar cannot implement previously implemented interface foo in filename on line n */


class foo {
	public $bar;
	function __get($var)
	{
		return $this->bar;
	}
}

$foo = new foo;
$bar =& $foo->prop;
/* Notice: Indirect modification of overloaded property foo::$prop has no effect in filename on line n */


class foo implements iterator {
    public function current() {

    }
    public function next() {

    }
    public function key() {

    }
    public function valid() {

    }
    public function rewind() {

    }
}

$foo = new foo();
foreach($foo as &$ref) {}
/* Fatal error: An iterator cannot be used with foreach by reference in filename on line n */


class foo {
    private function __construct() {
    }
}
class bar extends foo {
    public function __construct() {
        parent::__construct();
        /* Fatal error:  Cannot call private foo::__construct() in filename on line n */
    }
}
new bar;


abstract class foo {
    abstract static function bar();
    /* Strict Standards:  Static function foo::bar() should not be abstract in filename on line n */
}


stream_filter_register("", "class");
/* Warning:  stream_filter_register(): Filter name cannot be empty in filename on line n */

stream_filter_register("filter", "");
/* Warning:  stream_filter_register(): Class name cannot be empty in filename on line n */


class foo {
    public function __toString() {
        throw new Exception;
    }
}
try {
    print new foo;
    /* Fatal error:  Method foo::__toString() must not throw an exception in filename on line n */
} catch(Exception $e) {}


class foo {}
$foo = new foo;
print $foo;
/* Catchable fatal error:  Object of class foo could not be converted to string in filename on line n */

?>

In the bzip2 extension
======================

<?php

bzopen("", "w");
/* Warning:  bzopen(): filename cannot be empty in filename on line n */

bzopen("foo", "a");
/* Warning:  bzopen(): 'a' is not a valid mode for bzopen(). Only 'w' and 'r' are supported in filename on line n */

$fp = fopen("foo", "w");
bzopen($fp, "r");
/* Warning:  bzopen(): cannot read from a stream opened in write only mode in filename on line n */

?>

In the dBase extension
======================

<?php

dbase_open("foo", -1);
/* Warning: Invalid access mode -1 in filename on line n */

?>

In the mcrypt extension
=======================

<?php

$key = "this is a secret key";

$td = mcrypt_module_open('tripledes', '', 'ecb', '');
$iv = mcrypt_create_iv (mcrypt_enc_get_iv_size($td), MCRYPT_RAND);
mcrypt_generic_init($td, $key, $iv);
$encrypted_data = mcrypt_generic($td, "");
/* Warning: mcrypt_generic(): An empty string was passed in filename on line n */

?>

In the oci8 extension
=====================

<?php

oci_connect("user", "pass", "db", "bogus_charset");
/* Warning: Invalid character set name: bogus_charset in filename on line n */

$oci = oci_connect("user", "pass", "db");
oci_password_change($oci, "", "old", "new");
/* Warning: username cannot be empty in filename on line n */

oci_password_change($oci, "user", "", "new");
/* Warning: old password cannot be empty in filename on line n */

oci_password_change($oci, "user", "old", "");
/* Warning: new password cannot be empty in filename on line n */

?>

In the SPL extension
====================

<?php

$obj = new SplFileObject(__FILE__);
$obj->fgetcsv("foo");
/* Warning:  SplFileObject::fgetcsv(): delimiter must be a character in filename on line n */

$obj->fgetcsv(",", "foo");
/* Warning:  SplFileObject::fgetcsv(): enclosure must be a character in filename on line n */

?>


============
NEW FEATURES
============

New extensions
==============

  Filter
    Methods:
      mixed filter_has_var(constant type, string variable_name)
        - Returns true if the variable with the name 'name' exists in source
      int filter_id(string filtername)
        - Returns the filter ID belonging to a named filter
      mixed filter_input(constant type, string variable_name [, long filter [, mixed options]])
        - Returns the filtered variable 'name'* from source `type`
      mixed filter_input_array(constant type, [, mixed options]])
        - Returns an array with all arguments defined in 'definition'
      array filter_list()
        - Returns a list of all supported filters
      mixed filter_var(mixed variable [, long filter [, mixed options]])
        - Returns the filtered version of the variable.
      mixed filter_var_array(array data, [, mixed options]])
        - Returns an array with all arguments defined in 'definition'

  JSON
    Methods:
      mixed json_decode(string json[, boolean assoc=0])
        - Decodes a JSON string into a PHP object/associative array
      string json_encode(mixed parameter)
        - Takes a object or an array and returns a JSON encoded string

  Zip
    Class constants:
      ZipArchive::CHECKCONS
      ZipArchive::CM_DEFAULT
      ZipArchive::CM_DEFLATE
      ZipArchive::CM_DEFLATE64
      ZipArchive::CM_IMPLODE
      ZipArchive::CM_PKWARE_IMPLODE
      ZipArchive::CM_REDUCE_1
      ZipArchive::CM_REDUCE_2
      ZipArchive::CM_REDUCE_3
      ZipArchive::CM_REDUCE_4
      ZipArchive::CM_SHRINK
      ZipArchive::CM_STORE
      ZipArchive::CREATE
      ZipArchive::ER_CHANGED
      ZipArchive::ER_CLOSE
      ZipArchive::ER_COMPNOTSUPP
      ZipArchive::ER_CRC
      ZipArchive::ER_DELETED
      ZipArchive::ER_EOF
      ZipArchive::ER_EXISTS
      ZipArchive::ER_INCONS
      ZipArchive::ER_INTERNAL
      ZipArchive::ER_INVAL
      ZipArchive::ER_MEMORY
      ZipArchive::ER_MULTIDISK
      ZipArchive::ER_NOENT
      ZipArchive::ER_NOZIP
      ZipArchive::ER_OK
      ZipArchive::ER_OPEN
      ZipArchive::ER_READ
      ZipArchive::ER_REMOVE
      ZipArchive::ER_RENAME
      ZipArchive::ER_SEEK
      ZipArchive::ER_TMPOPEN
      ZipArchive::ER_WRITE
      ZipArchive::ER_ZIPCLOSED
      ZipArchive::ER_ZLIB
      ZipArchive::EXCL
      ZipArchive::FL_COMPRESSED
      ZipArchive::FL_NOCASE
      ZipArchive::FL_NODIR
      ZipArchive::FL_UNCHANGED
      ZipArchive::OVERWRITE

    Functions:
      void zip_close(resource zip)
        - Close a Zip archive
      void zip_entry_close(resource zip_ent)
        - Close a zip entry
      int zip_entry_compressedsize(resource zip_entry)
        - Return the compressed size of a Zip entry
      string zip_entry_compressionmethod(resource zip_entry)
        - Return a string containing the compression method used on a particular entry
      int zip_entry_filesize(resource zip_entry)
        - Return the actual filesize of a Zip entry
      string zip_entry_name(resource zip_entry)
        - Return the name given a Zip entry
      bool zip_entry_open(resource zip_dp, resource zip_entry [, string mode])
        - Open a Zip File, pointed by the resource entry
      mixed zip_entry_read(resource zip_entry [, int len])
        - Read from an open directory entry
      resource zip_open(string filename)
        - Create new zip using source URI for output
      resource zip_read(resource zip)
        - Returns the next file in the archive
    Methods:
      bool ZipArchive::addFile(string filepath[, string entryname[, int start [, int length]]])
        - Add a file in a Zip archive using its path and the name to use
      bool ZipArchive::addFromString(string name, string content)
        - Add a file using content and the entry name
      void ZipArchive::close()
        - close the zip archive
      bool ZipArchive::deleteIndex(int index)
        - Delete a file using its index
      bool ZipArchive::deleteName(string name)
        - Delete a file using its index
      bool ZipArchive::extractTo(string pathto[, mixed files])
        - Extract one or more file from a zip archive to a specified destination
      string ZipArchive::getArchiveComment()
        - Returns the Zip archive comment
      string ZipArchive::getCommentIndex(int index)
        - Returns the comment of an entry using its index
      string ZipArchive::getCommentName(string name)
        - Returns the comment of an entry using its name
      string ZipArchive::getFromName(string entryname[, int len [, int flags]])
        - get the contents of an entry using its name
      string ZipArchive::getFromIndex(string entryname[, int len [, int flags]])
        - get the contents of an entry using its index
      string ZipArchive::getNameIndex(int index [, int flags])
        - Returns the name of the file at position index
      resource ZipArchive::getStream(string entryname)
        - Get a stream for an entry using its name
      int ZipArchive::locateName(string filename[, int flags])
        - Returns the index of the entry named filename in the archive
      mixed ZipArchive::open(string source [, int flags])
        - Create new zip using source URI for output, return TRUE on success or the error code
      bool ZipArchive::renameIndex(int index, string new_name)
        - Rename an entry selected by its index to new_name
      bool ZipArchive::renameName(string name, string new_name)
        - Rename an entry selected by its name to new_name
      bool ZipArchive::setArchiveComment(string name, string comment)
        - Set or remove (NULL/'') the comment of the archive
      bool ZipArchive::setCommentIndex(int index, string comment)
        - Set or remove (NULL/'') the comment of an entry using its index
      bool ZipArchive::setCommentName(string name, string comment)
        - Set or remove (NULL/'') the comment of an entry using its Name
      array ZipArchive::statIndex(int index[, int flags])
        - Returns the zip entry information using its index
      array ZipArchive::statName(string filename[, int flags])
        - Returns the information about a the zip entry filename
      bool ZipArchive::unchangeAll()
        - All changes made to the archive are reverted
      bool ZipArchive::unchangeArchive()
        - Revert all global changes to the archive.  For now, this only reverts archive comment changes
      bool ZipArchive::unchangeIndex(int index)
        - Changes to the file at position index are reverted
      bool ZipArchive::unchangeName(string name)
        - Changes to the file named 'name' are reverted


New classes
===========

  DateTime:
    Constants:
      DateTime::ATOM
      DateTime::COOKIE
      DateTime::ISO8601
      DateTime::RFC822
      DateTime::RFC850
      DateTime::RFC1036
      DateTime::RFC1123
      DateTime::RFC2822
      DateTime::RFC3339
      DateTime::RSS
      DateTime::W3C
    Methods:
      DateTime::__construct([string time[, DateTimeZone object]])
      - Returns new DateTime object
      string DateTime::format(DateTime object, string format)
      - Returns date formatted according to given format
      long DateTime::getOffset(DateTime object)
      - Returns the DST offset
      DateTimeZone DateTime::getTimezone(DateTime object)
      - Return new DateTimeZone object relative to give DateTime
      void DateTime::modify(DateTime object, string modify)
      - Alters the timestamp
      array DateTime::parse(string date)
      - Returns associative array with detailed info about given date
      void DateTime::setDate(DateTime object, long year, long month, long day)
      - Sets the date
      void DateTime::setISODate(DateTime object, long year, long week[, long day])
      - Sets the ISO date
      void DateTime::setTime(DateTime object, long hour, long minute[, long second])
      - Sets the time
      void DateTime::setTimezone(DateTime object, DateTimeZone object)
      - Sets the timezone for the DateTime object

  DateTimeZone:
    Methods:
      DateTimeZone DateTimeZone::__construct(string timezone)
      - Returns new DateTimeZone object
      string DateTimeZone::getName(DateTimeZone object)
      - Returns the name of the timezone
      long DateTimeZone::getOffset(DateTimeZone object, DateTime object)
      - Returns the timezone offset
      array DateTimeZone::getTransitions(DateTimeZone object)
      - Returns numerically indexed array containing associative array for all transitions for the timezone

  RecursiveRegexIterator:
      extends RegexIterator
      implements OuterIterator, Traversable, Iterator, RecursiveIterator
    Methods:
      RecursiveRegexIterator::__construct(RecursiveIterator it, string regex [, int mode [, int flags [, int preg_flags]]])
        Create an RecursiveRegexIterator from another recursive iterator and a regular expression
      RecursiveRegexIterator RecursiveRegexIterator::getChildren()
        Return the inner iterator's children contained in a RecursiveRegexIterator
      bool RecursiveRegexIterator::hasChildren()
        Check whether the inner iterator's current element has children

  RegexIterator:
      extends FilterIterator
      implements Iterator, Traversable, OuterIterator
    Constants:
      RecursiveRegexIterator::ALL_MATCHES
      RecursiveRegexIterator::GET_MATCH
      RecursiveRegexIterator::MATCH
      RecursiveRegexIterator::REPLACE
      RecursiveRegexIterator::SPLIT
      RecursiveRegexIterator::USE_KEY
    Properties:
      public $replacement
    Methods:
      RegexIterator::__construct(Iterator it, string regex [, int mode [, int flags [, int preg_flags]]])
        - Create an RegexIterator from another iterator and a regular expression
      bool RegexIterator::accept()
        - Match (string)current() against regular expression
      bool RegexIterator::getFlags()
        - Returns current operation flags
      bool RegexIterator::getMode()
        - Returns current operation mode
      bool RegexIterator::getPregFlags()
        - Returns current PREG flags (if in use or NULL)
      bool RegexIterator::setFlags(int new_flags)
        - Set operation flags
      bool RegexIterator::setMode(int new_mode)
        - Set new operation mode
      bool RegexIterator::setPregFlags(int new_flags)
        - Set PREG flags


New methods
===========

In ext/dom
==========
    DOMDocument:
      DOMDocument::registerNodeClass(string baseclass, string extendedclass)
        - Register extended class used to create base node type

    DOMElement:
      DOMElement::setIDAttribute(string name, boolean isId)
        - Declares the attribute specified by name to be of type ID
      DOMElement::setIDAttributeNode(DOMAttr idAttr, boolean isId)
        - Declares the attribute specified by node to be of type ID
      DOMElement::setIDAttributeNS(string namespaceURI, string localName, boolean isId)
        - Declares the attribute specified by local name and namespace URI to be of type ID

    DOMNode:
      DOMNode::C14N([bool exclusive [, bool with_comments [, array xpath [, array ns_prefixes]]]])
        - Canonicalize nodes to a string
      DOMNode::C14NFile(string uri [, bool exclusive [, bool with_comments [, array xpath [, array ns_prefixes]]]])
        - Canonicalize nodes to a file
      DOMNode::getNodePath()
        - Gets an xpath for a node

In ext/soap
===========
    SoapServer:
      SoapServer::setObject(object obj)
        - Sets object which will handle SOAP requests

In ext/spl
==========
    ArrayObject:
      int ArrayObject::asort(void)
        - Sort the entries by values
      int ArrayObject::ksort(void)
        - Sort the entries by key
      int ArrayObject::natcasesort(void)
        - Sort the entries by key using case insensitive "natural order" algorithm.
      int ArrayObject::natsort(void)
        - Sort the entries by values using "natural order" algorithm.
      int ArrayObject::uasort(callback cmp_function)
        - Sort the entries by values user defined function
      int ArrayObject::uksort(callback cmp_function)
        - Sort the entries by key using user defined function.

    AppendIterator:
      ArrayIterator AppendIterator::getArrayIterator()
        Get access to inner ArrayIterator
      int AppendIterator::getIteratorIndex()
        Get index of iterator

    CachingIterator:
      bool CachingIterator::getCache()
        Return the cache
      int CachingIterator::getFlags()
        Return the internal flags
      bool CachingIterator::offsetExists(mixed index)
        Return whether the requested index exists
      string CachingIterator::offsetGet(mixed index)
        - Return the internal cache if used
      void CachingIterator::offsetSet(mixed index, mixed newval)
        - Set given index in cache
      void CachingIterator::offsetUnset(mixed index)
        - Unset given index in cache
      void CachingIterator::setFlags()
        Set the internal flags

    SplFileObject:
      array("delimiter" =>, "enclosure" =>) SplFileObject::getCsvControl(void)
        - Get the delimiter and enclosure character used in fgetcsv
      void SplFileObject::setCsvControl([string delimiter = ',' [, string enclosure = '"']])
        - Set the delimiter and enclosure character used in fgetcsv

    XMLReader:
      boolean XMLReader::setSchema(string filename)
        Use W3C XSD schema to validate the document as it is processed. Activation is only possible before the first Read()


New class constants
===================

In ext/pdo
==========
  PDO::ATTR_DEFAULT_FETCH_MODE
  PDO::FETCH_PROPS_LATE

In ext/spl
==========
  CachingIterator::FULL_CACHE
  CachingIterator::TOSTRING_USE_INNER

  SplFileObject::READ_AHEAD
  SplFileObject::READ_CSV
  SplFileObject::SKIP_EMPTY


New functions
=============

In the PHP core
===============
    array array_fill_keys(array keys, mixed val)
      - Create an array using the elements of the first parameter as keys, each initialized to val
    array error_get_last()
      - Get the last occurred error as associative array. Returns NULL if there hasn't been an error yet
    string image_type_to_extension(int imagetype [, bool include_dot])
      - Get file extension for image-type returned by getimagesize, exif_read_data, exif_thumbnail, exif_imagetype
    int memory_get_peak_usage([real_usage])
      - Returns the peak allocated by PHP memory
    array timezone_abbreviations_list()
     - Returns associative array containing DST, offset and the timezone name
    array timezone_identifiers_list()
     - Returns numerically indexed array with all timezone identifiers
    string timezone_name_from_abbr(string abbr[, long gmtOffset[, long isdst]])
     - Returns the timezone name from abbreviation

In ext/mbstring
===============
    array mb_list_encodings_alias_names([string encoding])
      - Returns an array of all supported entity encodings
    mixed mb_list_mime_names([string encoding])
      - Returns an array or string of all supported mime names
    int mb_stripos(string haystack, string needle [, int offset [, string encoding]])
      - Finds position of first occurrence of a string within another, case insensitive
    string mb_stristr(string haystack, string needle[, bool part[, string encoding]])
      - Finds first occurrence of a string within another, case insensitive
    string mb_strrchr(string haystack, string needle[, bool part[, string encoding]])
      - Finds the last occurrence of a character in a string within another
    string mb_strrichr(string haystack, string needle[, bool part[, string encoding]])
      - Finds the last occurrence of a character in a string within another, case insensitive
    int mb_strripos(string haystack, string needle [, int offset [, string encoding]])
      - Finds position of last occurrence of a string within another, case insensitive
    string mb_strstr(string haystack, string needle[, bool part[, string encoding]])
      - Finds first occurrence of a string within another

In ext/openssl
==============
    resource openssl_csr_get_public_key(mixed csr)
      - Extracts public key from a CERT and prepares it for use
    array openssl_csr_get_subject(mixed csr [, bool use_short_names])
      - Returns the subject of a CERT
    array openssl_pkey_get_details(resource key)
      - returns an array with the key details (bits, pkey, type)

In ext/spl
==========
    string spl_object_hash(object obj)
      - Return hash id for given object
    int iterator_apply(Traversable it, mixed function [, mixed params])
      - Calls a function for every element in an iterator

In ext/pcre
===========
    int preg_last_error(void)
      - Returns the error code of the last regex execution

In ext/pgsql
============
    mixed pg_field_table(resource result, int field_number[, bool oid_only])
      - Returns the name of the table field belongs to, or table's oid if oid_only is true

In ext/posix
============
    bool posix_initgroups(string name, int base_group_id)
      - Calculate the group access list for the user specified in name

In ext/gmp
==========
    resource gmp_nextprime(resource a)
      - Finds next prime of a

In ext/xmlwriter
================
    bool xmlwriter_full_end_element(resource xmlwriter)
     - End current element - returns FALSE on error
    bool xmlwriter_write_raw(resource xmlwriter, string content)
     - Write text - returns FALSE on error


New optional parameters
=======================

In the PHP core
===============
  - string base64_decode(string str[, bool strict=false]) (strict)
  - bool setcookie(string name [, string value [, int expires [, string path [, string domain [, bool secure[, bool httponly=false]]]]]] (httponly)
  - bool setrawcookie(string name [, string value [, int expires [, string path [, string domain [, bool secure[, bool httponly=false]]]]]] (httponly)
  - void session_set_cookie_params(int lifetime [, string path [, string domain [, bool secure[, bool httponly]]]]) (httponly)
  - int memory_get_usage([bool real_usage=false]) (real_usage)

In ext/curl
===========
  - array curl_multi_info_read(resource mh [, long msgs_in_queue]) (msgs_in_queue)

In ext/mbstring
===============
  - int mb_strrpos(string haystack, string needle [, int offset [, string encoding]]) (offset)

In ext/openssl
==============
  - int openssl_verify(string data, string signature, mixed key [, int signature_algo]) (signature_algo)

In ext/pgsql
============
  - string pg_escape_bytea([resource connection,] string data) (connection)
  - string pg_escape_string([resource connection,] string data) (connection)

In ext/simplexml
================
  - SimpleXMLElement::__construct(string data [, int options [, bool data_is_url [, string ns [, bool is_prefix]]]]) (ns, is_prefix)
  - SimpleXMLElement SimpleXMLElement::attributes([string ns [, bool is_prefix]]) (is_prefix)
  - SimpleXMLElement SimpleXMLElement::children([string ns [, bool is_prefix]]) (is_prefix)
  - SimpleXMLElement simplexml_load_file(string filename [, string class_name [, int options [, string ns [, bool is_prefix]]]]) (ns, is_prefix)
  - SimpleXMLElement simplexml_load_string(string data [, string class_name [, int options [, string ns [, bool is_prefix]]]]) (ns, is_prefix)

In ext/xmlreader
================
  - boolean XMLReader::open(string URI [, string encoding [, int options]]) (encoding, options)
  - boolean XMLReader::XML(string source [, string encoding [, int options]]) (encoding, options)


New INI settings
================
allow_url_include PHP_INI_SYSTEM, default: false
pcre.backtrack_limit PHP_INI_ALL, default: 100000
pcre.recursion_limit PHP_INI_ALL, default: 100000
session.cookie_httponly PHP_INI_ALL, default: false


New global constants
====================

In the PHP core
===============
    - M_EULER
    - M_LNPI
    - M_SQRT3
    - M_SQRTPI
    - PATHINFO_FILENAME
    - PREG_BACKTRACK_LIMIT_ERROR
    - PREG_BAD_UTF8_ERROR
    - PREG_INTERNAL_ERROR
    - PREG_NO_ERROR
    - PREG_RECURSION_LIMIT_ERROR
    - UPLOAD_ERR_EXTENSION

In ext/curl
===========
    - CURLE_FILESIZE_EXCEEDED
    - CURLE_FTP_SSL_FAILED
    - CURLE_LDAP_INVALID_URL
    - CURLFTPAUTH_DEFAULT
    - CURLFTPAUTH_SSL
    - CURLFTPAUTH_TLS
    - CURLFTPSSL_ALL
    - CURLFTPSSL_CONTROL
    - CURLFTPSSL_NONE
    - CURLFTPSSL_TRY
    - CURLOPT_FTP_SSL
    - CURLOPT_FTPSSLAUTH

In ext/openssl
==============
    - OPENSSL_VERSION_NUMBER
    - OPENSSL_VERSION_TEXT

In ext/snmp
===========
    - SNMP_OID_OUTPUT_FULL
    - SNMP_OID_OUTPUT_NUMERIC

In ext/sysvmsg
==============
    - MSG_EAGAIN
    - MSG_ENOMSG

The Win32 Build System.
$Id: README.WIN32-BUILD-SYSTEM,v 1.4 2003/12/23 02:51:18 wez Exp $
Wez Furlong <wez (a] thebrainroom.com>

If you need help with the build system, send mail to
internals (a] lists.php.net; please don't email me directly.

===========================================================
Contents:
1. How to build PHP under windows
 a. Requirements
 b. Opening a command prompt
 c. Generating configure.js
 d. Configuring
 e. Building
 f. Cleaning up
 g. Running the test suite
 h. snapshot building
 
2. How to write config.w32 files
 x. to be written.

===========================================================
1. How to build PHP under windows
a. Requirements

 You need:
  - Windows Scripting Host (cscript.exe)
  - Microsoft Build Tools from:
     Microsoft Visual Studio (VC6) or later
 
 You also need:
  - bindlib_w32 [http://www.php.net/extra/bindlib_w32.zip]
  - win32build  [http://www.php.net/extra/win32build.zip]

 b. Opening the Build Environment Command Prompt:
  - Using Visual Studio (VC6)
    1. Install it
    2. If you have a VC++ Command Prompt icon on your start menu,
       click on it to get a Command Prompt with the env vars
       set up correctly.

       If not, create a new shortcut and set the Target to:

       %comspec% /k "C:\Program Files\Microsoft Visual Studio\VC98\Bin\vcvars32.bat"

       You might also want to set the prompt to start in
       a convenient location (such as the root of your
       PHP source checkout).

  - Using Visual Studio .Net
    1. Install it.
    2. Under the Visual Studio .Net Tools sub menu of your start
       menu, you should have a Visual Studio .Net Command Prompt
       icon.  If not, create a new shortcut and set the Target to:

       %comspec% /k "C:\Program Files\Microsoft Visual Studio .NET 2003\Common7\Tools\vsvars32.bat"

       You might also want to set the prompt to start in
       a convenient location (such as the root of your
       PHP source checkout).

  - Using the Platform SDK tools
    1. Download the Platform SDK:
       http://www.microsoft.com/msdownload/platformsdk/sdkupdate/

       - You need the Core SDK, which is approx 200MB to download
         and requires approx 500MB of disk space.
       - The other components of the SDK are not required by PHP
       - You might be able to reduce the download size by downloading
         the installer control component first and then selecting
         only the Build Environment (around 30MB), but I haven't
         tried this.

         ** Note: it seems that MS don't include the 32 bit
            build tools in the platform SDK any longer, so
            you will probably have very limited luck if you
            don't also have VC++ or VS.Net already installed.

    2. Once installed, you will have an icon on your start menu
       that will launch the build environment; the latest SDK's
       install a number of different versions of this; you probably
       want to choose the Windows 2000 Retail build environment.
       Clicking on this will open a command prompt with its Path,
       Include and Lib env vars set to point to the build tools
       and win32 headers.

c. Generating configure

 Change directory to where you have your PHP 5 sources.
 Run buildconf.bat.

d. Configuring
 
 cscript /nologo configure.js --help
 
 Will give you a list of configuration options; these will
 have the form:
 
 --enable-foo or --disable-foo or --with-foo or --without-foo.
 
 --enable-foo will turn something on, and is equivalent to
 specifying --enable-foo=yes
 
 --disable-foo will turn something off, and is equivalent to
 specifying --enable-foo=no

 --enable-foo=shared will attempt to build that feature as
 a shared, dynamically loadable module.

 Sometimes a configure option needs additional information
 about where to find headers and libraries; quite often
 you can specify --enable-foo=option where option could be
 the path to where to find those files.  If you want to
 specify a parameter and build it as shared, you can use
 this syntax instead:  --enable-foo=shared,option

 The same rules all apply to --with-foo and --without-foo;
 the only difference is the way the options are named;
 the convention is that --enable-foo means that you are
 switching on something that comes with PHP, whereas
 --with-foo means that you want to build in something
 external to PHP.

e. Building

 Once you have successfully configured your build (make
 sure you read the output from the command to make sure
 it worked correctly), you can build the code; simply type

 "nmake" at the command prompt, and it will build everthing
 you asked for.

 Once the build has completed, you will find your binaries
 in the build dir determined by configure; this is typically
 Release_TS for release builds or Debug_TS for debug builds.
 If you build a non-thread-safe build, it will use Release
 or Debug to store the files.  Also in this build dir you
 will find sub directories for each module that went into
 your PHP build.  The files you'll want to keep are the
 .exe and .dll files directly in your build dir.

f. Cleaning Up
 
 You can automatically delete everything that was built
 by running "nmake clean".  This will delete everything
 that was put there when you ran nmake, including the
 .exe and .dll files.

g. Running the test suite

 You can verify that your build is working well by running
 the regression test suite.  You do this by typing
 "nmake test".  You can specify the tests you want to run
 by defing the TESTS variable - if you wanted to run the
 sqlite test suite only, you would type
 "nmake /D TESTS=ext/sqlite/tests test"

h. Snapshot Building

 If you want to set up an automated build that will tolerate
 breakages in some of the modules, you can use the
 --enable-snapshot-build configure option to generate a
 makefile optimized for that purpose.  A snapshot build will
 switch the argument parser so that the default option for
 configure switches that your don't specify will be set
 to "shared".  The effect of this is to turn on all options
 unless you explicitly disable them.  When you have configured
 your snapshot build, you can use "nmake build-snap" to build
 everything, ignoring build errors in individual extensions
 or SAPI.

vim:tw=78:sw=1:ts=1:et

Using PHP 5 with the Zeus Web Server
-----------------------------------

Zeus fully supports running PHP in combination with our
webserver. There are three different interfaces that can be used to
enable PHP:

* CGI
* ISAPI
* FastCGI

Of the three, we recommend using FastCGI, which has been tested and
benchmarked as providing the best performance and reliability.

Full details of how to install PHP are available from our
website, at:

http://support.zeus.com/products/php.html

If you have any problems, please check the support site for more
up-to-date information and advice.


Quick guide to installing CGI/FastCGI with Zeus
-----------------------------------------------

Step 1 - Compile PHP as FastCGI.

Compile as follows:
        ./configure --enable-fastcgi
        make

Note that PHP has many options to the configure script -
e.g. --with-mysql. You will probably want to select your usual options
before compiling; the above is just a bare minimum, for illustration.

After compilation finishes, you will be left with an executable
program called 'php'. Copy this into your document root, under a
dedicated FastCGI directory (e.g. $DOCROOT/fcgi-bin/php)


Step 2 - configure Zeus

Four stages:
        -  enable FastCGI
        -  configure FastCGI
        -  setup alias for FastCGI
        -  setup alias for PHP

1) Using the admin server, go to the 'module configuration' page for
your virtual server, and ensure that 'fastcgi' is enabled (select the
tickbox to the left).

2) While we can run FastCGI's locally, there are known problems with
some OS's (specifically, the communication between web server and
FastCGI happens over a unix domain socket, and some OS's have trouble
sustaining high connection rates over these sockets). So instead, we
are going to set up the PHP FastCGI to run 'remotely' over localhost
(this uses TCP sockets, which do not suffer this problem). Go to the
'fastcgi configuration' page, and under 'add remote fastcgi':
        Add Remote FastCGI
                Docroot path            /fcgi-bin/php
                Remote machine          localhost:8002
The first entry is where you saved PHP, above.
The second entry is localhost:<any unused port>
We will start the FastCGI listening on this port shortly.
Click 'update' to commit these changes.

3) Go to the path mapping module and add an alias for FastCGI:
        Add Alias
                Docroot path            /fcgi-bin
                Filesystem directory    /path/to/docroot/fcgi-bin
                Alias type              fastcgi
Click 'update' to commit these changes

4) Also on the path mapping module, add a handler for PHP:
        Add handler
                File extension          php
                Handler                 /fcgi-bin/php
Click 'update' to commit these changes

Finally restart your virtual server for these changes to take effect.


Step 3 - start PHP as a FastCGI runner

When you start PHP, it will pre-fork a given number of child processes
to handle incoming PHP requests. Each process will handle a given
number of requests before exiting (and being replaced by a newly
forked process). You can control these two parameters by setting the
following environment variables BEFORE starting the FastCGI runner:

PHP_FCGI_CHILDREN - the number of child processes to pre-fork. This
variable MUST be set, if not then the PHP will not run as a FastCGI.
We recommend a value of 8 for a fairly busy site. If you have many,
long-running PHP scripts, then you may need to increase this further.

PHP_FCGI_MAX_REQUESTS - the number of requests each PHP child process
handles before exiting. If not set, defaults to 500.

To start the FastCGI runner, execute '$ZEUSHOME/web/bin/fcgirunner
8002 $DOCROOT/fcgi-bin/php'.  Substitute the appropriate values for
$ZEUSHOME and $DOCROOT; also substitute for 8002 the port you chose,
above.

To stop the runner (e.g. to experiment with the above environment
variables) you will need to manually stop and running PHP
processes. (Use 'ps' and 'kill'). As it is PHP which is forking lots
of children and not the runner, Zeus unfortunately cannot keep track
of what processes are running, sorry. A typical command line may look
like 'ps -efl | grep $DOCROOT/fcgi-bin/php | grep -v grep | awk
'{print $4}' | xargs kill'

Indexes created Sat Nov 28 12:39:51 UTC 2009

Terms of Use | Privacy | Trademarks | Copyright Policy | Site Guidelines | Help
Your use of this web site or any of its content or software indicates your agreement to be bound by these Terms of Use.
Copyright © 1995-2008 Sun Microsystems, Inc.