|
Name |
|
Date |
Size |
#Lines |
LOC |
| .. | | 28-Sep-2023 | - |
| TSRM/ | H | 05-May-2020 | - | | |
| Zend/ | H | 16-Nov-2021 | - | | |
| appveyor/ | H | 05-Dec-2019 | - | | |
| build/ | H | 03-Nov-2020 | - | | |
| ext/ | H | 05-Dec-2019 | - | | |
| main/ | H | 16-Nov-2021 | - | | |
| pear/ | H | 05-Dec-2019 | - | | |
| sapi/ | H | 05-Dec-2019 | - | | |
| scripts/ | H | 05-Dec-2019 | - | | |
| tests/ | H | 05-Dec-2019 | - | | |
| travis/ | H | 03-Aug-2020 | - | | |
| win32/ | H | 17-Dec-2019 | - | | |
| .appveyor.yml | H A D | 05-Dec-2019 | 1.4 KiB | 52 | 42 |
| .editorconfig | H A D | 05-Dec-2019 | 736 | 35 | 26 |
| .gdbinit | H A D | 05-Dec-2019 | 12.7 KiB | 648 | 591 |
| .gitattributes | H A D | 05-Dec-2019 | 8 KiB | 160 | 159 |
| .gitignore | H A D | 05-Dec-2019 | 3.6 KiB | 211 | 204 |
| .travis.yml | H A D | 05-Dec-2019 | 1.9 KiB | 75 | 67 |
| CODING_STANDARDS | H A D | 05-Dec-2019 | 12.4 KiB | 323 | 251 |
| CONTRIBUTING.md | H A D | 05-Dec-2019 | 3.3 KiB | 79 | 57 |
| CREDITS | H A D | 05-Dec-2019 | 93 | 4 | 2 |
| EXTENSIONS | H A D | 05-Dec-2019 | 23 KiB | 512 | 497 |
| INSTALL | H A D | 05-Dec-2019 | 105 | 4 | 2 |
| LICENSE | H A D | 05-Dec-2019 | 3.1 KiB | 69 | 55 |
| Makefile.frag | H A D | 05-Dec-2019 | 1.1 KiB | 23 | 13 |
| Makefile.gcov | H A D | 05-Dec-2019 | 2.4 KiB | 79 | 68 |
| Makefile.global | H A D | 05-Dec-2019 | 6.9 KiB | 148 | 127 |
| NEWS | H A D | 16-Nov-2021 | 92.2 KiB | 2,662 | 2,116 |
| README.EXT_SKEL | H A D | 05-Dec-2019 | 1.3 KiB | 44 | 26 |
| README.GIT-RULES | H A D | 05-Dec-2019 | 5.2 KiB | 142 | 92 |
| README.MAILINGLIST_RULES | H A D | 05-Dec-2019 | 3.3 KiB | 80 | 56 |
| README.NEW-OUTPUT-API | H A D | 05-Dec-2019 | 5 KiB | 140 | 105 |
| README.PARAMETER_PARSING_API | H A D | 05-Dec-2019 | 7.6 KiB | 236 | 185 |
| README.REDIST.BINS | H A D | 05-Dec-2019 | 24.2 KiB | 546 | 432 |
| README.RELEASE_PROCESS | H A D | 05-Dec-2019 | 15.3 KiB | 373 | 258 |
| README.SELF-CONTAINED-EXTENSIONS | H A D | 05-Dec-2019 | 4.9 KiB | 167 | 108 |
| README.STREAMS | H A D | 05-Dec-2019 | 15 KiB | 379 | 288 |
| README.SUBMITTING_PATCH | H A D | 05-Dec-2019 | 7.9 KiB | 195 | 149 |
| README.TESTING | H A D | 05-Dec-2019 | 11.4 KiB | 317 | 252 |
| README.UNIX-BUILD-SYSTEM | H A D | 05-Dec-2019 | 4.2 KiB | 124 | 81 |
| README.WIN32-BUILD-SYSTEM | H A D | 05-Dec-2019 | 114 | 6 | 3 |
| README.input_filter | H A D | 05-Dec-2019 | 5.2 KiB | 183 | 157 |
| README.md | H A D | 05-Dec-2019 | 1.6 KiB | 40 | 29 |
| UPGRADING | H A D | 29-Sep-2020 | 29.4 KiB | 775 | 660 |
| UPGRADING.INTERNALS | H A D | 05-Dec-2019 | 9.1 KiB | 209 | 166 |
| acinclude.m4 | H A D | 09-Nov-2020 | 86.7 KiB | 3,328 | 3,010 |
| buildconf | H A D | 05-Dec-2019 | 773 | 47 | 36 |
| buildconf.bat | H A D | 30-Jan-2020 | 346 | 8 | 6 |
| config.guess | H A D | 05-Dec-2019 | 43.1 KiB | 1,477 | 1,284 |
| config.sub | H A D | 05-Dec-2019 | 35.6 KiB | 1,834 | 1,690 |
| configure.ac | H A D | 16-Nov-2021 | 46.7 KiB | 1,724 | 1,450 |
| footer | H A D | 05-Dec-2019 | 136 | 9 | 8 |
| genfiles | H A D | 05-Dec-2019 | 580 | 29 | 20 |
| header | H A D | 05-Dec-2019 | 1.1 KiB | 18 | 17 |
| ltmain.sh | H A D | 05-Dec-2019 | 195 KiB | 6,958 | 5,500 |
| makedist | H A D | 27-Apr-2021 | 4.1 KiB | 158 | 96 |
| php.gif | H A D | 05-Dec-2019 | 2.5 KiB | | |
| php.ini-development | H A D | 18-Mar-2020 | 69.7 KiB | 1,938 | 1,604 |
| php.ini-production | H A D | 18-Mar-2020 | 69.9 KiB | 1,940 | 1,606 |
| php7.spec.in | H A D | 05-Dec-2019 | 1.5 KiB | 49 | 39 |
| run-tests.php | H A D | 23-Feb-2021 | 85.2 KiB | 3,032 | 2,325 |
| server-tests-config.php | H A D | 05-Dec-2019 | 2 KiB | 75 | 18 |
| server-tests.php | H A D | 05-Dec-2019 | 51.2 KiB | 1,609 | 1,256 |
| snapshot | H A D | 05-Dec-2019 | 108 | 8 | 4 |
| stamp-h.in | H A D | 05-Dec-2019 | 10 | 2 | 1 |
| vcsclean | H A D | 05-Dec-2019 | 159 | 8 | 5 |
README.EXT_SKEL
1WHAT IT IS
2
3 It's a tool for automatically creating the basic framework for a PHP extension.
4
5HOW TO USE IT
6
7 Very simple. First, change to the ext/ directory of the PHP sources. Then
8 run the following
9
10 php ext_skel.php --ext extension_name
11
12 and everything you need will be placed in directory ext/extension_name.
13
14 If you don't need to test the existence of any external header files,
15 libraries or functions in them, the extension is ready to be compiled in
16 PHP. To compile the extension, run the following:
17
18 ./buildconf; ./configure --enable-extension_name; make
19
20 The definition of PHP_extension_NAME_VERSION will be present in the
21 php_extension_name.h and injected into the zend_extension_entry definition. This
22 is required by the PECL website for the version string conformity checks
23 against package.xml
24
25SOURCE AND HEADER FILE NAME
26
27 The ext_skel.php script generates 'extension_name.c' and 'php_extension_name.h'
28 as the main source and header files. Keep these names.
29
30 extension functions (User functions) must be named
31
32 extension_name_function()
33
34 When you need to expose extension functions to other extensions, expose functions
35 strictly needed by others. Exposed internal function must be named
36
37 php_extension_name_function()
38
39 See also CODING_STANDARDS.
40
41OTHER OPTIONS
42
43 Run php ext_skel.php --help to see the available options.
44
README.GIT-RULES
1====================
2 Git Commit Rules
3====================
4
5This is the first file you should be reading when contributing code via Git.
6We'll assume you're basically familiar with Git, but feel free to post
7your questions on the mailing list. Please have a look at
8http://git-scm.com/ for more detailed information on Git.
9
10PHP is developed through the efforts of a large number of people.
11Collaboration is a Good Thing(tm), and Git lets us do this. Thus, following
12some basic rules with regards to Git usage will::
13
14 a. Make everybody happier, especially those responsible for maintaining
15 PHP itself.
16
17 b. Keep the changes consistently well documented and easily trackable.
18
19 c. Prevent some of those 'Oops' moments.
20
21 d. Increase the general level of good will on planet Earth.
22
23Having said that, here are the organizational rules::
24
25 1. Respect other people working on the project.
26
27 2. Discuss any significant changes on the list before committing and get
28 confirmation from the release manager for the given branch.
29
30 3. Look at EXTENSIONS file to see who is the primary maintainer of
31 the code you want to contribute to.
32
33 4. If you "strongly disagree" about something another person did, don't
34 start fighting publicly - take it up in private email.
35
36 5. If you don't know how to do something, ask first!
37
38 6. Test your changes before committing them. We mean it. Really.
39 To do so use "make test".
40
41 7. For development use the --enable-debug switch to avoid memory leaks
42 and the --enable-maintainer-zts switch to ensure your code handles
43 TSRM correctly and doesn't break for those who need that.
44
45Currently we have the following branches in use::
46
47 master The active development branch.
48
49 PHP-7.2 Is used to release the PHP 7.2.x series. This is a current
50 stable version and is open for bugfixes only.
51
52 PHP-7.1 Is used to release the PHP 7.1.x series. This is a current
53 stable version and is open for bugfixes only.
54
55 PHP-7.0 Is used to release the PHP 7.0.x series. This is an old
56 stable version and is open for security fixes only.
57
58 PHP-5.6 Is used to release the PHP 5.6.x series. This is an old
59 stable version and is open for security fixes only.
60
61 PHP-5.5 This branch is closed.
62
63 PHP-5.4 This branch is closed.
64
65 PHP-5.3 This branch is closed.
66
67 PHP-5.2 This branch is closed.
68
69 PHP-5.1 This branch is closed.
70
71 PHP-4.4 This branch is closed.
72
73 PHP-X.Y.Z These branches are used for the release managers for tagging
74 the releases, hence they are closed to the general public.
75
76The next few rules are more of a technical nature::
77
78 1. All changes should first go to the lowest branch (i.e. 5.6) and then
79 get merged up to all other branches. If a change is not needed for
80 later branches (i.e. fixes for features which were dropped from later
81 branches) an empty merge should be done.
82
83 2. All news updates intended for public viewing, such as new features,
84 bug fixes, improvements, etc., should go into the NEWS file of *any
85 stable release* version with the given change. In other words,
86 news about a bug fix which went into PHP-5.4, PHP-5.5 and master
87 should be noted in both PHP-5.4/NEWS and PHP-5.5/NEWS but
88 not master, which is not a public released version yet.
89
90 3. Do not commit multiple files and dump all messages in one commit. If you
91 modified several unrelated files, commit each group separately and
92 provide a nice commit message for each one. See example below.
93
94 4. Do write your commit message in such a way that it makes sense even
95 without the corresponding diff. One should be able to look at it, and
96 immediately know what was modified. Definitely include the function name
97 in the message as shown below.
98
99 5. In your commit messages, keep each line shorter than 80 characters. And
100 try to align your lines vertically, if they wrap. It looks bad otherwise.
101
102 6. If you modified a function that is callable from PHP, prepend PHP to
103 the function name as shown below.
104
105
106The format of the commit messages is pretty simple.
107
108<max 79 characters short description>\n
109\n
110<long description, 79 chars per line>
111\n
112
113An Example from the git project (commit 2b34e486bc):
114
115pack-objects: Fix compilation with NO_PTHREDS
116
117It looks like commit 99fb6e04 (pack-objects: convert to use
118parse_options(), 2012-02-01) moved the #ifdef NO_PTHREDS around but
119hasn't noticed that the 'arg' variable no longer is available.
120
121If you fix some bugs, you should note the bug ID numbers in your
122commit message. Bug ID should be prefixed by "#" for easier access to
123bug report when developers are browsing CVS via LXR or Bonsai.
124
125Example:
126
127Fixed bug #14016 (pgsql notice handler double free crash bug.)
128
129When you change the NEWS file for a bug fix, then please keep the bugs
130sorted in decreasing order under the fixed version.
131
132You can use OpenGrok (http://lxr.php.net/) and gitweb (http://git.php.net/)
133to look at PHP Git repository in various ways.
134
135
136For further information on the process and further details please refer to
137https://wiki.php.net/vcs/gitworkflow and https://wiki.php.net/vcs/gitfaq
138
139Happy hacking,
140
141PHP Team
142
README.MAILINGLIST_RULES
1====================
2 Mailinglist Rules
3====================
4
5This is the first file you should be reading before doing any posts on PHP
6mailinglists. Following these rules is considered imperative to the success of
7the PHP project. Therefore expect your contributions to be of much less positive
8impact if you do not follow these rules. More importantly you can actually
9assume that not following these rules will hurt the PHP project.
10
11PHP is developed through the efforts of a large number of people.
12Collaboration is a Good Thing(tm), and mailinglists lets us do this. Thus,
13following some basic rules with regards to mailinglist usage will:
14
15 a. Make everybody happier, especially those responsible for developing PHP
16 itself.
17
18 b. Help in making sure we all use our time more efficiently.
19
20 c. Prevent you from making a fool of yourself in public.
21
22 d. Increase the general level of good will on planet Earth.
23
24
25Having said that, here are the organizational rules:
26
27 1. Respect other people working on the project.
28
29 2. Do not post when you are angry. Any post can wait a few hours. Review
30 your post after a good breather or a good nights sleep.
31
32 3. Make sure you pick the right mailinglist for your posting. Please review
33 the descriptions on the mailinglist overview page
34 (http://www.php.net/mailing-lists.php). When in doubt ask a friend or
35 someone you trust on IRC.
36
37 4. Make sure you know what you are talking about. PHP is a very large project
38 that strives to be very open. The flip side is that the core developers
39 are faced with a lot of requests. Make sure that you have done your
40 research before posting to the entire developer community.
41
42 5. Patches have a much greater chance of acceptance than just asking the
43 PHP developers to implement a feature for you. For one it makes the
44 discussion more concrete and it shows that the poster put thought and time
45 into the request.
46
47 6. If you are posting to an existing thread, make sure that you know what
48 previous posters have said. This is even more important the longer the
49 thread is already.
50
51 7. Please configure your email client to use a real name and keep message
52 signatures to a maximum of 2 lines if at all necessary.
53
54The next few rules are more some general hints:
55
56 1. If you notice that your posting ratio is much higher than that of other
57 people, double check the above rules. Try to wait a bit longer before
58 sending your replies to give other people more time to digest your answers
59 and more importantly give you the opportunity to make sure that you
60 aggregate your current position into a single mail instead of multiple
61 ones.
62
63 2. Consider taking a step back from a very active thread now and then. Maybe
64 talking to some friends and fellow developers will help in understanding
65 the other opinions better.
66
67 3. Do not top post. Place your answer underneath anyone you wish to quote
68 and remove any previous comment that is not relevant to your post.
69
70 4. Do not high-jack threads, by bringing up entirely new topics. Please
71 create an entirely new thread copying anything you wish to quote into the
72 new thread.
73
74Finally, additional hints on how to behave inside the virtual community can be
75found in RFC 1855 (http://www.faqs.org/rfcs/rfc1855.html).
76
77Happy hacking,
78
79PHP Team
80
README.NEW-OUTPUT-API
1API adjustment to the old output control code:
2
3 Everything now resides beneath the php_output namespace,
4 and there's an API call for every output handler op.
5
6 Checking output control layers status:
7 // Using OG()
8 php_output_get_status();
9
10 Starting the default output handler:
11 // php_start_ob_buffer(NULL, 0, 1);
12 php_output_start_default();
13
14 Starting an user handler by zval:
15 // php_start_ob_buffer(zhandler, chunk_size, erase);
16 php_output_start_user(zhandler, chunk_size, flags);
17
18 Starting an internal handler without context:
19 // php_ob_set_internal_handler(my_php_output_handler_func_t, buffer_size, "output handler name", erase);
20 php_output_start_internal(handler_name, handler_name_len, my_php_output_handler_func_t, chunk_size, flags);
21
22 Starting an internal handler with context:
23 // not possible with old API
24 php_output_handler *h;
25 h = php_output_handler_create_internal(handler_name, handler_name_len, my_php_output_handler_context_func_t, chunk_size, flags);
26 php_output_handler_set_context(h, my_context, my_context_dtor);
27 php_output_handler_start(h);
28
29 Testing whether a certain output handler has already been started:
30 // php_ob_handler_used("output handler name");
31 php_output_handler_started(handler_name, handler_name_len);
32
33 Flushing one output buffer:
34 // php_end_ob_buffer(1, 1);
35 php_output_flush();
36
37 Flushing all output buffers:
38 // not possible with old API
39 php_output_flush_all();
40
41 Cleaning one output buffer:
42 // php_ob_end_buffer(0, 1);
43 php_output_clean();
44
45 Cleaning all output buffers:
46 // not possible with old API
47 php_output_clean_all();
48
49 Discarding one output buffer:
50 // php_ob_end_buffer(0, 0);
51 php_output_discard();
52
53 Discarding all output buffers:
54 // php_ob_end_buffers(0);
55 php_output_discard_all();
56
57 Stopping (and dropping) one output buffer:
58 // php_ob_end_buffer(1, 0)
59 php_output_end();
60
61 Stopping (and dropping) all output buffers:
62 // php_ob_end_buffers(1, 0);
63 php_output_end_all();
64
65 Retrieving output buffers contents:
66 // php_ob_get_buffer(zstring);
67 php_output_get_contents(zstring);
68
69 Retrieving output buffers length:
70 // php_ob_get_length(zlength);
71 php_output_get_length(zlength);
72
73 Retrieving output buffering level:
74 // OG(nesting_level);
75 php_output_get_level();
76
77 Issue a warning because of an output handler conflict:
78 // php_ob_init_conflict("to be started handler name", "to be tested if already started handler name");
79 php_output_handler_conflict(new_handler_name, new_handler_name_len, set_handler_name, set_handler_name_len);
80
81 Registering a conflict checking function, which will be checked prior starting the handler:
82 // not possible with old API, unless hardcoding into output.c
83 php_output_handler_conflict_register(handler_name, handler_name_len, my_php_output_handler_conflict_check_t);
84
85 Registering a reverse conflict checking function, which will be checked prior starting the specified foreign handler:
86 // not possible with old API
87 php_output_handler_reverse_conflict_register(foreign_handler_name, foreign_handler_name_len, my_php_output_handler_conflict_check_t);
88
89 Facilitating a context from within an output handler callable with ob_start():
90 // not possible with old API
91 php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_GET_OPAQ, (void *) &custom_ctx_ptr_ptr);
92
93 Disabling of the output handler by itself:
94 //not possible with old API
95 php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_DISABLE, NULL);
96
97 Marking an output handler immutable by itself because of irreversibility of its operation:
98 // not possible with old API
99 php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_IMMUTABLE, NULL);
100
101 Restarting the output handler because of a CLEAN operation:
102 // not possible with old API
103 if (flags & PHP_OUTPUT_HANDLER_CLEAN) { ... }
104
105 Recognizing by the output handler itself if it gets discarded:
106 // not possible with old API
107 if ((flags & PHP_OUTPUT_HANDLER_CLEAN) && (flags & PHP_OUTPUT_HANDLER_FINAL)) { ... }
108
109
110Output handler hooks
111
112 The output handler can change its abilities at runtime. Eg. the gz handler can
113 remove the CLEANABLE and REMOVABLE bits when the first output has passed through it;
114 or handlers implemented in C to be used with ob_start() can contain a non-global
115 context:
116 PHP_OUTPUT_HANDLER_HOOK_GET_OPAQ
117 pass a void*** pointer as second arg to receive the address of a pointer
118 pointer to the opaque field of the output handler context
119 PHP_OUTPUT_HANDLER_HOOK_GET_FLAGS
120 pass a int* pointer as second arg to receive the flags set for the output handler
121 PHP_OUTPUT_HANDLER_HOOK_GET_LEVEL
122 pass a int* pointer as second arg to receive the level of this output handler
123 (starts with 0)
124 PHP_OUTPUT_HANDLER_HOOK_IMMUTABLE
125 the second arg is ignored; marks the output handler to be neither cleanable
126 nor removable
127 PHP_OUTPUT_HANDLER_HOOK_DISABLE
128 the second arg is ignored; marks the output handler as disabled
129
130
131Open questions
132
133 Should the userland API be adjusted and unified?
134
135 Many bits of the manual (and very first implementation) do not comply
136 with the behaviour of the current (to be obsoleted) code, thus should
137 the manual or the behaviour be adjusted?
138
139END
140
README.PARAMETER_PARSING_API
1New parameter parsing functions
2===============================
3
4It should be easier to parse input parameters to an extension function.
5Hence, borrowing from Python's example, there are now a set of functions
6that given the string of type specifiers, can parse the input parameters
7and store the results in the user specified variables. This avoids most
8of the IS_* checks and convert_to_* conversions. The functions also
9check for the appropriate number of parameters, and try to output
10meaningful error messages.
11
12
13Prototypes
14----------
15/* Implemented. */
16int zend_parse_parameters(int num_args, char *type_spec, ...);
17int zend_parse_parameters_ex(int flags, int num_args, char *type_spec, ...);
18
19The zend_parse_parameters() function takes the number of parameters
20passed to the extension function, the type specifier string, and the
21list of pointers to variables to store the results in. The _ex() version
22also takes 'flags' argument -- current only ZEND_PARSE_PARAMS_QUIET can
23be used as 'flags' to specify that the function should operate quietly
24and not output any error messages.
25
26Both functions return SUCCESS or FAILURE depending on the result.
27
28The auto-conversions are performed as necessary. Arrays, objects, and
29resources cannot be auto-converted.
30
31PHP 5.3 includes a new function (actually implemented as macro):
32
33int zend_parse_parameters_none();
34
35This returns SUCCESS if no argument has been passed to the function,
36FAILURE otherwise.
37
38PHP 5.5 includes a new function:
39
40int zend_parse_parameter(int flags, int arg_num, zval **arg, const char *spec, ...);
41
42This function behaves like zend_parse_parameters_ex() except that instead of
43reading the arguments from the stack, it receives a single zval to convert
44(passed with double indirection). The passed zval may be changed in place as
45part of the conversion process.
46
47See also https://wiki.php.net/rfc/zpp_improv#expose_zend_parse_arg_as_zend_parse_parameter
48
49
50Type specifiers
51---------------
52 The following list shows the type specifier, its meaning and the parameter
53 types that need to be passed by address. All passed parameters are set
54 if the PHP parameter is non optional and untouched if optional and the
55 parameter is not present. The only exception is O where the zend_class_entry*
56 has to be provided on input and is used to verify the PHP parameter is an
57 instance of that class.
58
59 a - array (zval*)
60 A - array or object (zval*)
61 b - boolean (zend_bool)
62 C - class (zend_class_entry*)
63 d - double (double)
64 f - function or array containing php method call info (returned as
65 zend_fcall_info and zend_fcall_info_cache)
66 h - array (returned as HashTable*)
67 H - array or HASH_OF(object) (returned as HashTable*)
68 l - long (zend_long)
69 L - long, limits out-of-range numbers to LONG_MAX/LONG_MIN (zend_long, ZEND_LONG_MAX/ZEND_LONG_MIN)
70 o - object of any type (zval*)
71 O - object of specific type given by class entry (zval*, zend_class_entry)
72 p - valid path (string without null bytes in the middle) and its length (char*, size_t)
73 P - valid path (string without null bytes in the middle) as zend_string (zend_string*)
74 r - resource (zval*)
75 s - string (with possible null bytes) and its length (char*, size_t)
76 S - string (with possible null bytes) as zend_string (zend_string*)
77 z - the actual zval (zval*)
78 * - variable arguments list (0 or more)
79 + - variable arguments list (1 or more)
80
81 The following characters also have a meaning in the specifier string:
82 | - indicates that the remaining parameters are optional, they
83 should be initialized to default values by the extension since they
84 will not be touched by the parsing function if they are not
85 passed to it.
86 / - use SEPARATE_ZVAL_IF_NOT_REF() on the parameter it follows
87 ! - the parameter it follows can be of specified type or NULL. If NULL is
88 passed and the output for such type is a pointer, then the output
89 pointer is set to a native NULL pointer.
90 For 'b', 'l' and 'd', an extra argument of type zend_bool* must be
91 passed after the corresponding bool*, zend_long* or double* arguments,
92 respectively. A non-zero value will be written to the zend_bool if a
93 PHP NULL is passed.
94
95
96Note on 64bit compatibility
97---------------------------
98Please note that since version 7 PHP uses zend_long as integer type and
99zend_string with size_t as length, so make sure you pass zend_longs to "l"
100and size_t to strings length (i.e. for "s" you need to pass char * and size_t),
101not the other way round!
102
103Both mistakes might cause memory corruptions and segfaults:
1041)
105 char *str;
106 long str_len; /* XXX THIS IS WRONG!! Use size_t instead. */
107 zend_parse_parameters(ZEND_NUM_ARGS(), "s", &str, &str_len)
108
1092)
110 int num; /* XXX THIS IS WRONG!! Use zend_long instead. */
111 zend_parse_parameters(ZEND_NUM_ARGS(), "l", &num)
112
113If you're in doubt, use check_parameters.php script to the parameters
114and their types (it can be found in ./scripts/dev/ directory of PHP sources):
115
116# php ./scripts/dev/check_parameters.php /path/to/your/sources/
117
118
119Examples
120--------
121/* Gets a long, a string and its length, and a zval */
122zend_long l;
123char *s;
124size_t s_len;
125zval *param;
126if (zend_parse_parameters(ZEND_NUM_ARGS(), "lsz",
127 &l, &s, &s_len, ¶m) == FAILURE) {
128 return;
129}
130
131
132/* Gets an object of class specified by my_ce, and an optional double. */
133zval *obj;
134double d = 0.5;
135zend_class_entry *my_ce;
136if (zend_parse_parameters(ZEND_NUM_ARGS(), "O|d",
137 &obj, my_ce, &d) == FAILURE) {
138 return;
139}
140
141
142/* Gets an object or null, and an array.
143 If null is passed for object, obj will be set to NULL. */
144zval *obj;
145zval *arr;
146if (zend_parse_parameters(ZEND_NUM_ARGS(), "o!a",
147 &obj, &arr) == FAILURE) {
148 return;
149}
150
151
152/* Gets a separated array which can also be null. */
153zval *arr;
154if (zend_parse_parameters(ZEND_NUM_ARGS(), "a/!",
155 &arr) == FAILURE) {
156 return;
157}
158
159/* Get either a set of 3 longs or a string. */
160zend_long l1, l2, l3;
161char *s;
162/*
163 * The function expects a pointer to a size_t in this case, not a long
164 * or any other type. If you specify a type which is larger
165 * than a 'size_t', the upper bits might not be initialized
166 * properly, leading to random crashes on platforms like
167 * Tru64 or Linux/Alpha.
168 */
169size_t length;
170
171if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS(),
172 "lll", &l1, &l2, &l3) == SUCCESS) {
173 /* manipulate longs */
174} else if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS(),
175 "s", &s, &length) == SUCCESS) {
176 /* manipulate string */
177} else {
178 /* output error */
179
180 return;
181}
182
183
184/* Function that accepts only varargs (0 or more) */
185
186int i, num_varargs;
187zval *varargs = NULL;
188
189
190if (zend_parse_parameters(ZEND_NUM_ARGS(), "*", &varargs, &num_varargs) == FAILURE) {
191 return;
192}
193
194for (i = 0; i < num_varargs; i++) {
195 /* do something with varargs[i] */
196}
197
198if (varargs) {
199 efree(varargs);
200}
201
202
203/* Function that accepts a string, followed by varargs (1 or more) */
204
205char *str;
206size_t str_len;
207int i, num_varargs;
208zval *varargs = NULL;
209
210if (zend_parse_parameters(ZEND_NUM_ARGS(), "s+", &str, &str_len, &varargs, &num_varargs) == FAILURE) {
211 return;
212}
213
214for (i = 0; i < num_varargs; i++) {
215 /* do something with varargs[i] */
216}
217
218/* Function that takes an array, followed by varargs, and ending with a long */
219zend_long num;
220zval *array;
221int i, num_varargs;
222zval *varargs = NULL;
223
224if (zend_parse_parameters(ZEND_NUM_ARGS(), "a*l", &array, &varargs, &num_varargs, &num) == FAILURE) {
225 return;
226}
227
228for (i = 0; i < num_varargs; i++) {
229 /* do something with varargs[i] */
230}
231
232/* Function that doesn't accept any arguments */
233if (zend_parse_parameters_none() == FAILURE) {
234 return;
235}
236
README.REDIST.BINS
11. libmagic (ext/fileinfo) see ext/fileinfo/libmagic/LICENSE
22. Oniguruma (ext/mbstring) see ext/mbstring/oniguruma/COPYING
33. libmbfl (ext/mbstring) see ext/mbstring/libmbfl/LICENSE
44. pcre2lib (ext/pcre)
55. ext/standard crypt
66. ext/standard crypt's blowfish implementation
77. Sqlite/Sqlite3 ext/sqlite3 ext/sqlite
88. ext/standard/rand
99. ext/standard/scanf
1010. ext/standard/strnatcmp.c
1111. ext/standard/uuencode
1212. libxmlrpc ext/xmlrpc
1313. libzip ext/zip
1414. main/snprintf.c
1515. main/strlcat
1616. main/strlcpy
1717. libgd see ext/gd/libgd/COPYING
1818. ext/phar portions of tar implementations
1919. libbcmath (ext/bcmath) see ext/bcmath/libbcmath/COPYING.LIB
20
21
224. pcre2lib (ext/pcre)
23
24PCRE2 LICENCE
25-------------
26
27PCRE2 is a library of functions to support regular expressions whose syntax
28and semantics are as close as possible to those of the Perl 5 language.
29
30Release 10 of PCRE2 is distributed under the terms of the "BSD" licence, as
31specified below, with one exemption for certain binary redistributions. The
32documentation for PCRE2, supplied in the "doc" directory, is distributed under
33the same terms as the software itself. The data in the testdata directory is
34not copyrighted and is in the public domain.
35
36The basic library functions are written in C and are freestanding. Also
37included in the distribution is a just-in-time compiler that can be used to
38optimize pattern matching. This is an optional feature that can be omitted when
39the library is built.
40
41
42THE BASIC LIBRARY FUNCTIONS
43---------------------------
44
45Written by: Philip Hazel
46Email local part: ph10
47Email domain: cam.ac.uk
48
49University of Cambridge Computing Service,
50Cambridge, England.
51
52Copyright (c) 1997-2018 University of Cambridge
53All rights reserved.
54
55
56PCRE2 JUST-IN-TIME COMPILATION SUPPORT
57--------------------------------------
58
59Written by: Zoltan Herczeg
60Email local part: hzmester
61Emain domain: freemail.hu
62
63Copyright(c) 2010-2018 Zoltan Herczeg
64All rights reserved.
65
66
67STACK-LESS JUST-IN-TIME COMPILER
68--------------------------------
69
70Written by: Zoltan Herczeg
71Email local part: hzmester
72Emain domain: freemail.hu
73
74Copyright(c) 2009-2018 Zoltan Herczeg
75All rights reserved.
76
77
78THE "BSD" LICENCE
79-----------------
80
81Redistribution and use in source and binary forms, with or without
82modification, are permitted provided that the following conditions are met:
83
84 * Redistributions of source code must retain the above copyright notices,
85 this list of conditions and the following disclaimer.
86
87 * Redistributions in binary form must reproduce the above copyright
88 notices, this list of conditions and the following disclaimer in the
89 documentation and/or other materials provided with the distribution.
90
91 * Neither the name of the University of Cambridge nor the names of any
92 contributors may be used to endorse or promote products derived from this
93 software without specific prior written permission.
94
95THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
96AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
97IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
98ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
99LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
100CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
101SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
102INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
103CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
104ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
105POSSIBILITY OF SUCH DAMAGE.
106
107
108EXEMPTION FOR BINARY LIBRARY-LIKE PACKAGES
109------------------------------------------
110
111The second condition in the BSD licence (covering binary redistributions) does
112not apply all the way down a chain of software. If binary package A includes
113PCRE2, it must respect the condition, but if package B is software that
114includes package A, the condition is not imposed on package B unless it uses
115PCRE2 independently.
116
117End
118
119
1205. ext/standard crypt
121
122FreeSec: libcrypt for NetBSD
123
124Copyright (c) 1994 David Burren
125All rights reserved.
126
127Redistribution and use in source and binary forms, with or without
128modification, are permitted provided that the following conditions
129are met:
1301. Redistributions of source code must retain the above copyright
131 notice, this list of conditions and the following disclaimer.
1322. Redistributions in binary form must reproduce the above copyright
133 notice, this list of conditions and the following disclaimer in the
134 documentation and/or other materials provided with the distribution.
1353. Neither the name of the author nor the names of other contributors
136 may be used to endorse or promote products derived from this software
137 without specific prior written permission.
138
139THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
140ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
141IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
142ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
143FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
144DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
145OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
146HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
147LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
148OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
149SUCH DAMAGE.
150
151
1526. ext/standard crypt's blowfish implementation
153
154The crypt_blowfish homepage is:
155
156http://www.openwall.com/crypt/
157
158This code comes from John the Ripper password cracker, with reentrant
159and crypt(3) interfaces added, but optimizations specific to password
160cracking removed.
161
162Written by Solar Designer <solar at openwall.com> in 1998-2011.
163No copyright is claimed, and the software is hereby placed in the public
164domain. In case this attempt to disclaim copyright and place the software
165in the public domain is deemed null and void, then the software is
166Copyright (c) 1998-2011 Solar Designer and it is hereby released to the
167general public under the following terms:
168
169Redistribution and use in source and binary forms, with or without
170modification, are permitted.
171
172There's ABSOLUTELY NO WARRANTY, express or implied.
173
174It is my intent that you should be able to use this on your system,
175as part of a software package, or anywhere else to improve security,
176ensure compatibility, or for any other purpose. I would appreciate
177it if you give credit where it is due and keep your modifications in
178the public domain as well, but I don't require that in order to let
179you place this code and any modifications you make under a license
180of your choice.
181
182This implementation is mostly compatible with OpenBSD's bcrypt.c (prefix
183"$2a$") by Niels Provos <provos at citi.umich.edu>, and uses some of his
184ideas. The password hashing algorithm was designed by David Mazieres
185<dm at lcs.mit.edu>. For more information on the level of compatibility,
186please refer to the comments in BF_set_key() and to the crypt(3) man page
187included in the crypt_blowfish tarball.
188
189There's a paper on the algorithm that explains its design decisions:
190
191http://www.usenix.org/events/usenix99/provos.html
192
193Some of the tricks in BF_ROUND might be inspired by Eric Young's
194Blowfish library (I can't be sure if I would think of something if I
195hadn't seen his code).
196
197
1987. Sqlite/Sqlite3 ext/sqlite3 ext/sqlite
199
200The author disclaims copyright to this source code. In place of
201a legal notice, here is a blessing:
202 May you do good and not evil.
203 May you find forgiveness for yourself and forgive others.
204 May you share freely, never taking more than you give.
205
206
2078. ext/standard/rand
208The following php_mt_...() functions are based on a C++ class MTRand by
209Richard J. Wagner. For more information see the web page at
210http://www-personal.engin.umich.edu/~wagnerr/MersenneTwister.html
211
212Mersenne Twister random number generator -- a C++ class MTRand
213Based on code by Makoto Matsumoto, Takuji Nishimura, and Shawn Cokus
214Richard J. Wagner v1.0 15 May 2003 rjwagner@writeme.com
215
216The Mersenne Twister is an algorithm for generating random numbers. It
217was designed with consideration of the flaws in various other generators.
218The period, 2^19937-1, and the order of equidistribution, 623 dimensions,
219are far greater. The generator is also fast; it avoids multiplication and
220division, and it benefits from caches and pipelines. For more information
221see the inventors' web page at http://www.math.keio.ac.jp/~matumoto/emt.html
222
223Reference
224M. Matsumoto and T. Nishimura, "Mersenne Twister: A 623-Dimensionally
225Equidistributed Uniform Pseudo-Random Number Generator", ACM Transactions on
226Modeling and Computer Simulation, Vol. 8, No. 1, January 1998, pp 3-30.
227
228Copyright (C) 1997 - 2002, Makoto Matsumoto and Takuji Nishimura,
229Copyright (C) 2000 - 2003, Richard J. Wagner
230All rights reserved.
231
232Redistribution and use in source and binary forms, with or without
233modification, are permitted provided that the following conditions
234are met:
235
2361. Redistributions of source code must retain the above copyright
237 notice, this list of conditions and the following disclaimer.
238
2392. Redistributions in binary form must reproduce the above copyright
240 notice, this list of conditions and the following disclaimer in the
241 documentation and/or other materials provided with the distribution.
242
2433. The names of its contributors may not be used to endorse or promote
244 products derived from this software without specific prior written
245 permission.
246
247THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
248"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
249LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
250A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
251CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
252EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
253PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
254PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
255LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
256NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
257SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
258
259
2609. ext/standard/scanf
261scanf.c --
262
263This file contains the base code which implements sscanf and by extension
264fscanf. Original code is from TCL8.3.0 and bears the following copyright:
265
266This software is copyrighted by the Regents of the University of
267California, Sun Microsystems, Inc., Scriptics Corporation,
268and other parties. The following terms apply to all files associated
269with the software unless explicitly disclaimed in individual files.
270
271The authors hereby grant permission to use, copy, modify, distribute,
272and license this software and its documentation for any purpose, provided
273that existing copyright notices are retained in all copies and that this
274notice is included verbatim in any distributions. No written agreement,
275license, or royalty fee is required for any of the authorized uses.
276Modifications to this software may be copyrighted by their authors
277and need not follow the licensing terms described here, provided that
278the new terms are clearly indicated on the first page of each file where
279they apply.
280
281IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY
282FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
283ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY
284DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE
285POSSIBILITY OF SUCH DAMAGE.
286
287THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
288INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,
289FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE
290IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE
291NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
292MODIFICATIONS.
293
294GOVERNMENT USE: If you are acquiring this software on behalf of the
295U.S. government, the Government shall have only "Restricted Rights"
296in the software and related documentation as defined in the Federal
297Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2). If you
298are acquiring the software on behalf of the Department of Defense, the
299software shall be classified as "Commercial Computer Software" and the
300Government shall have only "Restricted Rights" as defined in Clause
301252.227-7013 (c) (1) of DFARs. Notwithstanding the foregoing, the
302authors grant the U.S. Government and others acting in its behalf
303permission to use and distribute the software in accordance with the
304terms specified in this license.
305
30610. ext/standard/strnatcmp.c
307
308strnatcmp.c -- Perform 'natural order' comparisons of strings in C.
309Copyright (C) 2000 by Martin Pool <mbp@humbug.org.au>
310
311This software is provided 'as-is', without any express or implied
312warranty. In no event will the authors be held liable for any damages
313arising from the use of this software.
314
315Permission is granted to anyone to use this software for any purpose,
316including commercial applications, and to alter it and redistribute it
317freely, subject to the following restrictions:
318
3191. The origin of this software must not be misrepresented; you must not
320 claim that you wrote the original software. If you use this software
321 in a product, an acknowledgment in the product documentation would be
322 appreciated but is not required.
3232. Altered source versions must be plainly marked as such, and must not be
324 misrepresented as being the original software.
3253. This notice may not be removed or altered from any source distribution.
326
32711. ext/standard/uuencode
328Portions of this code are based on Berkeley's uuencode/uudecode
329implementation.
330
331Copyright (c) 1983, 1993
332The Regents of the University of California. All rights reserved.
333
334Redistribution and use in source and binary forms, with or without
335modification, are permitted provided that the following conditions
336are met:
3371. Redistributions of source code must retain the above copyright
338 notice, this list of conditions and the following disclaimer.
3392. Redistributions in binary form must reproduce the above copyright
340 notice, this list of conditions and the following disclaimer in the
341 documentation and/or other materials provided with the distribution.
3423. All advertising materials mentioning features or use of this software
343 must display the following acknowledgement:
344This product includes software developed by the University of
345California, Berkeley and its contributors.
3464. Neither the name of the University nor the names of its contributors
347 may be used to endorse or promote products derived from this software
348 without specific prior written permission.
349
350THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
351ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
352IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
353ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
354FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
355DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
356OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
357HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
358LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
359OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
360SUCH DAMAGE.
361
362
36312. libxmlrpc ext/xmlrpc
364
365Copyright 2000 Epinions, Inc.
366
367Subject to the following 3 conditions, Epinions, Inc. permits you, free
368of charge, to (a) use, copy, distribute, modify, perform and display this
369software and associated documentation files (the "Software"), and (b)
370permit others to whom the Software is furnished to do so as well.
371
3721) The above copyright notice and this permission notice shall be included
373without modification in all copies or substantial portions of the
374Software.
375
3762) THE SOFTWARE IS PROVIDED "AS IS", WITHOUT ANY WARRANTY OR CONDITION OF
377ANY KIND, EXPRESS, IMPLIED OR STATUTORY, INCLUDING WITHOUT LIMITATION ANY
378IMPLIED WARRANTIES OF ACCURACY, MERCHANTABILITY, FITNESS FOR A PARTICULAR
379PURPOSE OR NONINFRINGEMENT.
380
3813) IN NO EVENT SHALL EPINIONS, INC. BE LIABLE FOR ANY DIRECT, INDIRECT,
382SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES OR LOST PROFITS ARISING OUT
383OF OR IN CONNECTION WITH THE SOFTWARE (HOWEVER ARISING, INCLUDING
384NEGLIGENCE), EVEN IF EPINIONS, INC. IS AWARE OF THE POSSIBILITY OF SUCH
385DAMAGES.
386
38713. libzip ext/zip
388zip.h -- exported declarations.
389Copyright (C) 1999-2009 Dieter Baron and Thomas Klausner
390
391This file is part of libzip, a library to manipulate ZIP archives.
392The authors can be contacted at <libzip@nih.at>
393
394Redistribution and use in source and binary forms, with or without
395modification, are permitted provided that the following conditions
396are met:
3971. Redistributions of source code must retain the above copyright
398 notice, this list of conditions and the following disclaimer.
3992. Redistributions in binary form must reproduce the above copyright
400 notice, this list of conditions and the following disclaimer in
401 the documentation and/or other materials provided with the
402 distribution.
4033. The names of the authors may not be used to endorse or promote
404 products derived from this software without specific prior
405 written permission.
406
407THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS
408OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
409WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
410ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY
411DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
412DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
413GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
414INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
415IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
416OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
417IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
418
41914. main/snprintf.c
420Copyright (c) 2002, 2006 Todd C. Miller <Todd.Miller@courtesan.com>
421
422Permission to use, copy, modify, and distribute this software for any
423purpose with or without fee is hereby granted, provided that the above
424copyright notice and this permission notice appear in all copies.
425
426THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
427WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
428MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
429ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
430WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
431ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
432OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
433
434Sponsored in part by the Defense Advanced Research Projects
435Agency (DARPA) and Air Force Research Laboratory, Air Force
436Materiel Command, USAF, under agreement number F39502-99-1-0512.
437
438main/spprintf
439Copyright (c) 1995-1998 The Apache Group. All rights reserved.
440
441Redistribution and use in source and binary forms, with or without
442modification, are permitted provided that the following conditions
443are met:
444
4451. Redistributions of source code must retain the above copyright
446 notice, this list of conditions and the following disclaimer.
447
4482. Redistributions in binary form must reproduce the above copyright
449 notice, this list of conditions and the following disclaimer in
450 the documentation and/or other materials provided with the
451 distribution.
452
4533. All advertising materials mentioning features or use of this
454 software must display the following acknowledgment:
455 "This product includes software developed by the Apache Group
456 for use in the Apache HTTP server project (http://www.apache.org/)."
457
4584. The names "Apache Server" and "Apache Group" must not be used to
459 endorse or promote products derived from this software without
460 prior written permission.
461
4625. Redistributions of any form whatsoever must retain the following
463 acknowledgment:
464 "This product includes software developed by the Apache Group
465 for use in the Apache HTTP server project (http://www.apache.org/)."
466
467THIS SOFTWARE IS PROVIDED BY THE APACHE GROUP ``AS IS'' AND ANY
468EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
469IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
470PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE GROUP OR
471ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
472SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
473NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
474LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
475HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
476STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
477ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
478OF THE POSSIBILITY OF SUCH DAMAGE.
479====================================================================
480
481This software consists of voluntary contributions made by many
482individuals on behalf of the Apache Group and was originally based
483on public domain software written at the National Center for
484Supercomputing Applications, University of Illinois, Urbana-Champaign.
485For more information on the Apache Group and the Apache HTTP server
486project, please see <http://www.apache.org/>.
487
488This code is based on, and used with the permission of, the
489SIO stdio-replacement strx_* functions by Panos Tsirigotis
490<panos@alumni.cs.colorado.edu> for xinetd.
491
49215. main/strlcat
49316. main/strlcpy
494Copyright (c) 1998 Todd C. Miller <Todd.Miller@courtesan.com>
495All rights reserved.
496
497Redistribution and use in source and binary forms, with or without
498modification, are permitted provided that the following conditions
499are met:
5001. Redistributions of source code must retain the above copyright
501 notice, this list of conditions and the following disclaimer.
5022. Redistributions in binary form must reproduce the above copyright
503 notice, this list of conditions and the following disclaimer in the
504 documentation and/or other materials provided with the distribution.
5053. The name of the author may not be used to endorse or promote products
506 derived from this software without specific prior written permission.
507
508THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
509INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
510AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
511THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
512EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
513PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
514OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
515WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
516OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
517ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
518
51918. ext/phar portions of tar implementations
520
521portions of tar implementations in ext/phar - phar_tar_octal() are based on an
522implementation by Tim Kientzle from libarchive, licensed with this license:
523
524 Copyright (c) 2003-2007 Tim Kientzle
525 All rights reserved.
526
527 Redistribution and use in source and binary forms, with or without
528 modification, are permitted provided that the following conditions
529 are met:
530 1. Redistributions of source code must retain the above copyright
531 notice, this list of conditions and the following disclaimer.
532 2. Redistributions in binary form must reproduce the above copyright
533 notice, this list of conditions and the following disclaimer in the
534 documentation and/or other materials provided with the distribution.
535
536 THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) ``AS IS'' AND ANY EXPRESS OR
537 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
538 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
539 IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT, INDIRECT,
540 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
541 NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
542 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
543 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
544 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
545 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
546
README.RELEASE_PROCESS
1=======================
2 PHP Release Process
3=======================
4
5General notes and tips
6----------------------
7
81. Do not release on Fridays, Saturdays or Sundays
9because the sysadmins can not upgrade stuff then.
10
112. Package two days before a release. So if the release is to be on Thursday,
12package on Tuesday. Think about timezones as well.
13
143. Ensure that the tests on Travis CI are green.
15See: https://travis-ci.org/php/php-src/builds
16It is recommended to do so a couple of days before the packaging day, to
17have enough time to investigate failures, communicate with the authors and
18commit the fixes.
19The RM for the branch is also responsible for keeping the CI green on
20ongoing basis between the releases. Check the CI status for your branch
21periodically and resolve the failures ASAP. See more in:
22https://wiki.php.net/rfc/travis_ci
23
244. Ensure that Windows builds will work before packaging
25
265. Follow all steps to the letter. When unclear ask previous RM's (David/Julien/
27Johannes/Stas/Derick/Ilia) before proceeding. Ideally make sure that for the
28first releases one of the previous RM's is around to answer questions. For the
29steps related to the php/QA/bug websites try to have someone from the webmaster
30team (Bjori) on hand.
31
326. Verify the tags to be extra sure everything was tagged properly.
33
347. Moving extensions from/to PECL requires write access to the destination.
35Most developers should have this.
36
37Moving extensions from php-src to PECL
38- Checkout the pecl directory, most likely you want a sparse-root checkout
39 svn co --depth=empty https://svn.php.net/repository/pecl
40- Create a directory for the extension incl. branch and tag structure,
41 no trunk at this point and commit this to svn
42 cd pecl; mkdir foo foo/tags foo/branches; svn add foo; svn commit
43- Move the extension from php-src to the new location
44 svn mv https://svn.php.net/repository/php/php-src/trunk/ext/foo \
45 https://svn.php.net/repository/pecl/foo/trunk
46
47If the extension is still usable or not dead, in cooperation with the extension
48maintainers if any:
49- create the pecl.php.net/foo package and its content, license, maintainer
50- create the package.xml, commit
51- release the package
52
53For Moving extensions from PECL to php-src the svn mv has to be done the other
54way round.
55
56Rolling a non stable release (alpha/beta/RC)
57--------------------------------------------
58
591. Check windows snapshot builder logs (http://windows.php.net/downloads/snaps/ the last revision)
60
612. Check the tests at https://travis-ci.org/php/php-src/builds
62
633. run the "scripts/dev/credits" script in php-src and commit the changes in the
64credits files in ext/standard.
65
664. Checkout the release branch for this release (e.g., PHP-5.4.2) from the main branch.
67
685. Bump the version numbers in ``main/php_version.h``, ``configure.ac`` and possibly ``NEWS``.
69Do not use abbreviations for alpha and beta. Do not use dashes, you should
70``#define PHP_VERSION "5.4.22RC1"`` and not ``#define PHP_VERSION "5.4.22-RC1"``
71
726. Compile and make test, with and without ZTS, using the right Bison version
73(for example, for 5.5, Bison 2.4.1 is used)
74
757. Check ./sapi/cli/php -v output for version matching.
76
778. If all is right, commit the changes to the release branch with ``git commit -a``.
78
799. Tag the repository release branch with the version, e.g.:
80``git tag -u YOURKEYID php-5.4.2RC2``
81
8210. Bump the version numbers in ``main/php_version.h``, ``configure.ac`` and ``NEWS``
83in the *main* branch (PHP-5.4 for example) to prepare for the **next** version.
84F.e. if the RC is "5.4.1RC1" then the new one should be "5.4.2-dev" - regardless if we get
85a new RC or not. This is to make sure ``version_compare()`` can correctly work.
86Commit the changes to the main branch.
87
8811. Push the changes to the main repo, the tag, the main branch and the release branch :
89``git push --tags origin HEAD``
90``git push origin {main branch}``
91``git push origin {release branch}``
92
9312. run: ``PHPROOT=. ./makedist 5.4.2RC2``, this will export the tree, create configure
94and build three tarballs (gz, bz2 and xz).
95
9613. run ``scripts/dev/gen_verify_stub <version> [identity]``, this will sign the tarballs
97and output verification information to be included in announcement email
98
9914. Copy those tarballs (scp, rsync) to downloads.php.net, in your homedir there should be a
100directory "public_html/". Copy them into there, so that the system can generate
101MD5 sums. If you do not have this directory, create it.
102
10315. Now the RC can be found on http://downloads.php.net/~yourname,
104f.e. http://downloads.php.net/~derick/
105
10616. Once the release has been tagged, contact the release-managers@ distribution list
107so that Windows binaries can be created. Once those are made, they can be found at
108http://windows.php.net/download
109
110Getting the non stable release (alpha/beta/RC) announced
111--------------------------------------------------------
112
1131. Update ``qa.git/include/release-qa.php`` with the appropriate information.
114 See the documentation within release-qa.php for more information, but all releases
115 and RCs are configured here. Only $QA_RELEASES needs to be edited.
116
117 Example: When rolling an RC, set the 'rc' with appropriate information for the
118 given version.
119
120 Note: Remember to update the MD5 and sha256 checksum information.
121
1222. Update ``web/php.git/include/version.inc`` (x=major version number)
123
124 a. ``$PHP_x_RC`` = "5.4.0RC1" (should be set to "false" before)
125
126 b. ``$PHP_x_RC_DATE`` = "06 September 2007"
127
1283. Add a short notice to phpweb stating that there is a new release, and
129highlight the major important things (security fixes) and when it is important
130to upgrade.
131
132 a. Call php bin/createNewsEntry in your local phpweb checkout
133 Use category "releases" for all stable releases.
134 Use category "frontpage" for X.Y.0 non-stable releases only (news only).
135
136 b. Add the content for the news entry. Be sure to include the text:
137 "THIS IS A DEVELOPMENT PREVIEW - DO NOT USE IT IN PRODUCTION!"
138
1394. Commit and push changes to qa and web
140
141*Wait for web and qa sites to update with new information before sending announce*
142
1435. Send **separate** emails **To** ``internals@lists.php.net`` and ``php-general@lists.php.net``
144lists pointing out "the location of the release" and "the possible release date of
145either the next RC, or the final release". Include in this information the verification
146information output by ``gen_verify_stub``.
147
1486. Send **separate** emails (see example here http://news.php.net/php.pear.qa/5201) **To**
149``php-qa@lists.php.net`` and ``primary-qa-tester@lists.php.net``.
150These emails are to notify the selected projects about a new release so that they
151can make sure their projects keep working. Make sure that you have been setup
152as a moderator for ``primary-qa-tester@lists.php.net`` by having someone (Hannes, Dan,
153Derick) run the following commands for you:
154
155``ssh lists.php.net``
156
157``sudo -u ezmlm ezmlm-sub ~ezmlm/primary-qa-tester/mod moderator-email-address``
158
159Rolling a stable release
160------------------------
161
1621. Checkout your release branch, you should have created when releasing previous RC
163and bump the version numbers in ``main/php_version.h``, ``configure.ac`` and possibly ``NEWS``.
164
1652. If a CVE commit needs to be merged to the release, then have it committed to
166the base branches and merged upwards as usual (f.e commit the CVE fix to 5.3,
167merge to 5.4, 5.5 etc...). Then you can cherry-pick it in your release branch.
168Don't forget to update NEWS manually in an extra commit then.
169
1703. Commit those changes. Ensure the tests at https://travis-ci.org/php/php-src/builds are
171still passing.
172
1734. run the "scripts/dev/credits" script in php-src and commit the changes in the
174credits files in ext/standard.
175
1765. Compile and make test, with and without ZTS, using the right Bison version
177(for example, for 5.5, Bison 2.4.1 is used)
178
1796. Check ./sapi/cli/php -v output for version matching.
180
1817. tag the repository with the version f.e. "``git tag -u YOURKEYID -s php-5.4.1``"
182
1838. Push the tag f.e. "``git push origin php-5.4.1``"
184
1859. run: ``PHPROOT=. ./makedist php 5.4.1``, this will export the tag, create configure
186and build three tarballs (gz, bz2 and xz).
187 Check if the pear files are updated (phar).
188 On some systems the behavior of GNU tar can default to produce POSIX compliant archives
189with PAX headers. As not every application is compatible with that format, creation of
190archives with PAX headers should be avoided. When packaging on such a system, the GNU tar
191can be influenced by defining the environment variable TAR_OPTIONS='--format=gnu'.
192
19310. Generate the GPG signature files for the archives.
194 ``gpg -u YOUREMAIL --armor --detach-sign php-X.Y.Z.tar.xxx``
195
19611. Commit and push all the tarballs and signature files to web/php-distributions.git,
197 then update the git submodule reference in web/php.git:
198 ``git submodule init;
199 git submodule update;
200 cd distributions;
201 git fetch;
202 git pull --rebase origin master;
203 cd ..;
204 git commit distributions;
205 git push;``
206This is to fetch the last commit id from php-distributions.git and commit this
207last commit id to web/php.git, then, mirrors will now sync
208
20912. Once the release has been tagged, contact release managers, windows builders, and package maintainers
210so that they can build releases. Do not send this announcement to any public lists.
211
212Getting the stable release announced
213------------------------------------
214
2151. Update phpweb/include/releases.inc with the old release info
216 (updates the download archives)
217
218 a. You can run ``php bin/bumpRelease 5`` if you are making a release for the
219 highest branch, otherwise you have to do this manually, see point 1.b
220
221 b. In case multiple PHP minor versions are in active development you have
222 to manually copy the old information to include/releases.inc
223
2242. Edit ``phpweb/include/version.inc`` and change (X=major release number):
225
226 a. ``$PHP_X_VERSION`` to the correct version
227
228 b. ``$PHP_X_DATE`` to the release date
229
230 c. ``$PHP_X_MD5`` array and update all the md5 sums
231
232 d. ``$PHP_X_SHA256`` array and update all the SHA256 sums
233
234 e. set ``$PHP_X_RC`` to false!
235
236 f. Make sure there are no outdated "notes" or edited "date" keys in the
237 ``$RELEASES[X][$PHP_X_VERSION]["source"]`` array
238
239 g. if the windows builds aren't ready yet prefix the "windows" key with a dot (".windows")
240
2413. Create the release file (releases/x_y_z.php)
242 Usually we use the same content as for point 6, but included in php template
243 instead of the release xml.
244
2454. Update php-qa/include/release-qa.php and add the next version as an QARELEASE
246 (prepare for next RC)
247
2485. Update the ChangeLog file for the given major version
249f.e. ``ChangeLog-5.php`` from the NEWS file
250
251 a. go over the list and put every element on one line
252
253 b. check for &, < and > and escape them if necessary
254
255 c. remove all the names at the ends of lines
256
257 d. for marking up, you can do the following (with VI):
258
259 I. ``s/^- /<li>/``
260
261 II. ``s/$/<\/li>/``
262
263 III. ``s/Fixed bug #\([0-9]\+\)/<?php bugfix(\1); ?>/``
264
265 IV. ``s/Fixed PECL bug #\([0-9]\+\)/<?php peclbugfix(\1); ?>/``
266
267 V. ``s/FR #\([0-9]\+\)/FR <?php bugl(\1); ?>/``
268
269 e. You may want to try php-web/bin/news2html to automate this task
270
2716. Add a short notice to phpweb stating that there is a new release, and
272highlight the major important things (security fixes) and when it is important
273to upgrade.
274
275 a. Call php bin/createNewsEntry in your local phpweb checkout
276
277 b. Add the content for the news entry
278
2797. **Check mirrors have been synced before announcing or pushing news**
280 Try, f.e. http://www.php.net/get/php-5.5.1.tar.bz2/from/a/mirror
281 Try several mirrors, mirrors may update slowly (may take an hour)
282
2838. Commit all the changes to their respective git repos
284
2859. Please note down the sha256 and the PGP signature (.asc). These *must* be
286 included in the release mail.
28710. Wait an hour or two, then send a mail to php-announce@lists.php.net,
288php-general@lists.php.net and internals@lists.php.net with a text similar to
289http://news.php.net/php.internals/17222.
290Please make sure that the mail to php-announce@ is its own completely separate email.
291This is to make sure that replies to the announcement on php-general@ or internals@
292will not accidentally hit the php-announce@ mailinglist.
293
294Re-releasing the same version (or -pl)
295--------------------------------------
296
2971. Commit the new binaries to ``phpweb/distributions/``
298
2992. Edit ``phpweb/include/version.inc`` and change (X=major release number):
300
301 a. If only releasing for one OS, make sure you edit only those variables
302
303 b. ``$PHP_X_VERSION`` to the correct version
304
305 c. ``$PHP_X_DATE`` to the release date
306
307 d. ``$PHP_X_MD5`` array and update all the md5 sums
308
309 e. ``$PHP_X_SHA256`` array and update all the SHA256 sums
310
311 f. Make sure there are no outdated "notes" or edited "date" keys in the
312 ``$RELEASES[X][$PHP_X_VERSION]["source"]`` array
313
3143. Add a short notice to phpweb stating that there is a new release, and
315highlight the major important things (security fixes) and when it is important
316to upgrade.
317
318 a. Call php bin/createNewsEntry in your local phpweb checkout
319
320 b. Add the content for the news entry
321
3224. Commit all the changes (``include/version.inc``, ``archive/archive.xml``,
323``archive/entries/YYYY-MM-DD-N.xml``)
324
3255. Wait an hour or two, then send a mail to php-announce@lists.php.net,
326php-general@lists.php.net and internals@lists.php.net with a text similar to
327the news entry.
328Please make sure that the mail to php-announce@ is its own completely separate email.
329This is to make sure that replies to the announcement on php-general@ or internals@
330will not accidentally hit the php-announce@ mailinglist.
331
332Forking a new release branch
333----------------------------
334
3351. One week prior to cutting X.Y.0beta1, warn internals@ that your version's branch
336 is about to be cut, and that PHP-X.Y will be moving into feature freeze.
337 Try to be specific about when the branch will be cut.
338 Example: http://news.php.net/php.internals/99864
339
3402. Just prior to cutting X.Y.0beta1, create the new branch locally.
341 Add a commit on master after the branch point clearing the NEWS file, and updating
342 main/php_versions.h and Zend/zend.h to update versions.
343 Example: https://github.com/php/php-src/commit/5230541ef59e0637d5522293a7d099bf18ce6af3
344 Push the new branch and the commit just added to master.
345
3463. Immediately notify internals@ of the branch cut and advise the new merging order:
347 Example: http://news.php.net/php.internals/99903
348
3494. Update php-web:git.php and wiki.php.net/vcs/gitworkflow to reflect the new branch:
350 Example: https://github.com/php/web-php/commit/74bcad4c770d95f21b7fbeeedbd76d943bb83f23
351
3525. Notify nlopess@ to add PHP_X_Y tag to gcov.php.net
353
354New Release Manager Checklist
355-----------------------------
356
3571. Email systems@ to get setup for access to downloads.php.net and to be added to the
358 release-managers@ distribution list.
359
3602. Create a GPG key for your @php.net address and publish it by editing `include/gpg-keys.inc`
361 in the `web-php` repository, adding the output of `gpg --fingerprint "$USER@php.net"`. Let
362 one or more of the previous RMs sign your key. Publish your public key to pgp.mit.edu with:
363 `gpg --keyserver pgp.mit.edu --send-keys $KEYID`
364
3653. Request karma to edit main/php_version.h. Possibly karma for other restricted parts of
366 php-src might come in question.
367
3684. Request karma for web/qa.git and web/php.git for publishing release announcements.
369
3705. Request moderation access to announce@php.net and primary-qa-tester@lists.php.net lists, to
371 be able to moderate your release announcements. All the announcements should be sent from
372 the @php.net alias.
373
README.SELF-CONTAINED-EXTENSIONS
1HOW TO CREATE A SELF-CONTAINED PHP EXTENSION
2
3 A self-contained extension can be distributed independently of
4 the PHP source. To create such an extension, two things are
5 required:
6
7 - Configuration file (config.m4)
8 - Source code for your module
9
10 We will describe now how to create these and how to put things
11 together.
12
13PREPARING YOUR SYSTEM
14
15 While the result will run on any system, a developer's setup needs these
16 tools:
17
18 GNU autoconf
19 GNU automake
20 GNU libtool
21 GNU m4
22
23 All of these are available from
24
25 ftp://ftp.gnu.org/pub/gnu/
26
27CONVERTING AN EXISTING EXTENSION
28
29 Just to show you how easy it is to create a self-contained
30 extension, we will convert an embedded extension into a
31 self-contained one. Install PHP and execute the following
32 commands.
33
34 $ mkdir /tmp/newext
35 $ cd /tmp/newext
36
37 You now have an empty directory. We will copy the files from
38 the mysql extension:
39
40 $ cp -rp php-4.0.X/ext/mysql/* .
41
42 It is time to finish the module. Run:
43
44 $ phpize
45
46 You can now ship the contents of the directory - the extension
47 can live completely on its own.
48
49 The user instructions boil down to
50
51 $ ./configure \
52 [--with-php-config=/path/to/php-config] \
53 [--with-mysql=MYSQL-DIR]
54 $ make install
55
56 The MySQL module will either use the embedded MySQL client
57 library or the MySQL installation in MYSQL-DIR.
58
59
60DEFINING THE NEW EXTENSION
61
62 Our demo extension is called "foobar".
63
64 It consists of two source files "foo.c" and "bar.c"
65 (and any arbitrary amount of header files, but that is not
66 important here).
67
68 The demo extension does not reference any external
69 libraries (that is important, because the user does not
70 need to specify anything).
71
72
73 LTLIBRARY_SOURCES specifies the names of the sources files. You can
74 name an arbitrary number of source files here.
75
76CREATING THE M4 CONFIGURATION FILE
77
78 The m4 configuration can perform additional checks. For a
79 self-contained extension, you do not need more than a few
80 macro calls.
81
82------------------------------------------------------------------------------
83PHP_ARG_ENABLE(foobar,whether to enable foobar,
84[ --enable-foobar Enable foobar])
85
86if test "$PHP_FOOBAR" != "no"; then
87 PHP_NEW_EXTENSION(foobar, foo.c bar.c, $ext_shared)
88fi
89------------------------------------------------------------------------------
90
91 PHP_ARG_ENABLE will automatically set the correct variables, so
92 that the extension will be enabled by PHP_NEW_EXTENSION in shared mode.
93
94 The first argument of PHP_NEW_EXTENSION describes the name of the
95 extension. The second names the source-code files. The third passes
96 $ext_shared which is set by PHP_ARG_ENABLE/WITH to PHP_NEW_EXTENSION.
97
98 Please use always PHP_ARG_ENABLE or PHP_ARG_WITH. Even if you do not
99 plan to distribute your module with PHP, these facilities allow you
100 to integrate your module easily into the main PHP module framework.
101
102CREATING SOURCE FILES
103
104 ext_skel can be of great help when creating the common code for all modules
105 in PHP for you and also writing basic function definitions and C code for
106 handling arguments passed to your functions. See README.EXT_SKEL for further
107 information.
108
109 As for the rest, you are currently alone here. There are a lot of existing
110 modules, use a simple module as a starting point and add your own code.
111
112
113CREATING THE SELF-CONTAINED EXTENSION
114
115 Put config.m4 and the source files into one directory. Then, run phpize
116 (this is installed during make install by PHP 4.0).
117
118 For example, if you configured PHP with --prefix=/php, you would run
119
120 $ /php/bin/phpize
121
122 This will automatically copy the necessary build files and create
123 configure from your config.m4.
124
125 And that's it. You now have a self-contained extension.
126
127INSTALLING A SELF-CONTAINED EXTENSION
128
129 An extension can be installed by running:
130
131 $ ./configure \
132 [--with-php-config=/path/to/php-config]
133 $ make install
134
135ADDING SHARED MODULE SUPPORT TO A MODULE
136
137 In order to be useful, a self-contained extension must be loadable
138 as a shared module. I will explain now how you can add shared module
139 support to an existing module called foo.
140
141 1. In config.m4, use PHP_ARG_WITH/PHP_ARG_ENABLE. Then you will
142 automatically be able to use --with-foo=shared[,..] or
143 --enable-foo=shared[,..].
144
145 2. In config.m4, use PHP_NEW_EXTENSION(foo,.., $ext_shared) to enable
146 building the extension.
147
148 3. Add the following lines to your C source file:
149
150 #ifdef COMPILE_DL_FOO
151 ZEND_GET_MODULE(foo)
152 #endif
153
154PECL SITE CONFORMITY
155
156 If you plan to release an extension to the PECL website, there are several
157 points to be regarded.
158
159 1. Add LICENSE or COPYING to the package.xml
160
161 2. The following should be defined in one of the extension header files
162
163 #define PHP_FOO_VERSION "1.2.3"
164
165 This macros has to be used within your foo_module_entry to indicate the
166 extension version.
167
README.STREAMS
1An Overview of the PHP Streams abstraction
2==========================================
3
4WARNING: some prototypes in this file are out of date.
5The information contained here is being integrated into
6the PHP manual - stay tuned...
7
8Please send comments to: Wez Furlong <wez@thebrainroom.com>
9
10Why Streams?
11============
12You may have noticed a shed-load of issock parameters flying around the PHP
13code; we don't want them - they are ugly and cumbersome and force you to
14special case sockets and files every time you need to work with a "user-level"
15PHP file pointer.
16Streams take care of that and present the PHP extension coder with an ANSI
17stdio-alike API that looks much nicer and can be extended to support non file
18based data sources.
19
20Using Streams
21=============
22Streams use a php_stream* parameter just as ANSI stdio (fread etc.) use a
23FILE* parameter.
24
25The main functions are:
26
27PHPAPI size_t php_stream_read(php_stream * stream, char * buf, size_t count);
28PHPAPI size_t php_stream_write(php_stream * stream, const char * buf, size_t
29 count);
30PHPAPI size_t php_stream_printf(php_stream * stream,
31 const char * fmt, ...);
32PHPAPI int php_stream_eof(php_stream * stream);
33PHPAPI int php_stream_getc(php_stream * stream);
34PHPAPI char *php_stream_gets(php_stream * stream, char *buf, size_t maxlen);
35PHPAPI int php_stream_close(php_stream * stream);
36PHPAPI int php_stream_flush(php_stream * stream);
37PHPAPI int php_stream_seek(php_stream * stream, off_t offset, int whence);
38PHPAPI off_t php_stream_tell(php_stream * stream);
39PHPAPI int php_stream_lock(php_stream * stream, int mode);
40
41These (should) behave in the same way as the ANSI stdio functions with similar
42names: fread, fwrite, fprintf, feof, fgetc, fgets, fclose, fflush, fseek, ftell, flock.
43
44Opening Streams
45===============
46In most cases, you should use this API:
47
48PHPAPI php_stream *php_stream_open_wrapper(const char *path, const char *mode,
49 int options, char **opened_path);
50
51Where:
52 path is the file or resource to open.
53 mode is the stdio compatible mode eg: "wb", "rb" etc.
54 options is a combination of the following values:
55 IGNORE_PATH (default) - don't use include path to search for the file
56 USE_PATH - use include path to search for the file
57 IGNORE_URL - do not use plugin wrappers
58 REPORT_ERRORS - show errors in a standard format if something
59 goes wrong.
60 STREAM_MUST_SEEK - If you really need to be able to seek the stream
61 and don't need to be able to write to the original
62 file/URL, use this option to arrange for the stream
63 to be copied (if needed) into a stream that can
64 be seek()ed.
65
66 opened_path is used to return the path of the actual file opened,
67 but if you used STREAM_MUST_SEEK, may not be valid. You are
68 responsible for efree()ing opened_path. opened_path may be (and usually
69 is) NULL.
70
71If you need to open a specific stream, or convert standard resources into
72streams there are a range of functions to do this defined in php_streams.h.
73A brief list of the most commonly used functions:
74
75PHPAPI php_stream *php_stream_fopen_from_file(FILE *file, const char *mode);
76 Convert a FILE * into a stream.
77
78PHPAPI php_stream *php_stream_fopen_tmpfile(void);
79 Open a FILE * with tmpfile() and convert into a stream.
80
81PHPAPI php_stream *php_stream_fopen_temporary_file(const char *dir,
82 const char *pfx, char **opened_path);
83 Generate a temporary file name and open it.
84
85There are some network enabled relatives in php_network.h:
86
87PHPAPI php_stream *php_stream_sock_open_from_socket(int socket, int persistent);
88 Convert a socket into a stream.
89
90PHPAPI php_stream *php_stream_sock_open_host(const char *host, unsigned short port,
91 int socktype, int timeout, int persistent);
92 Open a connection to a host and return a stream.
93
94PHPAPI php_stream *php_stream_sock_open_unix(const char *path, int persistent,
95 struct timeval *timeout);
96 Open a UNIX domain socket.
97
98
99Stream Utilities
100================
101
102If you need to copy some data from one stream to another, you will be please
103to know that the streams API provides a standard way to do this:
104
105PHPAPI size_t php_stream_copy_to_stream(php_stream *src,
106 php_stream *dest, size_t maxlen);
107
108If you want to copy all remaining data from the src stream, pass
109PHP_STREAM_COPY_ALL as the maxlen parameter, otherwise maxlen indicates the
110number of bytes to copy.
111This function will try to use mmap where available to make the copying more
112efficient.
113
114If you want to read the contents of a stream into an allocated memory buffer,
115you should use:
116
117PHPAPI size_t php_stream_copy_to_mem(php_stream *src, char **buf,
118 size_t maxlen, int persistent);
119
120This function will set buf to the address of the buffer that it allocated,
121which will be maxlen bytes in length, or will be the entire length of the
122data remaining on the stream if you set maxlen to PHP_STREAM_COPY_ALL.
123The buffer is allocated using pemalloc(); you need to call pefree() to
124release the memory when you are done.
125As with copy_to_stream, this function will try use mmap where it can.
126
127If you have an existing stream and need to be able to seek() it, you
128can use this function to copy the contents into a new stream that can
129be seek()ed:
130
131PHPAPI int php_stream_make_seekable(php_stream *origstream, php_stream **newstream);
132
133It returns one of the following values:
134#define PHP_STREAM_UNCHANGED 0 /* orig stream was seekable anyway */
135#define PHP_STREAM_RELEASED 1 /* newstream should be used; origstream is no longer valid */
136#define PHP_STREAM_FAILED 2 /* an error occurred while attempting conversion */
137#define PHP_STREAM_CRITICAL 3 /* an error occurred; origstream is in an unknown state; you should close origstream */
138
139make_seekable will always set newstream to be the stream that is valid
140if the function succeeds.
141When you have finished, remember to close the stream.
142
143NOTE: If you only need to seek forward, there is no need to call this
144function, as the php_stream_seek can emulate forward seeking when the
145whence parameter is SEEK_CUR.
146
147NOTE: Writing to the stream may not affect the original source, so it
148only makes sense to use this for read-only use.
149
150NOTE: If the origstream is network based, this function will block
151until the whole contents have been downloaded.
152
153NOTE: Never call this function with an origstream that is referenced
154as a resource! It will close the origstream on success, and this
155can lead to a crash when the resource is later used/released.
156
157NOTE: If you are opening a stream and need it to be seekable, use the
158STREAM_MUST_SEEK option to php_stream_open_wrapper();
159
160PHPAPI int php_stream_supports_lock(php_stream * stream);
161
162This function will return either 1 (success) or 0 (failure) indicating whether or
163not a lock can be set on this stream. Typically you can only set locks on stdio streams.
164
165Casting Streams
166===============
167What if your extension needs to access the FILE* of a user level file pointer?
168You need to "cast" the stream into a FILE*, and this is how you do it:
169
170FILE * fp;
171php_stream * stream; /* already opened */
172
173if (php_stream_cast(stream, PHP_STREAM_AS_STDIO, (void*)&fp, REPORT_ERRORS) == FAILURE) {
174 RETURN_FALSE;
175}
176
177The prototype is:
178
179PHPAPI int php_stream_cast(php_stream * stream, int castas, void ** ret, int
180 show_err);
181
182The show_err parameter, if non-zero, will cause the function to display an
183appropriate error message of type E_WARNING if the cast fails.
184
185castas can be one of the following values:
186PHP_STREAM_AS_STDIO - a stdio FILE*
187PHP_STREAM_AS_FD - a generic file descriptor
188PHP_STREAM_AS_SOCKETD - a socket descriptor
189
190If you ask a socket stream for a FILE*, the abstraction will use fdopen to
191create it for you. Be warned that doing so may cause buffered data to be lost
192if you mix ANSI stdio calls on the FILE* with php stream calls on the stream.
193
194If your system has the fopencookie function, php streams can synthesize a
195FILE* on top of any stream, which is useful for SSL sockets, memory based
196streams, data base streams etc. etc.
197
198In situations where this is not desirable, you should query the stream
199to see if it naturally supports FILE *. You can use this code snippet
200for this purpose:
201
202 if (php_stream_is(stream, PHP_STREAM_IS_STDIO)) {
203 /* can safely cast to FILE* with no adverse side effects */
204 }
205
206You can use:
207
208PHPAPI int php_stream_can_cast(php_stream * stream, int castas)
209
210to find out if a stream can be cast, without actually performing the cast, so
211to check if a stream is a socket you might use:
212
213if (php_stream_can_cast(stream, PHP_STREAM_AS_SOCKETD) == SUCCESS) {
214 /* it can be a socket */
215}
216
217Please note the difference between php_stream_is and php_stream_can_cast;
218stream_is tells you if the stream is a particular type of stream, whereas
219can_cast tells you if the stream can be forced into the form you request.
220The former doesn't change anything, while the later *might* change some
221state in the stream.
222
223Stream Internals
224================
225
226There are two main structures associated with a stream - the php_stream
227itself, which holds some state information (and possibly a buffer) and a
228php_stream_ops structure, which holds the "virtual method table" for the
229underlying implementation.
230
231The php_streams ops struct consists of pointers to methods that implement
232read, write, close, flush, seek, gets and cast operations. Of these, an
233implementation need only implement write, read, close and flush. The gets
234method is intended to be used for streams if there is an underlying method
235that can efficiently behave as fgets. The ops struct also contains a label
236for the implementation that will be used when printing error messages - the
237stdio implementation has a label of "STDIO" for example.
238
239The idea is that a stream implementation defines a php_stream_ops struct, and
240associates it with a php_stream using php_stream_alloc.
241
242As an example, the php_stream_fopen() function looks like this:
243
244PHPAPI php_stream * php_stream_fopen(const char * filename, const char * mode)
245{
246 FILE * fp = fopen(filename, mode);
247 php_stream * ret;
248
249 if (fp) {
250 ret = php_stream_alloc(&php_stream_stdio_ops, fp, 0, 0, mode);
251 if (ret)
252 return ret;
253
254 fclose(fp);
255 }
256 return NULL;
257}
258
259php_stream_stdio_ops is a php_stream_ops structure that can be used to handle
260FILE* based streams.
261
262A socket based stream would use code similar to that above to create a stream
263to be passed back to fopen_wrapper (or it's yet to be implemented successor).
264
265The prototype for php_stream_alloc is this:
266
267PHPAPI php_stream * php_stream_alloc(php_stream_ops * ops, void * abstract,
268 size_t bufsize, int persistent, const char * mode)
269
270ops is a pointer to the implementation,
271abstract holds implementation specific data that is relevant to this instance
272of the stream,
273bufsize is the size of the buffer to use - if 0, then buffering at the stream
274level will be disabled (recommended for underlying sources that implement
275their own buffering - such a FILE*),
276persistent controls how the memory is to be allocated - persistently so that
277it lasts across requests, or non-persistently so that it is freed at the end
278of a request (it uses pemalloc),
279mode is the stdio-like mode of operation - php streams places no real meaning
280in the mode parameter, except that it checks for a 'w' in the string when
281attempting to write (this may change).
282
283The mode parameter is passed on to fdopen/fopencookie when the stream is cast
284into a FILE*, so it should be compatible with the mode parameter of fopen().
285
286Writing your own stream implementation
287======================================
288
289!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
290RULE #1: when writing your own streams: make sure you have configured PHP with
291--enable-debug.
292I've taken some great pains to hook into the Zend memory manager to help track
293down allocation problems. It will also help you spot incorrect use of the
294STREAMS_DC, STREAMS_CC and the semi-private STREAMS_REL_CC macros for function
295definitions.
296!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
297
298RULE #2: Please use the stdio stream as a reference; it will help you
299understand the semantics of the stream operations, and it will always
300be more up to date than these docs :-)
301
302First, you need to figure out what data you need to associate with the
303php_stream. For example, you might need a pointer to some memory for memory
304based streams, or if you were making a stream to read data from an RDBMS like
305MySQL, you might want to store the connection and rowset handles.
306
307The stream has a field called abstract that you can use to hold this data.
308If you need to store more than a single field of data, define a structure to
309hold it, allocate it (use pemalloc with the persistent flag set
310appropriately), and use the abstract pointer to refer to it.
311
312For structured state you might have this:
313
314struct my_state {
315 MYSQL conn;
316 MYSQL_RES * result;
317};
318
319struct my_state * state = pemalloc(sizeof(struct my_state), persistent);
320
321/* initialize the connection, and run a query, using the fields in state to
322 * hold the results */
323
324state->result = mysql_use_result(&state->conn);
325
326/* now allocate the stream itself */
327stream = php_stream_alloc(&my_ops, state, 0, persistent, "r");
328
329/* now stream->abstract == state */
330
331Once you have that part figured out, you can write your implementation and
332define the your own php_stream_ops struct (we called it my_ops in the above
333example).
334
335For example, for reading from this weird MySQL stream:
336
337static size_t php_mysqlop_read(php_stream * stream, char * buf, size_t count)
338{
339 struct my_state * state = (struct my_state*)stream->abstract;
340
341 if (buf == NULL && count == 0) {
342 /* in this special case, php_streams is asking if we have reached the
343 * end of file */
344 if (... at end of file ...)
345 return EOF;
346 else
347 return 0;
348 }
349
350 /* pull out some data from the stream and put it in buf */
351 ... mysql_fetch_row(state->result) ...
352 /* we could do something strange, like format the data as XML here,
353 and place that in the buf, but that brings in some complexities,
354 such as coping with a buffer size too small to hold the data,
355 so I won't even go in to how to do that here */
356}
357
358Implement the other operations - remember that write, read, close and flush
359are all mandatory. The rest are optional. Declare your stream ops struct:
360
361php_stream_ops my_ops = {
362 php_mysqlop_write, php_mysqlop_read, php_mysqlop_close,
363 php_mysqlop_flush, NULL, NULL, NULL,
364 "Strange MySQL example"
365}
366
367Thats it!
368
369Take a look at the STDIO implementation in streams.c for more information
370about how these operations work.
371The main thing to remember is that in your close operation you need to release
372and free the resources you allocated for the abstract field. In the case of
373the example above, you need to use mysql_free_result on the rowset, close the
374connection and then use pefree to dispose of the struct you allocated.
375You may read the stream->persistent field to determine if your struct was
376allocated in persistent mode or not.
377
378vim:tw=78:et
379
README.SUBMITTING_PATCH
1Submitting Enhancements and Patches to PHP
2==========================================
3
4This document describes how to submit an enhancement or patch for PHP.
5It's easy!
6
7You don't need any login accounts or special access to download,
8build, debug and begin submitting PHP or PECL code, tests or
9documentation. Once you've followed this README and had several
10patches accepted, commit privileges are often quickly granted.
11
12An excellent article to read first is:
13http://phpadvent.org/2008/less-whining-more-coding-by-elizabeth-smith
14
15
16Online Forums
17-------------
18There are several IRC channels where PHP developers are often
19available to discuss questions. They include #php.pecl and #php.doc
20on the EFNet network and #winphp-dev on FreeNode.
21
22
23PHP Patches
24-----------
25If you are fixing broken functionality in PHP C source code first
26create a bug or identify an existing bug at http://bugs.php.net/. A
27bug can be used to track the patch progress and prevent your changes
28getting lost in the PHP mail archives.
29
30If your change is large then create a Request For Comment (RFC) page
31on http://wiki.php.net/rfc, discuss it with the extension maintainer,
32and discuss it on the development mail list internals@lists.php.net.
33RFC Wiki accounts can be requested on
34http://wiki.php.net/start?do=register. PHP extension maintainers can
35be found in the EXTENSIONS file in the PHP source. Mail list
36subscription is explained on http://php.net/mailing-lists.php.
37
38Information on PHP internal C functions is at
39http://php.net/internals, though this is considered incomplete.
40Various external resources can be found on the web. See
41https://wiki.php.net/internals for some references. A standard
42printed reference is the book "Extending and Embedding PHP" by Sara
43Golemon.
44
45The preferred way to propose PHP patch is sending pull request from
46GitHub: https://github.com/php/php-src
47
48Fork the official PHP repository and send a pull request. A
49notification will be sent to the pull request mailing list. Sending a
50note to PHP Internals list (internals@lists.php.net) may help getting
51more feedback and quicker turnaround. You can also add pull requests
52to bug reports at http://bugs.php.net/.
53
54If you are not using GitHub, attach your patch to a PHP bug and
55consider sending a notification email about the change to
56internals@lists.php.net. If the bug is for an extension, also CC the
57extension maintainer. Explain what has been changed by your patch.
58Test scripts should be included.
59
60Please make the mail subject prefix "[PATCH]". If attaching a patch,
61ensure it has a file extension of ".txt". This is because only MIME
62attachments of type 'text/*' are accepted.
63
64
65
66PHP Documentation Patches
67-------------------------
68If you are fixing incorrect PHP documentation first create a bug or
69identify an existing bug at http://bugs.php.net/. A bug can be used
70to track the patch progress and prevent your changes getting lost in
71the PHP mail archives.
72
73If your change is large, then first discuss it with the mail list
74phpdoc@lists.php.net. Subscription is explained on
75http://php.net/mailing-lists.php.
76
77Information on contributing to PHP documentation is at
78http://php.net/dochowto and http://wiki.php.net/doc/howto
79
80Attach the patch to the PHP bug and consider sending a notification
81email about the change to phpdoc@lists.php.net. Explain what has been
82fixed/added/changed by your patch.
83
84Please make the mail subject prefix "[PATCH]". Include the bug id(s)
85which can be closed by your patch. If attaching a patch, ensure it
86has a file extension of ".txt". This is because only MIME attachments
87of type 'text/*' are accepted.
88
89
90PECL Extension Patches: http://pecl.php.net/
91--------------------------------------------
92If you are fixing broken functionality in a PECL extension then create
93a bug or identify an existing bug at http://bugs.php.net/. A bug
94can be used to track the patch progress and prevent your changes
95getting lost in the PHP mail archives.
96
97If your change is large then create a Request For Comment (RFC) page
98on http://wiki.php.net/rfc, discuss it with the extension maintainer,
99and discuss it on the development mail list pecl-dev@lists.php.net.
100PECL mail list subscription is explained on
101http://pecl.php.net/support.php. RFC Wiki accounts can be requested
102on http://wiki.php.net/start?do=register
103
104Information on PHP internal C functions is at
105http://www.php.net/internals, though this is considered incomplete.
106Various external resources can be found on the web. A standard
107printed reference is the book "Extending and Embedding PHP" by Sara
108Golemon.
109
110Update any open bugs and add a link to the source of your patch. Send
111the patch or pointer to the bug to pecl-dev@lists.php.net. Also CC
112the extension maintainer. Explain what has been changed by your
113patch. Test scripts should be included.
114
115Please make the mail subject prefix "[PATCH] ...". Include the patch
116as an attachment with a file extension of ".txt". This is because
117only MIME attachments of type 'text/*' are accepted.
118
119
120PEAR Package Patches: http://pear.php.net/
121------------------------------------------
122Information on contributing to PEAR is available at
123http://pear.php.net/manual/en/developers-newmaint.php and
124http://pear.php.net/manual/en/guide-developers.php
125
126
127How to create your PHP, PHP Documentation or PECL patch
128-------------------------------------------------------
129PHP and most PECL packages use Git for revision control. Some PECL
130packages use Subversion (SVN) Read http://www.php.net/git.php for help
131on using Git to get and build PHP source code. We recommend to look
132at our workflow on https://wiki.php.net/vcs/gitworkflow and our FAQ
133https://wiki.php.net/vcs/gitfaq.
134
135Generally we ask that bug fix patches work on the current stable PHP
136development branches and on "master". New PHP features only need to
137work on "master".
138
139Read CODING_STANDARDS before you start working.
140
141After modifying the source see README.TESTING and
142http://qa.php.net/write-test.php for how to test. Submitting test
143scripts helps us to understand what functionality has changed. It is
144important for the stability and maintainability of PHP that tests are
145comprehensive.
146
147After testing is finished, create a patch file using the command:
148
149 git diff > your_patch.txt
150
151For ease of review and later troubleshooting, submit individual
152patches for each bug or feature.
153
154
155Checklist for submitting your PHP or PECL code patch
156----------------------------------------------------
157 - Update git source just before running your final 'diff' and
158 before testing.
159 - Add in-line comments and/or have external documentation ready.
160 Use only "/* */" style comments, not "//".
161 - Create test scripts for use with "make test".
162 - Run "make test" to check your patch doesn't break other features.
163 - Rebuild PHP with --enable-debug (which will show some kinds of
164 memory errors) and check the PHP and web server error logs after
165 running your PHP tests.
166 - Rebuild PHP with --enable-maintainer-zts to check your patch
167 compiles on multi-threaded web servers.
168 - Review the patch once more just before submitting it.
169
170
171What happens after submitting your PHP, PHP Documentation or PECL patch
172-----------------------------------------------------------------------
173If your patch is easy to review and obviously has no side-effects,
174it might be committed relatively quickly.
175
176Because PHP is a volunteer-driven effort more complex patches will
177require patience on your side. If you do not receive feedback in a
178few days, consider resubmitting the patch. Before doing this think
179about these questions:
180
181 - Did I send the patch to the right mail list?
182 - Did I review the mail list archives to see if these kind of
183 changes had been discussed before?
184 - Did I explain my patch clearly?
185 - Is my patch too hard to review? Because of what factors?
186
187
188What happens when your PHP or PECL patch is applied
189---------------------------------------------------
190Your name will likely be included in the Git commit log. If your
191patch affects end users, a brief description and your name might be
192added to the NEWS file.
193
194Thank you for patching PHP!
195
README.TESTING
1[IMPORTANT NOTICE]
2------------------
3 Failed tests usually indicate a problem with your local system setup
4and not within PHP itself (at least for official PHP release versions).
5You may decide to automatically submit a test summary to our QA workflow
6at the end of a test run.
7 Please do *not* submit a failed test as a bug or ask for help on why
8it failed on your system without providing substantial backup information
9on *why* the test failed on your special setup. Thank you :-)
10
11
12[Testing Basics]
13----------------
14 The easiest way to test your PHP build is to run "make test" from the
15command line after successfully compiling. This will run the complete
16tests for all enabled functionalities and extensions using the PHP
17CLI binary.
18 To execute test scripts, you must build PHP with some SAPI, then you
19type "make test" to execute all or some test scripts saved under
20"tests" directory under source root directory.
21
22Usage:
23make test
24
25 "make test" basically executes "run-tests.php" script
26under the source root (parallel builds will not work). Therefore you
27can execute the script as follows:
28
29TEST_PHP_EXECUTABLE=sapi/cli/php \
30sapi/cli/php [-c /path/to/php.ini] run-tests.php [ext/foo/tests/GLOB]
31
32
33[Which "php" executable "make test" look for]
34---------------------------------------------
35If you are running the run-tests.php script from the command line (as above)
36you must set the TEST_PHP_EXECUTABLE environment variable to explicitly
37select the PHP executable that is to be tested, that is, used to run the test scripts.
38
39If you run the tests using make test, the PHP CLI and CGI executables are
40automatically set for you. "make test" executes "run-tests.php" script with the CLI binary. Some
41test scripts such as session must be executed by CGI SAPI. Therefore,
42you must build PHP with CGI SAPI to perform all tests.
43
44NOTE: PHP binary executing "run-tests.php" and php binary used for
45executing test scripts may differ. If you use different PHP binary for
46executing "run-tests.php" script, you may get errors.
47
48
49[Which php.ini is used]
50-----------------------
51 "make test" uses the same php.ini file as it would once installed.
52The tests have been written to be independent of that php.ini file,
53so if you find a test that is affected by a setting, please report
54this, so we can address the issue.
55
56
57[Which test scripts are executed]
58---------------------------------
59 "run-tests.php" ("make test"), without any arguments executes all
60test scripts by extracting all directories named "tests"
61from the source root and any subdirectories below. If there are files,
62which have a "phpt" extension, "run-tests.php" looks at the sections
63in these files, determines whether it should run it, by evaluating
64the 'SKIPIF' section. If the test is eligible for execution, the 'FILE'
65section is extracted into a ".php" file (with the same name besides
66the extension) and gets executed.
67When an argument is given or TESTS environment variable is set, the
68GLOB is expanded by the shell and any file with extension "*.phpt" is
69regarded as a test file.
70
71 Tester can easily execute tests selectively with as follows.
72
73Examples:
74./sapi/cli/php run-tests.php ext/mbstring/*
75./sapi/cli/php run-tests.php ext/mbstring/020.phpt
76
77
78[Test results]
79--------------
80 Test results are printed to standard output. If there is a failed test,
81the "run-tests.php" script saves the result, the expected result and the
82code executed to the test script directory. For example, if
83ext/myext/tests/myext.phpt fails to pass, the following files are created:
84
85ext/myext/tests/myext.php - actual test file executed
86ext/myext/tests/myext.log - log of test execution (L)
87ext/myext/tests/myext.exp - expected output (E)
88ext/myext/tests/myext.out - output from test script (O)
89ext/myext/tests/myext.diff - diff of .out and .exp (D)
90
91 Failed tests are always bugs. Either the test is bugged or not considering
92factors applying to the tester's environment, or there is a bug in PHP.
93If this is a known bug, we strive to provide bug numbers, in either the
94test name or the file name. You can check the status of such a bug, by
95going to: http://bugs.php.net/12345 where 12345 is the bug number.
96For clarity and automated processing, bug numbers are prefixed by a hash
97sign '#' in test names and/or test cases are named bug12345.phpt.
98
99NOTE: The files generated by tests can be selected by setting the
100environment variable TEST_PHP_LOG_FORMAT. For each file you want to be
101generated use the character in brackets as shown above (default is LEOD).
102The php file will be generated always.
103
104NOTE: You can set environment variable TEST_PHP_DETAILED to enable
105detailed test information.
106
107[Automated Testing]
108--------------
109 If you like to keep up to speed, with latest developments and quality
110assurance, setting the environment variable NO_INTERACTION to 1, will not
111prompt the tester for any user input.
112
113Normally, the exit status of "make test" is zero, regardless of the results
114of independent tests. Set the environment variable REPORT_EXIT_STATUS to 1,
115and "make test" will set the exit status ("$?") to non-zero, when an
116individual test has failed.
117
118Example script to be run by cron(1):
119========== qa-test.sh =============
120#!/bin/sh
121
122CO_DIR=$HOME/cvs/php7
123MYMAIL=qa-test@domain.com
124TMPDIR=/var/tmp
125TODAY=`date +"%Y%m%d"`
126
127# Make sure compilation environment is correct
128CONFIGURE_OPTS='--disable-all --enable-cli --with-pcre'
129export MAKE=gmake
130export CC=gcc
131
132# Set test environment
133export NO_INTERACTION=1
134export REPORT_EXIT_STATUS=1
135
136cd $CO_DIR
137cvs update . >>$TMPDIR/phpqatest.$TODAY
138./cvsclean ; ./buildconf ; ./configure $CONFIGURE_OPTS ; $MAKE
139$MAKE test >>$TMPDIR/phpqatest.$TODAY 2>&1
140if test $? -gt 0
141then
142 cat $TMPDIR/phpqatest.$TODAY | mail -s"PHP-QA Test Failed for $TODAY" $MYMAIL
143fi
144========== end of qa-test.sh =============
145
146NOTE: The exit status of run-tests.php will be 1 when
147REPORT_EXIT_STATUS is set. The result of "make test" may be higher
148than that. At present, gmake 3.79.1 returns 2, so it is
149advised to test for non-zero, rather then a specific value.
150
151
152[Creating new test files]
153-------------------------
154 Writing test file is very easy if you are used to PHP.
155See the HOWTO at http://qa.php.net/write-test.php
156
157
158[How to help us]
159----------------
160 If you find bug in PHP, you can submit bug report AND test script
161for us. You don't have to write complete script, just give us test
162script with following format. Please test the script and make sure
163you write the correct ACTUAL OUTPUT and EXPECTED OUTPUT before you
164submit.
165
166<?php
167/*
168Bug #12345
169substr() bug. Do not return expected string.
170
171ACTUAL OUTPUT
172XYXA
173
174EXPECTED OUTPUT
175ABCD
176*/
177
178$str = "XYZABCD";
179echo substr($str,3,7);
180
181?>
182
183[IMPORTANT NOTICE]
184------------------
185This is an addendum to README.TESTING with additional information
186specific to server-tests.php.
187
188server-tests.php is backward compatible with tests developed for
189the original run-tests.php script. server-tests is *not* used by
190'make test'. server-tests was developed to provide support for
191testing PHP under it's primary environment, HTTP, and can run the
192PHP tests under any of the SAPI modules that are direct executables,
193or are accessible via HTTP.
194
195[New features]
196----------------
197* Command line interface:
198 You can run 'php server-tests.php -h' to get all the possible options.
199* Configuration file:
200 the -c argument will allow you to use a configuration file. This is
201 handy if you are testing multiple environments and need various options
202 depending on the environment.
203 see server-tests-config.php for details.
204* CGI Emulation:
205 Will emulate a CGI environment when testing with the cgi sapi executable.
206* HTTP testing:
207 can be configured to run test scripts through an HTTP server running
208 on localhost. localhost is required since either the web server must
209 alias a directory to the php source directory, or the test scripts
210 must be copied to a directory under the web server
211 (see config options TEST_WEB_BASE_URL, TEST_BASE_PATH, and TEST_WEB_EXT)
212* New sections supported for test files (see below)
213
214When running tests over http, tests that require ini settings different that what
215the web server runs under will be skipped. Since the test harness defines a number
216of ini settings by default, the web server may require special configuration to
217make testing work.
218
219[Example Usage]
220----------------
221Some (but not all!) examples of usage:
222
2231. run tests from the php source directory
224 php server-tests.php -p /path/to/php-cli
225
2262. run tests using cgi emulation
227 php server-tests.php -p /path/to/php-cgi
228
2293. run tests over http, copying test files into document root
230 php server-tests.php -w -u http://localhost/test -m /path/to/htdocs/test
231
2324. run tests over http, php sources have been aliased in web server
233 php server-tests.php -w -u http://localhost/test
234
2355. run tests using configuration file
236 php server-tests.php -c /path/to/server-tests-config.php
237
2386. run tests using configuration file, but overriding some settings:
239 (config file must be first)
240 php server-tests.php -c /path/to/server-tests-config.php -w -t 3 -d /path/to/testdir
241
242NOTE: configuration as described in README.TESTING still works.
243
244[New Test Sections]
245----------------
246In addition to the traditional test sections
247(see http://qa.php.net/write-test.php), several new sections are available
248under server-tests.
249
250--POST--
251This is not a new section, but not multipart posts are supported for testing
252file uploads, or other types of POST data.
253
254--CGI--
255This section takes no value. It merely provides a simple marker for tests
256that MUST be run as CGI, even if there is no --POST-- or --GET-- sections
257in the test file.
258
259--DESCRIPTION--
260Not used for anything, just a section for documenting the test
261
262--ENV--
263This section get's eval()'d to help build an environment for the
264execution of the test. This can be used to change environment
265vars that are used for CGI emulation, or simply to set env vars
266for cli testing. A full example looks like:
267
268 --ENV--
269 return <<<END
270 PATH_TRANSLATED=$filename
271 PATH_INFO=$scriptname
272 SCRIPT_NAME=$scriptname
273 END;
274
275Some variables are made easily available for use in this section, they
276include:
277 $filename full native path to file, will become PATH_TRANSLATED
278 $filepath =dirname($filename)
279 $scriptname this is what will become SCRIPT_NAME unless you override it
280 $docroot the equivalent of DOCUMENT_ROOT under Apache
281 $cwd the directory that the test is being initiated from
282 $this->conf all server-tests configuration vars
283 $this->env all environment variables that will get passed to the test
284
285
286--REQUEST--
287This section is also eval'd, and is similar in nature to --ENV--. However,
288this section is used to build the url used in an HTTP request. Valid values
289to set in this section would include:
290 SCRIPT_NAME The initial part of the request url
291 PATH_INFO The pathinfo part of a request url
292 FRAGMENT The fragment section of a url (after #)
293 QUERY_STRING The query part of a url (after ?)
294
295 --REQUEST--
296 return <<<END
297 PATH_INFO=/path/info
298 END;
299
300--HEADERS--
301This section is also eval'd. It is used to provide additional headers sent
302in an HTTP request, such as content type for multipart posts, cookies, etc.
303
304 --HEADERS--
305 return <<<END
306 Content-Type=multipart/form-data; boundary=---------------------------240723202011929
307 Content-Length=100
308 END;
309
310--EXPECTHEADERS--
311This section can be used to define what headers are required to be
312received back from a request, and is checked in addition to the
313regular expect sections. For example:
314
315 --EXPECTHEADERS--
316 Status: 404
317
README.UNIX-BUILD-SYSTEM
1PHP Build System V5 Overview
2
3- supports Makefile.ins during transition phase
4- not-really-portable Makefile includes have been eliminated
5- supports separate build directories without VPATH by using
6 explicit rules only
7- does not waste disk-space/CPU-time for building temporary libraries
8 => especially noticeable on slower systems
9- slow recursive make replaced with one global Makefile
10- eases integration of proper dependencies
11- adds PHP_DEFINE(what[, value]) which creates a single include-file
12 per what. This will allow more fine-grained dependencies.
13- abandoning the "one library per directory" concept
14- improved integration of the CLI
15- several new targets
16 build-modules: builds and copies dynamic modules into modules/
17 install-cli: installs the CLI only, so that the install-sapi
18 target does only what its name says
19- finally abandoned automake (still requires aclocal at this time)
20- changed some configure-time constructs to run at buildconf-time
21- upgraded shtool to 1.5.4
22- removed $(moduledir) (use EXTENSION_DIR)
23
24The Reason For a New System
25
26It became more and more apparent that there is a severe need
27for addressing the portability concerns and improving the chance
28that your build is correct (how often have you been told to
29"make clean"? When this is done, you won't need to anymore).
30
31
32If You Build PHP on a Unix System
33
34
35You, as a user of PHP, will notice no changes. Of course, the build
36system will be faster, look better and work smarter.
37
38
39
40If You Are Developing PHP
41
42
43
44
45Extension developers:
46
47Makefile.ins are abandoned. The files which are to be compiled
48are specified in the config.m4 now using the following macro:
49
50PHP_NEW_EXTENSION(foo, foo.c bar.c baz.cpp, $ext_shared)
51
52E.g. this enables the extension foo which consists of three source-code
53modules, two in C and one in C++. And, depending on the user's wishes,
54the extension will even be built as a dynamic module.
55
56The full syntax:
57
58PHP_NEW_EXTENSION(extname, sources [, shared [,sapi_class[, extra-cflags]]])
59
60Please have a look at acinclude.m4 for the gory details and meanings
61of the other parameters.
62
63And that's basically it for the extension side.
64
65If you previously built sub-libraries for this module, add
66the source-code files here as well. If you need to specify
67separate include directories, do it this way:
68
69PHP_NEW_EXTENSION(foo, foo.c mylib/bar.c mylib/gregor.c,,,-I@ext_srcdir@/lib)
70
71E.g. this builds the three files which are located relative to the
72extension source directory and compiles all three files with the
73special include directive (@ext_srcdir@ is automatically replaced).
74
75Now, you need to tell the build system that you want to build files
76in a directory called $ext_builddir/lib:
77
78PHP_ADD_BUILD_DIR($ext_builddir/lib)
79
80Make sure to call this after PHP_NEW_EXTENSION, because $ext_builddir
81is only set by the latter.
82
83If you have a complex extension, you might to need add special
84Make rules. You can do this by calling PHP_ADD_MAKEFILE_FRAGMENT
85in your config.m4 after PHP_NEW_EXTENSION.
86
87This will read a file in the source-dir of your extension called
88Makefile.frag. In this file, $(builddir) and $(srcdir) will be
89replaced by the values which are correct for your extension
90and which are again determined by the PHP_NEW_EXTENSION macro.
91
92Make sure to prefix *all* relative paths correctly with either
93$(builddir) or $(srcdir). Because the build system does not
94change the working directory anymore, we must use either
95absolute paths or relative ones to the top build-directory.
96Correct prefixing ensures that.
97
98
99SAPI developers:
100
101Instead of using PHP_SAPI=foo/PHP_BUILD_XYZ, you will need to type
102
103PHP_SELECT_SAPI(name, type, sources.c)
104
105I.e. specify the source-code files as above and also pass the
106information regarding how PHP is supposed to be built (shared
107module, program, etc).
108
109For example for APXS:
110
111PHP_SELECT_SAPI(apache, shared, sapi_apache.c mod_php7.c php_apache.c)
112
113
114
115General info
116
117The foundation for the new system is the flexible handling of
118sources and their contexts. With the help of macros you
119can define special flags for each source-file, where it is
120located, in which target context it can work, etc.
121
122Have a look at the well documented macros
123PHP_ADD_SOURCES(_X) in acinclude.m4.
124
README.WIN32-BUILD-SYSTEM
README.input_filter
1Input Filter Support in PHP 5
2-----------------------------
3
4XSS (Cross Site Scripting) hacks are becoming more and more prevalent,
5and can be quite difficult to prevent. Whenever you accept user data
6and somehow display this data back to users, you are likely vulnerable
7to XSS hacks.
8
9The Input Filter support in PHP 5 is aimed at providing the framework
10through which a company-wide or site-wide security policy can be
11enforced. It is implemented as a SAPI hook and is called from the
12treat_data and post handler functions. To implement your own security
13policy you will need to write a standard PHP extension. There is also
14a powerful standard implementation in ext/filter that should suit most
15peoples' needs. However, if you want to implement your own security
16policy, read on.
17
18A simple implementation might look like the following. This stores the
19original raw user data and adds a my_get_raw() function while the normal
20$_POST, $_GET and $_COOKIE arrays are only populated with stripped
21data. In this simple example all I am doing is calling strip_tags() on
22the data.
23
24ZEND_BEGIN_MODULE_GLOBALS(my_input_filter)
25 zval *post_array;
26 zval *get_array;
27 zval *cookie_array;
28ZEND_END_MODULE_GLOBALS(my_input_filter)
29
30#ifdef ZTS
31#define IF_G(v) TSRMG(my_input_filter_globals_id, zend_my_input_filter_globals *, v)
32#else
33#define IF_G(v) (my_input_filter_globals.v)
34#endif
35
36ZEND_DECLARE_MODULE_GLOBALS(my_input_filter)
37
38zend_function_entry my_input_filter_functions[] = {
39 PHP_FE(my_get_raw, NULL)
40 {NULL, NULL, NULL}
41};
42
43zend_module_entry my_input_filter_module_entry = {
44 STANDARD_MODULE_HEADER,
45 "my_input_filter",
46 my_input_filter_functions,
47 PHP_MINIT(my_input_filter),
48 PHP_MSHUTDOWN(my_input_filter),
49 NULL,
50 PHP_RSHUTDOWN(my_input_filter),
51 PHP_MINFO(my_input_filter),
52 "0.1",
53 STANDARD_MODULE_PROPERTIES
54};
55
56PHP_MINIT_FUNCTION(my_input_filter)
57{
58 ZEND_INIT_MODULE_GLOBALS(my_input_filter, php_my_input_filter_init_globals, NULL);
59
60 REGISTER_LONG_CONSTANT("POST", PARSE_POST, CONST_CS | CONST_PERSISTENT);
61 REGISTER_LONG_CONSTANT("GET", PARSE_GET, CONST_CS | CONST_PERSISTENT);
62 REGISTER_LONG_CONSTANT("COOKIE", PARSE_COOKIE, CONST_CS | CONST_PERSISTENT);
63
64 sapi_register_input_filter(my_sapi_input_filter);
65 return SUCCESS;
66}
67
68PHP_RSHUTDOWN_FUNCTION(my_input_filter)
69{
70 if(IF_G(get_array)) {
71 zval_ptr_dtor(&IF_G(get_array));
72 IF_G(get_array) = NULL;
73 }
74 if(IF_G(post_array)) {
75 zval_ptr_dtor(&IF_G(post_array));
76 IF_G(post_array) = NULL;
77 }
78 if(IF_G(cookie_array)) {
79 zval_ptr_dtor(&IF_G(cookie_array));
80 IF_G(cookie_array) = NULL;
81 }
82 return SUCCESS;
83}
84
85PHP_MINFO_FUNCTION(my_input_filter)
86{
87 php_info_print_table_start();
88 php_info_print_table_row( 2, "My Input Filter Support", "enabled" );
89 php_info_print_table_end();
90}
91
92/* The filter handler. If you return 1 from it, then PHP also registers the
93 * (modified) variable. Returning 0 prevents PHP from registering the variable;
94 * you can use this if your filter already registers the variable under a
95 * different name, or if you just don't want the variable registered at all. */
96SAPI_INPUT_FILTER_FUNC(my_sapi_input_filter)
97{
98 zval new_var;
99 zval *array_ptr = NULL;
100 char *raw_var;
101 int var_len;
102
103 assert(*val != NULL);
104
105 switch(arg) {
106 case PARSE_GET:
107 if(!IF_G(get_array)) {
108 ALLOC_ZVAL(array_ptr);
109 array_init(array_ptr);
110 INIT_PZVAL(array_ptr);
111 }
112 IF_G(get_array) = array_ptr;
113 break;
114 case PARSE_POST:
115 if(!IF_G(post_array)) {
116 ALLOC_ZVAL(array_ptr);
117 array_init(array_ptr);
118 INIT_PZVAL(array_ptr);
119 }
120 IF_G(post_array) = array_ptr;
121 break;
122 case PARSE_COOKIE:
123 if(!IF_G(cookie_array)) {
124 ALLOC_ZVAL(array_ptr);
125 array_init(array_ptr);
126 INIT_PZVAL(array_ptr);
127 }
128 IF_G(cookie_array) = array_ptr;
129 break;
130 }
131 Z_STRLEN(new_var) = val_len;
132 Z_STRVAL(new_var) = estrndup(*val, val_len);
133 Z_TYPE(new_var) = IS_STRING;
134
135 var_len = strlen(var);
136 raw_var = emalloc(var_len+5); /* RAW_ and a \0 */
137 strcpy(raw_var, "RAW_");
138 strlcat(raw_var,var,var_len+5);
139
140 php_register_variable_ex(raw_var, &new_var, array_ptr);
141
142 php_strip_tags(*val, val_len, NULL, NULL, 0);
143
144 *new_val_len = strlen(*val);
145 return 1;
146}
147
148PHP_FUNCTION(my_get_raw)
149{
150 long arg;
151 char *var;
152 int var_len;
153 zval **tmp;
154 zval *array_ptr = NULL;
155
156 if(zend_parse_parameters(2, "ls", &arg, &var, &var_len) == FAILURE) {
157 return;
158 }
159
160 switch(arg) {
161 case PARSE_GET:
162 array_ptr = IF_G(get_array);
163 break;
164 case PARSE_POST:
165 array_ptr = IF_G(post_array);
166 break;
167 case PARSE_COOKIE:
168 array_ptr = IF_G(post_array);
169 break;
170 }
171
172 if(!array_ptr) {
173 RETURN_FALSE;
174 }
175
176 if(zend_hash_find(HASH_OF(array_ptr), var, var_len+5, (void **)&tmp) == SUCCESS) {
177 *return_value = **tmp;
178 zval_copy_ctor(return_value);
179 } else {
180 RETVAL_FALSE;
181 }
182}
183