php-src/CONTRIBUTING.md

Contributing to PHP

Anybody who programs in PHP can be a contributing member of the community that develops and deploys it; the task of deploying PHP, documentation and associated websites is a never ending one. With every release, or release candidate comes a wave of work, which takes a lot of organization and co-ordination.

Pull requests

PHP welcomes pull requests to add tests, fix bugs and to implement RFCs. Please be sure to include tests as appropriate!

If you are fixing a bug, then please submit your PR against the lowest actively supported branch of PHP that the bug affects (only green branches on the supported version page are supported). For example, at the time of writing in early-2018, the lowest supported version is PHP 7.1, which corresponds to the PHP-7.1 branch in Git. Please also make sure you add a link to the PR in the bug on the bug tracker.

Pull requests implementing RFCs should be submitted against master.

Pull requests should never be submitted against PHP-x.y.z branches, as these are only used for release management.

If your pull request exhibits conflicts with the base branch, please resolve them by using git rebase instead of git merge.

Filing bugs

Bugs can be filed on the PHP bug tracker. If this is the first time you've filed a bug, we suggest reading the guide to reporting a bug.

Where possible, please include a self-contained reproduction case!

Feature requests

Feature requests are generally submitted in the form of Requests for Comment, ideally accompanied by pull requests. You can find the extremely large list of RFCs that have been previously considered on the PHP Wiki.

You may want to read The Mysterious PHP RFC Process for additional notes on the best way to approach submitting an RFC.

Writing tests

We love getting new tests! PHP is a huge project and improving code coverage is a huge win for every PHP user.

Our QA site includes a page detailing how to write test cases. Please note that the section on submitting pull requests is outdated: in addition to the process listed there, you can also submit pull requests.

Writing documentation

There are two ways to contribute to the PHP manual. You can edit the manual and send patches anonymously via the online editor, or you can check the XML source out from Subversion and edit that and build it per the instructions on the documentation site. Patches created that way should be sent to the documentation mailing list.

Getting help

If you are having trouble contributing to PHP, or just want to talk to a human about what you're working on, you can contact us via the internals mailing list, or the documentation mailing list for documentation issues.

Although not a formal channel, you can also find a number of core developers on the #php.pecl channel on EFnet. Similarly, many documentation writers can be found on #php.doc.

PHP source code directory structure

PHP source code also includes several files generated during development and several parts where maintenance is happening upstream in their respective locations.

<php-src>/
 ├─ .git/                           # Git configuration and source directory
 └─ TSRM/                           # Thread Safe Resource Manager
    └─ m4/                          # https://github.com/autoconf-archive/autoconf-archive
       └─ ax_func_which_gethostbyname_r.m4
    └─ ...
 └─ Zend/                           # Zend Engine
    ├─ zend_language_scanner.c      # Generated by re2c
    ├─ zend_language_scanner_defs.h # Generated by re2c
    ├─ zend_ini_scanner.c           # Generated by re2c
    ├─ zend_ini_scanner_defs.h      # Generated by re2c
    ├─ zend_vm_execute.h            # Generated by `Zend/zend_vm_gen.php`
    ├─ zend_vm_opcodes.c            # Generated by `Zend/zend_vm_gen.php`
    ├─ zend_vm_opcodes.h            # Generated by `Zend/zend_vm_gen.php`
    └─ ...
 ├─ appveyor/                       # Appveyor CI service files
 └─ build/                          # *nix build system files
    ├─ ax_check_compile_flag.m4     # https://github.com/autoconf-archive/autoconf-archive
    ├─ ax_gcc_func_attribute.m4     # https://github.com/autoconf-archive/autoconf-archive
    ├─ libtool.m4                   # https://git.savannah.gnu.org/cgit/libtool.git
    ├─ shtool                       # https://www.gnu.org/software/shtool/
    └─ ...
 └─ ext/                            # PHP core extensions
    └─ bcmath/
       ├─ libbcmath/                # Forked and maintained in php-src
       └─ ...
    └─ curl/
       ├─ sync-constants.php        # The curl symbols checker
       └─ ...
    └─ date/
       └─ lib/                      # Bundled datetime library https://github.com/derickr/timelib
          ├─ parse_date.c           # Generated by re2c 0.15.3
          ├─ parse_iso_intervals.c  # Generated by re2c 0.15.3
          └─ ...
       └─ ...
    └─ fileinfo/
       ├─ libmagic/                 # Modified libmagic https://github.com/file/file
       ├─ data_file.c               # Generated by `ext/fileinfo/create_data_file.php`
       ├─ libmagic.patch            # Modifications patch from upstream libmagic
       ├─ magicdata.patch           # Modifications patch from upstream libmagic
       └─ ...
    └─ gd/
       ├─ libgd/                    # Bundled and modified GD library https://github.com/libgd/libgd
       └─ ...
    └─ json/
       ├─ json_parser.tab.c         # Generated by bison
       ├─ json_parser.tab.h         # Generated by bison
       ├─ json_scanner.c            # Generated by re2c
       ├─ php_json_scanner_defs.h   # Generated by re2c
       └─ ...
    └─ mbstring/
       ├─ libmbfl/                  # Forked and maintained in php-src
       ├─ oniguruma/                # Bundled https://github.com/kkos/oniguruma
       ├─ oniguruma.patch           # Modifications patch from upstream oniguruma
       ├─ unicode_data.h            # Generated by `ext/mbstring/ucgendat/ucgendat.php`
       └─ ...
    └─ pcre/
       ├─ pcre2lib/                 # https://www.pcre.org/
       └─ ...
    └─ pdo/
       ├─ pdo_sql_parser.c          # Generated by re2c
       └─ ...
    └─ phar/
       ├─ phar_path_check.c         # Generated by re2c
       └─ ...
    └─ skeleton/                    # Skeleton for developing new extensions with `ext/ext_skel.php`
       └─ ...
    └─ sqlite3/
       ├─ libsqlite/                # https://www.sqlite.org mirror: https://github.com/mackyle/sqlite
       └─ ...
    └─ standard/
       └─ html_tables/
          ├─ mappings/              # https://www.unicode.org/Public/MAPPINGS/
          └─ ...
       ├─ credits_ext.h             # Generated by `scripts/dev/credits`
       ├─ credits_sapi.h            # Generated by `scripts/dev/credits`
       ├─ html_tables.h             # Generated by `ext/standard/html_tables/html_table_gen.php`
       ├─ url_scanner_ex.c          # Generated by re2c
       ├─ var_unserializer.c        # Generated by re2c
       └─ ...
    └─ tokenizer/
       ├─ tokenizer_data.c          # Generated by `ext/tokenizer/tokenizer_data_gen.sh`
       └─ ...
    └─ xmlrpc/
       ├─ libxmlrpc/                # Forked and maintained in php-src
       └─ ...
    └─ zend_test                    # For testing internal APIs. Not needed for regular builds.
       └─ ...
    └─ zip/                         # Bundled https://github.com/pierrejoye/php_zip
       └─ ...
    └─ ...
 └─ main/                           # Binding that ties extensions, SAPIs, and engine together
    ├─ streams/                     # Streams layer subsystem
    ├─ php_version.h                # Generated by release managers using `configure`
    └─ ...
 ├─ pear/                           # PEAR installation
 └─ sapi/                           # PHP SAPI modules
    └─ cli/
       ├─ mime_type_map.h           # Generated by `sapi/cli/generate_mime_type_map.php`
       └─ ...
    └─ phpdbg/
       ├─ phpdbg_lexer.c            # Generated by re2c
       ├─ phpdbg_parser.c           # Generated by bison
       ├─ phpdbg_parser.h           # Generated by bison
       └─ ...
    └─ ...
 ├─ scripts/                        # php-config, phpize and internal development scripts
 ├─ tests/                          # Core features tests
 ├─ travis/                         # Travis CI service files
 └─ win32/                          # Windows build system files
    ├─ cp_enc_map.c                 # Generated by `win32/cp_enc_map_gen.exe`
    └─ ...
 ├─ config.guess                    # https://git.savannah.gnu.org/cgit/config.git
 ├─ config.sub                      # https://git.savannah.gnu.org/cgit/config.git
 ├─ ltmain.sh                       # https://git.savannah.gnu.org/cgit/libtool.git
 └─ ...