xref: /PHP-5.4/CODING_STANDARDS (revision d65ddb63)
1========================
2  PHP Coding Standards
3========================
4
5This file lists several standards that any programmer adding or changing
6code in PHP should follow.  Since this file was added at a very late
7stage of the development of PHP v3.0, the code base does not (yet) fully
8follow it, but it's going in that general direction.  Since we are now
9well into version 5 releases, many sections have been recoded to use
10these rules.
11
12Code Implementation
13-------------------
14
150.  Document your code in source files and the manual. [tm]
16
171.  Functions that are given pointers to resources should not free them
18
19For instance, ``function int mail(char *to, char *from)`` should NOT free
20to and/or from.
21Exceptions:
22
23- The function's designated behavior is freeing that resource.  E.g. efree()
24
25- The function is given a boolean argument, that controls whether or not
26  the function may free its arguments (if true - the function must free its
27  arguments, if false - it must not)
28
29- Low-level parser routines, that are tightly integrated with the token
30  cache and the bison code for minimum memory copying overhead.
31
322.  Functions that are tightly integrated with other functions within the
33    same module, and rely on each other non-trivial behavior, should be
34    documented as such and declared 'static'.  They should be avoided if
35    possible.
36
373.  Use definitions and macros whenever possible, so that constants have
38    meaningful names and can be easily manipulated.  The only exceptions
39    to this rule are 0 and 1, when used as false and true (respectively).
40    Any other use of a numeric constant to specify different behavior
41    or actions should be done through a #define.
42
434.  When writing functions that deal with strings, be sure to remember
44    that PHP holds the length property of each string, and that it
45    shouldn't be calculated with strlen().  Write your functions in a such
46    a way so that they'll take advantage of the length property, both
47    for efficiency and in order for them to be binary-safe.
48    Functions that change strings and obtain their new lengths while
49    doing so, should return that new length, so it doesn't have to be
50    recalculated with strlen() (e.g. php_addslashes())
51
525.  NEVER USE strncat().  If you're absolutely sure you know what you're doing,
53    check its man page again, and only then, consider using it, and even then,
54    try avoiding it.
55
566.  Use ``PHP_*`` macros in the PHP source, and ``ZEND_*`` macros in the Zend
57    part of the source. Although the ``PHP_*`` macro's are mostly aliased to the
58    ``ZEND_*`` macros it gives a better understanding on what kind of macro
59    you're calling.
60
617.  When commenting out code using a #if statement, do NOT use 0 only. Instead
62    use "<git username here>_0". For example, #if FOO_0, where FOO is your
63    git user foo.  This allows easier tracking of why code was commented out,
64    especially in bundled libraries.
65
668.  Do not define functions that are not available.  For instance, if a
67    library is missing a function, do not define the PHP version of the
68    function, and do not raise a run-time error about the function not
69    existing.  End users should use function_exists() to test for the
70    existence of a function
71
729.  Prefer emalloc(), efree(), estrdup(), etc. to their standard C library
73    counterparts.  These functions implement an internal "safety-net"
74    mechanism that ensures the deallocation of any unfreed memory at the
75    end of a request.  They also provide useful allocation and overflow
76    information while running in debug mode.
77
78    In almost all cases, memory returned to the engine must be allocated
79    using emalloc().
80
81    The use of malloc() should be limited to cases where a third-party
82    library may need to control or free the memory, or when the memory in
83    question needs to survive between multiple requests.
84
85User Functions/Methods Naming Conventions
86------------------
87
881.  Function names for user-level functions should be enclosed with in
89    the PHP_FUNCTION() macro. They should be in lowercase, with words
90    underscore delimited, with care taken to minimize the letter count.
91    Abbreviations should not be used when they greatly decrease the
92    readability of the function name itself::
93
94    Good:
95    'mcrypt_enc_self_test'
96    'mysql_list_fields'
97
98    Ok:
99    'mcrypt_module_get_algo_supported_key_sizes'
100    (could be 'mcrypt_mod_get_algo_sup_key_sizes'?)
101    'get_html_translation_table'
102    (could be 'html_get_trans_table'?)
103
104    Bad:
105    'hw_GetObjectByQueryCollObj'
106    'pg_setclientencoding'
107    'jf_n_s_i'
108
1092.  If they are part of a "parent set" of functions, that parent should
110    be included in the user function name, and should be clearly related
111    to the parent program or function family. This should be in the form
112    of ``parent_*``::
113
114    A family of 'foo' functions, for example:
115    Good:
116    'foo_select_bar'
117    'foo_insert_baz'
118    'foo_delete_baz'
119
120    Bad:
121    'fooselect_bar'
122    'fooinsertbaz'
123    'delete_foo_baz'
124
1253.  Function names used by user functions should be prefixed
126    with ``_php_``, and followed by a word or an underscore-delimited list of
127    words, in lowercase letters, that describes the function.  If applicable,
128    they should be declared 'static'.
129
1304.  Variable names must be meaningful.  One letter variable names must be
131    avoided, except for places where the variable has no real meaning or
132    a trivial meaning (e.g. for (i=0; i<100; i++) ...).
133
1345.  Variable names should be in lowercase.  Use underscores to separate
135    between words.
136
1376.  Method names follow the 'studlyCaps' (also referred to as 'bumpy case'
138    or 'camel caps') naming convention, with care taken to minimize the
139    letter count. The initial letter of the name is lowercase, and each
140    letter that starts a new 'word' is capitalized::
141
142    Good:
143    'connect()'
144    'getData()'
145    'buildSomeWidget()'
146
147    Bad:
148    'get_Data()'
149    'buildsomewidget'
150    'getI()'
151
1527.  Classes should be given descriptive names. Avoid using abbreviations where
153    possible. Each word in the class name should start with a capital letter,
154    without underscore delimiters (CamelCaps starting with a capital letter).
155    The class name should be prefixed with the name of the 'parent set' (e.g.
156    the name of the extension)::
157
158    Good:
159    'Curl'
160    'FooBar'
161
162    Bad:
163    'foobar'
164    'foo_bar'
165
166Internal Function Naming Convensions
167----------------------
168
1691.  Functions that are part of the external API should be named
170    'php_modulename_function()' to avoid symbol collision. They should be in
171    lowercase, with words underscore delimited. Exposed API must be defined
172    in 'php_modulename.h'.
173
174    PHPAPI char *php_session_create_id(PS_CREATE_SID_ARGS);
175
176    Unexposed module function should be static and should not be defined in
177    'php_modulename.h'.
178
179    static int php_session_destroy(TSRMLS_D)
180
1812.  Main module source file must be named 'modulename.c'.
182
1833.  Header file that is used by other sources must be named 'php_modulename.h'.
184
185
186Syntax and indentation
187----------------------
188
1891.  Never use C++ style comments (i.e. // comment).  Always use C-style
190    comments instead.  PHP is written in C, and is aimed at compiling
191    under any ANSI-C compliant compiler.  Even though many compilers
192    accept C++-style comments in C code, you have to ensure that your
193    code would compile with other compilers as well.
194    The only exception to this rule is code that is Win32-specific,
195    because the Win32 port is MS-Visual C++ specific, and this compiler
196    is known to accept C++-style comments in C code.
197
1982.  Use K&R-style.  Of course, we can't and don't want to
199    force anybody to use a style he or she is not used to, but,
200    at the very least, when you write code that goes into the core
201    of PHP or one of its standard modules, please maintain the K&R
202    style.  This applies to just about everything, starting with
203    indentation and comment styles and up to function declaration
204    syntax. Also see Indentstyle.
205
206    Indentstyle: http://www.catb.org/~esr/jargon/html/I/indent-style.html
207
2083.  Be generous with whitespace and braces.  Keep one empty line between the
209    variable declaration section and the statements in a block, as well as
210    between logical statement groups in a block.  Maintain at least one empty
211    line between two functions, preferably two.  Always prefer::
212
213    if (foo) {
214        bar;
215    }
216
217    to:
218
219    if(foo)bar;
220
2214.  When indenting, use the tab character.  A tab is expected to represent
222    four spaces.  It is important to maintain consistency in indenture so
223    that definitions, comments, and control structures line up correctly.
224
2255.  Preprocessor statements (#if and such) MUST start at column one. To
226    indent preprocessor directives you should put the # at the beginning
227    of a line, followed by any number of whitespace.
228
229Testing
230-------
231
2321.  Extensions should be well tested using *.phpt tests. Read about that
233    in README.TESTING.
234
235Documentation and Folding Hooks
236-------------------------------
237
238In order to make sure that the online documentation stays in line with
239the code, each user-level function should have its user-level function
240prototype before it along with a brief one-line description of what the
241function does.  It would look like this::
242
243  /* {{{ proto int abs(int number)
244     Returns the absolute value of the number */
245  PHP_FUNCTION(abs)
246  {
247     ...
248  }
249  /* }}} */
250
251The {{{ symbols are the default folding symbols for the folding mode in
252Emacs and vim (set fdm=marker).  Folding is very useful when dealing with
253large files because you can scroll through the file quickly and just unfold
254the function you wish to work on.  The }}} at the end of each function marks
255the end of the fold, and should be on a separate line.
256
257The "proto" keyword there is just a helper for the doc/genfuncsummary script
258which generates a full function summary.  Having this keyword in front of the
259function prototypes allows us to put folds elsewhere in the code without
260messing up the function summary.
261
262Optional arguments are written like this::
263
264  /* {{{ proto object imap_header(int stream_id, int msg_no [, int from_length [, int subject_length [, string default_host]]])
265     Returns a header object with the defined parameters */
266
267And yes, please keep the prototype on a single line, even if that line
268is massive.
269
270New and Experimental Functions
271-----------------------------------
272To reduce the problems normally associated with the first public
273implementation of a new set of functions, it has been suggested
274that the first implementation include a file labeled 'EXPERIMENTAL'
275in the function directory, and that the functions follow the
276standard prefixing conventions during their initial implementation.
277
278The file labelled 'EXPERIMENTAL' should include the following
279information::
280
281  Any authoring information (known bugs, future directions of the module).
282  Ongoing status notes which may not be appropriate for SVN comments.
283
284Aliases & Legacy Documentation
285-----------------------------------
286You may also have some deprecated aliases with close to duplicate
287names, for example, somedb_select_result and somedb_selectresult. For
288documentation purposes, these will only be documented by the most
289current name, with the aliases listed in the documentation for
290the parent function. For ease of reference, user-functions with
291completely different names, that alias to the same function (such as
292highlight_file and show_source), will be separately documented. The
293proto should still be included, describing which function is aliased.
294
295Backwards compatible functions and names should be maintained as long
296as the code can be reasonably be kept as part of the codebase. See
297/phpdoc/README for more information on documentation.
298