5
This file lists several standards that any programmer, adding or changing
6
code in PHP, should follow. Since this file was added at a very late
7
stage of the development of PHP v3.0, the code base does not (yet) fully
8
follow it, but it's going in that general direction. Since we are now
9
well into the version 4 releases, many sections have been recoded to use
16
[0] Document your code in source files and the manual. [tm]
18
[1] Functions that are given pointers to resources should not free them
20
For instance, function int mail(char *to, char *from) should NOT free
24
- The function's designated behavior is freeing that resource. E.g. efree()
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
- Low-level parser routines, that are tightly integrated with the token
29
cache and the bison code for minimum memory copying overhead.
31
[2] Functions that are tightly integrated with other functions within the
32
same module, and rely on each other non-trivial behavior, should be
33
documented as such and declared 'static'. They should be avoided if
36
[3] Use definitions and macros whenever possible, so that constants have
37
meaningful names and can be easily manipulated. The only exceptions
38
to this rule are 0 and 1, when used as false and true (respectively).
39
Any other use of a numeric constant to specify different behavior
40
or actions should be done through a #define.
42
[4] When writing functions that deal with strings, be sure to remember
43
that PHP holds the length property of each string, and that it
44
shouldn't be calculated with strlen(). Write your functions in a such
45
a way so that they'll take advantage of the length property, both
46
for efficiency and in order for them to be binary-safe.
47
Functions that change strings and obtain their new lengths while
48
doing so, should return that new length, so it doesn't have to be
49
recalculated with strlen() (e.g. php_addslashes())
51
[5] NEVER USE strncat(). If you're absolutely sure you know what you're doing,
52
check its man page again, and only then, consider using it, and even then,
55
[6] Use PHP_* macros in the PHP source, and ZEND_* macros in the Zend
56
part of the source. Although the PHP_* macro's are mostly aliased to the
57
ZEND_* macros it gives a better understanding on what kind of macro you're
60
[7] When commenting out code using a #if statement, do NOT use 0 only. Instead
61
use "<cvs username here>_0". For example, #if FOO_0, where FOO is your
62
cvs user foo. This allows easier tracking of why code was commented out,
63
especially in bundled libraries.
65
[8] Do not define functions that are not available. For instance, if a
66
library is missing a function, do not define the PHP version of the
67
function, and do not raise a run-time error about the function not
68
existing. End users should use function_exists() to test for the
69
existence of a function
71
[9] Prefer emalloc(), efree(), estrdup(), etc. to their standard C library
72
counterparts. These functions implement an internal "safety-net"
73
mechanism that ensures the deallocation of any unfreed memory at the
74
end of a request. They also provide useful allocation and overflow
75
information while running in debug mode.
77
In almost all cases, memory returned to the engine must be allocated
80
The use of malloc() should be limited to cases where a third-party
81
library may need to control or free the memory, or when the memory in
82
question needs to survive between multiple requests.
87
[1] Function names for user-level functions should be enclosed with in
88
the PHP_FUNCTION() macro. They should be in lowercase, with words
89
underscore delimited, with care taken to minimize the letter count.
90
Abbreviations should not be used when they greatly decrease the
91
readability of the function name itself.
94
'mcrypt_enc_self_test'
98
'mcrypt_module_get_algo_supported_key_sizes'
99
(could be 'mcrypt_mod_get_algo_sup_key_sizes'?)
100
'get_html_translation_table'
101
(could be 'html_get_trans_table'?)
104
'hw_GetObjectByQueryCollObj'
105
'pg_setclientencoding'
108
[2] If they are part of a "parent set" of functions, that parent should
109
be included in the user function name, and should be clearly related
110
to the parent program or function family. This should be in the form
113
A family of 'foo' functions, for example:
124
[3] Function names used by user functions should be prefixed
125
with "_php_", and followed by a word or an underscore-delimited list of
126
words, in lowercase letters, that describes the function. If applicable,
127
they should be declared 'static'.
129
[4] Variable names must be meaningful. One letter variable names must be
130
avoided, except for places where the variable has no real meaning or
131
a trivial meaning (e.g. for (i=0; i<100; i++) ...).
133
[5] Variable names should be in lowercase. Use underscores to separate
136
[6] Method names follow the 'studlyCaps' (also referred to as 'bumpy case'
137
or 'camel caps') naming convention, with care taken to minimize the
138
letter count. The initial letter of the name is lowercase, and each
139
letter that starts a new 'word' is capitalized.
151
[7] Classes should be given descriptive names. Avoid using abbreviations
152
where possible. Each word in the class name should start with a capital
153
letter, with words underscore delimited. The class name should be prefixed
154
with the name of the 'parent set'.
166
Syntax and indentation
167
----------------------
169
[1] Never use C++ style comments (i.e. // comment). Always use C-style
170
comments instead. PHP is written in C, and is aimed at compiling
171
under any ANSI-C compliant compiler. Even though many compilers
172
accept C++-style comments in C code, you have to ensure that your
173
code would compile with other compilers as well.
174
The only exception to this rule is code that is Win32-specific,
175
because the Win32 port is MS-Visual C++ specific, and this compiler
176
is known to accept C++-style comments in C code.
178
[2] Use K&R-style. Of course, we can't and don't want to
179
force anybody to use a style he or she is not used to, but,
180
at the very least, when you write code that goes into the core
181
of PHP or one of its standard modules, please maintain the K&R
182
style. This applies to just about everything, starting with
183
indentation and comment styles and up to function declaration
186
(see also http://www.catb.org/~esr/jargon/html/I/indent-style.html)
188
[3] Be generous with whitespace and braces. Always prefer:
198
Keep one empty line between the variable declaration section and
199
the statements in a block, as well as between logical statement
200
groups in a block. Maintain at least one empty line between
201
two functions, preferably two.
203
[4] When indenting, use the tab character. A tab is expected to represent
204
four spaces. It is important to maintain consistency in indenture so
205
that definitions, comments, and control structures line up correctly.
207
[5] Preprocessor statements (#if and such) MUST start at column one. To
208
indent preprocessor directives you should put the # at the beginning
209
of a line, followed by any number of whitespace.
211
Documentation and Folding Hooks
212
-------------------------------
214
In order to make sure that the online documentation stays in line with
215
the code, each user-level function should have its user-level function
216
prototype before it along with a brief one-line description of what the
217
function does. It would look like this:
219
/* {{{ proto int abs(int number)
220
Returns the absolute value of the number */
227
The {{{ symbols are the default folding symbols for the folding mode in
228
Emacs and vim (set fdm=marker). Folding is very useful when dealing with
229
large files because you can scroll through the file quickly and just unfold
230
the function you wish to work on. The }}} at the end of each function marks
231
the end of the fold, and should be on a separate line.
233
The "proto" keyword there is just a helper for the doc/genfuncsummary script
234
which generates a full function summary. Having this keyword in front of the
235
function prototypes allows us to put folds elsewhere in the code without
236
messing up the function summary.
238
Optional arguments are written like this:
240
/* {{{ proto object imap_header(int stream_id, int msg_no [, int from_length [, int subject_length [, string default_host]]])
241
Returns a header object with the defined parameters */
243
And yes, please keep the prototype on a single line, even if that line
246
New and Experimental Functions
247
-----------------------------------
248
To reduce the problems normally associated with the first public
249
implementation of a new set of functions, it has been suggested
250
that the first implementation include a file labeled 'EXPERIMENTAL'
251
in the function directory, and that the functions follow the
252
standard prefixing conventions during their initial implementation.
254
The file labelled 'EXPERIMENTAL' should include the following
256
Any authoring information (known bugs, future directions of the module).
257
Ongoing status notes which may not be appropriate for CVS comments.
259
Aliases & Legacy Documentation
260
-----------------------------------
261
You may also have some deprecated aliases with close to duplicate
262
names, for example, somedb_select_result and somedb_selectresult. For
263
documentation purposes, these will only be documented by the most
264
current name, with the aliases listed in the documentation for
265
the parent function. For ease of reference, user-functions with
266
completely different names, that alias to the same function (such as
267
highlight_file and show_source), will be separately documented. The
268
proto should still be included, describing which function is aliased.
270
Backwards compatible functions and names should be maintained as long
271
as the code can be reasonably be kept as part of the codebase. See
272
/phpdoc/README for more information on documentation.
added
removed
CODING_STANDARDS
