Newer Older
1 2 3
  PHP Coding Standards

5 6
This file lists several standards that any programmer adding or changing
code in PHP should follow.  Since this file was added at a very late
7 8
stage of the development of PHP v3.0, the code base does not (yet) fully
follow it, but it's going in that general direction.  Since we are now
well into version 5 releases, many sections have been recoded to use
10 11 12 13 14
these rules.

Code Implementation

0.  Document your code in source files and the manual. [tm]

1.  Functions that are given pointers to resources should not free them

For instance, ``function int mail(char *to, char *from)`` should NOT free
20 21 22
to and/or from.

23 24 25 26 27 28 29 30 31 32
- The function's designated behavior is freeing that resource.  E.g. efree()

- The function is given a boolean argument, that controls whether or not
  the function may free its arguments (if true - the function must free its
  arguments, if false - it must not)

- Low-level parser routines, that are tightly integrated with the token
  cache and the bison code for minimum memory copying overhead.

2.  Functions that are tightly integrated with other functions within the
33 34 35 36
    same module, and rely on each other non-trivial behavior, should be
    documented as such and declared 'static'.  They should be avoided if

3.  Use definitions and macros whenever possible, so that constants have
38 39 40 41 42
    meaningful names and can be easily manipulated.  The only exceptions
    to this rule are 0 and 1, when used as false and true (respectively).
    Any other use of a numeric constant to specify different behavior
    or actions should be done through a #define.

4.  When writing functions that deal with strings, be sure to remember
44 45 46 47 48 49 50 51
    that PHP holds the length property of each string, and that it
    shouldn't be calculated with strlen().  Write your functions in a such
    a way so that they'll take advantage of the length property, both
    for efficiency and in order for them to be binary-safe.
    Functions that change strings and obtain their new lengths while
    doing so, should return that new length, so it doesn't have to be
    recalculated with strlen() (e.g. php_addslashes())

5.  NEVER USE strncat().  If you're absolutely sure you know what you're doing,
53 54 55
    check its man page again, and only then, consider using it, and even then,
    try avoiding it.

56 57 58 59
6.  Use ``PHP_*`` macros in the PHP source, and ``ZEND_*`` macros in the Zend
    part of the source. Although the ``PHP_*`` macro's are mostly aliased to the
    ``ZEND_*`` macros it gives a better understanding on what kind of macro
    you're calling.

7.  When commenting out code using a #if statement, do NOT use 0 only. Instead
62 63
    use "<svn username here>_0". For example, #if FOO_0, where FOO is your
    svn user foo.  This allows easier tracking of why code was commented out,
    especially in bundled libraries.

66 67 68 69 70
8.  Do not define functions that are not available.  For instance, if a
    library is missing a function, do not define the PHP version of the
    function, and do not raise a run-time error about the function not
    existing.  End users should use function_exists() to test for the
    existence of a function

72 73 74 75 76
9.  Prefer emalloc(), efree(), estrdup(), etc. to their standard C library
    counterparts.  These functions implement an internal "safety-net"
    mechanism that ensures the deallocation of any unfreed memory at the
    end of a request.  They also provide useful allocation and overflow
    information while running in debug mode.

78 79
    In almost all cases, memory returned to the engine must be allocated
    using emalloc().

81 82 83
    The use of malloc() should be limited to cases where a third-party
    library may need to control or free the memory, or when the memory in
    question needs to survive between multiple requests.
84 85 86 87

Naming Conventions

1.  Function names for user-level functions should be enclosed with in
89 90 91
    the PHP_FUNCTION() macro. They should be in lowercase, with words
    underscore delimited, with care taken to minimize the letter count.
    Abbreviations should not be used when they greatly decrease the
    readability of the function name itself::
93 94 95 96 97 98 99 100 101


    (could be 'mcrypt_mod_get_algo_sup_key_sizes'?)
    (could be 'html_get_trans_table'?)
103 104 105 106 107 108


2.  If they are part of a "parent set" of functions, that parent should
110 111
    be included in the user function name, and should be clearly related
    to the parent program or function family. This should be in the form
112 113
    of ``parent_*``::

114 115 116 117 118 119 120 121 122 123 124
    A family of 'foo' functions, for example:


125 126
3.  Function names used by user functions should be prefixed
    with ``_php_``, and followed by a word or an underscore-delimited list of
127 128 129
    words, in lowercase letters, that describes the function.  If applicable,
    they should be declared 'static'.

4.  Variable names must be meaningful.  One letter variable names must be
131 132 133
    avoided, except for places where the variable has no real meaning or
    a trivial meaning (e.g. for (i=0; i<100; i++) ...).

5.  Variable names should be in lowercase.  Use underscores to separate
135 136
    between words.

6.  Method names follow the 'studlyCaps' (also referred to as 'bumpy case'
138 139
    or 'camel caps') naming convention, with care taken to minimize the
    letter count. The initial letter of the name is lowercase, and each
    letter that starts a new 'word' is capitalized::
141 142 143 144 145 146 147 148 149 150 151



152 153 154 155 156
7.  Classes should be given descriptive names. Avoid using abbreviations where
    possible. Each word in the class name should start with a capital letter,
    without underscore delimiters (CampelCaps starting with a capital letter).
    The class name should be prefixed with the name of the 'parent set' (e.g.
    the name of the extension)::
157 158 159

161 162 163 164 165 166 167 168


Syntax and indentation

1.  Never use C++ style comments (i.e. // comment).  Always use C-style
170 171 172 173 174 175 176 177
    comments instead.  PHP is written in C, and is aimed at compiling
    under any ANSI-C compliant compiler.  Even though many compilers
    accept C++-style comments in C code, you have to ensure that your
    code would compile with other compilers as well.
    The only exception to this rule is code that is Win32-specific,
    because the Win32 port is MS-Visual C++ specific, and this compiler
    is known to accept C++-style comments in C code.

2.  Use K&R-style.  Of course, we can't and don't want to
179 180 181 182 183
    force anybody to use a style he or she is not used to, but,
    at the very least, when you write code that goes into the core
    of PHP or one of its standard modules, please maintain the K&R
    style.  This applies to just about everything, starting with
    indentation and comment styles and up to function declaration
184 185 186
    syntax. Also see Indentstyle_.

.. _Indentstyle:

188 189 190 191
3.  Be generous with whitespace and braces.  Keep one empty line between the
    variable declaration section and the statements in a block, as well as
    between logical statement groups in a block.  Maintain at least one empty
    line between two functions, preferably two.  Always prefer::
192 193 194 195 196 197 198 199 200

    if (foo) {



4.  When indenting, use the tab character.  A tab is expected to represent
202 203 204
    four spaces.  It is important to maintain consistency in indenture so
    that definitions, comments, and control structures line up correctly.

5.  Preprocessor statements (#if and such) MUST start at column one. To
206 207 208
    indent preprocessor directives you should put the # at the beginning
    of a line, followed by any number of whitespace.

209 210 211

1.  Extensions should be well tested using *.phpt tests. Read about that
213 214

215 216 217 218 219 220
Documentation and Folding Hooks

In order to make sure that the online documentation stays in line with
the code, each user-level function should have its user-level function
prototype before it along with a brief one-line description of what the
function does.  It would look like this::

223 224 225 226 227 228 229
  /* {{{ proto int abs(int number)
     Returns the absolute value of the number */
  /* }}} */
230 231

The {{{ symbols are the default folding symbols for the folding mode in
232 233 234
Emacs and vim (set fdm=marker).  Folding is very useful when dealing with
large files because you can scroll through the file quickly and just unfold
the function you wish to work on.  The }}} at the end of each function marks
235 236 237 238 239 240 241
the end of the fold, and should be on a separate line.

The "proto" keyword there is just a helper for the doc/genfuncsummary script
which generates a full function summary.  Having this keyword in front of the
function prototypes allows us to put folds elsewhere in the code without
messing up the function summary.

Optional arguments are written like this::

244 245
  /* {{{ proto object imap_header(int stream_id, int msg_no [, int from_length [, int subject_length [, string default_host]]])
     Returns a header object with the defined parameters */
246 247 248 249 250 251 252 253 254 255 256 257

And yes, please keep the prototype on a single line, even if that line
is massive.

New and Experimental Functions
To reduce the problems normally associated with the first public
implementation of a new set of functions, it has been suggested
that the first implementation include a file labeled 'EXPERIMENTAL'
in the function directory, and that the functions follow the
standard prefixing conventions during their initial implementation.

258 259 260 261
The file labelled 'EXPERIMENTAL' should include the following

  Any authoring information (known bugs, future directions of the module).
  Ongoing status notes which may not be appropriate for SVN comments.
263 264 265 266 267 268 269 270 271 272 273 274 275 276 277

Aliases & Legacy Documentation
You may also have some deprecated aliases with close to duplicate
names, for example, somedb_select_result and somedb_selectresult. For
documentation purposes, these will only be documented by the most
current name, with the aliases listed in the documentation for
the parent function. For ease of reference, user-functions with
completely different names, that alias to the same function (such as
highlight_file and show_source), will be separately documented. The
proto should still be included, describing which function is aliased.

Backwards compatible functions and names should be maintained as long
as the code can be reasonably be kept as part of the codebase. See
/phpdoc/README for more information on documentation.