Name Date Size #Lines LOC

..28-Sep-2023-

TSRM/H05-May-2020-

Zend/H16-Nov-2021-

appveyor/H05-Dec-2019-

build/H03-Nov-2020-

ext/H05-Dec-2019-

main/H16-Nov-2021-

pear/H05-Dec-2019-

sapi/H05-Dec-2019-

scripts/H05-Dec-2019-

tests/H05-Dec-2019-

travis/H03-Aug-2020-

win32/H17-Dec-2019-

.appveyor.ymlH A D05-Dec-20191.4 KiB5242

.editorconfigH A D05-Dec-2019736 3526

.gdbinitH A D05-Dec-201912.7 KiB648591

.gitattributesH A D05-Dec-20198 KiB160159

.gitignoreH A D05-Dec-20193.6 KiB211204

.travis.ymlH A D05-Dec-20191.9 KiB7567

CODING_STANDARDSH A D05-Dec-201912.4 KiB323251

CONTRIBUTING.mdH A D05-Dec-20193.3 KiB7957

CREDITSH A D05-Dec-201993 42

EXTENSIONSH A D05-Dec-201923 KiB512497

INSTALLH A D05-Dec-2019105 42

LICENSEH A D05-Dec-20193.1 KiB6955

Makefile.fragH A D05-Dec-20191.1 KiB2313

Makefile.gcovH A D05-Dec-20192.4 KiB7968

Makefile.globalH A D05-Dec-20196.9 KiB148127

NEWSH A D16-Nov-202192.2 KiB2,6622,116

README.EXT_SKELH A D05-Dec-20191.3 KiB4426

README.GIT-RULESH A D05-Dec-20195.2 KiB14292

README.MAILINGLIST_RULESH A D05-Dec-20193.3 KiB8056

README.NEW-OUTPUT-APIH A D05-Dec-20195 KiB140105

README.PARAMETER_PARSING_APIH A D05-Dec-20197.6 KiB236185

README.REDIST.BINSH A D05-Dec-201924.2 KiB546432

README.RELEASE_PROCESSH A D05-Dec-201915.3 KiB373258

README.SELF-CONTAINED-EXTENSIONSH A D05-Dec-20194.9 KiB167108

README.STREAMSH A D05-Dec-201915 KiB379288

README.SUBMITTING_PATCHH A D05-Dec-20197.9 KiB195149

README.TESTINGH A D05-Dec-201911.4 KiB317252

README.UNIX-BUILD-SYSTEMH A D05-Dec-20194.2 KiB12481

README.WIN32-BUILD-SYSTEMH A D05-Dec-2019114 63

README.input_filterH A D05-Dec-20195.2 KiB183157

README.mdH A D05-Dec-20191.6 KiB4029

UPGRADINGH A D29-Sep-202029.4 KiB775660

UPGRADING.INTERNALSH A D05-Dec-20199.1 KiB209166

acinclude.m4H A D09-Nov-202086.7 KiB3,3283,010

buildconfH A D05-Dec-2019773 4736

buildconf.batH A D30-Jan-2020346 86

config.guessH A D05-Dec-201943.1 KiB1,4771,284

config.subH A D05-Dec-201935.6 KiB1,8341,690

configure.acH A D16-Nov-202146.7 KiB1,7241,450

footerH A D05-Dec-2019136 98

genfilesH A D05-Dec-2019580 2920

headerH A D05-Dec-20191.1 KiB1817

ltmain.shH A D05-Dec-2019195 KiB6,9585,500

makedistH A D27-Apr-20214.1 KiB15896

php.gifH A D05-Dec-20192.5 KiB

php.ini-developmentH A D18-Mar-202069.7 KiB1,9381,604

php.ini-productionH A D18-Mar-202069.9 KiB1,9401,606

php7.spec.inH A D05-Dec-20191.5 KiB4939

run-tests.phpH A D23-Feb-202185.2 KiB3,0322,325

server-tests-config.phpH A D05-Dec-20192 KiB7518

server-tests.phpH A D05-Dec-201951.2 KiB1,6091,256

snapshotH A D05-Dec-2019108 84

stamp-h.inH A D05-Dec-201910 21

vcscleanH A D05-Dec-2019159 85

README.EXT_SKEL

1WHAT IT IS
2
3  It's a tool for automatically creating the basic framework for a PHP extension.
4
5HOW TO USE IT
6
7  Very simple. First, change to the ext/ directory of the PHP sources. Then
8  run the following
9
10   php ext_skel.php --ext extension_name
11
12  and everything you need will be placed in directory ext/extension_name.
13
14  If you don't need to test the existence of any external header files,
15  libraries or functions in them, the extension is ready to be compiled in
16  PHP. To compile the extension, run the following:
17
18    ./buildconf; ./configure --enable-extension_name; make
19
20  The definition of PHP_extension_NAME_VERSION will be present in the
21  php_extension_name.h and injected into the zend_extension_entry definition. This
22  is required by the PECL website for the version string conformity checks
23  against package.xml
24
25SOURCE AND HEADER FILE NAME
26
27  The ext_skel.php script generates 'extension_name.c' and 'php_extension_name.h'
28  as the main source and header files. Keep these names.
29
30  extension functions (User functions) must be named
31
32  extension_name_function()
33
34  When you need to expose extension functions to other extensions, expose functions
35  strictly needed by others. Exposed internal function must be named
36
37  php_extension_name_function()
38
39  See also CODING_STANDARDS.
40
41OTHER OPTIONS
42
43  Run php ext_skel.php --help to see the available options.
44

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      PHP 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-debug switch to avoid memory leaks
42      and the --enable-maintainer-zts switch to ensure your code handles
43      TSRM correctly and doesn't break for those who need that.
44
45Currently we have the following branches in use::
46
47  master    The active development branch.
48
49  PHP-7.2   Is used to release the PHP 7.2.x series. This is a current
50            stable version and is open for bugfixes only.
51
52  PHP-7.1   Is used to release the PHP 7.1.x series. This is a current
53            stable version and is open for bugfixes only.
54
55  PHP-7.0   Is used to release the PHP 7.0.x series. This is an old
56            stable version and is open for security fixes only.
57
58  PHP-5.6   Is used to release the PHP 5.6.x series. This is an old
59            stable version and is open for security fixes only.
60
61  PHP-5.5   This branch is closed.
62
63  PHP-5.4   This branch is closed.
64
65  PHP-5.3   This branch is closed.
66
67  PHP-5.2   This branch is closed.
68
69  PHP-5.1   This branch is closed.
70
71  PHP-4.4   This branch is closed.
72
73  PHP-X.Y.Z These branches are used for the release managers for tagging
74            the releases, hence they are closed to the general public.
75
76The next few rules are more of a technical nature::
77
78   1. All changes should first go to the lowest branch (i.e. 5.6) and then
79      get merged up to all other branches. If a change is not needed for
80      later branches (i.e. fixes for features which were dropped from later
81      branches) an empty merge should be done.
82
83   2. All news updates intended for public viewing, such as new features,
84      bug fixes, improvements, etc., should go into the NEWS file of *any
85      stable release* version with the given change. In other words,
86      news about a bug fix which went into PHP-5.4, PHP-5.5 and master
87      should be noted in both PHP-5.4/NEWS and PHP-5.5/NEWS but
88      not master, which is not a public released version yet.
89
90   3. Do not commit multiple files and dump all messages in one commit. If you
91      modified several unrelated files, commit each group separately and
92      provide a nice commit message for each one. See example below.
93
94   4. Do write your commit message in such a way that it makes sense even
95      without the corresponding diff. One should be able to look at it, and
96      immediately know what was modified. Definitely include the function name
97      in the message as shown below.
98
99   5. In your commit messages, keep each line shorter than 80 characters. And
100      try to align your lines vertically, if they wrap. It looks bad otherwise.
101
102   6. If you modified a function that is callable from PHP, prepend PHP to
103      the function name as shown below.
104
105
106The format of the commit messages is pretty simple.
107
108<max 79 characters short description>\n
109\n
110<long description, 79 chars per line>
111\n
112
113An Example from the git project (commit 2b34e486bc):
114
115pack-objects: Fix compilation with NO_PTHREDS
116
117It looks like commit 99fb6e04 (pack-objects: convert to use
118parse_options(), 2012-02-01) moved the #ifdef NO_PTHREDS around but
119hasn't noticed that the 'arg' variable no longer is available.
120
121If you fix some bugs, you should note the bug ID numbers in your
122commit message. Bug ID should be prefixed by "#" for easier access to
123bug report when developers are browsing CVS via LXR or Bonsai.
124
125Example:
126
127Fixed bug #14016 (pgsql notice handler double free crash bug.)
128
129When you change the NEWS file for a bug fix, then please keep the bugs
130sorted in decreasing order under the fixed version.
131
132You can use OpenGrok (http://lxr.php.net/) and gitweb (http://git.php.net/)
133to look at PHP Git repository in various ways.
134
135
136For further information on the process and further details please refer to
137https://wiki.php.net/vcs/gitworkflow and https://wiki.php.net/vcs/gitfaq
138
139Happy hacking,
140
141PHP Team
142

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.NEW-OUTPUT-API

1API adjustment to the old output control code:
2
3	Everything now resides beneath the php_output namespace,
4	and there's an API call for every output handler op.
5
6	Checking output control layers status:
7		// Using OG()
8		php_output_get_status();
9
10	Starting the default output handler:
11		// php_start_ob_buffer(NULL, 0, 1);
12		php_output_start_default();
13
14	Starting an user handler by zval:
15		// php_start_ob_buffer(zhandler, chunk_size, erase);
16		php_output_start_user(zhandler, chunk_size, flags);
17
18	Starting an internal handler without context:
19		// php_ob_set_internal_handler(my_php_output_handler_func_t, buffer_size, "output handler name", erase);
20		php_output_start_internal(handler_name, handler_name_len, my_php_output_handler_func_t, chunk_size, flags);
21
22	Starting an internal handler with context:
23		// not possible with old API
24		php_output_handler *h;
25		h = php_output_handler_create_internal(handler_name, handler_name_len, my_php_output_handler_context_func_t, chunk_size, flags);
26		php_output_handler_set_context(h, my_context, my_context_dtor);
27		php_output_handler_start(h);
28
29	Testing whether a certain output handler has already been started:
30		// php_ob_handler_used("output handler name");
31		php_output_handler_started(handler_name, handler_name_len);
32
33	Flushing one output buffer:
34		// php_end_ob_buffer(1, 1);
35		php_output_flush();
36
37	Flushing all output buffers:
38		// not possible with old API
39		php_output_flush_all();
40
41	Cleaning one output buffer:
42		// php_ob_end_buffer(0, 1);
43		php_output_clean();
44
45	Cleaning all output buffers:
46		// not possible with old API
47		php_output_clean_all();
48
49	Discarding one output buffer:
50		// php_ob_end_buffer(0, 0);
51		php_output_discard();
52
53	Discarding all output buffers:
54		// php_ob_end_buffers(0);
55		php_output_discard_all();
56
57	Stopping (and dropping) one output buffer:
58		// php_ob_end_buffer(1, 0)
59		php_output_end();
60
61	Stopping (and dropping) all output buffers:
62		// php_ob_end_buffers(1, 0);
63		php_output_end_all();
64
65	Retrieving output buffers contents:
66		// php_ob_get_buffer(zstring);
67		php_output_get_contents(zstring);
68
69	Retrieving output buffers length:
70		// php_ob_get_length(zlength);
71		php_output_get_length(zlength);
72
73	Retrieving output buffering level:
74		// OG(nesting_level);
75		php_output_get_level();
76
77	Issue a warning because of an output handler conflict:
78		// php_ob_init_conflict("to be started handler name", "to be tested if already started handler name");
79		php_output_handler_conflict(new_handler_name, new_handler_name_len, set_handler_name, set_handler_name_len);
80
81	Registering a conflict checking function, which will be checked prior starting the handler:
82		// not possible with old API, unless hardcoding into output.c
83		php_output_handler_conflict_register(handler_name, handler_name_len, my_php_output_handler_conflict_check_t);
84
85	Registering a reverse conflict checking function, which will be checked prior starting the specified foreign handler:
86		// not possible with old API
87		php_output_handler_reverse_conflict_register(foreign_handler_name, foreign_handler_name_len, my_php_output_handler_conflict_check_t);
88
89	Facilitating a context from within an output handler callable with ob_start():
90		// not possible with old API
91		php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_GET_OPAQ, (void *) &custom_ctx_ptr_ptr);
92
93	Disabling of the output handler by itself:
94		//not possible with old API
95		php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_DISABLE, NULL);
96
97	Marking an output handler immutable by itself because of irreversibility of its operation:
98		// not possible with old API
99		php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_IMMUTABLE, NULL);
100
101	Restarting the output handler because of a CLEAN operation:
102		// not possible with old API
103		if (flags & PHP_OUTPUT_HANDLER_CLEAN) { ... }
104
105	Recognizing by the output handler itself if it gets discarded:
106		// not possible with old API
107		if ((flags & PHP_OUTPUT_HANDLER_CLEAN) && (flags & PHP_OUTPUT_HANDLER_FINAL)) { ... }
108
109
110Output handler hooks
111
112	The output handler can change its abilities at runtime. Eg. the gz handler can
113	remove the CLEANABLE and REMOVABLE bits when the first output has passed through it;
114	or handlers implemented in C to be used with ob_start() can contain a non-global
115	context:
116		PHP_OUTPUT_HANDLER_HOOK_GET_OPAQ
117			pass a void*** pointer as second arg to receive the address of a pointer
118			pointer to the opaque field of the output handler context
119		PHP_OUTPUT_HANDLER_HOOK_GET_FLAGS
120			pass a int* pointer as second arg to receive the flags set for the output handler
121		PHP_OUTPUT_HANDLER_HOOK_GET_LEVEL
122			pass a int* pointer as second arg to receive the level of this output handler
123			(starts with 0)
124		PHP_OUTPUT_HANDLER_HOOK_IMMUTABLE
125			the second arg is ignored; marks the output handler to be neither cleanable
126			nor removable
127		PHP_OUTPUT_HANDLER_HOOK_DISABLE
128			the second arg is ignored; marks the output handler as disabled
129
130
131Open questions
132
133	Should the userland API be adjusted and unified?
134
135	Many bits of the manual (and very first implementation) do not comply
136	with the behaviour of the current (to be obsoleted) code, thus should
137	the manual or the behaviour be adjusted?
138
139END
140

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, char *type_spec, ...);
17int zend_parse_parameters_ex(int flags, int num_args, 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
31PHP 5.3 includes a new function (actually implemented as macro):
32
33int zend_parse_parameters_none();
34
35This returns SUCCESS if no argument has been passed to the function,
36FAILURE otherwise.
37
38PHP 5.5 includes a new function:
39
40int zend_parse_parameter(int flags, int arg_num, zval **arg, const char *spec, ...);
41
42This function behaves like zend_parse_parameters_ex() except that instead of
43reading the arguments from the stack, it receives a single zval to convert
44(passed with double indirection). The passed zval may be changed in place as
45part of the conversion process.
46
47See also https://wiki.php.net/rfc/zpp_improv#expose_zend_parse_arg_as_zend_parse_parameter
48
49
50Type specifiers
51---------------
52 The following list shows the type specifier, its meaning and the parameter
53 types that need to be passed by address. All passed parameters are set
54 if the PHP parameter is non optional and untouched if optional and the
55 parameter is not present. The only exception is O where the zend_class_entry*
56 has to be provided on input and is used to verify the PHP parameter is an
57 instance of that class.
58
59 a  - array (zval*)
60 A  - array or object (zval*)
61 b  - boolean (zend_bool)
62 C  - class (zend_class_entry*)
63 d  - double (double)
64 f  - function or array containing php method call info (returned as
65      zend_fcall_info and zend_fcall_info_cache)
66 h  - array (returned as HashTable*)
67 H  - array or HASH_OF(object) (returned as HashTable*)
68 l  - long (zend_long)
69 L  - long, limits out-of-range numbers to LONG_MAX/LONG_MIN (zend_long, ZEND_LONG_MAX/ZEND_LONG_MIN)
70 o  - object of any type (zval*)
71 O  - object of specific type given by class entry (zval*, zend_class_entry)
72 p  - valid path (string without null bytes in the middle) and its length (char*, size_t)
73 P  - valid path (string without null bytes in the middle) as zend_string (zend_string*)
74 r  - resource (zval*)
75 s  - string (with possible null bytes) and its length (char*, size_t)
76 S  - string (with possible null bytes) as zend_string (zend_string*)
77 z  - the actual zval (zval*)
78 *  - variable arguments list (0 or more)
79 +  - variable arguments list (1 or more)
80
81 The following characters also have a meaning in the specifier string:
82    | - indicates that the remaining parameters are optional, they
83        should be initialized to default values by the extension since they
84        will not be touched by the parsing function if they are not
85        passed to it.
86    / - use SEPARATE_ZVAL_IF_NOT_REF() on the parameter it follows
87    ! - the parameter it follows can be of specified type or NULL. If NULL is
88		passed and the output for such type is a pointer, then the output
89		pointer is set to a native NULL pointer.
90		For 'b', 'l' and 'd', an extra argument of type zend_bool* must be
91		passed after the corresponding bool*, zend_long* or double* arguments,
92		respectively. A non-zero value will be written to the zend_bool if a
93		PHP NULL is passed.
94
95
96Note on 64bit compatibility
97---------------------------
98Please note that since version 7 PHP uses zend_long as integer type and
99zend_string with size_t as length, so make sure you pass zend_longs to "l"
100and size_t to strings length (i.e. for "s" you need to pass char * and size_t),
101not the other way round!
102
103Both mistakes might cause memory corruptions and segfaults:
1041)
105  char *str;
106  long str_len; /* XXX THIS IS WRONG!! Use size_t instead. */
107  zend_parse_parameters(ZEND_NUM_ARGS(), "s", &str, &str_len)
108
1092)
110  int num; /* XXX THIS IS WRONG!! Use zend_long instead. */
111  zend_parse_parameters(ZEND_NUM_ARGS(), "l", &num)
112
113If you're in doubt, use check_parameters.php script to the parameters
114and their types (it can be found in ./scripts/dev/ directory of PHP sources):
115
116# php ./scripts/dev/check_parameters.php /path/to/your/sources/
117
118
119Examples
120--------
121/* Gets a long, a string and its length, and a zval */
122zend_long l;
123char *s;
124size_t s_len;
125zval *param;
126if (zend_parse_parameters(ZEND_NUM_ARGS(), "lsz",
127                          &l, &s, &s_len, &param) == FAILURE) {
128    return;
129}
130
131
132/* Gets an object of class specified by my_ce, and an optional double. */
133zval *obj;
134double d = 0.5;
135zend_class_entry *my_ce;
136if (zend_parse_parameters(ZEND_NUM_ARGS(), "O|d",
137                          &obj, my_ce, &d) == FAILURE) {
138    return;
139}
140
141
142/* Gets an object or null, and an array.
143   If null is passed for object, obj will be set to NULL. */
144zval *obj;
145zval *arr;
146if (zend_parse_parameters(ZEND_NUM_ARGS(), "o!a",
147                          &obj, &arr) == FAILURE) {
148    return;
149}
150
151
152/* Gets a separated array which can also be null. */
153zval *arr;
154if (zend_parse_parameters(ZEND_NUM_ARGS(), "a/!",
155                          &arr) == FAILURE) {
156    return;
157}
158
159/* Get either a set of 3 longs or a string. */
160zend_long l1, l2, l3;
161char *s;
162/*
163 * The function expects a pointer to a size_t in this case, not a long
164 * or any other type.  If you specify a type which is larger
165 * than a 'size_t', the upper bits might not be initialized
166 * properly, leading to random crashes on platforms like
167 * Tru64 or Linux/Alpha.
168 */
169size_t length;
170
171if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS(),
172                             "lll", &l1, &l2, &l3) == SUCCESS) {
173    /* manipulate longs */
174} else if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS(),
175                                    "s", &s, &length) == SUCCESS) {
176    /* manipulate string */
177} else {
178    /* output error */
179
180    return;
181}
182
183
184/* Function that accepts only varargs (0 or more) */
185
186int i, num_varargs;
187zval *varargs = NULL;
188
189
190if (zend_parse_parameters(ZEND_NUM_ARGS(), "*", &varargs, &num_varargs) == FAILURE) {
191    return;
192}
193
194for (i = 0; i < num_varargs; i++) {
195    /* do something with varargs[i] */
196}
197
198if (varargs) {
199    efree(varargs);
200}
201
202
203/* Function that accepts a string, followed by varargs (1 or more) */
204
205char *str;
206size_t str_len;
207int i, num_varargs;
208zval *varargs = NULL;
209
210if (zend_parse_parameters(ZEND_NUM_ARGS(), "s+", &str, &str_len, &varargs, &num_varargs) == FAILURE) {
211    return;
212}
213
214for (i = 0; i < num_varargs; i++) {
215    /* do something with varargs[i] */
216}
217
218/* Function that takes an array, followed by varargs, and ending with a long */
219zend_long num;
220zval *array;
221int i, num_varargs;
222zval *varargs = NULL;
223
224if (zend_parse_parameters(ZEND_NUM_ARGS(), "a*l", &array, &varargs, &num_varargs, &num) == FAILURE) {
225    return;
226}
227
228for (i = 0; i < num_varargs; i++) {
229    /* do something with varargs[i] */
230}
231
232/* Function that doesn't accept any arguments */
233if (zend_parse_parameters_none() == FAILURE) {
234    return;
235}
236

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. pcre2lib (ext/pcre)
55. ext/standard crypt
66. ext/standard crypt's blowfish implementation
77. Sqlite/Sqlite3 ext/sqlite3 ext/sqlite
88. ext/standard/rand
99. ext/standard/scanf
1010. ext/standard/strnatcmp.c
1111. ext/standard/uuencode
1212. libxmlrpc ext/xmlrpc
1313. libzip ext/zip
1414. main/snprintf.c
1515. main/strlcat
1616. main/strlcpy
1717. libgd see ext/gd/libgd/COPYING
1818. ext/phar portions of tar implementations
1919. libbcmath (ext/bcmath) see ext/bcmath/libbcmath/COPYING.LIB
20
21
224. pcre2lib (ext/pcre)
23
24PCRE2 LICENCE
25-------------
26
27PCRE2 is a library of functions to support regular expressions whose syntax
28and semantics are as close as possible to those of the Perl 5 language.
29
30Release 10 of PCRE2 is distributed under the terms of the "BSD" licence, as
31specified below, with one exemption for certain binary redistributions. The
32documentation for PCRE2, supplied in the "doc" directory, is distributed under
33the same terms as the software itself. The data in the testdata directory is
34not copyrighted and is in the public domain.
35
36The basic library functions are written in C and are freestanding. Also
37included in the distribution is a just-in-time compiler that can be used to
38optimize pattern matching. This is an optional feature that can be omitted when
39the library is built.
40
41
42THE BASIC LIBRARY FUNCTIONS
43---------------------------
44
45Written by:       Philip Hazel
46Email local part: ph10
47Email domain:     cam.ac.uk
48
49University of Cambridge Computing Service,
50Cambridge, England.
51
52Copyright (c) 1997-2018 University of Cambridge
53All rights reserved.
54
55
56PCRE2 JUST-IN-TIME COMPILATION SUPPORT
57--------------------------------------
58
59Written by:       Zoltan Herczeg
60Email local part: hzmester
61Emain domain:     freemail.hu
62
63Copyright(c) 2010-2018 Zoltan Herczeg
64All rights reserved.
65
66
67STACK-LESS JUST-IN-TIME COMPILER
68--------------------------------
69
70Written by:       Zoltan Herczeg
71Email local part: hzmester
72Emain domain:     freemail.hu
73
74Copyright(c) 2009-2018 Zoltan Herczeg
75All rights reserved.
76
77
78THE "BSD" LICENCE
79-----------------
80
81Redistribution and use in source and binary forms, with or without
82modification, are permitted provided that the following conditions are met:
83
84    * Redistributions of source code must retain the above copyright notices,
85      this list of conditions and the following disclaimer.
86
87    * Redistributions in binary form must reproduce the above copyright
88      notices, this list of conditions and the following disclaimer in the
89      documentation and/or other materials provided with the distribution.
90
91    * Neither the name of the University of Cambridge nor the names of any
92      contributors may be used to endorse or promote products derived from this
93      software without specific prior written permission.
94
95THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
96AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
97IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
98ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
99LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
100CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
101SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
102INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
103CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
104ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
105POSSIBILITY OF SUCH DAMAGE.
106
107
108EXEMPTION FOR BINARY LIBRARY-LIKE PACKAGES
109------------------------------------------
110
111The second condition in the BSD licence (covering binary redistributions) does
112not apply all the way down a chain of software. If binary package A includes
113PCRE2, it must respect the condition, but if package B is software that
114includes package A, the condition is not imposed on package B unless it uses
115PCRE2 independently.
116
117End
118
119
1205. ext/standard crypt
121
122FreeSec: libcrypt for NetBSD
123
124Copyright (c) 1994 David Burren
125All rights reserved.
126
127Redistribution and use in source and binary forms, with or without
128modification, are permitted provided that the following conditions
129are met:
1301. Redistributions of source code must retain the above copyright
131	 notice, this list of conditions and the following disclaimer.
1322. Redistributions in binary form must reproduce the above copyright
133	 notice, this list of conditions and the following disclaimer in the
134	 documentation and/or other materials provided with the distribution.
1353. Neither the name of the author nor the names of other contributors
136	 may be used to endorse or promote products derived from this software
137	 without specific prior written permission.
138
139THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
140ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
141IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
142ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
143FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
144DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
145OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
146HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
147LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
148OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
149SUCH DAMAGE.
150
151
1526. ext/standard crypt's blowfish implementation
153
154The crypt_blowfish homepage is:
155
156http://www.openwall.com/crypt/
157
158This code comes from John the Ripper password cracker, with reentrant
159and crypt(3) interfaces added, but optimizations specific to password
160cracking removed.
161
162Written by Solar Designer <solar at openwall.com> in 1998-2011.
163No copyright is claimed, and the software is hereby placed in the public
164domain. In case this attempt to disclaim copyright and place the software
165in the public domain is deemed null and void, then the software is
166Copyright (c) 1998-2011 Solar Designer and it is hereby released to the
167general public under the following terms:
168
169Redistribution and use in source and binary forms, with or without
170modification, are permitted.
171
172There's ABSOLUTELY NO WARRANTY, express or implied.
173
174It is my intent that you should be able to use this on your system,
175as part of a software package, or anywhere else to improve security,
176ensure compatibility, or for any other purpose. I would appreciate
177it if you give credit where it is due and keep your modifications in
178the public domain as well, but I don't require that in order to let
179you place this code and any modifications you make under a license
180of your choice.
181
182This implementation is mostly compatible with OpenBSD's bcrypt.c (prefix
183"$2a$") by Niels Provos <provos at citi.umich.edu>, and uses some of his
184ideas. The password hashing algorithm was designed by David Mazieres
185<dm at lcs.mit.edu>. For more information on the level of compatibility,
186please refer to the comments in BF_set_key() and to the crypt(3) man page
187included in the crypt_blowfish tarball.
188
189There's a paper on the algorithm that explains its design decisions:
190
191http://www.usenix.org/events/usenix99/provos.html
192
193Some of the tricks in BF_ROUND might be inspired by Eric Young's
194Blowfish library (I can't be sure if I would think of something if I
195hadn't seen his code).
196
197
1987. Sqlite/Sqlite3 ext/sqlite3 ext/sqlite
199
200The author disclaims copyright to this source code.  In place of
201a legal notice, here is a blessing:
202  May you do good and not evil.
203  May you find forgiveness for yourself and forgive others.
204  May you share freely, never taking more than you give.
205
206
2078. ext/standard/rand
208The following php_mt_...() functions are based on a C++ class MTRand by
209Richard J. Wagner. For more information see the web page at
210http://www-personal.engin.umich.edu/~wagnerr/MersenneTwister.html
211
212Mersenne Twister random number generator -- a C++ class MTRand
213Based on code by Makoto Matsumoto, Takuji Nishimura, and Shawn Cokus
214Richard J. Wagner  v1.0  15 May 2003  rjwagner@writeme.com
215
216The Mersenne Twister is an algorithm for generating random numbers.  It
217was designed with consideration of the flaws in various other generators.
218The period, 2^19937-1, and the order of equidistribution, 623 dimensions,
219are far greater.  The generator is also fast; it avoids multiplication and
220division, and it benefits from caches and pipelines.  For more information
221see the inventors' web page at http://www.math.keio.ac.jp/~matumoto/emt.html
222
223Reference
224M. Matsumoto and T. Nishimura, "Mersenne Twister: A 623-Dimensionally
225Equidistributed Uniform Pseudo-Random Number Generator", ACM Transactions on
226Modeling and Computer Simulation, Vol. 8, No. 1, January 1998, pp 3-30.
227
228Copyright (C) 1997 - 2002, Makoto Matsumoto and Takuji Nishimura,
229Copyright (C) 2000 - 2003, Richard J. Wagner
230All rights reserved.
231
232Redistribution and use in source and binary forms, with or without
233modification, are permitted provided that the following conditions
234are met:
235
2361. Redistributions of source code must retain the above copyright
237	 notice, this list of conditions and the following disclaimer.
238
2392. Redistributions in binary form must reproduce the above copyright
240	 notice, this list of conditions and the following disclaimer in the
241	 documentation and/or other materials provided with the distribution.
242
2433. The names of its contributors may not be used to endorse or promote
244	 products derived from this software without specific prior written
245	 permission.
246
247THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
248"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
249LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
250A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
251CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
252EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
253PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
254PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
255LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
256NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
257SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
258
259
2609. ext/standard/scanf
261scanf.c --
262
263This file contains the base code which implements sscanf and by extension
264fscanf. Original code is from TCL8.3.0 and bears the following copyright:
265
266This software is copyrighted by the Regents of the University of
267California, Sun Microsystems, Inc., Scriptics Corporation,
268and other parties.  The following terms apply to all files associated
269with the software unless explicitly disclaimed in individual files.
270
271The authors hereby grant permission to use, copy, modify, distribute,
272and license this software and its documentation for any purpose, provided
273that existing copyright notices are retained in all copies and that this
274notice is included verbatim in any distributions. No written agreement,
275license, or royalty fee is required for any of the authorized uses.
276Modifications to this software may be copyrighted by their authors
277and need not follow the licensing terms described here, provided that
278the new terms are clearly indicated on the first page of each file where
279they apply.
280
281IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY
282FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
283ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY
284DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE
285POSSIBILITY OF SUCH DAMAGE.
286
287THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
288INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,
289FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.  THIS SOFTWARE
290IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE
291NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
292MODIFICATIONS.
293
294GOVERNMENT USE: If you are acquiring this software on behalf of the
295U.S. government, the Government shall have only "Restricted Rights"
296in the software and related documentation as defined in the Federal
297Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2).  If you
298are acquiring the software on behalf of the Department of Defense, the
299software shall be classified as "Commercial Computer Software" and the
300Government shall have only "Restricted Rights" as defined in Clause
301252.227-7013 (c) (1) of DFARs.  Notwithstanding the foregoing, the
302authors grant the U.S. Government and others acting in its behalf
303permission to use and distribute the software in accordance with the
304terms specified in this license.
305
30610. ext/standard/strnatcmp.c
307
308strnatcmp.c -- Perform 'natural order' comparisons of strings in C.
309Copyright (C) 2000 by Martin Pool <mbp@humbug.org.au>
310
311This software is provided 'as-is', without any express or implied
312warranty.  In no event will the authors be held liable for any damages
313arising from the use of this software.
314
315Permission is granted to anyone to use this software for any purpose,
316including commercial applications, and to alter it and redistribute it
317freely, subject to the following restrictions:
318
3191. The origin of this software must not be misrepresented; you must not
320	 claim that you wrote the original software. If you use this software
321	 in a product, an acknowledgment in the product documentation would be
322	 appreciated but is not required.
3232. Altered source versions must be plainly marked as such, and must not be
324	 misrepresented as being the original software.
3253. This notice may not be removed or altered from any source distribution.
326
32711. ext/standard/uuencode
328Portions of this code are based on Berkeley's uuencode/uudecode
329implementation.
330
331Copyright (c) 1983, 1993
332The Regents of the University of California.  All rights reserved.
333
334Redistribution and use in source and binary forms, with or without
335modification, are permitted provided that the following conditions
336are met:
3371. Redistributions of source code must retain the above copyright
338	notice, this list of conditions and the following disclaimer.
3392. Redistributions in binary form must reproduce the above copyright
340	notice, this list of conditions and the following disclaimer in the
341	documentation and/or other materials provided with the distribution.
3423. All advertising materials mentioning features or use of this software
343	must display the following acknowledgement:
344This product includes software developed by the University of
345California, Berkeley and its contributors.
3464. Neither the name of the University nor the names of its contributors
347	may be used to endorse or promote products derived from this software
348	without specific prior written permission.
349
350THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
351ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
352IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
353ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
354FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
355DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
356OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
357HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
358LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
359OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
360SUCH DAMAGE.
361
362
36312. libxmlrpc ext/xmlrpc
364
365Copyright 2000 Epinions, Inc.
366
367Subject to the following 3 conditions, Epinions, Inc.  permits you, free
368of charge, to (a) use, copy, distribute, modify, perform and display this
369software and associated documentation files (the "Software"), and (b)
370permit others to whom the Software is furnished to do so as well.
371
3721) The above copyright notice and this permission notice shall be included
373without modification in all copies or substantial portions of the
374Software.
375
3762) THE SOFTWARE IS PROVIDED "AS IS", WITHOUT ANY WARRANTY OR CONDITION OF
377ANY KIND, EXPRESS, IMPLIED OR STATUTORY, INCLUDING WITHOUT LIMITATION ANY
378IMPLIED WARRANTIES OF ACCURACY, MERCHANTABILITY, FITNESS FOR A PARTICULAR
379PURPOSE OR NONINFRINGEMENT.
380
3813) IN NO EVENT SHALL EPINIONS, INC. BE LIABLE FOR ANY DIRECT, INDIRECT,
382SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES OR LOST PROFITS ARISING OUT
383OF OR IN CONNECTION WITH THE SOFTWARE (HOWEVER ARISING, INCLUDING
384NEGLIGENCE), EVEN IF EPINIONS, INC.  IS AWARE OF THE POSSIBILITY OF SUCH
385DAMAGES.
386
38713. libzip ext/zip
388zip.h -- exported declarations.
389Copyright (C) 1999-2009 Dieter Baron and Thomas Klausner
390
391This file is part of libzip, a library to manipulate ZIP archives.
392The authors can be contacted at <libzip@nih.at>
393
394Redistribution and use in source and binary forms, with or without
395modification, are permitted provided that the following conditions
396are met:
3971. Redistributions of source code must retain the above copyright
398	 notice, this list of conditions and the following disclaimer.
3992. Redistributions in binary form must reproduce the above copyright
400	 notice, this list of conditions and the following disclaimer in
401	 the documentation and/or other materials provided with the
402	 distribution.
4033. The names of the authors may not be used to endorse or promote
404	 products derived from this software without specific prior
405	 written permission.
406
407THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS
408OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
409WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
410ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY
411DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
412DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
413GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
414INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
415IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
416OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
417IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
418
41914. main/snprintf.c
420Copyright (c) 2002, 2006 Todd C. Miller <Todd.Miller@courtesan.com>
421
422Permission to use, copy, modify, and distribute this software for any
423purpose with or without fee is hereby granted, provided that the above
424copyright notice and this permission notice appear in all copies.
425
426THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
427WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
428MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
429ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
430WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
431ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
432OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
433
434Sponsored in part by the Defense Advanced Research Projects
435Agency (DARPA) and Air Force Research Laboratory, Air Force
436Materiel Command, USAF, under agreement number F39502-99-1-0512.
437
438main/spprintf
439Copyright (c) 1995-1998 The Apache Group.  All rights reserved.
440
441Redistribution and use in source and binary forms, with or without
442modification, are permitted provided that the following conditions
443are met:
444
4451. Redistributions of source code must retain the above copyright
446	 notice, this list of conditions and the following disclaimer.
447
4482. Redistributions in binary form must reproduce the above copyright
449	 notice, this list of conditions and the following disclaimer in
450	 the documentation and/or other materials provided with the
451	 distribution.
452
4533. All advertising materials mentioning features or use of this
454	 software must display the following acknowledgment:
455	 "This product includes software developed by the Apache Group
456	 for use in the Apache HTTP server project (http://www.apache.org/)."
457
4584. The names "Apache Server" and "Apache Group" must not be used to
459	 endorse or promote products derived from this software without
460	 prior written permission.
461
4625. Redistributions of any form whatsoever must retain the following
463	 acknowledgment:
464	 "This product includes software developed by the Apache Group
465	 for use in the Apache HTTP server project (http://www.apache.org/)."
466
467THIS SOFTWARE IS PROVIDED BY THE APACHE GROUP ``AS IS'' AND ANY
468EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
469IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
470PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE APACHE GROUP OR
471ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
472SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
473NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
474LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
475HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
476STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
477ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
478OF THE POSSIBILITY OF SUCH DAMAGE.
479====================================================================
480
481This software consists of voluntary contributions made by many
482individuals on behalf of the Apache Group and was originally based
483on public domain software written at the National Center for
484Supercomputing Applications, University of Illinois, Urbana-Champaign.
485For more information on the Apache Group and the Apache HTTP server
486project, please see <http://www.apache.org/>.
487
488This code is based on, and used with the permission of, the
489SIO stdio-replacement strx_* functions by Panos Tsirigotis
490<panos@alumni.cs.colorado.edu> for xinetd.
491
49215. main/strlcat
49316. main/strlcpy
494Copyright (c) 1998 Todd C. Miller <Todd.Miller@courtesan.com>
495All rights reserved.
496
497Redistribution and use in source and binary forms, with or without
498modification, are permitted provided that the following conditions
499are met:
5001. Redistributions of source code must retain the above copyright
501	notice, this list of conditions and the following disclaimer.
5022. Redistributions in binary form must reproduce the above copyright
503	notice, this list of conditions and the following disclaimer in the
504	documentation and/or other materials provided with the distribution.
5053. The name of the author may not be used to endorse or promote products
506	derived from this software without specific prior written permission.
507
508THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
509INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
510AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
511THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
512EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
513PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
514OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
515WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
516OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
517ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
518
51918. ext/phar portions of tar implementations
520
521portions of tar implementations in ext/phar - phar_tar_octal() are based on an
522implementation by Tim Kientzle from libarchive, licensed with this license:
523
524 Copyright (c) 2003-2007 Tim Kientzle
525 All rights reserved.
526
527 Redistribution and use in source and binary forms, with or without
528 modification, are permitted provided that the following conditions
529 are met:
530 1. Redistributions of source code must retain the above copyright
531    notice, this list of conditions and the following disclaimer.
532 2. Redistributions in binary form must reproduce the above copyright
533    notice, this list of conditions and the following disclaimer in the
534    documentation and/or other materials provided with the distribution.
535
536 THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) ``AS IS'' AND ANY EXPRESS OR
537 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
538 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
539 IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT, INDIRECT,
540 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
541 NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
542 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
543 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
544 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
545 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
546

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 the tests on Travis CI are green.
15See: https://travis-ci.org/php/php-src/builds
16It is recommended to do so a couple of days before the packaging day, to
17have enough time to investigate failures, communicate with the authors and
18commit the fixes.
19The RM for the branch is also responsible for keeping the CI green on
20ongoing basis between the releases. Check the CI status for your branch
21periodically and resolve the failures ASAP. See more in:
22https://wiki.php.net/rfc/travis_ci
23
244. Ensure that Windows builds will work before packaging
25
265. Follow all steps to the letter. When unclear ask previous RM's (David/Julien/
27Johannes/Stas/Derick/Ilia) before proceeding. Ideally make sure that for the
28first releases one of the previous RM's is around to answer questions. For the
29steps related to the php/QA/bug websites try to have someone from the webmaster
30team (Bjori) on hand.
31
326. Verify the tags to be extra sure everything was tagged properly.
33
347. Moving extensions from/to PECL requires write access to the destination.
35Most developers should have this.
36
37Moving extensions from php-src to PECL
38- Checkout the pecl directory, most likely you want a sparse-root checkout
39  svn co --depth=empty https://svn.php.net/repository/pecl
40- Create a directory for the extension incl. branch and tag structure,
41  no trunk at this point and commit this to svn
42  cd pecl; mkdir foo foo/tags foo/branches; svn add foo; svn commit
43- Move the extension from php-src to the new location
44  svn mv https://svn.php.net/repository/php/php-src/trunk/ext/foo \
45         https://svn.php.net/repository/pecl/foo/trunk
46
47If the extension is still usable or not dead, in cooperation with the extension
48maintainers if any:
49- create the pecl.php.net/foo package and its content, license, maintainer
50- create the package.xml, commit
51- release the package
52
53For Moving extensions from PECL to php-src the svn mv has to be done the other
54way round.
55
56Rolling a non stable release (alpha/beta/RC)
57--------------------------------------------
58
591. Check windows snapshot builder logs (http://windows.php.net/downloads/snaps/ the last revision)
60
612. Check the tests at https://travis-ci.org/php/php-src/builds
62
633. run the "scripts/dev/credits" script in php-src and commit the changes in the
64credits files in ext/standard.
65
664. Checkout the release branch for this release (e.g., PHP-5.4.2) from the main branch.
67
685. Bump the version numbers in ``main/php_version.h``, ``configure.ac`` and possibly ``NEWS``.
69Do not use abbreviations for alpha and beta. Do not use dashes, you should
70``#define PHP_VERSION "5.4.22RC1"`` and not ``#define PHP_VERSION "5.4.22-RC1"``
71
726. Compile and make test, with and without ZTS, using the right Bison version
73(for example, for 5.5, Bison 2.4.1 is used)
74
757. Check ./sapi/cli/php -v output for version matching.
76
778. If all is right, commit the changes to the release branch with ``git commit -a``.
78
799. Tag the repository release branch with the version, e.g.:
80``git tag -u YOURKEYID php-5.4.2RC2``
81
8210. Bump the version numbers in ``main/php_version.h``, ``configure.ac`` and ``NEWS``
83in the *main* branch (PHP-5.4 for example) to prepare for the **next** version.
84F.e. if the RC is "5.4.1RC1" then the new one should be "5.4.2-dev" - regardless if we get
85a new RC or not. This is to make sure ``version_compare()`` can correctly work.
86Commit the changes to the main branch.
87
8811. Push the changes to the main repo, the tag, the main branch and the release branch :
89``git push --tags origin HEAD``
90``git push origin {main branch}``
91``git push origin {release branch}``
92
9312. run: ``PHPROOT=. ./makedist 5.4.2RC2``, this will export the tree, create configure
94and build three tarballs (gz, bz2 and xz).
95
9613. run ``scripts/dev/gen_verify_stub <version> [identity]``, this will sign the tarballs
97and output verification information to be included in announcement email
98
9914. Copy those tarballs (scp, rsync) to downloads.php.net, in your homedir there should be a
100directory "public_html/". Copy them into there, so that the system can generate
101MD5 sums. If you do not have this directory, create it.
102
10315. Now the RC can be found on http://downloads.php.net/~yourname,
104f.e. http://downloads.php.net/~derick/
105
10616. Once the release has been tagged, contact the release-managers@ distribution list
107so that Windows binaries can be created.  Once those are made, they can be found at
108http://windows.php.net/download
109
110Getting the non stable release (alpha/beta/RC) announced
111--------------------------------------------------------
112
1131. Update ``qa.git/include/release-qa.php`` with the appropriate information.
114   See the documentation within release-qa.php for more information, but all releases
115   and RCs are configured here. Only $QA_RELEASES needs to be edited.
116
117   Example: When rolling an RC, set the 'rc' with appropriate information for the
118   given version.
119
120   Note: Remember to update the MD5 and sha256 checksum information.
121
1222. Update ``web/php.git/include/version.inc`` (x=major version number)
123
124 a. ``$PHP_x_RC`` = "5.4.0RC1"  (should be set to "false" before)
125
126 b. ``$PHP_x_RC_DATE`` = "06 September 2007"
127
1283. Add a short notice to phpweb stating that there is a new release, and
129highlight the major important things (security fixes) and when it is important
130to upgrade.
131
132 a. Call php bin/createNewsEntry in your local phpweb checkout
133    Use category "releases" for all stable releases.
134    Use category "frontpage" for X.Y.0 non-stable releases only (news only).
135
136 b. Add the content for the news entry. Be sure to include the text:
137    "THIS IS A DEVELOPMENT PREVIEW - DO NOT USE IT IN PRODUCTION!"
138
1394. Commit and push changes to qa and web
140
141*Wait for web and qa sites to update with new information before sending announce*
142
1435. Send **separate** emails **To** ``internals@lists.php.net`` and ``php-general@lists.php.net``
144lists pointing out "the location of the release" and "the possible release date of
145either the next RC, or the final release". Include in this information the verification
146information output by ``gen_verify_stub``.
147
1486. Send **separate** emails (see example here http://news.php.net/php.pear.qa/5201) **To**
149``php-qa@lists.php.net`` and ``primary-qa-tester@lists.php.net``.
150These emails are to notify the selected projects about a new release so that they
151can make sure their projects keep working. Make sure that you have been setup
152as a moderator for ``primary-qa-tester@lists.php.net`` by having someone (Hannes, Dan,
153Derick) run the following commands for you:
154
155``ssh lists.php.net``
156
157``sudo -u ezmlm ezmlm-sub ~ezmlm/primary-qa-tester/mod moderator-email-address``
158
159Rolling a stable release
160------------------------
161
1621. Checkout your release branch, you should have created when releasing previous RC
163and bump the version numbers in ``main/php_version.h``, ``configure.ac`` and possibly ``NEWS``.
164
1652. If a CVE commit needs to be merged to the release, then have it committed to
166the base branches and merged upwards as usual (f.e commit the CVE fix to 5.3,
167merge to 5.4, 5.5 etc...). Then you can cherry-pick it in your release branch.
168Don't forget to update NEWS manually in an extra commit then.
169
1703. Commit those changes. Ensure the tests at https://travis-ci.org/php/php-src/builds are
171still passing.
172
1734. run the "scripts/dev/credits" script in php-src and commit the changes in the
174credits files in ext/standard.
175
1765. Compile and make test, with and without ZTS, using the right Bison version
177(for example, for 5.5, Bison 2.4.1 is used)
178
1796. Check ./sapi/cli/php -v output for version matching.
180
1817. tag the repository with the version f.e. "``git tag -u YOURKEYID -s php-5.4.1``"
182
1838. Push the tag f.e. "``git push origin php-5.4.1``"
184
1859. run: ``PHPROOT=. ./makedist php 5.4.1``, this will export the tag, create configure
186and build three tarballs (gz, bz2 and xz).
187   Check if the pear files are updated (phar).
188   On some systems the behavior of GNU tar can default to produce POSIX compliant archives
189with PAX headers. As not every application is compatible with that format, creation of
190archives with PAX headers should be avoided. When packaging on such a system, the GNU tar
191can be influenced by defining the environment variable TAR_OPTIONS='--format=gnu'.
192
19310. Generate the GPG signature files for the archives.
194  ``gpg -u YOUREMAIL --armor --detach-sign php-X.Y.Z.tar.xxx``
195
19611. Commit and push all the tarballs and signature files to web/php-distributions.git,
197    then update the git submodule reference in web/php.git:
198    ``git submodule init;
199    git submodule update;
200    cd distributions;
201    git fetch;
202    git pull --rebase origin master;
203    cd ..;
204    git commit distributions;
205    git push;``
206This is to fetch the last commit id from php-distributions.git and commit this
207last commit id to web/php.git, then, mirrors will now sync
208
20912. Once the release has been tagged, contact release managers, windows builders, and package maintainers
210so that they can build releases. Do not send this announcement to any public lists.
211
212Getting the stable release announced
213------------------------------------
214
2151. Update phpweb/include/releases.inc with the old release info
216  (updates the download archives)
217
218 a. You can run ``php bin/bumpRelease 5`` if you are making a release for the
219    highest branch, otherwise you have to do this manually, see point 1.b
220
221 b. In case multiple PHP minor versions are in active development you have
222    to manually copy the old information to include/releases.inc
223
2242. Edit ``phpweb/include/version.inc`` and change (X=major release number):
225
226 a. ``$PHP_X_VERSION`` to the correct version
227
228 b. ``$PHP_X_DATE`` to the release date
229
230 c. ``$PHP_X_MD5`` array and update all the md5 sums
231
232 d. ``$PHP_X_SHA256`` array and update all the SHA256 sums
233
234 e. set ``$PHP_X_RC`` to false!
235
236 f. Make sure there are no outdated "notes" or edited "date" keys in the
237 ``$RELEASES[X][$PHP_X_VERSION]["source"]`` array
238
239 g. if the windows builds aren't ready yet prefix the "windows" key with a dot (".windows")
240
2413. Create the release file (releases/x_y_z.php)
242   Usually we use the same content as for point 6, but included in php template
243   instead of the release xml.
244
2454. Update php-qa/include/release-qa.php and add the next version as an QARELEASE
246   (prepare for next RC)
247
2485. Update the ChangeLog file for the given major version
249f.e. ``ChangeLog-5.php`` from the NEWS file
250
251 a. go over the list and put every element on one line
252
253 b. check for &, < and > and escape them if necessary
254
255 c. remove all the names at the ends of lines
256
257 d. for marking up, you can do the following (with VI):
258
259  I. ``s/^- /<li>/``
260
261  II. ``s/$/<\/li>/``
262
263  III. ``s/Fixed bug #\([0-9]\+\)/<?php bugfix(\1); ?>/``
264
265  IV. ``s/Fixed PECL bug #\([0-9]\+\)/<?php peclbugfix(\1); ?>/``
266
267  V. ``s/FR #\([0-9]\+\)/FR <?php bugl(\1); ?>/``
268
269  e. You may want to try php-web/bin/news2html to automate this task
270
2716. Add a short notice to phpweb stating that there is a new release, and
272highlight the major important things (security fixes) and when it is important
273to upgrade.
274
275 a. Call php bin/createNewsEntry in your local phpweb checkout
276
277 b. Add the content for the news entry
278
2797. **Check mirrors have been synced before announcing or pushing news**
280  Try, f.e. http://www.php.net/get/php-5.5.1.tar.bz2/from/a/mirror
281  Try several mirrors, mirrors may update slowly (may take an hour)
282
2838. Commit all the changes to their respective git repos
284
2859. Please note down the sha256 and the PGP signature (.asc). These *must* be
286   included in the release mail.
28710. Wait an hour or two, then send a mail to php-announce@lists.php.net,
288php-general@lists.php.net and internals@lists.php.net with a text similar to
289http://news.php.net/php.internals/17222.
290Please make sure that the mail to php-announce@ is its own completely separate email.
291This is to make sure that replies to the announcement on php-general@ or internals@
292will not accidentally hit the php-announce@ mailinglist.
293
294Re-releasing the same version (or -pl)
295--------------------------------------
296
2971. Commit the new binaries to ``phpweb/distributions/``
298
2992. Edit ``phpweb/include/version.inc`` and change (X=major release number):
300
301 a. If only releasing for one OS, make sure you edit only those variables
302
303 b. ``$PHP_X_VERSION`` to the correct version
304
305 c. ``$PHP_X_DATE`` to the release date
306
307 d. ``$PHP_X_MD5`` array and update all the md5 sums
308
309 e. ``$PHP_X_SHA256`` array and update all the SHA256 sums
310
311 f. Make sure there are no outdated "notes" or edited "date" keys in the
312 ``$RELEASES[X][$PHP_X_VERSION]["source"]`` array
313
3143. Add a short notice to phpweb stating that there is a new release, and
315highlight the major important things (security fixes) and when it is important
316to upgrade.
317
318 a. Call php bin/createNewsEntry in your local phpweb checkout
319
320 b. Add the content for the news entry
321
3224. Commit all the changes (``include/version.inc``, ``archive/archive.xml``,
323``archive/entries/YYYY-MM-DD-N.xml``)
324
3255. Wait an hour or two, then send a mail to php-announce@lists.php.net,
326php-general@lists.php.net and internals@lists.php.net with a text similar to
327the news entry.
328Please make sure that the mail to php-announce@ is its own completely separate email.
329This is to make sure that replies to the announcement on php-general@ or internals@
330will not accidentally hit the php-announce@ mailinglist.
331
332Forking a new release branch
333----------------------------
334
3351. One week prior to cutting X.Y.0beta1, warn internals@ that your version's branch
336   is about to be cut, and that PHP-X.Y will be moving into feature freeze.
337   Try to be specific about when the branch will be cut.
338      Example: http://news.php.net/php.internals/99864
339
3402. Just prior to cutting X.Y.0beta1, create the new branch locally.
341   Add a commit on master after the branch point clearing the NEWS file, and updating
342     main/php_versions.h and Zend/zend.h to update versions.
343     Example: https://github.com/php/php-src/commit/5230541ef59e0637d5522293a7d099bf18ce6af3
344   Push the new branch and the commit just added to master.
345
3463. Immediately notify internals@ of the branch cut and advise the new merging order:
347     Example: http://news.php.net/php.internals/99903
348
3494. Update php-web:git.php and wiki.php.net/vcs/gitworkflow to reflect the new branch:
350     Example: https://github.com/php/web-php/commit/74bcad4c770d95f21b7fbeeedbd76d943bb83f23
351
3525. Notify nlopess@ to add PHP_X_Y tag to gcov.php.net
353
354New Release Manager Checklist
355-----------------------------
356
3571. Email systems@ to get setup for access to downloads.php.net and to be added to the
358   release-managers@ distribution list.
359
3602. Create a GPG key for your @php.net address and publish it by editing `include/gpg-keys.inc`
361   in the `web-php` repository, adding the output of `gpg --fingerprint "$USER@php.net"`. Let
362   one or more of the previous RMs sign your key. Publish your public key to pgp.mit.edu with:
363   `gpg --keyserver pgp.mit.edu --send-keys $KEYID`
364
3653. Request karma to edit main/php_version.h. Possibly karma for other restricted parts of
366   php-src might come in question.
367
3684. Request karma for web/qa.git and web/php.git for publishing release announcements.
369
3705. Request moderation access to announce@php.net and primary-qa-tester@lists.php.net lists, to
371   be able to moderate your release announcements. All the announcements should be sent from
372   the @php.net alias.
373

README.SELF-CONTAINED-EXTENSIONS

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

README.STREAMS

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

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 or PECL 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 and #php.doc
20on the EFNet network and #winphp-dev 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://php.net/mailing-lists.php.
37
38Information on PHP internal C functions is at
39http://php.net/internals, though this is considered incomplete.
40Various external resources can be found on the web.  See
41https://wiki.php.net/internals for some references.  A standard
42printed reference is the book "Extending and Embedding PHP" by Sara
43Golemon.
44
45The preferred way to propose PHP patch is sending pull request from
46GitHub: https://github.com/php/php-src
47
48Fork the official PHP repository and send a pull request. A
49notification will be sent to the pull request mailing list. Sending a
50note to PHP Internals list (internals@lists.php.net) may help getting
51more feedback and quicker turnaround.  You can also add pull requests
52to bug reports at http://bugs.php.net/.
53
54If you are not using GitHub, attach your patch to a PHP bug and
55consider sending a notification email about the change to
56internals@lists.php.net.  If the bug is for an extension, also CC the
57extension maintainer.  Explain what has been changed by your patch.
58Test scripts should be included.
59
60Please make the mail subject prefix "[PATCH]".  If attaching a patch,
61ensure it has a file extension of ".txt".  This is because only MIME
62attachments of type 'text/*' are accepted.
63
64
65
66PHP Documentation Patches
67-------------------------
68If you are fixing incorrect PHP documentation first create a bug or
69identify an existing bug at http://bugs.php.net/.  A bug can be used
70to track the patch progress and prevent your changes getting lost in
71the PHP mail archives.
72
73If your change is large, then first discuss it with the mail list
74phpdoc@lists.php.net.  Subscription is explained on
75http://php.net/mailing-lists.php.
76
77Information on contributing to PHP documentation is at
78http://php.net/dochowto and http://wiki.php.net/doc/howto
79
80Attach the patch to the PHP bug and consider sending a notification
81email about the change to phpdoc@lists.php.net.  Explain what has been
82fixed/added/changed by your patch.
83
84Please make the mail subject prefix "[PATCH]".  Include the bug id(s)
85which can be closed by your patch.  If attaching a patch, ensure it
86has a file extension of ".txt".  This is because only MIME attachments
87of type 'text/*' are accepted.
88
89
90PECL Extension Patches: http://pecl.php.net/
91--------------------------------------------
92If you are fixing broken functionality in a PECL extension then create
93a bug or identify an existing bug at http://bugs.php.net/.  A bug
94can be used to track the patch progress and prevent your changes
95getting lost in the PHP mail archives.
96
97If your change is large then create a Request For Comment (RFC) page
98on http://wiki.php.net/rfc, discuss it with the extension maintainer,
99and discuss it on the development mail list pecl-dev@lists.php.net.
100PECL mail list subscription is explained on
101http://pecl.php.net/support.php.  RFC Wiki accounts can be requested
102on http://wiki.php.net/start?do=register
103
104Information on PHP internal C functions is at
105http://www.php.net/internals, though this is considered incomplete.
106Various external resources can be found on the web.  A standard
107printed reference is the book "Extending and Embedding PHP" by Sara
108Golemon.
109
110Update any open bugs and add a link to the source of your patch.  Send
111the patch or pointer to the bug to pecl-dev@lists.php.net.  Also CC
112the extension maintainer.  Explain what has been changed by your
113patch.  Test scripts should be included.
114
115Please make the mail subject prefix "[PATCH] ...".  Include the patch
116as an attachment with a file extension of ".txt".  This is because
117only MIME attachments of type 'text/*' are accepted.
118
119
120PEAR Package Patches: http://pear.php.net/
121------------------------------------------
122Information on contributing to PEAR is available at
123http://pear.php.net/manual/en/developers-newmaint.php and
124http://pear.php.net/manual/en/guide-developers.php
125
126
127How to create your PHP, PHP Documentation or PECL patch
128-------------------------------------------------------
129PHP and most PECL packages use Git for revision control. Some PECL
130packages use Subversion (SVN) Read http://www.php.net/git.php for help
131on using Git to get and build PHP source code.  We recommend to look
132at our workflow on https://wiki.php.net/vcs/gitworkflow and our FAQ
133https://wiki.php.net/vcs/gitfaq.
134
135Generally we ask that bug fix patches work on the current stable PHP
136development branches and on "master".  New PHP features only need to
137work on "master".
138
139Read CODING_STANDARDS before you start working.
140
141After modifying the source see README.TESTING and
142http://qa.php.net/write-test.php for how to test.  Submitting test
143scripts helps us to understand what functionality has changed.  It is
144important for the stability and maintainability of PHP that tests are
145comprehensive.
146
147After testing is finished, create a patch file using the command:
148
149  git diff > your_patch.txt
150
151For ease of review and later troubleshooting, submit individual
152patches for each bug or feature.
153
154
155Checklist for submitting your PHP or PECL code patch
156----------------------------------------------------
157 - Update git source just before running your final 'diff' and
158   before testing.
159 - Add in-line comments and/or have external documentation ready.
160   Use only "/* */" style comments, not "//".
161 - Create test scripts for use with "make test".
162 - Run "make test" to check your patch doesn't break other features.
163 - Rebuild PHP with --enable-debug (which will show some kinds of
164   memory errors) and check the PHP and web server error logs after
165   running your PHP tests.
166 - Rebuild PHP with --enable-maintainer-zts to check your patch
167   compiles on multi-threaded web servers.
168 - Review the patch once more just before submitting it.
169
170
171What happens after submitting your PHP, PHP Documentation or PECL patch
172-----------------------------------------------------------------------
173If your patch is easy to review and obviously has no side-effects,
174it might be committed relatively quickly.
175
176Because PHP is a volunteer-driven effort more complex patches will
177require patience on your side.  If you do not receive feedback in a
178few days, consider resubmitting the patch.  Before doing this think
179about these questions:
180
181 - Did I send the patch to the right mail list?
182 - Did I review the mail list archives to see if these kind of
183   changes had been discussed before?
184 - Did I explain my patch clearly?
185 - Is my patch too hard to review? Because of what factors?
186
187
188What happens when your PHP or PECL patch is applied
189---------------------------------------------------
190Your name will likely be included in the Git commit log.  If your
191patch affects end users, a brief description and your name might be
192added to the NEWS file.
193
194Thank you for patching PHP!
195

README.TESTING

1[IMPORTANT NOTICE]
2------------------
3 Failed tests usually indicate a problem with your local system setup
4and not within PHP itself (at least for official PHP release versions).
5You may decide to automatically 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 'SKIPIF' 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--------------
109 If you like to keep up to speed, with latest developments and quality
110assurance, setting the environment variable NO_INTERACTION to 1, will not
111prompt the tester for any user input.
112
113Normally, the exit status of "make test" is zero, regardless of the results
114of independent tests. Set the environment variable REPORT_EXIT_STATUS to 1,
115and "make test" will set the exit status ("$?") to non-zero, when an
116individual test has failed.
117
118Example script to be run by cron(1):
119========== qa-test.sh =============
120#!/bin/sh
121
122CO_DIR=$HOME/cvs/php7
123MYMAIL=qa-test@domain.com
124TMPDIR=/var/tmp
125TODAY=`date +"%Y%m%d"`
126
127# Make sure compilation environment is correct
128CONFIGURE_OPTS='--disable-all --enable-cli --with-pcre'
129export MAKE=gmake
130export CC=gcc
131
132# Set test environment
133export NO_INTERACTION=1
134export REPORT_EXIT_STATUS=1
135
136cd $CO_DIR
137cvs update . >>$TMPDIR/phpqatest.$TODAY
138./cvsclean ; ./buildconf ; ./configure $CONFIGURE_OPTS ; $MAKE
139$MAKE test >>$TMPDIR/phpqatest.$TODAY 2>&1
140if test $? -gt 0
141then
142        cat $TMPDIR/phpqatest.$TODAY | mail -s"PHP-QA Test Failed for $TODAY" $MYMAIL
143fi
144========== end of qa-test.sh =============
145
146NOTE: The exit status of run-tests.php will be 1 when
147REPORT_EXIT_STATUS is set. The result of "make test" may be higher
148than that. At present, gmake 3.79.1 returns 2, so it is
149advised to test for non-zero, rather then a specific value.
150
151
152[Creating new test files]
153-------------------------
154 Writing test file is very easy if you are used to PHP.
155See the HOWTO at http://qa.php.net/write-test.php
156
157
158[How to help us]
159----------------
160 If you find bug in PHP, you can submit bug report AND test script
161for us. You don't have to write complete script, just give us test
162script with following format. Please test the script and make sure
163you write the correct ACTUAL OUTPUT and EXPECTED OUTPUT before you
164submit.
165
166<?php
167/*
168Bug #12345
169substr() bug. Do not return expected string.
170
171ACTUAL OUTPUT
172XYXA
173
174EXPECTED OUTPUT
175ABCD
176*/
177
178$str = "XYZABCD";
179echo substr($str,3,7);
180
181?>
182
183[IMPORTANT NOTICE]
184------------------
185This is an addendum to README.TESTING with additional information
186specific to server-tests.php.
187
188server-tests.php is backward compatible with tests developed for
189the original run-tests.php script.  server-tests is *not* used by
190'make test'.  server-tests was developed to provide support for
191testing PHP under it's primary environment, HTTP, and can run the
192PHP tests under any of the SAPI modules that are direct executables,
193or are accessible via HTTP.
194
195[New features]
196----------------
197* Command line interface:
198  You can run 'php server-tests.php -h' to get all the possible options.
199* Configuration file:
200  the -c argument will allow you to use a configuration file.  This is
201  handy if you are testing multiple environments and need various options
202  depending on the environment.
203  see server-tests-config.php for details.
204* CGI Emulation:
205  Will emulate a CGI environment when testing with the cgi sapi executable.
206* HTTP testing:
207  can be configured to run test scripts through an HTTP server running
208  on localhost.  localhost is required since either the web server must
209  alias a directory to the php source directory, or the test scripts
210  must be copied to a directory under the web server
211  (see config options TEST_WEB_BASE_URL, TEST_BASE_PATH, and TEST_WEB_EXT)
212* New sections supported for test files (see below)
213
214When running tests over http, tests that require ini settings different that what
215the web server runs under will be skipped.  Since the test harness defines a number
216of ini settings by default, the web server may require special configuration to
217make testing work.
218
219[Example Usage]
220----------------
221Some (but not all!) examples of usage:
222
2231. run tests from the php source directory
224    php server-tests.php -p /path/to/php-cli
225
2262. run tests using cgi emulation
227    php server-tests.php -p /path/to/php-cgi
228
2293. run tests over http, copying test files into document root
230    php server-tests.php -w -u http://localhost/test -m /path/to/htdocs/test
231
2324. run tests over http, php sources have been aliased in web server
233    php server-tests.php -w -u http://localhost/test
234
2355. run tests using configuration file
236    php server-tests.php -c /path/to/server-tests-config.php
237
2386. run tests using configuration file, but overriding some settings:
239   (config file must be first)
240    php server-tests.php -c /path/to/server-tests-config.php -w -t 3 -d /path/to/testdir
241
242NOTE: configuration as described in README.TESTING still works.
243
244[New Test Sections]
245----------------
246In addition to the traditional test sections
247(see http://qa.php.net/write-test.php), several new sections are available
248under server-tests.
249
250--POST--
251This is not a new section, but not multipart posts are supported for testing
252file uploads, or other types of POST data.
253
254--CGI--
255This section takes no value.  It merely provides a simple marker for tests
256that MUST be run as CGI, even if there is no --POST-- or --GET-- sections
257in the test file.
258
259--DESCRIPTION--
260Not used for anything, just a section for documenting the test
261
262--ENV--
263This section get's eval()'d to help build an environment for the
264execution of the test.  This can be used to change environment
265vars that are used for CGI emulation, or simply to set env vars
266for cli testing.  A full example looks like:
267
268  --ENV--
269  return <<<END
270  PATH_TRANSLATED=$filename
271  PATH_INFO=$scriptname
272  SCRIPT_NAME=$scriptname
273  END;
274
275Some variables are made easily available for use in this section, they
276include:
277  $filename     full native path to file, will become PATH_TRANSLATED
278  $filepath     =dirname($filename)
279  $scriptname   this is what will become SCRIPT_NAME unless you override it
280  $docroot      the equivalent of DOCUMENT_ROOT under Apache
281  $cwd          the directory that the test is being initiated from
282  $this->conf   all server-tests configuration vars
283  $this->env    all environment variables that will get passed to the test
284
285
286--REQUEST--
287This section is also eval'd, and is similar in nature to --ENV--.  However,
288this section is used to build the url used in an HTTP request.  Valid values
289to set in this section would include:
290  SCRIPT_NAME   The initial part of the request url
291  PATH_INFO     The pathinfo part of a request url
292  FRAGMENT      The fragment section of a url (after #)
293  QUERY_STRING  The query part of a url (after ?)
294
295  --REQUEST--
296  return <<<END
297  PATH_INFO=/path/info
298  END;
299
300--HEADERS--
301This section is also eval'd.  It is used to provide additional headers sent
302in an HTTP request, such as content type for multipart posts, cookies, etc.
303
304  --HEADERS--
305  return <<<END
306  Content-Type=multipart/form-data; boundary=---------------------------240723202011929
307  Content-Length=100
308  END;
309
310--EXPECTHEADERS--
311This section can be used to define what headers are required to be
312received back from a request, and is checked in addition to the
313regular expect sections.  For example:
314
315  --EXPECTHEADERS--
316  Status: 404
317

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_php7.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 https://wiki.php.net/internals/windows/stepbystepbuild_sdk_2
4
5vim:tw=78:sw=1:ts=1:et
6

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.
23
24ZEND_BEGIN_MODULE_GLOBALS(my_input_filter)
25        zval *post_array;
26        zval *get_array;
27        zval *cookie_array;
28ZEND_END_MODULE_GLOBALS(my_input_filter)
29
30#ifdef ZTS
31#define IF_G(v) TSRMG(my_input_filter_globals_id, zend_my_input_filter_globals *, v)
32#else
33#define IF_G(v) (my_input_filter_globals.v)
34#endif
35
36ZEND_DECLARE_MODULE_GLOBALS(my_input_filter)
37
38zend_function_entry my_input_filter_functions[] = {
39    PHP_FE(my_get_raw,   NULL)
40    {NULL, NULL, NULL}
41};
42
43zend_module_entry my_input_filter_module_entry = {
44    STANDARD_MODULE_HEADER,
45    "my_input_filter",
46    my_input_filter_functions,
47    PHP_MINIT(my_input_filter),
48    PHP_MSHUTDOWN(my_input_filter),
49    NULL,
50    PHP_RSHUTDOWN(my_input_filter),
51    PHP_MINFO(my_input_filter),
52    "0.1",
53    STANDARD_MODULE_PROPERTIES
54};
55
56PHP_MINIT_FUNCTION(my_input_filter)
57{
58    ZEND_INIT_MODULE_GLOBALS(my_input_filter, php_my_input_filter_init_globals, NULL);
59
60    REGISTER_LONG_CONSTANT("POST", PARSE_POST, CONST_CS | CONST_PERSISTENT);
61    REGISTER_LONG_CONSTANT("GET", PARSE_GET, CONST_CS | CONST_PERSISTENT);
62    REGISTER_LONG_CONSTANT("COOKIE", PARSE_COOKIE, CONST_CS | CONST_PERSISTENT);
63
64    sapi_register_input_filter(my_sapi_input_filter);
65    return SUCCESS;
66}
67
68PHP_RSHUTDOWN_FUNCTION(my_input_filter)
69{
70    if(IF_G(get_array)) {
71        zval_ptr_dtor(&IF_G(get_array));
72        IF_G(get_array) = NULL;
73    }
74    if(IF_G(post_array)) {
75        zval_ptr_dtor(&IF_G(post_array));
76        IF_G(post_array) = NULL;
77    }
78    if(IF_G(cookie_array)) {
79        zval_ptr_dtor(&IF_G(cookie_array));
80        IF_G(cookie_array) = NULL;
81    }
82    return SUCCESS;
83}
84
85PHP_MINFO_FUNCTION(my_input_filter)
86{
87    php_info_print_table_start();
88    php_info_print_table_row( 2, "My Input Filter Support", "enabled" );
89    php_info_print_table_end();
90}
91
92/* The filter handler. If you return 1 from it, then PHP also registers the
93 * (modified) variable. Returning 0 prevents PHP from registering the variable;
94 * you can use this if your filter already registers the variable under a
95 * different name, or if you just don't want the variable registered at all. */
96SAPI_INPUT_FILTER_FUNC(my_sapi_input_filter)
97{
98    zval new_var;
99    zval *array_ptr = NULL;
100    char *raw_var;
101    int var_len;
102
103    assert(*val != NULL);
104
105    switch(arg) {
106        case PARSE_GET:
107            if(!IF_G(get_array)) {
108                ALLOC_ZVAL(array_ptr);
109                array_init(array_ptr);
110                INIT_PZVAL(array_ptr);
111            }
112            IF_G(get_array) = array_ptr;
113            break;
114        case PARSE_POST:
115            if(!IF_G(post_array)) {
116                ALLOC_ZVAL(array_ptr);
117                array_init(array_ptr);
118                INIT_PZVAL(array_ptr);
119            }
120            IF_G(post_array) = array_ptr;
121            break;
122        case PARSE_COOKIE:
123            if(!IF_G(cookie_array)) {
124                ALLOC_ZVAL(array_ptr);
125                array_init(array_ptr);
126                INIT_PZVAL(array_ptr);
127            }
128            IF_G(cookie_array) = array_ptr;
129            break;
130    }
131    Z_STRLEN(new_var) = val_len;
132    Z_STRVAL(new_var) = estrndup(*val, val_len);
133    Z_TYPE(new_var) = IS_STRING;
134
135    var_len = strlen(var);
136    raw_var = emalloc(var_len+5);  /* RAW_ and a \0 */
137    strcpy(raw_var, "RAW_");
138    strlcat(raw_var,var,var_len+5);
139
140    php_register_variable_ex(raw_var, &new_var, array_ptr);
141
142    php_strip_tags(*val, val_len, NULL, NULL, 0);
143
144    *new_val_len = strlen(*val);
145    return 1;
146}
147
148PHP_FUNCTION(my_get_raw)
149{
150    long arg;
151    char *var;
152    int var_len;
153    zval **tmp;
154    zval *array_ptr = NULL;
155
156    if(zend_parse_parameters(2, "ls", &arg, &var, &var_len) == FAILURE) {
157        return;
158    }
159
160    switch(arg) {
161        case PARSE_GET:
162            array_ptr = IF_G(get_array);
163            break;
164        case PARSE_POST:
165            array_ptr = IF_G(post_array);
166            break;
167        case PARSE_COOKIE:
168            array_ptr = IF_G(post_array);
169            break;
170    }
171
172    if(!array_ptr) {
173        RETURN_FALSE;
174    }
175
176    if(zend_hash_find(HASH_OF(array_ptr), var, var_len+5, (void **)&tmp) == SUCCESS) {
177        *return_value = **tmp;
178        zval_copy_ctor(return_value);
179    } else {
180        RETVAL_FALSE;
181    }
182}
183

README.md

1The PHP Interpreter
2===================
3
4This is the github mirror of the official PHP repository located at
5https://git.php.net.
6
7[![Build Status](https://secure.travis-ci.org/php/php-src.svg?branch=master)](http://travis-ci.org/php/php-src)
8[![Build status](https://ci.appveyor.com/api/projects/status/meyur6fviaxgdwdy?svg=true)](https://ci.appveyor.com/project/php/php-src)
9
10Pull Requests
11=============
12PHP accepts pull requests via github. Discussions are done on github, but
13depending on the topic can also be relayed to the official PHP developer
14mailing list internals@lists.php.net.
15
16New features require an RFC and must be accepted by the developers.
17See https://wiki.php.net/rfc and https://wiki.php.net/rfc/voting for more
18information on the process.
19
20Bug fixes **do not** require an RFC, but require a bugtracker ticket. Always
21open a ticket at https://bugs.php.net and reference the bug id using #NNNNNN.
22
23    Fix #55371: get_magic_quotes_gpc() throws deprecation warning
24
25    After removing magic quotes, the get_magic_quotes_gpc function caused
26    a deprecate warning. get_magic_quotes_gpc can be used to detected
27    the magic_quotes behavior and therefore should not raise a warning at any
28    time. The patch removes this warning
29
30We do not merge pull requests directly on github. All PRs will be
31pulled and pushed through https://git.php.net.
32
33
34Guidelines for contributors
35===========================
36- [CODING_STANDARDS](/CODING_STANDARDS)
37- [README.GIT-RULES](/README.GIT-RULES)
38- [README.MAILINGLIST_RULES](/README.MAILINGLIST_RULES)
39- [README.RELEASE_PROCESS](/README.RELEASE_PROCESS)
40