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