NameDateSize

..30-Oct-2015

.gdbinit01-Sep-201512.9 KiB

.gitattributes17-Jan-20158.8 KiB

.gitignore17-Dec-20155 KiB

.travis.yml19-Oct-20151.6 KiB

acinclude.m403-Feb-201680.2 KiB

build/04-Jan-2016

buildconf18-Dec-2012772

buildconf.bat18-Dec-2012334

CODING_STANDARDS26-Dec-201511.7 KiB

config.guess01-Feb-201541.9 KiB

config.sub01-Feb-201535.1 KiB

configure.in03-Dec-201545.7 KiB

CONTRIBUTING.md21-May-20153.1 KiB

CREDITS18-Dec-201291

ext/16-Dec-2015

EXTENSIONS18-Jun-201520.3 KiB

footer18-Dec-2012137

genfiles10-Jun-2015581

header01-Jan-20161.1 KiB

INSTALL05-Apr-201685.8 KiB

LICENSE01-Jan-20163.1 KiB

ltmain.sh18-Dec-2012195 KiB

main/Today

makedist15-Nov-20154 KiB

Makefile.frag27-Mar-20151.1 KiB

Makefile.gcov24-Oct-20152.4 KiB

Makefile.global08-Feb-20167.1 KiB

makerpm01-Feb-20155.2 KiB

netware/01-Jan-2016

NEWSToday3.2 KiB

pear/07-Oct-2015

php.gif18-Dec-20122.5 KiB

php.ini-development24-Dec-201567.3 KiB

php.ini-production24-Dec-201567.3 KiB

php7.spec.in20-Sep-20141.5 KiB

README.EXT_SKEL26-Dec-20156.8 KiB

README.GIT-RULES29-Jan-20164.9 KiB

README.input_filter26-Dec-20155.3 KiB

README.MAILINGLIST_RULES18-Dec-20123.3 KiB

README.md01-Feb-20151.4 KiB

README.namespaces05-Jun-20145.9 KiB

README.NEW-OUTPUT-API26-Dec-20155.1 KiB

README.PARAMETER_PARSING_API03-Mar-20167.4 KiB

README.REDIST.BINS20-Feb-201619.3 KiB

README.RELEASE_PROCESS29-Jan-201612.4 KiB

README.SELF-CONTAINED-EXTENSIONS14-Oct-20135 KiB

README.STREAMS26-Dec-201515 KiB

README.SUBMITTING_PATCH07-Aug-20147.9 KiB

README.TESTING09-Feb-20156.5 KiB

README.TESTING223-Nov-20144.8 KiB

README.UNIX-BUILD-SYSTEM20-Sep-20144.2 KiB

README.WIN32-BUILD-SYSTEM18-Dec-2012109

run-tests.php01-Jan-201679.9 KiB

sapi/30-May-2015

scripts/12-May-2015

server-tests-config.php20-Nov-20142.1 KiB

server-tests.php01-Jan-201651.5 KiB

snapshot18-Dec-2012108

stamp-h.in18-Dec-201210

stub.c18-Dec-20121

tests/24-Nov-2014

travis/05-Dec-2015

TSRM/31-Mar-2016

UPGRADING30-Mar-20165.8 KiB

UPGRADING.INTERNALS17-Sep-2015652

vcsclean09-Jun-2014146

win32/01-Jan-2016

Zend/Today

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.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.svg?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

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.SUBMITTING_PATCH

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

README.TESTING

1[IMPORTANT NOTICE]
2------------------
3 Failed tests usually indicate a problem with your local system setup
4and not within PHP itself (at least for official PHP release versions).
5You may decide to automatically submit a test summary to our QA workflow
6at the end of a test run.
7 Please do *not* submit a failed test as a bug or ask for help on why
8it failed on your system without providing substantial backup information
9on *why* the test failed on your special setup. Thank you :-)
10
11
12[Testing Basics] 
13----------------
14 The easiest way to test your PHP build is to run "make test" from the
15command line after successfully compiling. This will run the complete
16tests for all enabled functionalities and extensions using the PHP
17CLI binary.
18 To execute test scripts, you must build PHP with some SAPI, then you
19type "make test" to execute all or some test scripts saved under
20"tests" directory under source root directory.
21
22Usage:
23make test
24
25 "make test" basically executes "run-tests.php" script
26under the source root (parallel builds will not work). Therefore you
27can execute the script as follows:
28
29TEST_PHP_EXECUTABLE=sapi/cli/php \
30sapi/cli/php [-c /path/to/php.ini] run-tests.php [ext/foo/tests/GLOB]
31
32
33[Which "php" executable "make test" look for]
34---------------------------------------------
35If you are running the run-tests.php script from the command line (as above)
36you must set the TEST_PHP_EXECUTABLE environment variable to explicitly
37select the PHP executable that is to be tested, that is, used to run the test scripts.
38
39If you run the tests using make test, the PHP CLI and CGI executables are 
40automatically set for you. "make test" executes "run-tests.php" script with the CLI binary.  Some
41test scripts such as session must be executed by CGI SAPI. Therefore,
42you must build PHP with CGI SAPI to perform all tests.
43
44NOTE: PHP binary executing "run-tests.php" and php binary used for
45executing test scripts may differ. If you use different PHP binary for
46executing "run-tests.php" script, you may get errors.
47
48
49[Which php.ini is used]
50-----------------------
51 "make test" uses the same php.ini file as it would once installed.
52The tests have been written to be independent of that php.ini file,
53so if you find a test that is affected by a setting, please report
54this, so we can address the issue.
55
56
57[Which test scripts are executed]
58---------------------------------
59 "run-tests.php" ("make test"), without any arguments executes all
60test scripts by extracting all directories named "tests"
61from the source root and any subdirectories below. If there are files,
62which have a "phpt" extension, "run-tests.php" looks at the sections
63in these files, determines whether it should run it, by evaluating
64the '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--------------
109 If you like to keep up to speed, with latest developments and quality
110assurance, setting the environment variable NO_INTERACTION to 1, will not
111prompt the tester for any user input.
112
113Normally, the exit status of "make test" is zero, regardless of the results
114of independent tests. Set the environment variable REPORT_EXIT_STATUS to 1,
115and "make test" will set the exit status ("$?") to non-zero, when an
116individual test has failed.
117
118Example script to be run by cron(1):
119========== qa-test.sh =============
120#!/bin/sh
121
122CO_DIR=$HOME/cvs/php7
123MYMAIL=qa-test@domain.com
124TMPDIR=/var/tmp
125TODAY=`date +"%Y%m%d"`
126
127# Make sure compilation environment is correct
128CONFIGURE_OPTS='--disable-all --enable-cli --with-pcre'
129export MAKE=gmake
130export CC=gcc
131
132# Set test environment
133export NO_INTERACTION=1
134export REPORT_EXIT_STATUS=1
135
136cd $CO_DIR
137cvs update . >>$TMPDIR/phpqatest.$TODAY
138./cvsclean ; ./buildconf ; ./configure $CONFIGURE_OPTS ; $MAKE
139$MAKE test >>$TMPDIR/phpqatest.$TODAY 2>&1
140if test $? -gt 0
141then
142        cat $TMPDIR/phpqatest.$TODAY | mail -s"PHP-QA Test Failed for $TODAY" $MYMAIL
143fi
144========== end of qa-test.sh =============
145
146NOTE: The exit status of run-tests.php will be 1 when
147REPORT_EXIT_STATUS is set. The result of "make test" may be higher
148than that. At present, gmake 3.79.1 returns 2, so it is
149advised to test for non-zero, rather then a specific value.
150
151
152[Creating new test files]
153-------------------------
154 Writing test file is very easy if you are used to PHP. 
155See the HOWTO at http://qa.php.net/write-test.php
156
157
158[How to help us]
159----------------
160 If you find bug in PHP, you can submit bug report AND test script 
161for us. You don't have to write complete script, just give us test
162script with following format. Please test the script and make sure
163you write the correct ACTUAL OUTPUT and EXPECTED OUTPUT before you
164submit.
165
166<?php
167/* 
168Bug #12345
169substr() bug. Do not return expected string.
170
171ACTUAL OUTPUT
172XYXA
173
174EXPECTED OUTPUT
175ABCD
176*/
177
178$str = "XYZABCD";
179echo substr($str,3,7);
180
181?>
182

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 accessible 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 equivalent 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 initial 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_php7.c php_apache.c)
112
113
114
115General info
116
117The foundation for the new system is the flexible handling of
118sources and their contexts.  With the help of macros you
119can define special flags for each source-file, where it is
120located, in which target context it can work, etc.
121
122Have a look at the well documented macros
123PHP_ADD_SOURCES(_X) in acinclude.m4.
124

README.WIN32-BUILD-SYSTEM

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