1# Contributing to PHP
2
3Anybody who programs in PHP can be a contributing member of the community that
4develops and deploys it; the task of deploying PHP, documentation and associated
5websites is a never-ending one. With every release or release candidate comes a
6wave of work, which takes a lot of organization and co-ordination.
7
8You don't need any special access to download, build, debug and begin submitting
9PHP or PECL code, tests or documentation. Once you've followed this guide and
10had several contributions accepted, commit privileges are often quickly granted.
11
12## Index
13
14* [Pull requests](#pull-requests)
15* [Filing bugs](#filing-bugs)
16* [Feature requests](#feature-requests)
17* [Writing tests](#writing-tests)
18* [Writing documentation](#writing-documentation)
19* [Getting help](#getting-help)
20* [PHP source code directory structure](#php-source-code-directory-structure)
21* [PHP internals](#php-internals)
22* [PECL extensions](#pecl-extensions)
23* [Checklist for submitting contribution](#checklist-for-submitting-contribution)
24* [What happens after submitting contribution?](#what-happens-after-submitting-contribution)
25* [What happens when your contribution is applied?](#what-happens-when-your-contribution-is-applied)
26* [Git commit rules](#git-commit-rules)
27* [Copyright and license headers](#copyright-and-license-headers)
28
29## Pull requests
30
31PHP welcomes pull requests to [add tests](#writing-tests), fix bugs and to
32implement RFCs. Please be sure to include tests as appropriate!
33
34If you are fixing a bug, then please submit your PR against the lowest actively
35supported branch of PHP that the bug affects (only green branches on
36[the supported version page](https://www.php.net/supported-versions.php) are
37supported). For example, at the time of writing, the lowest supported version is
38PHP 7.3, which corresponds to the `PHP-7.3` branch in Git. Please also make sure
39you add a link to the PR in the bug on [the bug tracker](https://bugs.php.net/).
40
41Pull requests implementing RFCs should be submitted against `master`.
42
43Pull requests should *never* be submitted against `PHP-x.y.z` branches, as these
44are only used for release management.
45
46If your pull request exhibits conflicts with the base branch, please resolve
47them by using `git rebase` instead of `git merge`.
48
49Fork the official PHP repository and send a pull request. A notification will be
50sent to the pull request mailing list. Sending a note to PHP Internals list
51(internals@lists.php.net) may help getting more feedback and quicker turnaround.
52You can also add pull requests to [bug reports](https://bugs.php.net/).
53
54Read [Git access page](https://www.php.net/git.php) for help on using Git to get
55and build PHP source code. We recommend to look at our
56[workflow](https://wiki.php.net/vcs/gitworkflow) and our
57[FAQ](https://wiki.php.net/vcs/gitfaq).
58
59## Filing bugs
60
61Bugs can be filed on the [PHP bug tracker](https://bugs.php.net/). If this is
62the first time you've filed a bug, we suggest reading the
63[guide to reporting a bug](https://bugs.php.net/how-to-report.php).
64
65Where possible, please include a self-contained reproduction case!
66
67## Feature requests
68
69Feature requests are generally submitted in the form of
70[Requests for Comments (RFC)](https://wiki.php.net/rfc/howto), ideally
71accompanied by [pull requests](#pull-requests). You can find the extremely large
72list of RFCs that have been previously considered on the
73[PHP Wiki](https://wiki.php.net/rfc).
74
75To create a RFC, discuss it with the extension maintainer, and discuss it on the
76development mailing list internals@lists.php.net. RFC Wiki accounts can be
77requested on https://wiki.php.net/start?do=register. PHP extension maintainers
78can be found in the [EXTENSIONS](/EXTENSIONS) file in the PHP source code
79repository. Mailing list subscription is explained on the
80[mailing lists page](https://www.php.net/mailing-lists.php).
81
82You may also want to read
83[The Mysterious PHP RFC Process](https://blogs.oracle.com/opal/entry/the_mysterious_php_rfc_process)
84for additional notes on the best way to approach submitting an RFC.
85
86## Writing tests
87
88We love getting new tests! PHP is a huge project and improving test coverage is
89a huge win for every PHP user.
90
91[Our QA site includes a page detailing how to write test cases.](https://qa.php.net/write-test.php)
92
93Submitting test scripts helps us to understand what functionality has changed.
94It is important for the stability and maintainability of PHP that tests are
95comprehensive.
96
97Failure conditions of `zend_parse_parameters`, `ZEND_PARSE_PARAMETERS()` and
98similar functions should not be tested. These parameter parsing APIs are already
99extensively tested, and additional tests only complicate future modifications.
100
101For newly created tests, a `--CREDITS--` section should no longer be included,
102as test authorship is already accurately tracked by Git. If multiple authors
103should be credited, the `Co-authored-by` tag in the commit message may be used.
104
105## Writing documentation
106
107There are two ways to contribute to the PHP manual. You can edit the manual and
108send patches anonymously via [the online editor](https://edit.php.net/), or you
109can check the XML source out from Subversion and edit that and build it
110[per the instructions on the documentation site](http://doc.php.net/tutorial/).
111Patches created that way should be sent to the
112[documentation mailing list](mailto:phpdoc@lists.php.net).
113
114## Getting help
115
116If you are having trouble contributing to PHP, or just want to talk to a human
117about what you're working on, you can contact us via the
118[internals mailing list](mailto:internals@lists.php.net), or the
119[documentation mailing list](mailto:phpdoc@lists.php.net) for documentation
120issues.
121
122Although not a formal channel, you can also find a number of core developers on
123the #php.pecl channel on [EFnet](http://www.efnet.org/). Similarly, many
124documentation writers can be found on #php.doc. Windows development IRC channel
125is available at #winphp-dev on FreeNode.
126
127## PHP source code directory structure
128
129PHP source code also includes several files generated during development and
130several parts where maintenance is happening upstream in their respective
131locations.
132
133```bash
134<php-src>/
135 ├─ .git/                           # Git configuration and source directory
136 ├─ TSRM/                           # Thread Safe Resource Manager
137 └─ Zend/                           # Zend Engine
138    ├─ asm/                         # Bundled from src/asm in https://github.com/boostorg/context
139    ├─ zend_vm_execute.h            # Generated by `Zend/zend_vm_gen.php`
140    ├─ zend_vm_opcodes.c            # Generated by `Zend/zend_vm_gen.php`
141    ├─ zend_vm_opcodes.h            # Generated by `Zend/zend_vm_gen.php`
142    └─ ...
143 ├─ appveyor/                       # Appveyor CI service files
144 └─ build/                          # *nix build system files
145    ├─ ax_*.m4                      # https://github.com/autoconf-archive/autoconf-archive
146    ├─ config.guess                 # https://git.savannah.gnu.org/cgit/config.git
147    ├─ config.sub                   # https://git.savannah.gnu.org/cgit/config.git
148    ├─ libtool.m4                   # https://git.savannah.gnu.org/cgit/libtool.git
149    ├─ ltmain.sh                    # https://git.savannah.gnu.org/cgit/libtool.git
150    ├─ pkg.m4                       # https://gitlab.freedesktop.org/pkg-config/pkg-config
151    ├─ shtool                       # https://www.gnu.org/software/shtool/
152    └─ ...
153 ├─ docs/                           # PHP internals and repository documentation
154 └─ ext/                            # PHP core extensions
155    └─ bcmath/
156       ├─ libbcmath/                # Forked and maintained in php-src
157       └─ ...
158    └─ curl/
159       ├─ sync-constants.php        # The curl symbols checker
160       └─ ...
161    └─ date/
162       └─ lib/                      # Bundled datetime library https://github.com/derickr/timelib
163          ├─ parse_date.c           # Generated by re2c 0.15.3
164          ├─ parse_iso_intervals.c  # Generated by re2c 0.15.3
165          └─ ...
166       └─ ...
167    └─ ffi/
168       ├─ ffi_parser.c              # Generated by https://github.com/dstogov/llk
169       └─ ...
170    └─ fileinfo/
171       ├─ libmagic/                 # Modified libmagic https://github.com/file/file
172       ├─ data_file.c               # Generated by `ext/fileinfo/create_data_file.php`
173       ├─ libmagic.patch            # Modifications patch from upstream libmagic
174       ├─ magicdata.patch           # Modifications patch from upstream libmagic
175       └─ ...
176    └─ gd/
177       ├─ libgd/                    # Bundled and modified GD library https://github.com/libgd/libgd
178       └─ ...
179    └─ mbstring/
180       ├─ libmbfl/                  # Forked and maintained in php-src
181       ├─ unicode_data.h            # Generated by `ext/mbstring/ucgendat/ucgendat.php`
182       └─ ...
183    └─ pcre/
184       ├─ pcre2lib/                 # https://www.pcre.org/
185       └─ ...
186    └─ pdo_mysql/
187       ├─ php_pdo_mysql_sqlstate.h  # Generated by `ext/pdo_mysql/get_error_codes.php`
188       └─ ...
189    └─ skeleton/                    # Skeleton for developing new extensions with `ext/ext_skel.php`
190       └─ ...
191    └─ standard/
192       └─ html_tables/
193          ├─ mappings/              # https://www.unicode.org/Public/MAPPINGS/
194          └─ ...
195       ├─ credits_ext.h             # Generated by `scripts/dev/credits`
196       ├─ credits_sapi.h            # Generated by `scripts/dev/credits`
197       ├─ html_tables.h             # Generated by `ext/standard/html_tables/html_table_gen.php`
198       └─ ...
199    └─ tokenizer/
200       ├─ tokenizer_data.c          # Generated by `ext/tokenizer/tokenizer_data_gen.sh`
201       └─ ...
202    └─ zend_test                    # For testing internal APIs. Not needed for regular builds.
203       └─ ...
204    └─ zip/                         # Bundled https://github.com/pierrejoye/php_zip
205       └─ ...
206    └─ ...
207 └─ main/                           # Binding that ties extensions, SAPIs, and engine together
208    ├─ streams/                     # Streams layer subsystem
209    ├─ php_version.h                # Generated by release managers using `configure`
210    └─ ...
211 ├─ pear/                           # PEAR installation
212 └─ sapi/                           # PHP SAPI modules
213    └─ cli/
214       ├─ mime_type_map.h           # Generated by `sapi/cli/generate_mime_type_map.php`
215       └─ ...
216    └─ ...
217 ├─ scripts/                        # php-config, phpize and internal development scripts
218 ├─ tests/                          # Core features tests
219 ├─ travis/                         # Travis CI service files
220 └─ win32/                          # Windows build system files
221    ├─ cp_enc_map.c                 # Generated by `win32/cp_enc_map_gen.exe`
222    └─ ...
223 └─ ...
224```
225
226## PHP internals
227
228For information on PHP internal C functions see
229[References about Maintaining and Extending PHP](https://wiki.php.net/internals/references).
230Various external resources can be found on the web. A standard printed reference
231is the book "Extending and Embedding PHP" by Sara Golemon.
232
233## PECL extensions
234
235If you are fixing broken functionality in a [PECL](https://pecl.php.net)
236extension then create a bug or identify an existing bug at
237[bugs.php.net](https://bugs.php.net). A bug can be used to track the change
238progress and prevent your changes getting lost in the PHP mail archives. Some
239PECL extensions have their own bug tracker locations and different contributing
240procedures.
241
242If your change is large then create a
243[Request for Comments (RFC)](https://wiki.php.net/rfc), discuss it with the
244extension maintainer, and discuss it on the development mailing list
245pecl-dev@lists.php.net depending on the extension. PECL mailing list
246subscription is explained on the
247[PECL support page](https://pecl.php.net/support.php).
248
249Update any open bugs and add a link to the source of your change. Send the patch
250or pointer to the bug to pecl-dev@lists.php.net. Also CC the extension
251maintainer. Explain what has been changed by your patch. Test scripts should be
252included.
253
254## Checklist for submitting contribution
255
256- Read [Coding standards](/CODING_STANDARDS.md) before you start working.
257- Update git source just before running your final `diff` and before testing.
258- Add inline comments and/or have external documentation ready. Use only
259  `/* */` style comments, not `//`.
260- Create test scripts for use with `make test`.
261- Run `make test` to check your change doesn't break other features.
262- Rebuild PHP with `--enable-debug` which will show some kinds of memory errors
263  and check the PHP and web server error logs after running your PHP tests.
264- Rebuild PHP with `--enable-zts` to check your change compiles and operates
265  correctly in a thread-safe PHP.
266- Review the change once more just before submitting it.
267
268## What happens after submitting contribution?
269
270If your change is easy to review and obviously has no side-effects, it might be
271committed relatively quickly.
272
273Because PHP is a volunteer-driven effort, more complex changes will require
274patience on your side. If you do not receive feedback in a few days, consider
275bumping. Before doing this think about these questions:
276
277- Did I send the patch to the right mailing list?
278- Did I review the mailing list archives to see if these kind of changes had
279  been discussed before?
280- Did I explain my change clearly?
281- Is my change too hard to review? If so, why?
282
283## What happens when your contribution is applied?
284
285Your name will likely be included in the Git commit log. If your change affects
286end users, a brief description and your name might be added to the [NEWS](/NEWS)
287file.
288
289## Git commit rules
290
291This section refers to contributors that have Git push access and make commit
292changes themselves. We'll assume you're basically familiar with Git, but feel
293free to post your questions on the mailing list. Please have a look at the more
294detailed [information on Git](https://git-scm.com/).
295
296PHP is developed through the efforts of a large number of people. Collaboration
297is a Good Thing(tm), and Git lets us do this. Thus, following some basic rules
298with regards to Git usage will:
299
300* Make everybody happier, especially those responsible for maintaining PHP
301  itself.
302* Keep the changes consistently well documented and easily trackable.
303* Prevent some of those 'Oops' moments.
304* Increase the general level of good will on planet Earth.
305
306Having said that, here are the organizational rules:
307
3081. Respect other people working on the project.
309
3102. Discuss any significant changes on the list before committing and get
311   confirmation from the release manager for the given branch.
312
3133. Look at [EXTENSIONS](/EXTENSIONS) file to see who is the primary maintainer
314   of the code you want to contribute to.
315
3164. If you "strongly disagree" about something another person did, don't start
317   fighting publicly - take it up in private email.
318
3195. If you don't know how to do something, ask first!
320
3216. Test your changes before committing them. We mean it. Really. To do so use
322   `make test`.
323
3247. For development use the `--enable-debug` switch to avoid memory leaks and the
325   `--enable-zts` switch to ensure your code handles TSRM correctly and doesn't
326   break for those who need that.
327
328Currently we have the following branches in use:
329
330| Branch    |           |
331| --------- | --------- |
332| master    | Active development branch for PHP 8.1, which is open for backwards incompatible changes and major internal API changes. |
333| PHP-8.0   | Is used to release the PHP 8.0.x series. This is a current stable version and is open for bugfixes only. |
334| PHP-7.4   | Is used to release the PHP 7.4.x series. This is a current stable version and is open for bugfixes only. |
335| PHP-7.3   | Is used to release the PHP 7.3.x series. This is a current stable version and is open for bugfixes only. |
336| PHP-7.2   | Is used to release the PHP 7.2.x series. This is an old stable version and is open for security fixes only. |
337| PHP-7.1   | This branch is closed. |
338| PHP-7.0   | This branch is closed. |
339| PHP-5.6   | This branch is closed. |
340| PHP-5.5   | This branch is closed. |
341| PHP-5.4   | This branch is closed. |
342| PHP-5.3   | This branch is closed. |
343| PHP-5.2   | This branch is closed. |
344| PHP-5.1   | This branch is closed. |
345| PHP-4.4   | This branch is closed. |
346| PHP-X.Y.Z | These branches are used for the release managers for tagging the releases, hence they are closed to the general public. |
347
348The next few rules are more of a technical nature:
349
3501. All non-security bugfix changes should first go to the lowest bugfix branch
351   (i.e. 7.3) and then get merged up to all other branches. All security fixes
352   should go to the lowest security fixes branch (i.e 7.2). If a change is not
353   needed for later branches (i.e. fixes for features which were dropped from
354   later branches) an empty merge should be done.
355
3562. All news updates intended for public viewing, such as new features, bug
357   fixes, improvements, etc., should go into the NEWS file of *any stable
358   release* version with the given change. In other words, news about a bug fix
359   which went into PHP-5.4, PHP-5.5 and master should be noted in both
360   PHP-5.4/NEWS and PHP-5.5/NEWS but not master, which is not a public released
361   version yet.
362
3633. Do not commit multiple files and dump all messages in one commit. If you
364   modified several unrelated files, commit each group separately and provide a
365   nice commit message for each one. See example below.
366
3674. Do write your commit message in such a way that it makes sense even without
368   the corresponding diff. One should be able to look at it, and immediately
369   know what was modified. Definitely include the function name in the message
370   as shown below.
371
3725. In your commit messages, keep each line shorter than 80 characters. And try
373   to align your lines vertically, if they wrap. It looks bad otherwise.
374
3756. If you modified a function that is callable from PHP, prepend PHP to the
376   function name as shown below.
377
378The format of the commit messages is pretty simple.
379
380    <max 79 characters short description>\n
381    \n
382    <long description, 79 chars per line>
383    \n
384
385An Example from the git project (commit 2b34e486bc):
386
387    pack-objects: Fix compilation with NO_PTHREDS
388
389    It looks like commit 99fb6e04 (pack-objects: convert to use parse_options(),
390    2012-02-01) moved the #ifdef NO_PTHREDS around but hasn't noticed that the
391    'arg' variable no longer is available.
392
393If you fix some bugs, you should note the bug ID numbers in your commit message.
394Bug ID should be prefixed by `#`.
395
396Example:
397
398    Fixed bug #14016 (pgsql notice handler double free crash bug.)
399
400When you change the NEWS file for a bug fix, then please keep the bugs sorted in
401decreasing order under the fixed version.
402
403## Copyright and license headers
404
405New source code files should include the following header block:
406
407```c
408/*
409  +----------------------------------------------------------------------+
410  | Copyright (c) The PHP Group                                          |
411  +----------------------------------------------------------------------+
412  | This source file is subject to version 3.01 of the PHP license,      |
413  | that is bundled with this package in the file LICENSE, and is        |
414  | available through the world-wide-web at the following url:           |
415  | https://www.php.net/license/3_01.txt                                 |
416  | If you did not receive a copy of the PHP license and are unable to   |
417  | obtain it through the world-wide-web, please send a note to          |
418  | license@php.net so we can mail you a copy immediately.               |
419  +----------------------------------------------------------------------+
420  | Author:                                                              |
421  +----------------------------------------------------------------------+
422*/
423```
424
425Thank you for contributing to PHP!
426