Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master
Fetching contributors…

Cannot retrieve contributors at this time

file 182 lines (140 sloc) 7.602 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182
Submitting Enhancements and Patches to PHP
==========================================

This document describes how to submit an enhancement or patch for PHP.
It's easy!

You don't need any login accounts or special access to download,
build, debug and begin submitting PHP or PECL code, tests or
documentation. Once you've followed this README and had several
patches accepted, commit privileges are often quickly granted.

An excellent article to read first is:
http://phpadvent.org/2008/less-whining-more-coding-by-elizabeth-smith


Online Forums
-------------
There are several IRC channels where PHP developers are often
available to discuss questions. They include #php.pecl and #php.doc
on the EFNet network and #php-dev-win on FreeNode.


PHP Patches
-----------
If you are fixing broken functionality in PHP C source code first
create a bug or identify an existing bug at http://bugs.php.net/. A
bug can be used to track the patch progress and prevent your changes
getting lost in the PHP mail archives.

If your change is large then create a Request For Comment (RFC) page
on http://wiki.php.net/rfc, discuss it with the extension maintainer,
and discuss it on the development mail list internals@lists.php.net.
RFC Wiki accounts can be requested on
http://wiki.php.net/start?do=register. PHP extension maintainers can
be found in the EXTENSIONS file in the PHP source. Mail list
subscription is explained on http://www.php.net/mailing-lists.php.

Information on PHP internal C functions is at
http://www.php.net/internals, though this is considered incomplete.
Various external resources can be found on the web. A standard
printed reference is the book "Extending and Embedding PHP" by Sara
Golemon.

Attach the patch to the PHP bug and consider sending a notification
email about the change to internals@lists.php.net. Also CC the
extension maintainer. Explain what has been changed by your patch.
Test scripts should be included.

Please make the mail subject prefix "[PATCH]". If attaching a patch,
ensure it has a file extension of ".txt". This is because only MIME
attachments of type 'text/*' are accepted.


PHP Documentation Patches
-------------------------
If you are fixing incorrect PHP documentation first create a bug or
identify an existing bug at http://bugs.php.net/. A bug can be used
to track the patch progress and prevent your changes getting lost in
the PHP mail archives.

If your change is large, then first discuss it with the mail list
phpdoc@lists.php.net. Subscription is explained on
http://www.php.net/mailing-lists.php.

Information on contributing to PHP documentation is at
http://php.net/dochowto and http://wiki.php.net/doc/howto

Attach the patch to the PHP bug and consider sending a notification
email about the change to phpdoc@lists.php.net. Explain what has been
fixed/added/changed by your patch.

Please make the mail subject prefix "[PATCH]". Include the bug id(s)
which can be closed by your patch. If attaching a patch, ensure it
has a file extension of ".txt". This is because only MIME attachments
of type 'text/*' are accepted.


PECL Extension Patches: http://pecl.php.net/
--------------------------------------------
If you are fixing broken functionality in a PECL extension then create
a bug or identify an existing bug at http://bugs.php.net/. A bug
can be used to track the patch progress and prevent your changes
getting lost in the PHP mail archives.

If your change is large then create a Request For Comment (RFC) page
on http://wiki.php.net/rfc, discuss it with the extension maintainer,
and discuss it on the development mail list pecl-dev@lists.php.net.
PECL mail list subscription is explained on
http://pecl.php.net/support.php. RFC Wiki accounts can be requested
on http://wiki.php.net/start?do=register

Information on PHP internal C functions is at
http://www.php.net/internals, though this is considered incomplete.
Various external resources can be found on the web. A standard
printed reference is the book "Extending and Embedding PHP" by Sara
Golemon.

Update any open bugs and add a link to the source of your patch. Send
the patch or pointer to the bug to pecl-dev@lists.php.net. Also CC
the extension maintainer. Explain what has been changed by your
patch. Test scripts should be included.

Please make the mail subject prefix "[PATCH] ...". Include the patch
as an attachment with a file extension of ".txt". This is because
only MIME attachments of type 'text/*' are accepted.


PEAR Package Patches: http://pear.php.net/
------------------------------------------
Information on contributing to PEAR is available at
http://pear.php.net/manual/en/developers-newmaint.php and
http://pear.php.net/manual/en/guide-developers.php


How to create your PHP, PHP Documentation or PECL patch
-------------------------------------------------------
PHP and most PECL packages use Git for revision control. Some PECL
packages use Subversion (SVN) Read http://www.php.net/git.php for help
on using Git to get and build PHP source code. We recommend to look
at our workflow on https://wiki.php.net/vcs/gitworkflow and our FAQ
https://wiki.php.net/vcs/gitfaq.

Generally we ask that bug fix patches work on the current stable PHP
development branches and on "master". New PHP features only need to
work on "master".

Read CODING_STANDARDS before you start working.

After modifying the source see README.TESTING and
http://qa.php.net/write-test.php for how to test. Submitting test
scripts helps us to understand what functionality has changed. It is
important for the stability and maintainability of PHP that tests are
comprehensive.

After testing is finished, create a patch file using the command:

  git diff > your_patch.txt

For ease of review and later troubleshooting, submit individual
patches for each bug or feature.


Checklist for submitting your PHP or PECL code patch
----------------------------------------------------
 - Update git source just before running your final 'diff' and
   before testing.
 - Add in-line comments and/or have external documentation ready.
   Use only "/* */" style comments, not "//".
 - Create test scripts for use with "make test".
 - Run "make test" to check your patch doesn't break other features.
 - Rebuild PHP with --enable-debug (which will show some kinds of
   memory errors) and check the PHP and web server error logs after
   running your PHP tests.
 - Rebuild PHP with --enable-maintainer-zts to check your patch
   compiles on multi-threaded web servers.
 - Review the patch once more just before submitting it.


What happens after submitting your PHP, PHP Documentation or PECL patch
-----------------------------------------------------------------------
If your patch is easy to review and obviously has no side-effects,
it might be committed relatively quickly.

Because PHP is a volunteer-driven effort more complex patches will
require patience on your side. If you do not receive feedback in a
few days, consider resubmitting the patch. Before doing this think
about these questions:

 - Did I send the patch to the right mail list?
 - Did I review the mail list archives to see if these kind of
   changes had been discussed before?
 - Did I explain my patch clearly?
 - Is my patch too hard to review? Because of what factors?


What happens when your PHP or PECL patch is applied
---------------------------------------------------
Your name will likely be included in the Git commit log. If your
patch affects end users, a brief description and your name might be
added to the NEWS file.

Thank you for patching PHP!
Something went wrong with that request. Please try again.