NameDateSize

..30-May-2014

.gdbinit18-Dec-201210.9 KiB

.gitattributes18-Dec-20128.6 KiB

.gitignore18-Dec-20124.5 KiB

.travis.yml28-Mar-2013118

acconfig.h.in18-Dec-201228

acinclude.m418-Dec-201274.3 KiB

build/18-Dec-2012

buildconf18-Dec-2012668

buildconf.bat18-Dec-2012334

CODING_STANDARDS18-Dec-201210.9 KiB

config.guess18-Dec-201243.8 KiB

config.sub18-Dec-201232.6 KiB

configure.in10-Dec-201344.4 KiB

CREDITS18-Dec-201291

ext/18-Dec-2012

EXTENSIONS18-Dec-201224.2 KiB

footer18-Dec-2012137

genfiles18-Dec-2012486

header01-Jan-20131.1 KiB

INSTALL18-Dec-201293.5 KiB

LICENSE18-Dec-20123.1 KiB

ltmain.sh18-Dec-2012195 KiB

main/10-Dec-2013

makedist18-Dec-20122.9 KiB

Makefile.frag18-Dec-20121 KiB

Makefile.gcov18-Dec-20122.2 KiB

Makefile.global18-Dec-20125.4 KiB

makerpm18-Dec-20125.2 KiB

netware/01-Jan-2013

NEWS12-May-2014353.3 KiB

pear/18-Dec-2012

php.gif18-Dec-20122.5 KiB

php.ini-development18-Dec-201268 KiB

php.ini-production18-Dec-201268 KiB

php5.spec.in18-Dec-20121.5 KiB

README.EXT_SKEL18-Dec-20126.1 KiB

README.EXTENSIONS18-Dec-20121.5 KiB

README.GIT-RULES20-Jun-20134.6 KiB

README.input_filter18-Dec-20125.8 KiB

README.MAILINGLIST_RULES18-Dec-20123.3 KiB

README.namespaces18-Dec-20125.9 KiB

README.PARAMETER_PARSING_API18-Dec-20126.7 KiB

README.PHP4-TO-PHP5-THIN-CHANGES18-Dec-20124.6 KiB

README.REDIST.BINS18-Dec-201220.4 KiB

README.RELEASE_PROCESS24-Jan-201411.1 KiB

README.SELF-CONTAINED-EXTENSIONS18-Dec-20124.6 KiB

README.STREAMS18-Dec-201215 KiB

README.SUBMITTING_PATCH18-Dec-20127.4 KiB

README.TESTING18-Dec-20126.5 KiB

README.TESTING218-Dec-20124.8 KiB

README.UNIX-BUILD-SYSTEM18-Dec-20124.2 KiB

README.WIN32-BUILD-SYSTEM18-Dec-2012109

run-tests.php18-Dec-201276.6 KiB

sapi/02-Jun-2012

scripts/18-Dec-2012

server-tests-config.php18-Dec-20122.1 KiB

server-tests.php18-Dec-201250.5 KiB

snapshot18-Dec-2012108

stamp-h.in18-Dec-201210

stub.c18-Dec-20121

svnclean.bat18-Dec-201250

tests/18-Dec-2012

TODO18-Dec-20125 KiB

TODO-5.118-Dec-2012163

TODO-PHP518-Dec-20123.7 KiB

TSRM/01-Jan-2013

UPGRADING18-Dec-201223 KiB

UPGRADING.INTERNALS18-Dec-2012737

vcsclean18-Dec-2012297

win32/22-Apr-2013

Zend/03-Jul-2013

README.EXT_SKEL

1(NOTE: you may also want to take a look at the pear package
2         PECL_Gen, a PHP-only alternative for this script that
3             supports way more extension writing tasks and is 
4             supposed to replace ext_skel completely in the long run ...)
5
6WHAT IT IS
7
8  It's a tool for automatically creating the basic framework for a PHP module
9  and writing C code handling arguments passed to your functions from a simple
10  configuration file. See an example at the end of this file.
11
12HOW TO USE IT
13
14  Very simple. First, change to the ext/ directory of the PHP 4 sources. If
15  you just need the basic framework and will be writing all the code in your
16  functions yourself, you can now do
17
18   ./ext_skel --extname=module_name
19
20  and everything you need is placed in directory module_name. 
21
22  [ Note that GNU awk is likely required for this script to work.  Debian 
23    systems seem to default to using mawk, so you may need to change the 
24    #! line in skeleton/create_stubs and the cat $proto | awk line in
25    ext_skel to use gawk explicitly. ]
26
27  If you don't need to test the existence of any external header files, 
28  libraries or functions in them, the module is already almost ready to be 
29  compiled in PHP.  Just remove 3 comments in your_module_name/config.m4, 
30  change back up to PHP sources top directory, and do
31
32    ./buildconf; ./configure --enable-module_name; make
33
34  But if you already have planned the overall scheme of your module, what
35  functions it will contain, their return types and the arguments they take
36  (a very good idea) and don't want to bother yourself with creating function
37  definitions and handling arguments passed yourself, it's time to create a
38  function definitions file, which you will give as an argument to ext_skel
39  with option
40
41    --proto=filename.
42
43FORMAT OF FUNCTION DEFINITIONS FILE
44
45  All the definitions must be on one line. In it's simplest form, it's just
46  the function name, e.g.
47
48    my_function
49
50  but then you'll be left with an almost empty function body without any
51  argument handling.
52
53  Arguments are given in parenthesis after the function name, and are of
54  the form 'argument_type argument_name'. Arguments are separated from each
55  other with a comma and optional space. Argument_type can be one of int,
56  bool, double, float, string, array, object or mixed.
57
58  An optional argument is separated from the previous by an optional space,
59  then '[' and of course comma and optional space, like all the other
60  arguments. You should close a row of optional arguments with same amount of
61  ']'s as there where '['s. Currently, it does not harm if you forget to do it
62  or there is a wrong amount of ']'s, but this may change in the future.
63
64    An additional short description may be added after the parameters. 
65  If present it will be filled into the 'proto' header comments in the stubs
66  code and the <refpurpose> tag in the XML documentation.
67
68  An example:
69
70    my_function(int arg1, int arg2 [, int arg3 [, int arg4]]) this is my 1st
71
72  Arguments arg3 and arg4 are optional.
73
74  If possible, the function definition should also contain it's return type
75  in front of the definition. It's not actually used for any C code generating
76  purposes but PHP in-source documentation instead, and as such, very useful.
77  It can be any of int, double, string, bool, array, object, resource, mixed
78  or void.
79
80  The file must contain nothing else but function definitions, no comments or
81  empty lines.
82
83OTHER OPTIONS
84
85    --no-help
86
87  By default, ext_skel creates both comments in the source code and a test
88  function to help first time module writers to get started and testing
89  configuring and compiling their module. This option turns off all such things
90  which may just annoy experienced PHP module coders. Especially useful with
91
92    --stubs=file
93
94  which will leave out also all module specific stuff and write just function
95  stubs with function value declarations and passed argument handling, and
96  function entries and definitions at the end of the file, for copying and
97  pasting into an already existing module.
98
99    --xml[=file]
100
101  Creates the basics for phpdoc .xml file.
102
103    --full-xml
104
105  Not implemented yet. When or if there will ever be created a framework for
106  self-contained extensions to use phpdoc system for their documentation, this
107  option enables it on the created xml file.
108
109CURRENT LIMITATIONS, BUGS AND OTHER ODDITIES
110
111  Only arguments of types int, bool, double, float, string and array are
112  handled. For other types you must write the code yourself. And for type
113  mixed, it wouldn't even be possible to write anything, because only you
114  know what to expect.
115  
116  It can't handle correctly, and probably never will, variable list of
117  of arguments. (void foo(int bar [, ...])
118
119  Don't trust the generated code too much. It tries to be useful in most of
120  the situations you might encounter, but automatic code generation will never
121  beat a programmer who knows the real situation at hand. ext_skel is generally
122  best suited for quickly generating a wrapper for c-library functions you
123  might want to have available in PHP too.
124
125  This program doesn't have a --help option. It has --no-help instead.
126
127EXAMPLE
128
129  The following _one_ line
130
131  bool my_drawtext(resource image, string text, resource font, int x, int y [, int color])
132
133  will create this function definition for you (note that there are a few
134  question marks to be replaced by you, and you must of course add your own
135  value definitions too):
136
137/* {{{ proto bool my_drawtext(resource image, string text, resource font, int x, int y [, int color])
138    */
139PHP_FUNCTION(my_drawtext)
140{
141    char *text = NULL;
142    int argc = ZEND_NUM_ARGS();
143    int image_id = -1;
144    int text_len;
145    int font_id = -1;
146    long x;
147    long y;
148    long color;
149    zval *image = NULL;
150    zval *font = NULL;
151
152    if (zend_parse_parameters(argc TSRMLS_CC, "rsrll|l", &image, &text, &text_len, &font, &x, &y, &color) == FAILURE)
153        return;
154
155    if (image) {
156        ZEND_FETCH_RESOURCE(???, ???, image, image_id, "???", ???_rsrc_id);
157    }
158    if (font) {
159        ZEND_FETCH_RESOURCE(???, ???, font, font_id, "???", ???_rsrc_id);
160    }
161
162    php_error(E_WARNING, "my_drawtext: not yet implemented");
163}
164/* }}} */
165
166

README.EXTENSIONS

1Between PHP 4.0.6 and 4.1.0, the Zend module struct changed in a way
2that broke both source and binary compatibility.  If you are
3maintaining a third party extension, here's how to update it:
4
5If this was your old module entry:
6
7zend_module_entry foo_module_entry = {
8    "foo",                /* extension name */
9    foo_functions,        /* extension function list */
10    NULL,                 /* extension-wide startup function */
11    NULL,                 /* extension-wide shutdown function */
12    PHP_RINIT(foo),       /* per-request startup function */
13    PHP_RSHUTDOWN(foo),   /* per-request shutdown function */
14    PHP_MINFO(foo),       /* information function */
15    STANDARD_MODULE_PROPERTIES
16};
17
18Here's how it should look if you want your code to build with PHP
194.1.0 and up:
20
21zend_module_entry foo_module_entry = {
22#if ZEND_MODULE_API_NO >= 20010901
23    STANDARD_MODULE_HEADER,
24#endif
25    "foo",                /* extension name */
26    foo_functions,        /* extension function list */
27    NULL,                 /* extension-wide startup function */
28    NULL,                 /* extension-wide shutdown function */
29    PHP_RINIT(foo),       /* per-request startup function */
30    PHP_RSHUTDOWN(foo),   /* per-request shutdown function */
31    PHP_MINFO(foo),       /* information function */
32#if ZEND_MODULE_API_NO >= 20010901
33    FOO_VERSION,          /* extension version number (string) */
34#endif
35    STANDARD_MODULE_PROPERTIES
36};
37
38If you don't care about source compatibility with earlier PHP releases
39than 4.1.0, you can drop the #if/#endif lines.
40

README.GIT-RULES

1====================
2  Git Commit Rules
3====================
4
5This is the first file you should be reading when contributing code via Git.
6We'll assume you're basically familiar with Git, but feel free to post
7your questions on the mailing list. Please have a look at
8http://git-scm.com/ for more detailed information on Git.
9
10PHP is developed through the efforts of a large number of people.
11Collaboration is a Good Thing(tm), and Git lets us do this. Thus, following
12some basic rules with regards to Git usage will::
13
14   a. Make everybody happier, especially those responsible for maintaining
15      Git itself.
16
17   b. Keep the changes consistently well documented and easily trackable.
18
19   c. Prevent some of those 'Oops' moments.
20
21   d. Increase the general level of good will on planet Earth.
22
23Having said that, here are the organizational rules::
24
25   1. Respect other people working on the project.
26
27   2. Discuss any significant changes on the list before committing and get
28      confirmation from the release manager for the given branch.
29
30   3. Look at EXTENSIONS file to see who is the primary maintainer of
31      the code you want to contribute to.
32
33   4. If you "strongly disagree" about something another person did, don't
34      start fighting publicly - take it up in private email.
35
36   5. If you don't know how to do something, ask first!
37
38   6. Test your changes before committing them. We mean it. Really.
39      To do so use "make test".
40
41   7. For development use the --enable-maintainer-zts switch to ensure your
42      code handles TSRM correctly and doesn't break for those who need that.
43
44Currently we have the following branches in use::
45
46  master    The active development branch. 
47
48  PHP-5.5   Is used to release the PHP 5.5.x series. This is a current
49            stable version and is open for bugfixes only.
50
51  PHP-5.4   Is used to release the PHP 5.4.x series. This is a current
52            stable version and is open for bugfixes only.
53
54  PHP-5.3   Is used to release the PHP 5.3.x series. This is currently 
55            in extended support and open forsecurity fixes only. Triaged
56            via security@php.net
57
58  PHP-5.2   This branch is closed.
59
60  PHP-5.1   This branch is closed.
61
62  PHP-4.4   This branch is closed.
63
64The next few rules are more of a technical nature::
65
66   1. All changes should first go to the lowest branch (i.e. 5.3) and then 
67      get merged up to all other branches. If a change is not needed for
68      later branches (i.e. fixes for features which where dropped from later
69      branches) an empty merge should be done.
70
71   2. All news updates intended for public viewing, such as new features,
72      bug fixes, improvements, etc., should go into the NEWS file of the
73      *first* to be released version with the given change. In other words
74      any NEWS file change only needs to done in one branch.
75
76   3. Do not commit multiple file and dump all messages in one commit. If you
77      modified several unrelated files, commit each group separately and
78      provide a nice commit message for each one. See example below.
79
80   4. Do write your commit message in such a way that it makes sense even
81      without the corresponding diff. One should be able to look at it, and
82      immediately know what was modified. Definitely include the function name
83      in the message as shown below.
84
85   5. In your commit messages, keep each line shorter than 80 characters. And
86      try to align your lines vertically, if they wrap. It looks bad otherwise.
87
88   6. If you modified a function that is callable from PHP, prepend PHP to
89      the function name as shown below.
90
91
92The format of the commit messages is pretty simple.
93
94<max 79 characters short description>\n
95\n
96<long description, 79 chars per line>
97\n
98
99An Example from the git project (commit 2b34e486bc):
100
101pack-objects: Fix compilation with NO_PTHREDS
102  
103It looks like commit 99fb6e04 (pack-objects: convert to use
104parse_options(), 2012-02-01) moved the #ifdef NO_PTHREDS around but
105hasn't noticed that the 'arg' variable no longer is available.
106
107If you fix some bugs, you should note the bug ID numbers in your
108commit message. Bug ID should be prefixed by "#" for easier access to
109bug report when developers are browsing CVS via LXR or Bonsai.
110
111Example::
112
113  Fixed bug #14016 (pgsql notice handler double free crash bug.)
114
115When you change the NEWS file for a bug fix, then please keep the bugs
116sorted in decreasing order under the fixed version.
117
118You can use OpenGrok (http://lxr.php.net/) and gitweb (http://git.php.net/)
119to look at PHP Git repository in various ways.
120
121
122For further information on the process and further details please refer to
123https://wiki.php.net/vcs/gitworkflow and https://wiki.php.net/vcs/gitfaq
124
125Happy hacking,
126
127PHP Team
128

README.input_filter

1Input Filter Support in PHP 5
2-----------------------------
3
4XSS (Cross Site Scripting) hacks are becoming more and more prevalent,
5and can be quite difficult to prevent.  Whenever you accept user data
6and somehow display this data back to users, you are likely vulnerable
7to XSS hacks.
8
9The Input Filter support in PHP 5 is aimed at providing the framework
10through which a company-wide or site-wide security policy can be
11enforced.  It is implemented as a SAPI hook and is called from the
12treat_data and post handler functions.  To implement your own security
13policy you will need to write a standard PHP extension.  There is also
14a powerful standard implementation in ext/filter that should suit most
15peoples' needs.  However, if you want to implement your own security 
16policy, read on.
17
18A simple implementation might look like the following.  This stores the
19original raw user data and adds a my_get_raw() function while the normal
20$_POST, $_GET and $_COOKIE arrays are only populated with stripped
21data.  In this simple example all I am doing is calling strip_tags() on
22the data.  If register_globals is turned on, the default globals that
23are created will be stripped ($foo) while a $RAW_foo is created with the
24original user input.
25
26ZEND_BEGIN_MODULE_GLOBALS(my_input_filter)
27        zval *post_array;
28        zval *get_array;
29        zval *cookie_array;
30ZEND_END_MODULE_GLOBALS(my_input_filter)
31
32#ifdef ZTS
33#define IF_G(v) TSRMG(my_input_filter_globals_id, zend_my_input_filter_globals *, v)
34#else
35#define IF_G(v) (my_input_filter_globals.v)
36#endif
37
38ZEND_DECLARE_MODULE_GLOBALS(my_input_filter)
39
40zend_function_entry my_input_filter_functions[] = {
41    PHP_FE(my_get_raw,   NULL)
42    {NULL, NULL, NULL}
43};
44
45zend_module_entry my_input_filter_module_entry = {
46    STANDARD_MODULE_HEADER,
47    "my_input_filter",
48    my_input_filter_functions,
49    PHP_MINIT(my_input_filter),
50    PHP_MSHUTDOWN(my_input_filter),
51    NULL,
52    PHP_RSHUTDOWN(my_input_filter),
53    PHP_MINFO(my_input_filter),
54    "0.1",
55    STANDARD_MODULE_PROPERTIES
56};
57
58PHP_MINIT_FUNCTION(my_input_filter)
59{
60    ZEND_INIT_MODULE_GLOBALS(my_input_filter, php_my_input_filter_init_globals, NULL);
61
62    REGISTER_LONG_CONSTANT("POST", PARSE_POST, CONST_CS | CONST_PERSISTENT);
63    REGISTER_LONG_CONSTANT("GET", PARSE_GET, CONST_CS | CONST_PERSISTENT);
64    REGISTER_LONG_CONSTANT("COOKIE", PARSE_COOKIE, CONST_CS | CONST_PERSISTENT);
65
66    sapi_register_input_filter(my_sapi_input_filter);
67    return SUCCESS;
68}
69
70PHP_RSHUTDOWN_FUNCTION(my_input_filter)
71{
72    if(IF_G(get_array)) {
73        zval_ptr_dtor(&IF_G(get_array));
74        IF_G(get_array) = NULL;
75    }
76    if(IF_G(post_array)) {
77        zval_ptr_dtor(&IF_G(post_array));
78        IF_G(post_array) = NULL;
79    }
80    if(IF_G(cookie_array)) {
81        zval_ptr_dtor(&IF_G(cookie_array));
82        IF_G(cookie_array) = NULL;
83    }
84    return SUCCESS;
85}
86
87PHP_MINFO_FUNCTION(my_input_filter)
88{
89    php_info_print_table_start();
90    php_info_print_table_row( 2, "My Input Filter Support", "enabled" );
91    php_info_print_table_row( 2, "Revision", "$Id: 488ca82a7b15672b2186e25e65f9efa13ff650a0 $");
92    php_info_print_table_end();
93}
94
95/* The filter handler. If you return 1 from it, then PHP also registers the
96 * (modified) variable. Returning 0 prevents PHP from registering the variable;
97 * you can use this if your filter already registers the variable under a
98 * different name, or if you just don't want the variable registered at all. */
99SAPI_INPUT_FILTER_FUNC(my_sapi_input_filter)
100{
101    zval new_var;
102    zval *array_ptr = NULL;
103    char *raw_var;
104    int var_len;
105
106    assert(*val != NULL);
107
108    switch(arg) {
109        case PARSE_GET:
110            if(!IF_G(get_array)) {
111                ALLOC_ZVAL(array_ptr);
112                array_init(array_ptr);
113                INIT_PZVAL(array_ptr);
114            }
115            IF_G(get_array) = array_ptr;
116            break;
117        case PARSE_POST:
118            if(!IF_G(post_array)) {
119                ALLOC_ZVAL(array_ptr);
120                array_init(array_ptr);
121                INIT_PZVAL(array_ptr);
122            }
123            IF_G(post_array) = array_ptr;
124            break;
125        case PARSE_COOKIE:
126            if(!IF_G(cookie_array)) {
127                ALLOC_ZVAL(array_ptr);
128                array_init(array_ptr);
129                INIT_PZVAL(array_ptr);
130            }
131            IF_G(cookie_array) = array_ptr;
132            break;
133    }
134    Z_STRLEN(new_var) = val_len;
135    Z_STRVAL(new_var) = estrndup(*val, val_len);
136    Z_TYPE(new_var) = IS_STRING;
137
138    var_len = strlen(var);
139    raw_var = emalloc(var_len+5);  /* RAW_ and a \0 */
140    strcpy(raw_var, "RAW_");
141    strlcat(raw_var,var,var_len+5);
142
143    php_register_variable_ex(raw_var, &new_var, array_ptr TSRMLS_DC);
144
145    php_strip_tags(*val, val_len, NULL, NULL, 0);
146
147    *new_val_len = strlen(*val);
148    return 1;
149}
150
151PHP_FUNCTION(my_get_raw)
152{
153    long arg;
154    char *var;
155    int var_len;
156    zval **tmp;
157    zval *array_ptr = NULL;
158    HashTable *hash_ptr;
159    char *raw_var;
160
161    if(zend_parse_parameters(2 TSRMLS_CC, "ls", &arg, &var, &var_len) == FAILURE) {
162        return;
163    }
164
165    switch(arg) {
166        case PARSE_GET:
167            array_ptr = IF_G(get_array);
168            break;
169        case PARSE_POST:
170            array_ptr = IF_G(post_array);
171            break;
172        case PARSE_COOKIE:
173            array_ptr = IF_G(post_array);
174            break;
175    }
176
177    if(!array_ptr) RETURN_FALSE;
178
179    /*
180     * I'm changing the variable name here because when running with register_globals on,
181     * the variable will end up in the global symbol table
182     */
183    raw_var = emalloc(var_len+5);  /* RAW_ and a \0 */
184    strcpy(raw_var, "RAW_");
185    strlcat(raw_var,var,var_len+5);
186    hash_ptr = HASH_OF(array_ptr);
187
188    if(zend_hash_find(hash_ptr, raw_var, var_len+5, (void **)&tmp) == SUCCESS) {
189        *return_value = **tmp;
190        zval_copy_ctor(return_value);
191    } else {
192        RETVAL_FALSE;
193    }
194    efree(raw_var);
195}
196
197

README.MAILINGLIST_RULES

1====================
2  Mailinglist Rules
3====================
4
5This is the first file you should be reading before doing any posts on PHP
6mailinglists. Following these rules is considered imperative to the success of
7the PHP project. Therefore expect your contributions to be of much less positive
8impact if you do not follow these rules. More importantly you can actually
9assume that not following these rules will hurt the PHP project.
10
11PHP is developed through the efforts of a large number of people.
12Collaboration is a Good Thing(tm), and mailinglists lets us do this. Thus,
13following some basic rules with regards to mailinglist usage will:
14
15   a. Make everybody happier, especially those responsible for developing PHP
16      itself.
17
18   b. Help in making sure we all use our time more efficiently.
19
20   c. Prevent you from making a fool of yourself in public.
21
22   d. Increase the general level of good will on planet Earth.
23
24
25Having said that, here are the organizational rules:
26
27   1. Respect other people working on the project.
28
29   2. Do not post when you are angry. Any post can wait a few hours. Review
30      your post after a good breather or a good nights sleep.
31
32   3. Make sure you pick the right mailinglist for your posting. Please review
33      the descriptions on the mailinglist overview page
34      (http://www.php.net/mailing-lists.php). When in doubt ask a friend or
35      someone you trust on IRC.
36
37   4. Make sure you know what you are talking about. PHP is a very large project
38      that strives to be very open. The flip side is that the core developers
39      are faced with a lot of requests. Make sure that you have done your
40      research before posting to the entire developer community.
41
42   5. Patches have a much greater chance of acceptance than just asking the
43      PHP developers to implement a feature for you. For one it makes the
44      discussion more concrete and it shows that the poster put thought and time
45      into the request.
46
47   6. If you are posting to an existing thread, make sure that you know what
48      previous posters have said. This is even more important the longer the
49      thread is already.
50
51   7. Please configure your email client to use a real name and keep message
52      signatures to a maximum of 2 lines if at all necessary.
53
54The next few rules are more some general hints:
55
56   1. If you notice that your posting ratio is much higher than that of other
57      people, double check the above rules. Try to wait a bit longer before
58      sending your replies to give other people more time to digest your answers
59      and more importantly give you the opportunity to make sure that you
60      aggregate your current position into a single mail instead of multiple
61      ones.
62
63   2. Consider taking a step back from a very active thread now and then. Maybe
64      talking to some friends and fellow developers will help in understanding
65      the other opinions better.
66
67   3. Do not top post. Place your answer underneath anyone you wish to quote
68      and remove any previous comment that is not relevant to your post.
69
70   4. Do not high-jack threads, by bringing up entirely new topics. Please
71      create an entirely new thread copying anything you wish to quote into the
72      new thread.
73
74Finally, additional hints on how to behave inside the virtual community can be
75found in RFC 1855 (http://www.faqs.org/rfcs/rfc1855.html).
76
77Happy hacking,
78
79PHP Team
80

README.namespaces

1Design
2======
3
4Main assumption of the model is that the problem that we are to solve is the
5problem of the very long class names in PHP libraries. We would not attempt
6to take autoloader's job or create packaging model - only make names
7manageable.
8
9Namespaces are defined the following way:
10
11Zend/DB/Connection.php:
12<?php
13namespace Zend\DB;
14
15class Connection {
16}
17
18function connect() {
19}
20?>
21
22Namespace definition does the following:
23All class and function names inside are automatically prefixed with
24namespace name. Inside namespace, local name always takes precedence over
25global name. Several files may be using the same namespace.
26The namespace declaration statement must be the very first statement in
27the file. The only exception is "declare" statement that can be used before.
28
29Every class and function in a namespace can be referred to by the full name
30- e.g. Zend\DB\Connection or Zend\DB\connect - at any time.
31
32<?php
33require 'Zend/Db/Connection.php';
34$x = new Zend\DB\Connection;
35Zend\DB\connect();
36?>
37
38Namespace or class name can be imported:
39
40<?php
41require 'Zend/Db/Connection.php';
42use Zend\DB;
43use Zend\DB\Connection as DbConnection;
44
45$x = new Zend\DB\Connection();
46$y = new DB\connection();
47$z = new DbConnection();
48DB\connect();
49?>
50
51The use statement only defines name aliasing. It may create name alias for
52namespace or class. The simple form of statement "use A\B\C\D;" is
53equivalent to "use A\B\C\D as D;". The use statement can be used at any
54time in the global scope (not inside function/class) and takes effect from 
55the point of definition down to the end of file. It is recommended however to
56place the use statements at the beginning of the file. The use statements have
57effect only on the file where they appear.
58
59The special "empty" namespace (\ prefix) is useful as explicit global
60namespace qualification. All class and function names started from \
61interpreted as global.
62
63<?php 
64namespace A\B\C;
65
66$con = \mysql_connect(...);
67?>
68
69A special constant __NAMESPACE__ contains the name of the current namespace. 
70It can be used to construct fully-qualified names to pass them as callbacks.
71
72<?php
73namespace A\B\C;
74
75function foo() {
76}
77
78set_error_handler(__NAMESPACE__ . "\foo");
79?>
80
81In global namespace __NAMESPACE__ constant has the value of empty string.
82
83Names inside namespace are resolved according to the following rules:
84
851) all qualified names are translated during compilation according to
86current import rules. So if we have "use A\B\C" and then "C\D\e()"
87it is translated to "A\B\C\D\e()".
882) unqualified class names translated during compilation according to
89current import rules. So if we have "use A\B\C" and then "new C()" it
90is translated to "new A\B\C()".
913) inside namespace, calls to unqualified functions that are defined in 
92current namespace (and are known at the time the call is parsed) are 
93interpreted as calls to these namespace functions.
944) inside namespace, calls to unqualified functions that are not defined 
95in current namespace are resolved at run-time. The call to function foo() 
96inside namespace (A\B) first tries to find and call function from current 
97namespace A\B\foo() and if it doesn't exist PHP tries to call internal
98function foo(). Note that using foo() inside namespace you can call only 
99internal PHP functions, however using \foo() you are able to call any
100function from the global namespace.
1015) unqualified class names are resolved at run-time. E.q. "new Exception()"
102first tries to use (and autoload) class from current namespace and in case 
103of failure uses internal PHP class. Note that using "new A" in namespace 
104you can only create class from this namespace or internal PHP class, however
105using "new \A" you are able to create any class from the global namespace.
1066) Calls to qualified functions are resolved at run-time. Call to
107A\B\foo() first tries to call function foo() from namespace A\B, then
108it tries to find class A\B (__autoload() it if necessary) and call its
109static method foo()
1107) qualified class names are interpreted as class from corresponding
111namespace. So "new A\B\C()" refers to class C from namespace A\B.
112
113Examples
114--------
115<?php
116namespace A;
117foo();   // first tries to call "foo" defined in namespace "A"
118         // then calls internal function "foo"
119\foo(); // calls function "foo" defined in global scope
120?>
121
122<?php
123namespace A;
124new B();   // first tries to create object of class "B" defined in namespace "A"
125           // then creates object of internal class "B"
126new \B(); // creates object of class "B" defined in global scope
127?>
128
129<?php
130namespace A;
131new A(); // first tries to create object of class "A" from namespace "A" (A\A)
132         // then creates object of internal class "A"
133?>
134
135<?php
136namespace A;
137B\foo();   // first tries to call function "foo" from namespace "A\B"
138            // then calls method "foo" of internal class "B"
139\B\foo(); // first tries to call function "foo" from namespace "B"
140            // then calls method "foo" of class "B" from global scope
141?>
142
143The worst case if class name conflicts with namespace name
144<?php
145namespace A;
146A\foo();   // first tries to call function "foo" from namespace "A\A"
147            // then tries to call method "foo" of class "A" from namespace "A"
148            // then tries to call function "foo" from namespace "A"
149            // then calls method "foo" of internal class "A"
150\A\foo(); // first tries to call function "foo" from namespace "A"
151            // then calls method "foo" of class "A" from global scope
152?>
153
154TODO
155====
156
157* Support for namespace constants?
158
159* performance problems
160  - calls to internal functions in namespaces are slower, because PHP first
161    looks for such function in current namespace
162  - calls to static methods are slower, because PHP first tries to look
163    for corresponding function in namespace
164
165* Extend the Reflection API?
166  * Add ReflectionNamespace class
167    + getName()
168    + getClasses()
169    + getFunctions()
170    + getFiles()
171  * Add getNamespace() methods to ReflectionClass and ReflectionFunction
172
173* Rename namespaces to packages?
174
175

README.PARAMETER_PARSING_API

1New parameter parsing functions
2===============================
3
4It should be easier to parse input parameters to an extension function.
5Hence, borrowing from Python's example, there are now a set of functions
6that given the string of type specifiers, can parse the input parameters
7and store the results in the user specified variables. This avoids most
8of the IS_* checks and convert_to_* conversions. The functions also
9check for the appropriate number of parameters, and try to output
10meaningful error messages.
11
12
13Prototypes
14----------
15/* Implemented. */
16int zend_parse_parameters(int num_args TSRMLS_DC, char *type_spec, ...);
17int zend_parse_parameters_ex(int flags, int num_args TSRMLS_DC, char *type_spec, ...);
18
19The zend_parse_parameters() function takes the number of parameters
20passed to the extension function, the type specifier string, and the
21list of pointers to variables to store the results in. The _ex() version
22also takes 'flags' argument -- current only ZEND_PARSE_PARAMS_QUIET can
23be used as 'flags' to specify that the function should operate quietly
24and not output any error messages.
25
26Both functions return SUCCESS or FAILURE depending on the result.
27
28The auto-conversions are performed as necessary. Arrays, objects, and
29resources cannot be auto-converted.
30
31
32Type specifiers
33---------------
34 The following list shows the type specifier, its meaning and the parameter 
35 types that need to be passed by address. All passed paramaters are set
36 if the PHP parameter is non optional and untouched if optional and the 
37 parameter is not present. The only exception is O where the zend_class_entry*
38 has to be provided on input and is used to verify the PHP parameter is an 
39 instance of that class.
40
41 a  - array (zval*)
42 A  - array or object (zval *)
43 b  - boolean (zend_bool)
44 C  - class (zend_class_entry*)
45 d  - double (double)
46 f  - function or array containing php method call info (returned as 
47      zend_fcall_info and zend_fcall_info_cache)
48 h  - array (returned as HashTable*)
49 H  - array or HASH_OF(object) (returned as HashTable*)
50 l  - long (long)
51 L  - long, limits out-of-range numbers to LONG_MAX/LONG_MIN (long)
52 o  - object of any type (zval*)
53 O  - object of specific type given by class entry (zval*, zend_class_entry)
54 r  - resource (zval*)
55 s  - string (with possible null bytes) and its length (char*, int)
56 z  - the actual zval (zval*)
57 Z  - the actual zval (zval**)
58 *  - variable arguments list (0 or more)
59 +  - variable arguments list (1 or more)
60
61 The following characters also have a meaning in the specifier string:
62    | - indicates that the remaining parameters are optional, they
63        should be initialized to default values by the extension since they
64        will not be touched by the parsing function if they are not
65        passed to it.
66    / - use SEPARATE_ZVAL_IF_NOT_REF() on the parameter it follows
67    ! - the parameter it follows can be of specified type or NULL (applies
68        to all specifiers except for 'b', 'l', and 'd'). If NULL is passed, the
69        results pointer is set to NULL as well.
70
71
72Note on 64bit compatibility
73---------------------------
74Please do not forget that int and long are two different things on 64bit 
75OSes (int is 4 bytes and long is 8 bytes), so make sure you pass longs to "l" 
76and ints to strings length (i.e. for "s" you need to pass char * and int), 
77not the other way round!
78Remember: "l" is the only case when you need to pass long (and that's why 
79it's "l", not "i" btw).
80
81Both mistakes cause memory corruptions and segfaults on 64bit OSes:
821)
83  char *str;
84  long str_len; /* XXX THIS IS WRONG!! Use int instead. */
85  zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s", &str, &str_len)
86
872)
88  int num; /* XXX THIS IS WRONG!! Use long instead. */
89  zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "l", &num)
90
91If you're in doubt, use check_parameters.php script to the parameters 
92and their types (it can be found in ./scripts/dev/ directory of PHP sources):
93
94# php ./scripts/dev/check_parameters.php /path/to/your/sources/
95
96
97Examples
98--------
99/* Gets a long, a string and its length, and a zval */
100long l;
101char *s;
102int s_len;
103zval *param;
104if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "lsz",
105                          &l, &s, &s_len, &param) == FAILURE) {
106    return;
107}
108
109
110/* Gets an object of class specified by my_ce, and an optional double. */
111zval *obj;
112double d = 0.5;
113zend_class_entry *my_ce;
114if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "O|d",
115                          &obj, my_ce, &d) == FAILURE) {
116    return;
117}
118
119
120/* Gets an object or null, and an array.
121   If null is passed for object, obj will be set to NULL. */
122zval *obj;
123zval *arr;
124if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "o!a",
125                          &obj, &arr) == FAILURE) {
126    return;
127}
128
129
130/* Gets a separated array which can also be null. */
131zval *arr;
132if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "a/!",
133                          &arr) == FAILURE) {
134    return;
135}
136
137/* Get either a set of 3 longs or a string. */
138long l1, l2, l3;
139char *s;
140/* 
141 * The function expects a pointer to a integer in this case, not a long
142 * or any other type.  If you specify a type which is larger
143 * than a 'int', the upper bits might not be initialized
144 * properly, leading to random crashes on platforms like
145 * Tru64 or Linux/Alpha.
146 */
147int length;
148
149if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS() TSRMLS_CC,
150                             "lll", &l1, &l2, &l3) == SUCCESS) {
151    /* manipulate longs */
152} else if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS() TSRMLS_CC,
153                                    "s", &s, &length) == SUCCESS) {
154    /* manipulate string */
155} else {
156    /* output error */
157
158    return;
159}
160
161
162/* Function that accepts only varargs (0 or more) */
163
164int i, num_varargs;
165zval ***varargs = NULL;
166
167
168if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "*", &varargs, &num_varargs) == FAILURE) {
169    return;
170}
171
172for (i = 0; i < num_varargs; i++) {
173    /* do something with varargs[i] */
174}
175
176if (varargs) {
177    efree(varargs);
178}
179
180
181/* Function that accepts a string, followed by varargs (1 or more) */
182
183char *str;
184int str_len;
185int i, num_varargs;
186zval ***varargs = NULL;
187
188if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s+", &str, &str_len, &varargs, &num_varargs) == FAILURE) {
189    return;
190}
191
192for (i = 0; i < num_varargs; i++) {
193    /* do something with varargs[i] */
194}
195
196if (varargs) {
197    efree(varargs);
198}
199
200
201/* Function that takes an array, followed by varargs, and ending with a long */
202long num;
203zval *array;
204int i, num_varargs;
205zval ***varargs = NULL;
206
207if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "a*l", &array, &varargs, &num_varargs, &num) == FAILURE) {
208    return;
209}
210
211for (i = 0; i < num_varargs; i++) {
212    /* do something with varargs[i] */
213}
214
215if (varargs) {
216    efree(varargs);
217}
218
219

README.PHP4-TO-PHP5-THIN-CHANGES

11. strrpos() and strripos() now use the entire string as a needle.  Be aware
2   that the existing scripts may no longer work as you expect.
3
4   EX :
5   <?php
6   var_dump(strrpos("ABCDEF","DEF"));
7   var_dump(strrpos("ABCDEF","DAF"));
8   ?>
9
10   Will give you different results. The former returns 3 while the latter
11   returns false rather than the position of the last occurrence of 'D'.
12   The same applies to strripos().
13
142. Illegal use of string offsets causes E_ERROR instead of E_WARNING.
15
16   EX :
17   <?php
18   $a = "foo";
19   unset($a[0][1][2]);
20   ?>
21
22   Fatal error: Cannot use string offset as an array in ... on line 1
23
243. array_merge() was changed to accept only arrays. If a non-array variable is
25   passed, a E_WARNING will be thrown for every such parameter. Be careful
26   because your code may start emitting E_WARNING out of the blue.
27
284. Be careful when porting from ext/mysql to ext/mysqli. The following
29   functions return NULL when no more data is available in the result set
30   (ext/mysql's functions return FALSE).
31
32    - mysqli_fetch_row()
33    - mysqli_fetch_array()
34    - mysqli_fetch_assoc()
35
365. PATH_TRANSLATED server variable is no longer set implicitly under
37   Apache2 SAPI in contrast to the situation in PHP 4, where it is set to the
38   same value as the SCRIPT_FILENAME server variable when it is not populated
39   by Apache.  This change was made to comply with the CGI specification.
40   Please refer to bug #23610 for further information.
41
426. Starting PHP 5.0.0 the T_ML_CONSTANT constant is no longer defined by the
43   ext/tokenizer extension. If error_reporting is set to E_ALL notices will
44   be produced. Instead of T_ML_CONSTANT for /* */ the T_COMMENT constant 
45   is used, thus both // and /* */ are resolved as the T_COMMENT constant.
46   However the PHPDoc style comments /** */ ,which starting PHP 5 are parsed
47   by PHP, are recongnized as T_DOC_COMMENT.
48
497. $_SERVER should be populated with argc and argv if variables_order
50   includes "S".  If you have specifically configured your system to not
51   create $_SERVER, then of course it shouldn't be there.  The change was to
52   always make argc and argv available in the CLI version regardless of the
53   variables_order setting.  As in, the CLI version will now always populate
54   the global $argc and $argv variables.
55
568. In some cases classes must be declared before used. It only happens only
57   if some of the new features of PHP 5 are used. Otherwise the behaviour is
58   the old.
59   Example 1 (works with no errors):
60   <?php
61   $a = new a();
62   class a {
63   }
64   ?>
65 
66   Example 2 (throws an error):
67   <?php 
68   $a = new a();
69   interface b{
70   }
71   class a implements b {
72   } 
73   ?>
74
75   Output (example 2) :
76   Fatal error: Class 'a' not found in /tmp/cl.php on line 2
77
789. get_class() starting PHP 5 returns the name of the class as it was
79   declared which may lead to problems in older scripts that rely on
80   the previous behaviour - the class name is lowercased. Expect the
81   same behaviour from get_parent_class() when applicable.
82   Example :
83   <?php
84   class FooBar {
85   }
86   class ExtFooBar extends FooBar{}
87   $a = new FooBar();
88   var_dump(get_class($a), get_parent_class($a));
89   ?>
90
91   Output (PHP 4):
92   string(6) "foobar"
93   string(9) "extfoobar"
94
95   Output (PHP 5):
96   string(6) "FooBar"
97   string(9) "ExtFooBar"
98   ----------------------------------------------------------------------
99   Example code that will break :
100   //....
101   function someMethod($p) {
102     if (get_class($p) != 'helpingclass') {
103       return FALSE;
104     }
105     //...
106   }
107   //...
108   Possible solution is to search for get_class() and get_parent_class() in
109   all your scripts and use strtolower().
110
11110. get_class_methods() returns the names of the methods of a class as they
112   declared. In PHP4 the names are all lowercased.
113   Example code :
114   <?php
115   class Foo{
116     function doFoo(){}
117     function hasFoo(){}
118   }
119   var_dump(get_class_methods("Foo")); 
120   ?>
121   Output (PHP4):
122   array(2) {
123     [0]=>
124     string(5) "dofoo"
125     [1]=>
126     string(6) "hasfoo"
127   }
128   Output (PHP5):
129   array(2) {
130     [0]=>
131     string(5) "doFoo"
132     [1]=>
133     string(6) "hasFoo"
134   }
135
13611. Assignment $this is impossible. Starting PHP 5.0.0 $this has special
137    meaning in class methods and is recognized by the PHP parser. The latter
138    will generate a parse error when assignment to $this is found
139    Example code :
140    <?php
141    class Foo {
142      function assignNew($obj) {
143        $this = $obj;
144      }
145    }
146    $a = new Foo();
147    $b = new Foo();
148    $a->assignNew($b);
149    echo "I was executed\n";
150    ?>
151    Output (PHP 4):
152    I was executed
153    Output (PHP 5):
154    PHP Fatal error:  Cannot re-assign $this in /tmp/this_ex.php on line 4
155
156

README.REDIST.BINS

11. libmagic (ext/fileinfo) see ext/fileinfo/libmagic/LICENSE
22. Oniguruma (ext/mbstring) see ext/mbstring/oniguruma/COPYING
33. libmbfl (ext/mbstring) see ext/mbstring/libmbfl/LICENSE
44. pcrelib (ext/pcre) see ext/pcre/pcrelib/LICENCE
55. ext/standard crypt
66. ext/standard crypt's blowfish implementation
77. Sqlite/Sqlite3 ext/sqlite3 ext/sqlite
88. ext/json/json_parser
99. ext/standard/rand
1010. ext/standard/scanf
1111. ext/standard/strnatcmp.c
1212. ext/standard/uuencode
1313. libxmlrpc ext/xmlrpc
1414. libzip ext/zip
1515. main/snprintf.c
1616. main/strlcat
1717. main/strlcpy
1818. libgd see ext/gd/libgd/COPYING
19
205. ext/standard crypt
21
22FreeSec: libcrypt for NetBSD
23
24Copyright (c) 1994 David Burren
25All rights reserved.
26
27Redistribution and use in source and binary forms, with or without
28modification, are permitted provided that the following conditions
29are met:
301. Redistributions of source code must retain the above copyright
31     notice, this list of conditions and the following disclaimer.
322. Redistributions in binary form must reproduce the above copyright
33     notice, this list of conditions and the following disclaimer in the
34     documentation and/or other materials provided with the distribution.
353. Neither the name of the author nor the names of other contributors
36     may be used to endorse or promote products derived from this software
37     without specific prior written permission.
38
39THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
40ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
41IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
42ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
43FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
44DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
45OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
46HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
47LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
48OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
49SUCH DAMAGE.
50 
51
526. ext/standard crypt's blowfish implementation
53
54The crypt_blowfish homepage is:
55
56http://www.openwall.com/crypt/
57
58This code comes from John the Ripper password cracker, with reentrant
59and crypt(3) interfaces added, but optimizations specific to password
60cracking removed.
61
62Written by Solar Designer <solar at openwall.com> in 1998-2011.
63No copyright is claimed, and the software is hereby placed in the public
64domain. In case this attempt to disclaim copyright and place the software
65in the public domain is deemed null and void, then the software is
66Copyright (c) 1998-2011 Solar Designer and it is hereby released to the
67general public under the following terms:
68
69Redistribution and use in source and binary forms, with or without
70modification, are permitted.
71
72There's ABSOLUTELY NO WARRANTY, express or implied.
73
74It is my intent that you should be able to use this on your system,
75as part of a software package, or anywhere else to improve security,
76ensure compatibility, or for any other purpose. I would appreciate
77it if you give credit where it is due and keep your modifications in
78the public domain as well, but I don't require that in order to let
79you place this code and any modifications you make under a license
80of your choice.
81
82This implementation is mostly compatible with OpenBSD's bcrypt.c (prefix
83"$2a$") by Niels Provos <provos at citi.umich.edu>, and uses some of his
84ideas. The password hashing algorithm was designed by David Mazieres
85<dm at lcs.mit.edu>. For more information on the level of compatibility,
86please refer to the comments in BF_set_key() and to the crypt(3) man page
87included in the crypt_blowfish tarball.
88
89There's a paper on the algorithm that explains its design decisions:
90
91http://www.usenix.org/events/usenix99/provos.html
92
93Some of the tricks in BF_ROUND might be inspired by Eric Young's
94Blowfish library (I can't be sure if I would think of something if I
95hadn't seen his code).
96 
97
987. Sqlite/Sqlite3 ext/sqlite3 ext/sqlite
99
100The author disclaims copyright to this source code.  In place of
101a legal notice, here is a blessing:
102  May you do good and not evil.
103  May you find forgiveness for yourself and forgive others.
104  May you share freely, never taking more than you give.
105
106
1078. ext/json/json_parser
108Copyright (c) 2005 JSON.org
109
110Permission is hereby granted, free of charge, to any person obtaining a copy
111of this software and associated documentation files (the "Software"), to deal
112in the Software without restriction, including without limitation the rights
113to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
114copies of the Software, and to permit persons to whom the Software is
115furnished to do so, subject to the following conditions:
116
117The above copyright notice and this permission notice shall be included in all
118copies or substantial portions of the Software.
119
120The Software shall be used for Good, not Evil.
121
122THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
123IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
124FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
125AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
126LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
127OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
128SOFTWARE.
129
130
1319. ext/standard/rand
132The following php_mt_...() functions are based on a C++ class MTRand by
133Richard J. Wagner. For more information see the web page at
134http://www-personal.engin.umich.edu/~wagnerr/MersenneTwister.html
135
136Mersenne Twister random number generator -- a C++ class MTRand
137Based on code by Makoto Matsumoto, Takuji Nishimura, and Shawn Cokus
138Richard J. Wagner  v1.0  15 May 2003  rjwagner@writeme.com
139
140The Mersenne Twister is an algorithm for generating random numbers.  It
141was designed with consideration of the flaws in various other generators.
142The period, 2^19937-1, and the order of equidistribution, 623 dimensions,
143are far greater.  The generator is also fast; it avoids multiplication and
144division, and it benefits from caches and pipelines.  For more information
145see the inventors' web page at http://www.math.keio.ac.jp/~matumoto/emt.html
146
147Reference
148M. Matsumoto and T. Nishimura, "Mersenne Twister: A 623-Dimensionally
149Equidistributed Uniform Pseudo-Random Number Generator", ACM Transactions on
150Modeling and Computer Simulation, Vol. 8, No. 1, January 1998, pp 3-30.
151
152Copyright (C) 1997 - 2002, Makoto Matsumoto and Takuji Nishimura,
153Copyright (C) 2000 - 2003, Richard J. Wagner
154All rights reserved.                          
155
156Redistribution and use in source and binary forms, with or without
157modification, are permitted provided that the following conditions
158are met:
159
1601. Redistributions of source code must retain the above copyright
161     notice, this list of conditions and the following disclaimer.
162
1632. Redistributions in binary form must reproduce the above copyright
164     notice, this list of conditions and the following disclaimer in the
165     documentation and/or other materials provided with the distribution.
166
1673. The names of its contributors may not be used to endorse or promote 
168     products derived from this software without specific prior written 
169     permission.
170
171THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
172"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
173LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
174A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
175CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
176EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
177PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
178PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
179LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
180NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
181SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
182
183
18410. ext/standard/scanf
185scanf.c --
186
187This file contains the base code which implements sscanf and by extension
188fscanf. Original code is from TCL8.3.0 and bears the following copyright:
189
190This software is copyrighted by the Regents of the University of
191California, Sun Microsystems, Inc., Scriptics Corporation,
192and other parties.  The following terms apply to all files associated
193with the software unless explicitly disclaimed in individual files.
194
195The authors hereby grant permission to use, copy, modify, distribute,
196and license this software and its documentation for any purpose, provided
197that existing copyright notices are retained in all copies and that this
198notice is included verbatim in any distributions. No written agreement,
199license, or royalty fee is required for any of the authorized uses.
200Modifications to this software may be copyrighted by their authors
201and need not follow the licensing terms described here, provided that
202the new terms are clearly indicated on the first page of each file where
203they apply.
204
205IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY
206FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
207ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY
208DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE
209POSSIBILITY OF SUCH DAMAGE.
210
211THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
212INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,
213FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.  THIS SOFTWARE
214IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE
215NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
216MODIFICATIONS.
217
218GOVERNMENT USE: If you are acquiring this software on behalf of the
219U.S. government, the Government shall have only "Restricted Rights"
220in the software and related documentation as defined in the Federal
221Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2).  If you
222are acquiring the software on behalf of the Department of Defense, the
223software shall be classified as "Commercial Computer Software" and the
224Government shall have only "Restricted Rights" as defined in Clause
225252.227-7013 (c) (1) of DFARs.  Notwithstanding the foregoing, the
226authors grant the U.S. Government and others acting in its behalf
227permission to use and distribute the software in accordance with the
228terms specified in this license.
229
23011. ext/standard/strnatcmp.c
231
232strnatcmp.c -- Perform 'natural order' comparisons of strings in C.
233Copyright (C) 2000 by Martin Pool <mbp@humbug.org.au>
234
235This software is provided 'as-is', without any express or implied
236warranty.  In no event will the authors be held liable for any damages
237arising from the use of this software.
238
239Permission is granted to anyone to use this software for any purpose,
240including commercial applications, and to alter it and redistribute it
241freely, subject to the following restrictions:
242
2431. The origin of this software must not be misrepresented; you must not
244     claim that you wrote the original software. If you use this software
245     in a product, an acknowledgment in the product documentation would be
246     appreciated but is not required.
2472. Altered source versions must be plainly marked as such, and must not be
248     misrepresented as being the original software.
2493. This notice may not be removed or altered from any source distribution.
250
25112. ext/standard/uuencode
252Portions of this code are based on Berkeley's uuencode/uudecode
253implementation.
254
255Copyright (c) 1983, 1993
256The Regents of the University of California.  All rights reserved.
257
258Redistribution and use in source and binary forms, with or without
259modification, are permitted provided that the following conditions
260are met:
2611. Redistributions of source code must retain the above copyright
262    notice, this list of conditions and the following disclaimer.
2632. Redistributions in binary form must reproduce the above copyright
264    notice, this list of conditions and the following disclaimer in the
265    documentation and/or other materials provided with the distribution.
2663. All advertising materials mentioning features or use of this software
267    must display the following acknowledgement:
268This product includes software developed by the University of
269California, Berkeley and its contributors.
2704. Neither the name of the University nor the names of its contributors
271    may be used to endorse or promote products derived from this software
272    without specific prior written permission.
273
274THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
275ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
276IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
277ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
278FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
279DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
280OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
281HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
282LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
283OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
284SUCH DAMAGE.
285
286
28713. libxmlrpc ext/xmlrpc
288
289Copyright 2000 Epinions, Inc. 
290
291Subject to the following 3 conditions, Epinions, Inc.  permits you, free 
292of charge, to (a) use, copy, distribute, modify, perform and display this 
293software and associated documentation files (the "Software"), and (b) 
294permit others to whom the Software is furnished to do so as well.  
295
2961) The above copyright notice and this permission notice shall be included 
297without modification in all copies or substantial portions of the 
298Software.  
299
3002) THE SOFTWARE IS PROVIDED "AS IS", WITHOUT ANY WARRANTY OR CONDITION OF 
301ANY KIND, EXPRESS, IMPLIED OR STATUTORY, INCLUDING WITHOUT LIMITATION ANY 
302IMPLIED WARRANTIES OF ACCURACY, MERCHANTABILITY, FITNESS FOR A PARTICULAR 
303PURPOSE OR NONINFRINGEMENT.  
304
3053) IN NO EVENT SHALL EPINIONS, INC. BE LIABLE FOR ANY DIRECT, INDIRECT, 
306SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES OR LOST PROFITS ARISING OUT 
307OF OR IN CONNECTION WITH THE SOFTWARE (HOWEVER ARISING, INCLUDING 
308NEGLIGENCE), EVEN IF EPINIONS, INC.  IS AWARE OF THE POSSIBILITY OF SUCH 
309DAMAGES.
310
31114. libzip ext/zip
312zip.h -- exported declarations.
313Copyright (C) 1999-2009 Dieter Baron and Thomas Klausner
314
315This file is part of libzip, a library to manipulate ZIP archives.
316The authors can be contacted at <libzip@nih.at>
317
318Redistribution and use in source and binary forms, with or without
319modification, are permitted provided that the following conditions
320are met:
3211. Redistributions of source code must retain the above copyright
322     notice, this list of conditions and the following disclaimer.
3232. Redistributions in binary form must reproduce the above copyright
324     notice, this list of conditions and the following disclaimer in
325     the documentation and/or other materials provided with the
326     distribution.
3273. The names of the authors may not be used to endorse or promote
328     products derived from this software without specific prior
329     written permission.
330
331THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS
332OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
333WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
334ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY
335DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
336DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
337GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
338INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
339IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
340OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
341IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
342
34315. main/snprintf.c
344Copyright (c) 2002, 2006 Todd C. Miller <Todd.Miller@courtesan.com>
345
346Permission to use, copy, modify, and distribute this software for any
347purpose with or without fee is hereby granted, provided that the above
348copyright notice and this permission notice appear in all copies.
349
350THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
351WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
352MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
353ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
354WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
355ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
356OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
357
358Sponsored in part by the Defense Advanced Research Projects
359Agency (DARPA) and Air Force Research Laboratory, Air Force
360Materiel Command, USAF, under agreement number F39502-99-1-0512.
361
362main/spprintf
363Copyright (c) 1995-1998 The Apache Group.  All rights reserved.
364
365Redistribution and use in source and binary forms, with or without
366modification, are permitted provided that the following conditions
367are met:
368
3691. Redistributions of source code must retain the above copyright
370     notice, this list of conditions and the following disclaimer.
371
3722. Redistributions in binary form must reproduce the above copyright
373     notice, this list of conditions and the following disclaimer in
374     the documentation and/or other materials provided with the
375     distribution.
376
3773. All advertising materials mentioning features or use of this
378     software must display the following acknowledgment:
379     "This product includes software developed by the Apache Group
380     for use in the Apache HTTP server project (http://www.apache.org/)."
381
3824. The names "Apache Server" and "Apache Group" must not be used to
383     endorse or promote products derived from this software without
384     prior written permission.
385
3865. Redistributions of any form whatsoever must retain the following
387     acknowledgment:
388     "This product includes software developed by the Apache Group
389     for use in the Apache HTTP server project (http://www.apache.org/)."
390
391THIS SOFTWARE IS PROVIDED BY THE APACHE GROUP ``AS IS'' AND ANY
392EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
393IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
394PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE APACHE GROUP OR
395ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
396SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
397NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
398LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
399HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
400STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
401ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
402OF THE POSSIBILITY OF SUCH DAMAGE.
403====================================================================
404
405This software consists of voluntary contributions made by many
406individuals on behalf of the Apache Group and was originally based
407on public domain software written at the National Center for
408Supercomputing Applications, University of Illinois, Urbana-Champaign.
409For more information on the Apache Group and the Apache HTTP server
410project, please see <http://www.apache.org/>.
411
412This code is based on, and used with the permission of, the
413SIO stdio-replacement strx_* functions by Panos Tsirigotis
414<panos@alumni.cs.colorado.edu> for xinetd.
415
41616. main/strlcat
41717. main/strlcpy
418Copyright (c) 1998 Todd C. Miller <Todd.Miller@courtesan.com>
419All rights reserved.
420
421Redistribution and use in source and binary forms, with or without
422modification, are permitted provided that the following conditions
423are met:
4241. Redistributions of source code must retain the above copyright
425    notice, this list of conditions and the following disclaimer.
4262. Redistributions in binary form must reproduce the above copyright
427    notice, this list of conditions and the following disclaimer in the
428    documentation and/or other materials provided with the distribution.
4293. The name of the author may not be used to endorse or promote products
430    derived from this software without specific prior written permission.
431
432THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
433INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
434AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
435THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
436EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
437PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
438OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
439WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
440OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
441ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
442
443

README.RELEASE_PROCESS

1=======================
2  PHP Release Process
3=======================
4
5General notes and tips
6----------------------
7
81. Do not release on Fridays, Saturdays or Sundays
9because the sysadmins can not upgrade stuff then.
10
112. Package two days before a release. So if the release is to be on Thursday,
12package on Tuesday. Think about timezones as well.
13
143. Ensure that Windows builds will work before packaging
15
164. Follow all steps to the letter. When unclear ask previous RM's (David/Julien/
17Johannes/Stas/Derick/Ilia) before proceeding. Ideally make sure that for the
18first releases one of the previous RM's is around to answer questions. For the
19steps related to the php/QA/bug websites try to have someone from the webmaster
20team (Bjori) on hand.
21
225. Verify the tags to be extra sure everything was tagged properly.
23
246. Moving extensions from/to PECL requires write acces to the destination.
25Most developers should have this. 
26
27Moving extensions from php-src to PECL
28- Checkout the pecl directory, most likely you want a sparse-root checkout
29  svn co --depth=empty https://svn.php.net/repository/pecl
30- Create an directory for the extension incl. branch and tag structure,
31  no trunk at this point and commit this to svn
32  cd pecl; mkdir foo foo/tags foo/branches; svn add foo; svn commit
33- Move the extension from php-src to the new location
34  svn mv https://svn.php.net/repository/php/php-src/trunk/ext/foo \
35         https://svn.php.net/repository/pecl/foo/trunk
36
37If the extension is still usable or not dead, in cooperation with the extension
38maintainers if any:
39- create the pecl.php.net/foo package and its content, license, maintainer
40- create the package.xml, commit
41- release the package
42
43For Moving extensions from PECL to php-src the svn mv has to be tone the other
44way round.
45
46Rolling a non stable release (alpha/beta/RC)
47--------------------------------------------
48
491. Check windows snapshot builder logs (http://windows.php.net/downloads/snaps/ the last revision)
50
512. run the "scripts/dev/credits" script in php-src and commit the changes in the
52credits files in ext/standard.
53
543. Checkout the release branch for this release (e.g., PHP-5.4.2) from the main branch.
55
564. Bump the version numbers in ``main/php_version.h``, ``configure.in`` and possibly ``NEWS``.
57Do not use abbreviations for alpha and beta. Do not use dashes, you should
58``#define PHP_VERSION "5.4.22RC1"`` and not ``#define PHP_VERSION "5.4.22-RC1"``
59
605. Compile and make test, with and without ZTS, using the right Bison version
61(for example, for 5.5, Bison 2.4.1 is used)
62
636. Check ./sapi/cli/php -v output for version matching.
64
657. If all is right, commit the changes to the release branch with ``git commit -a``.
66
678. Tag the repository release branch with the version, e.g.: 
68``git tag -u YOURKEYID php-5.4.2RC2``
69
709. Bump the version numbers in ``main/php_version.h``, ``configure.in`` and ``NEWS``
71in the *main* branch (PHP-5.4 for example) to prepare for the **next** version.
72F.e. if the RC is "5.4.1RC1" then the new one should be "5.4.2-dev" - regardless if we get
73a new RC or not. This is to make sure ``version_compare()`` can correctly work.
74Commit the changes to the main branch.
75
7610. Push the changes to the main repo, the tag, the main branch and the release branch :
77``git push --tags origin HEAD``
78``git push origin {main branch}``
79``git push origin {release branch}``
80
8111. run: ``PHPROOT=. ./makedist 5.4.2RC2``, this will export the tree, create configure
82and build three tarballs (gz, bz2 and xz).
83
8412. Copy those tarballs (scp, rsync) to downloads.php.net, in your homedir there should be a
85directory "downloads/". Copy them into there, so that the system can generate
86MD5 sums. If you do not have this directory, talk to Derick or Dan.
87
8813. Now the RC can be found on http://downloads.php.net/yourname,
89f.e. http://downloads.php.net/derick/
90
9114. Once the release has been tagged, contact the PHP Windows development team
92(internals-win@lists.php.net) so that Windows binaries can be created. Once
93those are made, they should be placed into the same directory as the source snapshots.
94
95Getting the non stable release (alpha/beta/RC) announced
96--------------------------------------------------------
97
981. Send an email (see example here: http://news.php.net/php.internals/19486)
99**To** ``internals@lists.php.net`` and ``php-general@lists.php.net`` lists
100pointing out "the location of the release" and "the possible release date of
101either the next RC, or the final release".
102
1032. Send an email (see example here http://news.php.net/php.pear.qa/5201) **To**
104``php-qa@lists.php.net`` and ``primary-qa-tester@lists.php.net``.
105This email is to notify the selected projects about a new release so that they
106can make sure their projects keep working. Make sure that you have been setup
107as a moderator for ``primary-qa-tester@lists.php.net`` by having someone (Hannes, Dan,
108Derick) run the following commands for you:
109
110``ssh lists.php.net``
111
112``sudo -u ezmlm ezmlm-sub ~ezmlm/primary-qa-tester/mod moderator-email-address``
113
1143. Update ``qa.git/include/release-qa.php`` with the appropriate information.
115   See the documentation within release-qa.php for more information, but all releases
116   and RCs are configured here. Only $QA_RELEASES needs to be edited.
117
118   Example: When rolling an RC, set the 'rc' with appropriate information for the
119   given version.
120
121   Note: Remember to update the MD5 checksum information.
122
1234. Update ``web/php.git/include/version.inc`` (x=major version number)
124
125 a. ``$PHP_x_RC`` = "5.4.0RC1"  (should be set to "false" before)
126
127 b. ``$PHP_x_RC_DATE`` = "06 September 2007"
128
1295. Commit and push those changes:
130
131 a. ``git commit -a && git push origin master``
132
1336. For the first RC, write the doc team (phpdoc@lists.php.net) about updating the
134INSTALL and win32/install.txt files which are generated from the PHP manual sources.
135
136Rolling a stable release
137------------------------
138
1391. Checkout your release branch, you should have created when releasing previous RC
140and bump the version numbers in ``main/php_version.h``, ``configure.in`` and possibly ``NEWS``.
141
1422. If a CVE commit needs to be merged to the release, then have it commited to
143the base branches and merged upwards as usual (f.e commit the CVE fix to 5.3,
144merge to 5.4, 5.5 etc...). Then you can cherry-pick it in your release branch.
145Don't forget to update NEWS manually in an extra commit then.
146
1473. Commit those changes
148
1494. run the "scripts/dev/credits" script in php-src and commit the changes in the
150credits files in ext/standard.
151
1525. Compile and make test, with and without ZTS, using the right Bison version
153(for example, for 5.5, Bison 2.4.1 is used)
154
1556. Check ./sapi/cli/php -v output for version matching.
156
1577. tag the repository with the version f.e. "``git tag -s php-5.4.1``"
158
1598. Push the tag f.e. "``git push origin php-5.4.1``"
160
1619. run: ``PHPROOT=. ./makedist php 5.4.1``, this will export the tag, create configure
162and build three tarballs (gz, bz2 and xz).
163Check if the pear files are updated (phar).
164
16510. Generate the GPG signature files for the archives.
166  ``gpg -u YOUREMAIL --armor --detach-sign php-X.Y.Z.tar.xxx``
167
16811. Commit and push all the tarballs and signature files to web/php-distributions.git,
169    then update the git submodule reference in web/php.git: 
170    ``git submodule init;
171    git submodule update;
172    cd distributions;
173    git pull origin master;
174    cd ..;
175    git commit distributions;
176    git push;``
177This is to fetch the last commit id from php-distributions.git and commit this
178last commit id to web/php.git, then, mirrors will now sync
179
18012. Once the release has been tagged, contact the PHP Windows development team
181(internals-win@lists.php.net) so that Windows binaries can be created.
182
183Getting the stable release announced
184------------------------------------
185
1861. Run the bumpRelease script for phpweb on your local checkout
187
188 a. ``php bin/bumpRelease 5`` to create the release file (releases/x_y_z.php)
189    The release announcement file should list in detail security fixes and
190    changes in behavior (whether due to a bug fix or not).
191
192 b. In case multiple PHP minor versions are in active development you have
193    to manually copy the old information to include/releases.inc
194
1952. Edit ``phpweb/include/version.inc`` and change (X=major release number):
196
197 a. ``$PHP_X_VERSION`` to the correct version
198
199 b. ``$PHP_X_DATE`` to the release date
200
201 c. ``$PHP_X_MD5`` array and update all the md5 sums
202
203 d. set ``$PHP_X_RC`` to false!
204
205 e. Make sure there are no outdated "notes" or edited "date" keys in the
206 ``$RELEASES[X][$PHP_X_VERSION]["source"]`` array
207
208 f. if the windows builds aren't ready yet prefix the "windows" key with a dot (".windows")
209
2103. Update phpweb/include/releases.php with the old release info
211  (updates the download archives)
212
2134. Update php-qa/include/release-qa.php and add the next version as an QARELEASE
214   (prepare for next RC)
215
2165. Update the ChangeLog file for the given major version
217f.e. ``ChangeLog-5.php`` from the NEWS file
218
219 a. go over the list and put every element on one line
220
221 b. check for &, < and > and escape them if necessary
222
223 c. remove all the names at the ends of lines
224
225 d. for marking up, you can do the following (with VI):
226
227  I. ``s/^- /<li>/``
228
229  II. ``s/$/<\/li>/``
230
231  III. ``s/Fixed bug #\([0-9]\+\)/<?php bugfix(\1); ?>/``
232
233  IV. ``s/Fixed PECL bug #\([0-9]\+\)/<?php peclbugfix(\1); ?>/``
234
235  V. ``s/FR #\([0-9]\+\)/FR <?php bugl(\1); ?>/``
236  
237  e. You may want to try php-web/bin/news2html to automate this task
238
2396. Add a short notice to phpweb stating that there is a new release, and
240highlight the major important things (security fixes) and when it is important
241to upgrade.
242
243 a. Call php bin/createNewsEntry in your local phpweb checkout
244
245 b. Add the content for the news entry
246
2477. **Check mirrors have been synced before announcing or pushing news**
248  Try, f.e. http://www.php.net/get/php-5.5.1.tar.bz2/from/a/mirror
249  Try several mirrors, mirrors may update slowly (may take an hour)
250
2518. Commit all the changes to their respective git repos
252
2539. Wait an hour or two, then send a mail to php-announce@lists.php.net,
254php-general@lists.php.net and internals@lists.php.net with a text similar to
255http://news.php.net/php.internals/17222.
256
257Re-releasing the same version (or -pl)
258--------------------------------------
259
2601. Commit the new binaries to ``phpweb/distributions/``
261
2622. Edit ``phpweb/include/version.inc`` and change (X=major release number):
263
264 a. If only releasing for one OS, make sure you edit only those variables
265
266 b. ``$PHP_X_VERSION`` to the correct version
267
268 c. ``$PHP_X_DATE`` to the release date
269
270 d. ``$PHP_X_MD5`` array and update all the md5 sums
271
272 e. Make sure there are no outdated "notes" or edited "date" keys in the
273 ``$RELEASES[X][$PHP_X_VERSION]["source"]`` array
274
2753. Add a short notice to phpweb stating that there is a new release, and
276highlight the major important things (security fixes) and when it is important
277to upgrade.
278
279 a. Call php bin/createNewsEntry in your local phpweb checkout
280
281 b. Add the content for the news entry
282
2834. Commit all the changes (``include/version.inc``, ``archive/archive.xml``,
284``archive/entries/YYYY-MM-DD-N.xml``)
285
2865. Wait an hour or two, then send a mail to php-announce@lists.php.net,
287php-general@lists.php.net and internals@lists.php.net with a text similar to
288the news entry.
289

README.SELF-CONTAINED-EXTENSIONS

1$Id$
2=============================================================================
3
4HOW TO CREATE A SELF-CONTAINED PHP EXTENSION
5
6  A self-contained extension can be distributed independently of
7  the PHP source. To create such an extension, two things are
8  required:
9
10  - Configuration file (config.m4)
11  - Source code for your module
12
13  We will describe now how to create these and how to put things
14  together.
15
16PREPARING YOUR SYSTEM
17
18  While the result will run on any system, a developer's setup needs these
19  tools:
20
21    GNU autoconf
22    GNU automake
23    GNU libtool
24    GNU m4
25
26  All of these are available from 
27
28    ftp://ftp.gnu.org/pub/gnu/
29
30CONVERTING AN EXISTING EXTENSION
31
32  Just to show you how easy it is to create a self-contained
33  extension, we will convert an embedded extension into a
34  self-contained one. Install PHP and execute the following
35  commands.
36  
37     $ mkdir /tmp/newext
38     $ cd /tmp/newext
39
40  You now have an empty directory. We will copy the files from
41  the mysql extension:
42
43     $ cp -rp php-4.0.X/ext/mysql/* .
44
45  It is time to finish the module. Run:
46
47     $ phpize
48
49  You can now ship the contents of the directory - the extension
50  can live completely on its own.
51
52  The user instructions boil down to
53
54     $ ./configure \
55            [--with-php-config=/path/to/php-config] \
56            [--with-mysql=MYSQL-DIR]
57     $ make install
58
59  The MySQL module will either use the embedded MySQL client 
60  library or the MySQL installation in MYSQL-DIR.
61
62
63DEFINING THE NEW EXTENSION
64
65  Our demo extension is called "foobar".
66
67  It consists of two source files "foo.c" and "bar.c"
68  (and any arbitrary amount of header files, but that is not
69  important here).
70  
71  The demo extension does not reference any external 
72  libraries (that is important, because the user does not
73  need to specify anything).
74
75
76  LTLIBRARY_SOURCES specifies the names of the sources files. You can
77  name an arbitrary number of source files here.
78
79CREATING THE M4 CONFIGURATION FILE
80
81  The m4 configuration can perform additional checks. For a 
82  self-contained extension, you do not need more than a few
83  macro calls.
84
85------------------------------------------------------------------------------
86PHP_ARG_ENABLE(foobar,whether to enable foobar,
87[  --enable-foobar            Enable foobar])
88
89if test "$PHP_FOOBAR" != "no"; then
90  PHP_NEW_EXTENSION(foobar, foo.c bar.c, $ext_shared)
91fi
92------------------------------------------------------------------------------
93
94  PHP_ARG_ENABLE will automatically set the correct variables, so
95  that the extension will be enabled by PHP_NEW_EXTENSION in shared mode.
96
97  The first argument of PHP_NEW_EXTENSION describes the name of the
98  extension.  The second names the source-code files.  The third passes
99  $ext_shared which is set by PHP_ARG_ENABLE/WITH to PHP_NEW_EXTENSION.
100  
101  Please use always PHP_ARG_ENABLE or PHP_ARG_WITH. Even if you do not
102  plan to distribute your module with PHP, these facilities allow you
103  to integrate your module easily into the main PHP module framework.
104
105CREATING SOURCE FILES
106
107  ext_skel can be of great help when creating the common code for all modules
108  in PHP for you and also writing basic function definitions and C code for
109  handling arguments passed to your functions. See README.EXT_SKEL for further
110  information.
111
112  As for the rest, you are currently alone here. There are a lot of existing
113  modules, use a simple module as a starting point and add your own code.
114
115
116CREATING THE SELF-CONTAINED EXTENSION
117
118  Put config.m4 and the source files into one directory. Then, run phpize
119  (this is installed during make install by PHP 4.0).
120
121  For example, if you configured PHP with --prefix=/php, you would run
122
123     $ /php/bin/phpize
124
125  This will automatically copy the necessary build files and create
126  configure from your config.m4.
127
128  And that's it. You now have a self-contained extension.
129
130INSTALLING A SELF-CONTAINED EXTENSION
131
132  An extension can be installed by running:
133
134     $ ./configure \
135            [--with-php-config=/path/to/php-config]
136     $ make install
137
138ADDING SHARED MODULE SUPPORT TO A MODULE
139
140  In order to be useful, a self-contained extension must be loadable
141  as a shared module. I will explain now how you can add shared module 
142  support to an existing module called foo.
143
144  1. In config.m4, use PHP_ARG_WITH/PHP_ARG_ENABLE. Then you will
145     automatically be able to use --with-foo=shared[,..] or
146     --enable-foo=shared[,..].
147
148  2. In config.m4, use PHP_NEW_EXTENSION(foo,.., $ext_shared) to enable
149     building the extension.
150
151  3. Add the following lines to your C source file:
152
153        #ifdef COMPILE_DL_FOO
154        ZEND_GET_MODULE(foo)
155        #endif
156

README.STREAMS

1An Overview of the PHP Streams abstraction
2==========================================
3$Id$
4
5WARNING: some prototypes in this file are out of date.
6The information contained here is being integrated into
7the PHP manual - stay tuned...
8
9Please send comments to: Wez Furlong <wez@thebrainroom.com>
10
11Why Streams?
12============
13You may have noticed a shed-load of issock parameters flying around the PHP
14code; we don't want them - they are ugly and cumbersome and force you to
15special case sockets and files every time you need to work with a "user-level"
16PHP file pointer.
17Streams take care of that and present the PHP extension coder with an ANSI
18stdio-alike API that looks much nicer and can be extended to support non file
19based data sources.
20
21Using Streams
22=============
23Streams use a php_stream* parameter just as ANSI stdio (fread etc.) use a
24FILE* parameter.
25
26The main functions are:
27
28PHPAPI size_t php_stream_read(php_stream * stream, char * buf, size_t count);
29PHPAPI size_t php_stream_write(php_stream * stream, const char * buf, size_t
30        count);
31PHPAPI size_t php_stream_printf(php_stream * stream TSRMLS_DC, 
32        const char * fmt, ...);
33PHPAPI int php_stream_eof(php_stream * stream);
34PHPAPI int php_stream_getc(php_stream * stream);
35PHPAPI char *php_stream_gets(php_stream * stream, char *buf, size_t maxlen);
36PHPAPI int php_stream_close(php_stream * stream);
37PHPAPI int php_stream_flush(php_stream * stream);
38PHPAPI int php_stream_seek(php_stream * stream, off_t offset, int whence);
39PHPAPI off_t php_stream_tell(php_stream * stream);
40PHPAPI int php_stream_lock(php_stream * stream, int mode);
41
42These (should) behave in the same way as the ANSI stdio functions with similar
43names: fread, fwrite, fprintf, feof, fgetc, fgets, fclose, fflush, fseek, ftell, flock.
44
45Opening Streams
46===============
47In most cases, you should use this API:
48
49PHPAPI php_stream *php_stream_open_wrapper(char *path, char *mode,
50    int options, char **opened_path TSRMLS_DC);
51
52Where:
53    path is the file or resource to open.
54    mode is the stdio compatible mode eg: "wb", "rb" etc.
55    options is a combination of the following values:
56        IGNORE_PATH  (default) - don't use include path to search for the file
57        USE_PATH        - use include path to search for the file
58        IGNORE_URL      - do not use plugin wrappers
59        REPORT_ERRORS   - show errors in a standard format if something
60                          goes wrong.
61        STREAM_MUST_SEEK - If you really need to be able to seek the stream
62                           and don't need to be able to write to the original
63                           file/URL, use this option to arrange for the stream
64                           to be copied (if needed) into a stream that can
65                           be seek()ed.
66                           
67    opened_path is used to return the path of the actual file opened,
68    but if you used STREAM_MUST_SEEK, may not be valid.  You are
69    responsible for efree()ing opened_path.  opened_path may be (and usually
70    is) NULL.
71
72If you need to open a specific stream, or convert standard resources into
73streams there are a range of functions to do this defined in php_streams.h.
74A brief list of the most commonly used functions:
75
76PHPAPI php_stream *php_stream_fopen_from_file(FILE *file, const char *mode);
77    Convert a FILE * into a stream.
78
79PHPAPI php_stream *php_stream_fopen_tmpfile(void);
80    Open a FILE * with tmpfile() and convert into a stream.
81
82PHPAPI php_stream *php_stream_fopen_temporary_file(const char *dir,
83    const char *pfx, char **opened_path TSRMLS_DC);
84    Generate a temporary file name and open it.
85
86There are some network enabled relatives in php_network.h:
87
88PHPAPI php_stream *php_stream_sock_open_from_socket(int socket, int persistent);
89    Convert a socket into a stream.
90
91PHPAPI php_stream *php_stream_sock_open_host(const char *host, unsigned short port,
92        int socktype, int timeout, int persistent);
93    Open a connection to a host and return a stream.
94
95PHPAPI php_stream *php_stream_sock_open_unix(const char *path, int persistent,
96    struct timeval *timeout);
97    Open a UNIX domain socket.
98   
99
100Stream Utilities
101================
102
103If you need to copy some data from one stream to another, you will be please
104to know that the streams API provides a standard way to do this:
105
106PHPAPI size_t php_stream_copy_to_stream(php_stream *src,
107    php_stream *dest, size_t maxlen);
108
109If you want to copy all remaining data from the src stream, pass
110PHP_STREAM_COPY_ALL as the maxlen parameter, otherwise maxlen indicates the
111number of bytes to copy.
112This function will try to use mmap where available to make the copying more
113efficient.
114
115If you want to read the contents of a stream into an allocated memory buffer,
116you should use:
117
118PHPAPI size_t php_stream_copy_to_mem(php_stream *src, char **buf,
119    size_t maxlen, int persistent);
120
121This function will set buf to the address of the buffer that it allocated,
122which will be maxlen bytes in length, or will be the entire length of the
123data remaining on the stream if you set maxlen to PHP_STREAM_COPY_ALL.
124The buffer is allocated using pemalloc(); you need to call pefree() to
125release the memory when you are done.
126As with copy_to_stream, this function will try use mmap where it can.
127
128If you have an existing stream and need to be able to seek() it, you
129can use this function to copy the contents into a new stream that can
130be seek()ed:
131
132PHPAPI int php_stream_make_seekable(php_stream *origstream, php_stream **newstream);
133
134It returns one of the following values:
135#define PHP_STREAM_UNCHANGED    0 /* orig stream was seekable anyway */
136#define PHP_STREAM_RELEASED     1 /* newstream should be used; origstream is no longer valid */
137#define PHP_STREAM_FAILED       2 /* an error occurred while attempting conversion */
138#define PHP_STREAM_CRITICAL     3 /* an error occurred; origstream is in an unknown state; you should close origstream */
139
140make_seekable will always set newstream to be the stream that is valid
141if the function succeeds.
142When you have finished, remember to close the stream.
143
144NOTE: If you only need to seek forward, there is no need to call this
145function, as the php_stream_seek can emulate forward seeking when the
146whence parameter is SEEK_CUR.
147
148NOTE: Writing to the stream may not affect the original source, so it
149only makes sense to use this for read-only use.
150
151NOTE: If the origstream is network based, this function will block
152until the whole contents have been downloaded.
153
154NOTE: Never call this function with an origstream that is referenced
155as a resource! It will close the origstream on success, and this
156can lead to a crash when the resource is later used/released.
157
158NOTE: If you are opening a stream and need it to be seekable, use the
159STREAM_MUST_SEEK option to php_stream_open_wrapper();
160
161PHPAPI int php_stream_supports_lock(php_stream * stream);
162
163This function will return either 1 (success) or 0 (failure) indicating whether or
164not a lock can be set on this stream. Typically you can only set locks on stdio streams.
165
166Casting Streams
167===============
168What if your extension needs to access the FILE* of a user level file pointer?
169You need to "cast" the stream into a FILE*, and this is how you do it:
170
171FILE * fp;
172php_stream * stream; /* already opened */
173
174if (php_stream_cast(stream, PHP_STREAM_AS_STDIO, (void*)&fp, REPORT_ERRORS) == FAILURE)    {
175    RETURN_FALSE;
176}
177
178The prototype is:
179
180PHPAPI int php_stream_cast(php_stream * stream, int castas, void ** ret, int
181        show_err);
182
183The show_err parameter, if non-zero, will cause the function to display an
184appropriate error message of type E_WARNING if the cast fails.
185
186castas can be one of the following values:
187PHP_STREAM_AS_STDIO - a stdio FILE*
188PHP_STREAM_AS_FD - a generic file descriptor
189PHP_STREAM_AS_SOCKETD - a socket descriptor
190
191If you ask a socket stream for a FILE*, the abstraction will use fdopen to
192create it for you.  Be warned that doing so may cause buffered data to be lost
193if you mix ANSI stdio calls on the FILE* with php stream calls on the stream.
194
195If your system has the fopencookie function, php streams can synthesize a
196FILE* on top of any stream, which is useful for SSL sockets, memory based
197streams, data base streams etc. etc.
198
199In situations where this is not desirable, you should query the stream
200to see if it naturally supports FILE *.  You can use this code snippet
201for this purpose:
202
203    if (php_stream_is(stream, PHP_STREAM_IS_STDIO)) {
204        /* can safely cast to FILE* with no adverse side effects */
205    }
206
207You can use:
208
209PHPAPI int php_stream_can_cast(php_stream * stream, int castas)
210
211to find out if a stream can be cast, without actually performing the cast, so
212to check if a stream is a socket you might use:
213
214if (php_stream_can_cast(stream, PHP_STREAM_AS_SOCKETD) == SUCCESS)  {
215    /* it can be a socket */
216}
217
218Please note the difference between php_stream_is and php_stream_can_cast;
219stream_is tells you if the stream is a particular type of stream, whereas
220can_cast tells you if the stream can be forced into the form you request.
221The former doesn't change anything, while the later *might* change some
222state in the stream.
223
224Stream Internals
225================
226
227There are two main structures associated with a stream - the php_stream
228itself, which holds some state information (and possibly a buffer) and a
229php_stream_ops structure, which holds the "virtual method table" for the
230underlying implementation.
231
232The php_streams ops struct consists of pointers to methods that implement
233read, write, close, flush, seek, gets and cast operations.  Of these, an
234implementation need only implement write, read, close and flush.  The gets
235method is intended to be used for streams if there is an underlying method
236that can efficiently behave as fgets.  The ops struct also contains a label
237for the implementation that will be used when printing error messages - the
238stdio implementation has a label of "STDIO" for example.
239
240The idea is that a stream implementation defines a php_stream_ops struct, and
241associates it with a php_stream using php_stream_alloc.
242
243As an example, the php_stream_fopen() function looks like this:
244
245PHPAPI php_stream * php_stream_fopen(const char * filename, const char * mode)
246{
247    FILE * fp = fopen(filename, mode);
248    php_stream * ret;
249    
250    if (fp) {
251        ret = php_stream_alloc(&php_stream_stdio_ops, fp, 0, 0, mode);
252        if (ret)
253            return ret;
254
255        fclose(fp);
256    }
257    return NULL;
258}
259
260php_stream_stdio_ops is a php_stream_ops structure that can be used to handle
261FILE* based streams.
262
263A socket based stream would use code similar to that above to create a stream
264to be passed back to fopen_wrapper (or it's yet to be implemented successor).
265
266The prototype for php_stream_alloc is this:
267
268PHPAPI php_stream * php_stream_alloc(php_stream_ops * ops, void * abstract,
269        size_t bufsize, int persistent, const char * mode)
270
271ops is a pointer to the implementation,
272abstract holds implementation specific data that is relevant to this instance
273of the stream,
274bufsize is the size of the buffer to use - if 0, then buffering at the stream
275level will be disabled (recommended for underlying sources that implement
276their own buffering - such a FILE*),
277persistent controls how the memory is to be allocated - persistently so that
278it lasts across requests, or non-persistently so that it is freed at the end
279of a request (it uses pemalloc),
280mode is the stdio-like mode of operation - php streams places no real meaning
281in the mode parameter, except that it checks for a 'w' in the string when
282attempting to write (this may change).
283
284The mode parameter is passed on to fdopen/fopencookie when the stream is cast
285into a FILE*, so it should be compatible with the mode parameter of fopen().
286
287Writing your own stream implementation
288======================================
289
290!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
291RULE #1: when writing your own streams: make sure you have configured PHP with
292--enable-debug.
293I've taken some great pains to hook into the Zend memory manager to help track
294down allocation problems.  It will also help you spot incorrect use of the
295STREAMS_DC, STREAMS_CC and the semi-private STREAMS_REL_CC macros for function
296definitions.
297!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
298
299RULE #2: Please use the stdio stream as a reference; it will help you
300understand the semantics of the stream operations, and it will always
301be more up to date than these docs :-)
302
303First, you need to figure out what data you need to associate with the
304php_stream.  For example, you might need a pointer to some memory for memory
305based streams, or if you were making a stream to read data from an RDBMS like
306MySQL, you might want to store the connection and rowset handles.
307
308The stream has a field called abstract that you can use to hold this data.
309If you need to store more than a single field of data, define a structure to
310hold it, allocate it (use pemalloc with the persistent flag set
311appropriately), and use the abstract pointer to refer to it.
312
313For structured state you might have this:
314
315struct my_state {
316    MYSQL conn;
317    MYSQL_RES * result;
318};
319
320struct my_state * state = pemalloc(sizeof(struct my_state), persistent);
321
322/* initialize the connection, and run a query, using the fields in state to
323 * hold the results */
324
325state->result = mysql_use_result(&state->conn);
326
327/* now allocate the stream itself */
328stream = php_stream_alloc(&my_ops, state, 0, persistent, "r");
329
330/* now stream->abstract == state */
331
332Once you have that part figured out, you can write your implementation and
333define the your own php_stream_ops struct (we called it my_ops in the above
334example).
335
336For example, for reading from this weird MySQL stream:
337
338static size_t php_mysqlop_read(php_stream * stream, char * buf, size_t count)
339{
340    struct my_state * state = (struct my_state*)stream->abstract;
341
342    if (buf == NULL && count == 0)  {
343        /* in this special case, php_streams is asking if we have reached the
344         * end of file */
345        if (... at end of file ...)
346            return EOF;
347        else
348            return 0;
349    }
350    
351    /* pull out some data from the stream and put it in buf */
352    ... mysql_fetch_row(state->result) ...
353    /* we could do something strange, like format the data as XML here,
354        and place that in the buf, but that brings in some complexities,
355        such as coping with a buffer size too small to hold the data,
356        so I won't even go in to how to do that here */
357}
358
359Implement the other operations - remember that write, read, close and flush
360are all mandatory.  The rest are optional.  Declare your stream ops struct:
361
362php_stream_ops my_ops = {
363    php_mysqlop_write, php_mysqlop_read, php_mysqlop_close,
364    php_mysqlop_flush, NULL, NULL, NULL,
365    "Strange MySQL example"
366}
367
368Thats it!
369
370Take a look at the STDIO implementation in streams.c for more information
371about how these operations work.
372The main thing to remember is that in your close operation you need to release
373and free the resources you allocated for the abstract field.  In the case of
374the example above, you need to use mysql_free_result on the rowset, close the
375connection and then use pefree to dispose of the struct you allocated.
376You may read the stream->persistent field to determine if your struct was
377allocated in persistent mode or not.
378
379vim:tw=78:et
380

README.SUBMITTING_PATCH

1Submitting Enhancements and Patches to PHP
2==========================================
3
4This document describes how to submit an enhancement or patch for PHP.
5It's easy!
6
7You don't need any login accounts or special access to download,
8build, debug and begin submitting PHP, PECL or PEAR code, tests or
9documentation.  Once you've followed this README and had several
10patches accepted, commit privileges are often quickly granted.
11
12An excellent article to read first is:
13http://phpadvent.org/2008/less-whining-more-coding-by-elizabeth-smith
14
15
16Online Forums
17-------------
18There are several IRC channels where PHP developers are often
19available to discuss questions.  They include #php.pecl, #php.doc and
20#pear on the EFNet network and #php-dev-win on FreeNode.
21
22
23PHP Patches
24-----------
25If you are fixing broken functionality in PHP C source code first
26create a bug or identify an existing bug at http://bugs.php.net/.  A
27bug can be used to track the patch progress and prevent your changes
28getting lost in the PHP mail archives.
29
30If your change is large then create a Request For Comment (RFC) page
31on http://wiki.php.net/rfc, discuss it with the extension maintainer,
32and discuss it on the development mail list internals@lists.php.net.
33RFC Wiki accounts can be requested on
34http://wiki.php.net/start?do=register.  PHP extension maintainers can
35be found in the EXTENSIONS file in the PHP source.  Mail list
36subscription is explained on http://www.php.net/mailing-lists.php.
37
38Information on PHP internal C functions is at
39http://www.php.net/internals, though this is considered incomplete.
40Various external resources can be found on the web.  A standard
41printed reference is the book "Extending and Embedding PHP" by Sara
42Golemon.
43
44Attach the patch to the PHP bug and consider sending a notification
45email about the change to internals@lists.php.net.  Also CC the
46extension maintainer.  Explain what has been changed by your patch.
47Test scripts should be included.
48
49Please make the mail subject prefix "[PATCH]".  If attaching a patch,
50ensure it has a file extension of ".txt".  This is because only MIME
51attachments of type 'text/*' are accepted.
52
53
54PHP Documentation Patches
55-------------------------
56If you are fixing incorrect PHP documentation first create a bug or
57identify an existing bug at http://bugs.php.net/.  A bug can be used
58to track the patch progress and prevent your changes getting lost in
59the PHP mail archives.
60
61If your change is large, then first discuss it with the mail list
62phpdoc@lists.php.net.  Subscription is explained on
63http://www.php.net/mailing-lists.php.
64
65Information on contributing to PHP documentation is at
66http://php.net/dochowto and http://wiki.php.net/doc/howto
67
68Attach the patch to the PHP bug and consider sending a notification
69email about the change to phpdoc@lists.php.net.  Explain what has been
70fixed/added/changed by your patch.
71
72Please make the mail subject prefix "[PATCH]".  Include the bug id(s)
73which can be closed by your patch.  If attaching a patch, ensure it
74has a file extension of ".txt".  This is because only MIME attachments
75of type 'text/*' are accepted.
76
77
78PECL Extension Patches: http://pecl.php.net/
79--------------------------------------------
80If you are fixing broken functionality in a PECL extension then create
81a bug or identify an existing bug at http://pecl.php.net/bugs/.  A bug
82can be used to track the patch progress and prevent your changes
83getting lost in the PHP mail archives.
84
85If your change is large then create a Request For Comment (RFC) page
86on http://wiki.php.net/rfc, discuss it with the extension maintainer,
87and discuss it on the development mail list pecl-dev@lists.php.net.
88PECL mail list subscription is explained on
89http://pecl.php.net/support.php.  RFC Wiki accounts can be requested
90on http://wiki.php.net/start?do=register
91
92Information on PHP internal C functions is at
93http://www.php.net/internals, though this is considered incomplete.
94Various external resources can be found on the web.  A standard
95printed reference is the book "Extending and Embedding PHP" by Sara
96Golemon.
97
98Update any open bugs and add a link to the source of your patch.  Send
99the patch or pointer to the bug to pecl-dev@lists.php.net.  Also CC
100the extension maintainer.  Explain what has been changed by your
101patch.  Test scripts should be included.
102
103Please make the mail subject prefix "[PATCH] ...".  Include the patch
104as an attachment with a file extension of ".txt".  This is because
105only MIME attachments of type 'text/*' are accepted.
106
107
108PEAR Package Patches: http://pear.php.net/
109------------------------------------------
110Information on contributing to PEAR is available at
111http://pear.php.net/manual/en/developers-newmaint.php and
112http://pear.php.net/manual/en/guide-developers.php
113
114
115How to create your PHP, PHP Documentation or PECL patch
116-------------------------------------------------------
117PHP and PECL use Subversion (SVN) for revision control.  Read
118http://www.php.net/svn.php for help on using SVN to get and build PHP
119source code.  We recommend using a Sparse Directory checkout described
120in http://wiki.php.net/vcs/svnfaq.  If you are new to SVN, read
121http://svnbook.red-bean.com.
122
123Generally we ask that bug fix patches work on the current stable PHP
124development branches and on "trunk".  New PHP features only need to
125work on "trunk".
126
127Read CODING_STANDARDS before you start working.
128
129After modifying the source see README.TESTING and
130http://qa.php.net/write-test.php for how to test.  Submitting test
131scripts helps us to understand what functionality has changed.  It is
132important for the stability and maintainability of PHP that tests are
133comprehensive.
134
135After testing is finished, create a patch file using the command:
136
137  svn diff > your_patch.txt
138
139For ease of review and later troubleshooting, submit individual
140patches for each bug or feature.
141
142
143Checklist for submitting your PHP or PECL code patch
144----------------------------------------------------
145 - Update SVN source just before running your final 'diff' and
146   before testing.
147 - Add in-line comments and/or have external documentation ready.
148   Use only "/* */" style comments, not "//".
149 - Create test scripts for use with "make test".
150 - Run "make test" to check your patch doesn't break other features.
151 - Rebuild PHP with --enable-debug (which will show some kinds of
152   memory errors) and check the PHP and web server error logs after
153   running your PHP tests.
154 - Rebuild PHP with --enable-maintainer-zts to check your patch
155   compiles on multi-threaded web servers.
156 - Review the patch once more just before submitting it.
157
158
159What happens after submitting your PHP, PHP Documentation or PECL patch
160-----------------------------------------------------------------------
161If your patch is easy to review and obviously has no side-effects,
162it might be committed relatively quickly.
163
164Because PHP is a volunteer-driven effort more complex patches will
165require patience on your side.  If you do not receive feedback in a
166few days, consider resubmitting the patch.  Before doing this think
167about these questions:
168
169 - Did I send the patch to the right mail list?
170 - Did I review the mail list archives to see if these kind of
171   changes had been discussed before?
172 - Did I explain my patch clearly?
173 - Is my patch too hard to review? Because of what factors?
174
175
176What happens when your PHP or PECL patch is applied
177---------------------------------------------------
178Your name will likely be included in the SVN commit log.  If your
179patch affects end users, a brief description and your name might be
180added to the NEWS file.
181
182Thank you for patching PHP!
183

README.TESTING

1[IMPORTANT NOTICE]
2------------------
3 Failed tests usualy indicate a problem with your local system setup
4and not within PHP itself (at least for official PHP release versions).
5You may decide to automaticaly submit a test summary to our QA workflow
6at the end of a test run.
7 Please do *not* submit a failed test as a bug or ask for help on why
8it failed on your system without providing substantial backup information
9on *why* the test failed on your special setup. Thank you :-)
10
11
12[Testing Basics] 
13----------------
14 The easiest way to test your PHP build is to run "make test" from the
15command line after successfully compiling. This will run the complete
16tests for all enabled functionalities and extensions using the PHP
17CLI binary.
18 To execute test scripts, you must build PHP with some SAPI, then you
19type "make test" to execute all or some test scripts saved under
20"tests" directory under source root directory.
21
22Usage:
23make test
24
25 "make test" basically executes "run-tests.php" script
26under the source root (parallel builds will not work). Therefore you
27can execute the script as follows:
28
29TEST_PHP_EXECUTABLE=sapi/cli/php \
30sapi/cli/php [-c /path/to/php.ini] run-tests.php [ext/foo/tests/GLOB]
31
32
33[Which "php" executable "make test" look for]
34---------------------------------------------
35If you are running the run-tests.php script from the command line (as above)
36you must set the TEST_PHP_EXECUTABLE environment variable to explicitly
37select the PHP executable that is to be tested, that is, used to run the test scripts.
38
39If you run the tests using make test, the PHP CLI and CGI executables are 
40automatically set for you. "make test" executes "run-tests.php" script with the CLI binary.  Some
41test scripts such as session must be executed by CGI SAPI. Therefore,
42you must build PHP with CGI SAPI to perform all tests.
43
44NOTE: PHP binary executing "run-tests.php" and php binary used for
45executing test scripts may differ. If you use different PHP binary for
46executing "run-tests.php" script, you may get errors.
47
48
49[Which php.ini is used]
50-----------------------
51 "make test" uses the same php.ini file as it would once installed.
52The tests have been written to be independent of that php.ini file,
53so if you find a test that is affected by a setting, please report
54this, so we can address the issue.
55
56
57[Which test scripts are executed]
58---------------------------------
59 "run-tests.php" ("make test"), without any arguments executes all
60test scripts by extracting all directories named "tests"
61from the source root and any subdirectories below. If there are files,
62which have a "phpt" extension, "run-tests.php" looks at the sections
63in these files, determines whether it should run it, by evaluating
64the 'SKIP' section. If the test is eligible for execution, the 'FILE'
65section is extracted into a ".php" file (with the same name besides 
66the extension) and gets executed.
67When an argument is given or TESTS environment variable is set, the
68GLOB is expanded by the shell and any file with extension "*.phpt" is
69regarded as a test file.
70
71 Tester can easily execute tests selectively with as follows.
72
73Examples:
74./sapi/cli/php run-tests.php ext/mbstring/*
75./sapi/cli/php run-tests.php ext/mbstring/020.phpt
76
77
78[Test results]
79--------------
80 Test results are printed to standard output. If there is a failed test, 
81the "run-tests.php" script saves the result, the expected result and the
82code executed to the test script directory. For example, if 
83ext/myext/tests/myext.phpt fails to pass, the following files are created:
84
85ext/myext/tests/myext.php   - actual test file executed
86ext/myext/tests/myext.log   - log of test execution (L)
87ext/myext/tests/myext.exp   - expected output (E)
88ext/myext/tests/myext.out   - output from test script (O)
89ext/myext/tests/myext.diff  - diff of .out and .exp (D)
90
91 Failed tests are always bugs. Either the test is bugged or not considering
92factors applying to the tester's environment, or there is a bug in PHP.
93If this is a known bug, we strive to provide bug numbers, in either the
94test name or the file name. You can check the status of such a bug, by
95going to: http://bugs.php.net/12345 where 12345 is the bug number.
96For clarity and automated processing, bug numbers are prefixed by a hash
97sign '#' in test names and/or test cases are named bug12345.phpt.
98
99NOTE: The files generated by tests can be selected by setting the
100environment variable TEST_PHP_LOG_FORMAT. For each file you want to be
101generated use the character in brackets as shown above (default is LEOD).
102The php file will be generated always.
103
104NOTE: You can set environment variable TEST_PHP_DETAILED to enable
105detailed test information.
106
107[Automated testing]
108 If you like to keep up to speed, with latest developments and quality
109assurance, setting the environment variable NO_INTERACTION to 1, will not
110prompt the tester for any user input.
111
112Normally, the exit status of "make test" is zero, regardless of the results
113of independent tests. Set the environment variable REPORT_EXIT_STATUS to 1,
114and "make test" will set the exit status ("$?") to non-zero, when an
115individual test has failed.
116
117Example script to be run by cron(1):
118========== qa-test.sh =============
119#!/bin/sh
120
121CO_DIR=$HOME/cvs/php5
122MYMAIL=qa-test@domain.com
123TMPDIR=/var/tmp
124TODAY=`date +"%Y%m%d"`
125
126# Make sure compilation enviroment is correct
127CONFIGURE_OPTS='--disable-all --enable-cli --with-pcre'
128export MAKE=gmake
129export CC=gcc
130
131# Set test environment
132export NO_INTERACTION=1
133export REPORT_EXIT_STATUS=1
134
135cd $CO_DIR
136cvs update . >>$TMPDIR/phpqatest.$TODAY
137./cvsclean ; ./buildconf ; ./configure $CONFIGURE_OPTS ; $MAKE
138$MAKE test >>$TMPDIR/phpqatest.$TODAY 2>&1
139if test $? -gt 0
140then
141        cat $TMPDIR/phpqatest.$TODAY | mail -s"PHP-QA Test Failed for $TODAY" $MYMAIL
142fi
143========== end of qa-test.sh =============
144
145NOTE: the exit status of run-tests.php will be 1 when
146REPORT_EXIT_STATUS is set. The result of "make test" may be higher
147than that. At present, gmake 3.79.1 returns 2, so it is
148advised to test for non-zero, rather then a specific value.
149
150
151[Creating new test files]
152-------------------------
153 Writing test file is very easy if you are used to PHP. 
154See the HOWTO at http://qa.php.net/write-test.php
155
156
157[How to help us]
158----------------
159 If you find bug in PHP, you can submit bug report AND test script 
160for us. You don't have to write complete script, just give us test
161script with following format. Please test the script and make sure
162you write the correct ACTUAL OUTPUT and EXPECTED OUTPUT before you
163submit.
164
165<?php
166/* 
167Bug #12345
168substr() bug. Do not return expected string.
169
170ACTUAL OUTPUT
171XYXA
172
173EXPECTED OUTPUT
174ABCD
175*/
176
177$str = "XYZABCD";
178echo substr($str,3,7);
179
180?>
181

README.TESTING2

1[IMPORTANT NOTICE]
2------------------
3This is an addendum to README.TESTING with additional information 
4specific to server-tests.php.
5
6server-tests.php is backward compatible with tests developed for
7the original run-tests.php script.  server-tests is *not* used by
8'make test'.  server-tests was developed to provide support for
9testing PHP under it's primary environment, HTTP, and can run the
10PHP tests under any of the SAPI modules that are direct executables, 
11or are accessable via HTTP.
12
13[New features]
14----------------
15* Command line interface:
16  You can run 'php server-tests.php -h' to get all the possible options.
17* Configuration file:
18  the -c argument will allow you to use a configuration file.  This is
19  handy if you are testing multiple environments and need various options
20  depending on the environment.
21  see server-tests-config.php for details.
22* CGI Emulation:
23  Will emulate a CGI environment when testing with the cgi sapi executable.
24* HTTP testing:
25  can be configured to run test scripts through an HTTP server running
26  on localhost.  localhost is required since either the web server must
27  alias a directory to the php source directory, or the test scripts
28  must be copied to a directory under the web server 
29  (see config options TEST_WEB_BASE_URL, TEST_BASE_PATH, and TEST_WEB_EXT)
30* New sections supported for test files (see below)
31
32When running tests over http, tests that require ini settings different that what
33the web server runs under will be skipped.  Since the test harness defines a number
34of ini settings by default, the web server may require special configuration to
35make testing work.
36
37[Example Usage]
38----------------
39Some (but not all!) examples of usage:
40
411. run tests from the php source directory
42    php server-tests.php -p /path/to/php-cli
43
442. run tests using cgi emulation
45    php server-tests.php -p /path/to/php-cgi
46
473. run tests over http, copying test files into document root
48    php server-tests.php -w -u http://localhost/test -m /path/to/htdocs/test
49
504. run tests over http, php sources have been aliased in web server
51    php server-tests.php -w -u http://localhost/test
52    
535. run tests using configuration file
54    php server-tests.php -c /path/to/server-tests-config.php
55
566. run tests using configuration file, but overriding some settings:
57   (config file must be first)
58    php server-tests.php -c /path/to/server-tests-config.php -w -t 3 -d /path/to/testdir
59
60NOTE: configuration as described in README.TESTING still works.
61
62[New Test Sections] 
63----------------
64In addition to the traditional test sections 
65(see http://qa.php.net/write-test.php), several new sections are available 
66under server-tests.
67
68--POST--
69This is not a new section, but not multipart posts are supported for testing
70file uploads, or other types of POST data.
71
72--CGI--
73This section takes no value.  It merely provides a simple marker for tests
74that MUST be run as CGI, even if there is no --POST-- or --GET-- sections
75in the test file.
76
77--DESCRIPTION--
78Not used for anything, just a section for documenting the test
79
80--ENV--
81This section get's eval()'d to help build an environment for the 
82execution of the test.  This can be used to change environment
83vars that are used for CGI emulation, or simply to set env vars
84for cli testing.  A full example looks like:
85
86  --ENV--
87  return <<<END
88  PATH_TRANSLATED=$filename
89  PATH_INFO=$scriptname
90  SCRIPT_NAME=$scriptname
91  END;
92
93Some variables are made easily available for use in this section, they
94include:
95  $filename     full native path to file, will become PATH_TRANSLATED
96  $filepath     =dirname($filename)
97  $scriptname   this is what will become SCRIPT_NAME unless you override it
98  $docroot      the equivelant of DOCUMENT_ROOT under Apache
99  $cwd          the directory that the test is being initiated from
100  $this->conf   all server-tests configuration vars
101  $this->env    all environment variables that will get passed to the test
102
103
104--REQUEST--
105This section is also eval'd, and is similar in nature to --ENV--.  However,
106this section is used to build the url used in an HTTP request.  Valid values
107to set in this section would include:
108  SCRIPT_NAME   The inital part of the request url
109  PATH_INFO     The pathinfo part of a request url
110  FRAGMENT      The fragment section of a url (after #)
111  QUERY_STRING  The query part of a url (after ?)
112
113  --REQUEST--
114  return <<<END
115  PATH_INFO=/path/info
116  END;
117
118--HEADERS--
119This section is also eval'd.  It is used to provide additional headers sent
120in an HTTP request, such as content type for multipart posts, cookies, etc.
121
122  --HEADERS--
123  return <<<END
124  Content-Type=multipart/form-data; boundary=---------------------------240723202011929
125  Content-Length=100
126  END;
127
128--EXPECTHEADERS--
129This section can be used to define what headers are required to be
130received back from a request, and is checked in addition to the
131regular expect sections.  For example:
132
133  --EXPECTHEADERS--
134  Status: 404
135
136
137
138

README.UNIX-BUILD-SYSTEM

1PHP Build System V5 Overview
2
3- supports Makefile.ins during transition phase
4- not-really-portable Makefile includes have been eliminated
5- supports separate build directories without VPATH by using
6  explicit rules only
7- does not waste disk-space/CPU-time for building temporary libraries
8  => especially noticeable on slower systems
9- slow recursive make replaced with one global Makefile
10- eases integration of proper dependencies
11- adds PHP_DEFINE(what[, value]) which creates a single include-file
12  per what.  This will allow more fine-grained dependencies.
13- abandoning the "one library per directory" concept
14- improved integration of the CLI
15- several new targets
16  build-modules: builds and copies dynamic modules into modules/
17  install-cli: installs the CLI only, so that the install-sapi
18               target does only what its name says
19- finally abandoned automake (still requires aclocal at this time)
20- changed some configure-time constructs to run at buildconf-time
21- upgraded shtool to 1.5.4
22- removed $(moduledir) (use EXTENSION_DIR)
23
24The Reason For a New System
25
26It became more and more apparent that there is a severe need
27for addressing the portability concerns and improving the chance
28that your build is correct (how often have you been told to
29"make clean"? When this is done, you won't need to anymore).
30
31
32If You Build PHP on a Unix System
33
34
35You, as a user of PHP, will notice no changes.  Of course, the build
36system will be faster, look better and work smarter.
37
38
39
40If You Are Developing PHP
41
42
43
44
45Extension developers:
46
47Makefile.ins are abandoned.  The files which are to be compiled
48are specified in the config.m4 now using the following macro:
49
50PHP_NEW_EXTENSION(foo, foo.c bar.c baz.cpp, $ext_shared)
51
52E.g. this enables the extension foo which consists of three source-code
53modules, two in C and one in C++.  And, depending on the user's wishes,
54the extension will even be built as a dynamic module.
55
56The full syntax:
57
58PHP_NEW_EXTENSION(extname, sources [, shared [,sapi_class[, extra-cflags]]])
59
60Please have a look at acinclude.m4 for the gory details and meanings
61of the other parameters.
62
63And that's basically it for the extension side.
64
65If you previously built sub-libraries for this module, add
66the source-code files here as well.  If you need to specify
67separate include directories, do it this way:
68
69PHP_NEW_EXTENSION(foo, foo.c mylib/bar.c mylib/gregor.c,,,-I@ext_srcdir@/lib)
70
71E.g. this builds the three files which are located relative to the
72extension source directory and compiles all three files with the
73special include directive (@ext_srcdir@ is automatically replaced).
74
75Now, you need to tell the build system that you want to build files
76in a directory called $ext_builddir/lib:
77
78PHP_ADD_BUILD_DIR($ext_builddir/lib)
79
80Make sure to call this after PHP_NEW_EXTENSION, because $ext_builddir
81is only set by the latter.
82
83If you have a complex extension, you might to need add special
84Make rules.  You can do this by calling PHP_ADD_MAKEFILE_FRAGMENT
85in your config.m4 after PHP_NEW_EXTENSION.
86
87This will read a file in the source-dir of your extension called
88Makefile.frag.  In this file, $(builddir) and $(srcdir) will be
89replaced by the values which are correct for your extension
90and which are again determined by the PHP_NEW_EXTENSION macro.
91
92Make sure to prefix *all* relative paths correctly with either
93$(builddir) or $(srcdir).  Because the build system does not
94change the working directory anymore, we must use either
95absolute paths or relative ones to the top build-directory.
96Correct prefixing ensures that.
97
98
99SAPI developers:
100
101Instead of using PHP_SAPI=foo/PHP_BUILD_XYZ, you will need to type
102
103PHP_SELECT_SAPI(name, type, sources.c)
104
105I.e. specify the source-code files as above and also pass the
106information regarding how PHP is supposed to be built (shared
107module, program, etc).
108
109For example for APXS:
110
111PHP_SELECT_SAPI(apache, shared, sapi_apache.c mod_php5.c php_apache.c)
112
113
114
115General info
116
117The foundation for the new system is the flexible handling of
118sources and their contexts.  With the help of macros you
119can define special flags for each source-file, where it is
120located, in which target context it can work, etc.
121
122Have a look at the well documented macros
123PHP_ADD_SOURCES(_X) in acinclude.m4.
124

README.WIN32-BUILD-SYSTEM

1The Win32 Build System.
2
3See http://wiki.php.net/internals/windows/stepbystepbuild 
4
5vim:tw=78:sw=1:ts=1:et
6
7