Name Date Size #Lines LOC

..28-Sep-2023-

TSRM/H05-Dec-2019-

Zend/H05-Dec-2019-

build/H05-Dec-2019-

ext/H05-Dec-2019-

main/H05-Dec-2019-

netware/H05-Dec-2019-

pear/H05-Dec-2019-

sapi/H05-Dec-2019-

scripts/H05-Dec-2019-

tests/H05-Dec-2019-

travis/H05-Dec-2019-

win32/H05-Dec-2019-

.gdbinitH A D05-Dec-201913.2 KiB670608

.gitattributesH A D05-Dec-20198.8 KiB182181

.gitignoreH A D05-Dec-20194.6 KiB265261

.travis.ymlH A D05-Dec-20191.3 KiB5247

CODING_STANDARDSH A D05-Dec-201911.6 KiB298229

CREDITSH A D05-Dec-201991 32

EXTENSIONSH A D05-Dec-201924.8 KiB560545

INSTALLH A D05-Dec-201993.5 KiB2,1211,718

LICENSEH A D05-Dec-20193.1 KiB6955

Makefile.fragH A D05-Dec-20191.1 KiB2413

Makefile.gcovH A D05-Dec-20192.4 KiB8068

Makefile.globalH A D05-Dec-20196.6 KiB135118

NEWSH A D05-Dec-2019474.7 KiB10,1989,233

README.EXTENSIONSH A D05-Dec-20191.7 KiB4838

README.EXT_SKELH A D05-Dec-20196.8 KiB189133

README.GIT-RULESH A D05-Dec-20194.9 KiB13487

README.MAILINGLIST_RULESH A D05-Dec-20193.3 KiB8056

README.NEW-OUTPUT-APIH A D05-Dec-20195.5 KiB143106

README.PARAMETER_PARSING_APIH A D05-Dec-20197.5 KiB235184

README.PHP4-TO-PHP5-THIN-CHANGESH A D05-Dec-20194.6 KiB156135

README.REDIST.BINSH A D05-Dec-201920.4 KiB443358

README.RELEASE_PROCESSH A D05-Dec-201912.3 KiB313213

README.SELF-CONTAINED-EXTENSIONSH A D05-Dec-20195 KiB171110

README.STREAMSH A D05-Dec-201915 KiB380289

README.SUBMITTING_PATCHH A D05-Dec-20197.8 KiB194148

README.TESTINGH A D05-Dec-20196.5 KiB181142

README.TESTING2H A D05-Dec-20194.8 KiB138109

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

README.WIN32-BUILD-SYSTEMH A D05-Dec-2019109 73

README.input_filterH A D05-Dec-20195.3 KiB185158

README.mdH A D05-Dec-20191.4 KiB4028

README.namespacesH A D05-Dec-20195.9 KiB175141

UPGRADINGH A D05-Dec-201918.1 KiB543449

UPGRADING.INTERNALSH A D05-Dec-20195.3 KiB137106

acinclude.m4H A D05-Dec-201978 KiB3,0152,756

buildconfH A D05-Dec-2019772 4836

buildconf.batH A D05-Dec-2019334 76

config.guessH A D05-Dec-201944 KiB1,5441,337

config.subH A D05-Dec-201934.9 KiB1,7941,651

configure.inH A D05-Dec-201945 KiB1,6791,411

footerH A D05-Dec-2019137 108

genfilesH A D05-Dec-2019581 3020

headerH A D05-Dec-20191.1 KiB2018

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

makedistH A D05-Dec-20193.1 KiB13680

makerpmH A D05-Dec-20195.2 KiB204159

php.gifH A D05-Dec-20192.5 KiB

php.ini-developmentH A D05-Dec-201967.6 KiB1,9371,588

php.ini-productionH A D05-Dec-201967.6 KiB1,9371,588

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

run-tests.phpH A D05-Dec-201978 KiB2,8332,157

server-tests-config.phpH A D05-Dec-20192.1 KiB7418

server-tests.phpH A D05-Dec-201952.1 KiB1,6221,269

snapshotH A D05-Dec-2019108 84

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

stub.cH A D05-Dec-20191 20

svnclean.batH A D05-Dec-201950 32

vcscleanH A D05-Dec-2019297 129

README.EXTENSIONS

1This file describes extension module API details. Refer to
2README.EXT_SKEL to create extension skeleton files. Refer to
3Hacker's Guide for PHP internals.
4
5http://www.php.net/manual/en/internals2.php
6
7
8
9Between PHP 4.0.6 and 4.1.0, the Zend module struct changed in a way
10that broke both source and binary compatibility.  If you are
11maintaining a third party extension, here's how to update it:
12
13If this was your old module entry:
14
15zend_module_entry foo_module_entry = {
16    "foo",                /* extension name */
17    foo_functions,        /* extension function list */
18    NULL,                 /* extension-wide startup function */
19    NULL,                 /* extension-wide shutdown function */
20    PHP_RINIT(foo),       /* per-request startup function */
21    PHP_RSHUTDOWN(foo),   /* per-request shutdown function */
22    PHP_MINFO(foo),       /* information function */
23    STANDARD_MODULE_PROPERTIES
24};
25
26Here's how it should look if you want your code to build with PHP
274.1.0 and up:
28
29zend_module_entry foo_module_entry = {
30#if ZEND_MODULE_API_NO >= 20010901
31    STANDARD_MODULE_HEADER,
32#endif
33    "foo",                /* extension name */
34    foo_functions,        /* extension function list */
35    NULL,                 /* extension-wide startup function */
36    NULL,                 /* extension-wide shutdown function */
37    PHP_RINIT(foo),       /* per-request startup function */
38    PHP_RSHUTDOWN(foo),   /* per-request shutdown function */
39    PHP_MINFO(foo),       /* information function */
40#if ZEND_MODULE_API_NO >= 20010901
41    PHP_FOO_VERSION,      /* extension version number (string) */
42#endif
43    STANDARD_MODULE_PROPERTIES
44};
45
46If you don't care about source compatibility with earlier PHP releases
47than 4.1.0, you can drop the #if/#endif lines.
48

README.EXT_SKEL

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

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

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

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

README.PARAMETER_PARSING_API

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

README.PHP4-TO-PHP5-THIN-CHANGES

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

README.REDIST.BINS

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

README.RELEASE_PROCESS

1=======================
2  PHP Release Process
3=======================
4
5General notes and tips
6----------------------
7
81. Do not release on Fridays, Saturdays or Sundays
9because the sysadmins can not upgrade stuff then.
10
112. Package two days before a release. So if the release is to be on Thursday,
12package on Tuesday. Think about timezones as well.
13
143. Ensure that 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 bases 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 acces 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 an 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 tone 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.in`` 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.in`` 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. Copy those tarballs (scp, rsync) to downloads.php.net, in your homedir there should be a
97directory "downloads/". Copy them into there, so that the system can generate
98MD5 sums. If you do not have this directory, talk to Derick or Dan.
99
10014. Now the RC can be found on http://downloads.php.net/yourname,
101f.e. http://downloads.php.net/derick/
102
10315. Once the release has been tagged, contact the PHP Windows development team
104(internals-win@lists.php.net) so that Windows binaries can be created. Once
105those are made, they should be placed into the same directory as the source snapshots.
106
107Getting the non stable release (alpha/beta/RC) announced
108--------------------------------------------------------
109
1101. Send an email (see example here: http://news.php.net/php.internals/19486)
111**To** ``internals@lists.php.net`` and ``php-general@lists.php.net`` lists
112pointing out "the location of the release" and "the possible release date of
113either the next RC, or the final release".
114
1152. Send an email (see example here http://news.php.net/php.pear.qa/5201) **To**
116``php-qa@lists.php.net`` and ``primary-qa-tester@lists.php.net``.
117This email is to notify the selected projects about a new release so that they
118can make sure their projects keep working. Make sure that you have been setup
119as a moderator for ``primary-qa-tester@lists.php.net`` by having someone (Hannes, Dan,
120Derick) run the following commands for you:
121
122``ssh lists.php.net``
123
124``sudo -u ezmlm ezmlm-sub ~ezmlm/primary-qa-tester/mod moderator-email-address``
125
1263. Update ``qa.git/include/release-qa.php`` with the appropriate information.
127   See the documentation within release-qa.php for more information, but all releases
128   and RCs are configured here. Only $QA_RELEASES needs to be edited.
129
130   Example: When rolling an RC, set the 'rc' with appropriate information for the
131   given version.
132
133   Note: Remember to update the MD5 checksum information.
134
1354. Update ``web/php.git/include/version.inc`` (x=major version number)
136
137 a. ``$PHP_x_RC`` = "5.4.0RC1"  (should be set to "false" before)
138
139 b. ``$PHP_x_RC_DATE`` = "06 September 2007"
140
1415. Commit and push those changes:
142
143 a. ``git commit -a && git push origin master``
144
1456. For the first RC, write the doc team (phpdoc@lists.php.net) about updating the
146INSTALL and win32/install.txt files which are generated from the PHP manual sources.
147
148Rolling a stable release
149------------------------
150
1511. Checkout your release branch, you should have created when releasing previous RC
152and bump the version numbers in ``main/php_version.h``, ``configure.in`` and possibly ``NEWS``.
153
1542. If a CVE commit needs to be merged to the release, then have it committed to
155the base branches and merged upwards as usual (f.e commit the CVE fix to 5.3,
156merge to 5.4, 5.5 etc...). Then you can cherry-pick it in your release branch.
157Don't forget to update NEWS manually in an extra commit then.
158
1593. Commit those changes. Ensure the tests at https://travis-ci.org/php/php-src/builds are
160still passing.
161
1624. run the "scripts/dev/credits" script in php-src and commit the changes in the
163credits files in ext/standard.
164
1655. Compile and make test, with and without ZTS, using the right Bison version
166(for example, for 5.5, Bison 2.4.1 is used)
167
1686. Check ./sapi/cli/php -v output for version matching.
169
1707. tag the repository with the version f.e. "``git tag -u YOURKEYID -s php-5.4.1``"
171
1728. Push the tag f.e. "``git push origin php-5.4.1``"
173
1749. run: ``PHPROOT=. ./makedist php 5.4.1``, this will export the tag, create configure
175and build three tarballs (gz, bz2 and xz).
176Check if the pear files are updated (phar).
177
17810. Generate the GPG signature files for the archives.
179  ``gpg -u YOUREMAIL --armor --detach-sign php-X.Y.Z.tar.xxx``
180
18111. Commit and push all the tarballs and signature files to web/php-distributions.git,
182    then update the git submodule reference in web/php.git:
183    ``git submodule init;
184    git submodule update;
185    cd distributions;
186    git pull origin master;
187    cd ..;
188    git commit distributions;
189    git push;``
190This is to fetch the last commit id from php-distributions.git and commit this
191last commit id to web/php.git, then, mirrors will now sync
192
19312. Once the release has been tagged, contact the PHP Windows development team
194(internals-win@lists.php.net) so that Windows binaries can be created.
195
196Getting the stable release announced
197------------------------------------
198
1991. Update phpweb/include/releases.inc with the old release info
200  (updates the download archives)
201
202 a. You can run ``php bin/bumpRelease 5`` if you are making a release for the
203    highest branch, otherwise you have to do this manually, see point 1.b
204
205 b. In case multiple PHP minor versions are in active development you have
206    to manually copy the old information to include/releases.inc
207
2082. Edit ``phpweb/include/version.inc`` and change (X=major release number):
209
210 a. ``$PHP_X_VERSION`` to the correct version
211
212 b. ``$PHP_X_DATE`` to the release date
213
214 c. ``$PHP_X_MD5`` array and update all the md5 sums
215
216 d. ``$PHP_X_SHA256`` array and update all the SHA256 sums
217
218 e. set ``$PHP_X_RC`` to false!
219
220 f. Make sure there are no outdated "notes" or edited "date" keys in the
221 ``$RELEASES[X][$PHP_X_VERSION]["source"]`` array
222
223 g. if the windows builds aren't ready yet prefix the "windows" key with a dot (".windows")
224
2253. Create the release file (releases/x_y_z.php)
226   Usually we use the same content as for point 6, but included in php template
227   instead of the release xml.
228
2294. Update php-qa/include/release-qa.php and add the next version as an QARELEASE
230   (prepare for next RC)
231
2325. Update the ChangeLog file for the given major version
233f.e. ``ChangeLog-5.php`` from the NEWS file
234
235 a. go over the list and put every element on one line
236
237 b. check for &, < and > and escape them if necessary
238
239 c. remove all the names at the ends of lines
240
241 d. for marking up, you can do the following (with VI):
242
243  I. ``s/^- /<li>/``
244
245  II. ``s/$/<\/li>/``
246
247  III. ``s/Fixed bug #\([0-9]\+\)/<?php bugfix(\1); ?>/``
248
249  IV. ``s/Fixed PECL bug #\([0-9]\+\)/<?php peclbugfix(\1); ?>/``
250
251  V. ``s/FR #\([0-9]\+\)/FR <?php bugl(\1); ?>/``
252
253  e. You may want to try php-web/bin/news2html to automate this task
254
2556. Add a short notice to phpweb stating that there is a new release, and
256highlight the major important things (security fixes) and when it is important
257to upgrade.
258
259 a. Call php bin/createNewsEntry in your local phpweb checkout
260
261 b. Add the content for the news entry
262
2637. **Check mirrors have been synced before announcing or pushing news**
264  Try, f.e. http://www.php.net/get/php-5.5.1.tar.bz2/from/a/mirror
265  Try several mirrors, mirrors may update slowly (may take an hour)
266
2678. Commit all the changes to their respective git repos
268
2699. Wait an hour or two, then send a mail to php-announce@lists.php.net,
270php-general@lists.php.net and internals@lists.php.net with a text similar to
271http://news.php.net/php.internals/17222.
272Please make sure that the mail to php-announce@ is its own completely seperate email.
273This is to make sure that repiles to the announcement on php-general@ or internals@
274will not accidentally hit the php-announce@ mailinglist.
275
276Re-releasing the same version (or -pl)
277--------------------------------------
278
2791. Commit the new binaries to ``phpweb/distributions/``
280
2812. Edit ``phpweb/include/version.inc`` and change (X=major release number):
282
283 a. If only releasing for one OS, make sure you edit only those variables
284
285 b. ``$PHP_X_VERSION`` to the correct version
286
287 c. ``$PHP_X_DATE`` to the release date
288
289 d. ``$PHP_X_MD5`` array and update all the md5 sums
290
291 e. ``$PHP_X_SHA256`` array and update all the SHA256 sums
292
293 f. Make sure there are no outdated "notes" or edited "date" keys in the
294 ``$RELEASES[X][$PHP_X_VERSION]["source"]`` array
295
2963. Add a short notice to phpweb stating that there is a new release, and
297highlight the major important things (security fixes) and when it is important
298to upgrade.
299
300 a. Call php bin/createNewsEntry in your local phpweb checkout
301
302 b. Add the content for the news entry
303
3044. Commit all the changes (``include/version.inc``, ``archive/archive.xml``,
305``archive/entries/YYYY-MM-DD-N.xml``)
306
3075. Wait an hour or two, then send a mail to php-announce@lists.php.net,
308php-general@lists.php.net and internals@lists.php.net with a text similar to
309the news entry.
310Please make sure that the mail to php-announce@ is its own completely seperate email.
311This is to make sure that repiles to the announcement on php-general@ or internals@
312will not accidentally hit the php-announce@ mailinglist.
313

README.SELF-CONTAINED-EXTENSIONS

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

README.STREAMS

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

README.SUBMITTING_PATCH

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

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 'SKIP' section. If the test is eligible for execution, the 'FILE'
65section is extracted into a ".php" file (with the same name besides
66the extension) and gets executed.
67When an argument is given or TESTS environment variable is set, the
68GLOB is expanded by the shell and any file with extension "*.phpt" is
69regarded as a test file.
70
71 Tester can easily execute tests selectively with as follows.
72
73Examples:
74./sapi/cli/php run-tests.php ext/mbstring/*
75./sapi/cli/php run-tests.php ext/mbstring/020.phpt
76
77
78[Test results]
79--------------
80 Test results are printed to standard output. If there is a failed test,
81the "run-tests.php" script saves the result, the expected result and the
82code executed to the test script directory. For example, if
83ext/myext/tests/myext.phpt fails to pass, the following files are created:
84
85ext/myext/tests/myext.php   - actual test file executed
86ext/myext/tests/myext.log   - log of test execution (L)
87ext/myext/tests/myext.exp   - expected output (E)
88ext/myext/tests/myext.out   - output from test script (O)
89ext/myext/tests/myext.diff  - diff of .out and .exp (D)
90
91 Failed tests are always bugs. Either the test is bugged or not considering
92factors applying to the tester's environment, or there is a bug in PHP.
93If this is a known bug, we strive to provide bug numbers, in either the
94test name or the file name. You can check the status of such a bug, by
95going to: http://bugs.php.net/12345 where 12345 is the bug number.
96For clarity and automated processing, bug numbers are prefixed by a hash
97sign '#' in test names and/or test cases are named bug12345.phpt.
98
99NOTE: The files generated by tests can be selected by setting the
100environment variable TEST_PHP_LOG_FORMAT. For each file you want to be
101generated use the character in brackets as shown above (default is LEOD).
102The php file will be generated always.
103
104NOTE: You can set environment variable TEST_PHP_DETAILED to enable
105detailed test information.
106
107[Automated testing]
108 If you like to keep up to speed, with latest developments and quality
109assurance, setting the environment variable NO_INTERACTION to 1, will not
110prompt the tester for any user input.
111
112Normally, the exit status of "make test" is zero, regardless of the results
113of independent tests. Set the environment variable REPORT_EXIT_STATUS to 1,
114and "make test" will set the exit status ("$?") to non-zero, when an
115individual test has failed.
116
117Example script to be run by cron(1):
118========== qa-test.sh =============
119#!/bin/sh
120
121CO_DIR=$HOME/cvs/php5
122MYMAIL=qa-test@domain.com
123TMPDIR=/var/tmp
124TODAY=`date +"%Y%m%d"`
125
126# Make sure compilation enviroment is correct
127CONFIGURE_OPTS='--disable-all --enable-cli --with-pcre'
128export MAKE=gmake
129export CC=gcc
130
131# Set test environment
132export NO_INTERACTION=1
133export REPORT_EXIT_STATUS=1
134
135cd $CO_DIR
136cvs update . >>$TMPDIR/phpqatest.$TODAY
137./cvsclean ; ./buildconf ; ./configure $CONFIGURE_OPTS ; $MAKE
138$MAKE test >>$TMPDIR/phpqatest.$TODAY 2>&1
139if test $? -gt 0
140then
141        cat $TMPDIR/phpqatest.$TODAY | mail -s"PHP-QA Test Failed for $TODAY" $MYMAIL
142fi
143========== end of qa-test.sh =============
144
145NOTE: the exit status of run-tests.php will be 1 when
146REPORT_EXIT_STATUS is set. The result of "make test" may be higher
147than that. At present, gmake 3.79.1 returns 2, so it is
148advised to test for non-zero, rather then a specific value.
149
150
151[Creating new test files]
152-------------------------
153 Writing test file is very easy if you are used to PHP.
154See the HOWTO at http://qa.php.net/write-test.php
155
156
157[How to help us]
158----------------
159 If you find bug in PHP, you can submit bug report AND test script
160for us. You don't have to write complete script, just give us test
161script with following format. Please test the script and make sure
162you write the correct ACTUAL OUTPUT and EXPECTED OUTPUT before you
163submit.
164
165<?php
166/*
167Bug #12345
168substr() bug. Do not return expected string.
169
170ACTUAL OUTPUT
171XYXA
172
173EXPECTED OUTPUT
174ABCD
175*/
176
177$str = "XYZABCD";
178echo substr($str,3,7);
179
180?>
181

README.TESTING2

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

README.UNIX-BUILD-SYSTEM

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

README.WIN32-BUILD-SYSTEM

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

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_row( 2, "Revision", "$Id: e2941d029ee4e89f8880c46d41a7e8fc60a7fbc3 $");
90    php_info_print_table_end();
91}
92
93/* The filter handler. If you return 1 from it, then PHP also registers the
94 * (modified) variable. Returning 0 prevents PHP from registering the variable;
95 * you can use this if your filter already registers the variable under a
96 * different name, or if you just don't want the variable registered at all. */
97SAPI_INPUT_FILTER_FUNC(my_sapi_input_filter)
98{
99    zval new_var;
100    zval *array_ptr = NULL;
101    char *raw_var;
102    int var_len;
103
104    assert(*val != NULL);
105
106    switch(arg) {
107        case PARSE_GET:
108            if(!IF_G(get_array)) {
109                ALLOC_ZVAL(array_ptr);
110                array_init(array_ptr);
111                INIT_PZVAL(array_ptr);
112            }
113            IF_G(get_array) = array_ptr;
114            break;
115        case PARSE_POST:
116            if(!IF_G(post_array)) {
117                ALLOC_ZVAL(array_ptr);
118                array_init(array_ptr);
119                INIT_PZVAL(array_ptr);
120            }
121            IF_G(post_array) = array_ptr;
122            break;
123        case PARSE_COOKIE:
124            if(!IF_G(cookie_array)) {
125                ALLOC_ZVAL(array_ptr);
126                array_init(array_ptr);
127                INIT_PZVAL(array_ptr);
128            }
129            IF_G(cookie_array) = array_ptr;
130            break;
131    }
132    Z_STRLEN(new_var) = val_len;
133    Z_STRVAL(new_var) = estrndup(*val, val_len);
134    Z_TYPE(new_var) = IS_STRING;
135
136    var_len = strlen(var);
137    raw_var = emalloc(var_len+5);  /* RAW_ and a \0 */
138    strcpy(raw_var, "RAW_");
139    strlcat(raw_var,var,var_len+5);
140
141    php_register_variable_ex(raw_var, &new_var, array_ptr TSRMLS_DC);
142
143    php_strip_tags(*val, val_len, NULL, NULL, 0);
144
145    *new_val_len = strlen(*val);
146    return 1;
147}
148
149PHP_FUNCTION(my_get_raw)
150{
151    long arg;
152    char *var;
153    int var_len;
154    zval **tmp;
155    zval *array_ptr = NULL;
156
157    if(zend_parse_parameters(2 TSRMLS_CC, "ls", &arg, &var, &var_len) == FAILURE) {
158        return;
159    }
160
161    switch(arg) {
162        case PARSE_GET:
163            array_ptr = IF_G(get_array);
164            break;
165        case PARSE_POST:
166            array_ptr = IF_G(post_array);
167            break;
168        case PARSE_COOKIE:
169            array_ptr = IF_G(post_array);
170            break;
171    }
172
173    if(!array_ptr) {
174        RETURN_FALSE;
175    }
176
177    if(zend_hash_find(HASH_OF(array_ptr), var, var_len+5, (void **)&tmp) == SUCCESS) {
178        *return_value = **tmp;
179        zval_copy_ctor(return_value);
180    } else {
181        RETVAL_FALSE;
182    }
183}
184
185

README.md

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

README.namespaces

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