Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 278 lines (217 sloc) 11.109 kb
aceaabc @zsuraski PHP 4.0
zsuraski authored
1 PHP Coding Standards
2 ====================
3
4
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
45807e6 @jparise Added a brief section documenting the preference of tabs over spaces.
jparise authored
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
10 these rules.
aceaabc @zsuraski PHP 4.0
zsuraski authored
11
12
13 Code Implementation
14 -------------------
15
6d10159 comments & php_error_docref
Marcus Boerger authored
16 [0] Document your code in source files and the manual. [tm]
17
aceaabc @zsuraski PHP 4.0
zsuraski authored
18 [1] Functions that are given pointers to resources should not free them
19
20 For instance, function int mail(char *to, char *from) should NOT free
21 to and/or from.
22 Exceptions:
23
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.
30
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
34 possible.
35
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.
41
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
585e338 php4ize a bit.
Sterling Hughes authored
49 recalculated with strlen() (e.g. php_addslashes())
aceaabc @zsuraski PHP 4.0
zsuraski authored
50
a072914 both these entries are bad, and were never agreed upon.
Sterling Hughes authored
51 [5] NEVER USE strncat(). If you're absolutely sure you know what you're doing,
aceaabc @zsuraski PHP 4.0
zsuraski authored
52 check its man page again, and only then, consider using it, and even then,
53 try avoiding it.
54
a072914 both these entries are bad, and were never agreed upon.
Sterling Hughes authored
55 [6] Use PHP_* macros in the PHP source, and ZEND_* macros in the Zend
612d5b9 - spaces instead of tabs
Derick Rethans authored
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
58 calling.
aceaabc @zsuraski PHP 4.0
zsuraski authored
59
a072914 both these entries are bad, and were never agreed upon.
Sterling Hughes authored
60 [7] When commenting out code using a #if statement, do NOT use 0 only. Instead
7705411 @rlerdorf Multi-branch test commit to see if email notifications are working
rlerdorf authored
61 use "<svn username here>_0". For example, #if FOO_0, where FOO is your
62 svn user foo. This allows easier tracking of why code was commented out,
2e6d771 As per the suggestion on php-dev, now please #ifdef 0_<username here>
Dan Kalowsky authored
63 especially in bundled libraries.
64
a072914 both these entries are bad, and were never agreed upon.
Sterling Hughes authored
65 [8] Do not define functions that are not available. For instance, if a
d6b4462 @jparise Reword item 10 for greater clarity.
jparise authored
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
ab0da7d It seems we're better to mention about missing functions.
Yasuo Ohgaki authored
70
a072914 both these entries are bad, and were never agreed upon.
Sterling Hughes authored
71 [9] Prefer emalloc(), efree(), estrdup(), etc. to their standard C library
e79772d @jparise Adding a new item (number 11) that explains why it's important to use
jparise authored
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.
76
77 In almost all cases, memory returned to the engine must be allocated
78 using emalloc().
79
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.
83
aceaabc @zsuraski PHP 4.0
zsuraski authored
84 Naming Conventions
85 ------------------
86
5cc6344 Updated to reflect recent discussions on php-dev.
Ron Chmara authored
87 [1] Function names for user-level functions should be enclosed with in
8e7147a - Use PHP_ instead of ZEND_
Derick Rethans authored
88 the PHP_FUNCTION() macro. They should be in lowercase, with words
aa20347 Updated naming standards as per 9/12 dev/doc discussion.
Ron Chmara authored
89 underscore delimited, with care taken to minimize the letter count.
5cc6344 Updated to reflect recent discussions on php-dev.
Ron Chmara authored
90 Abbreviations should not be used when they greatly decrease the
91 readability of the function name itself.
aa20347 Updated naming standards as per 9/12 dev/doc discussion.
Ron Chmara authored
92
93 Good:
94 'mcrypt_enc_self_test'
95 'mysql_list_fields'
96
97 Ok:
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'?)
102
103 Bad:
104 'hw_GetObjectByQueryCollObj'
105 'pg_setclientencoding'
5cc6344 Updated to reflect recent discussions on php-dev.
Ron Chmara authored
106 'jf_n_s_i'
b94bd05 - Update codinf standards with the posted RFC (results from PEAR Meet…
Derick Rethans authored
107
5cc6344 Updated to reflect recent discussions on php-dev.
Ron Chmara authored
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
111 of parent_*.
112
113 A family of 'foo' functions, for example:
114 Good:
115 'foo_select_bar'
116 'foo_insert_baz'
117 'foo_delete_baz'
aceaabc @zsuraski PHP 4.0
zsuraski authored
118
5cc6344 Updated to reflect recent discussions on php-dev.
Ron Chmara authored
119 Bad:
120 'fooselect_bar'
121 'fooinsertbaz'
122 'delete_foo_baz'
123
124 [3] Function names used by user functions should be prefixed
585e338 php4ize a bit.
Sterling Hughes authored
125 with "_php_", and followed by a word or an underscore-delimited list of
aceaabc @zsuraski PHP 4.0
zsuraski authored
126 words, in lowercase letters, that describes the function. If applicable,
127 they should be declared 'static'.
b94bd05 - Update codinf standards with the posted RFC (results from PEAR Meet…
Derick Rethans authored
128
5cc6344 Updated to reflect recent discussions on php-dev.
Ron Chmara authored
129 [4] Variable names must be meaningful. One letter variable names must be
aceaabc @zsuraski PHP 4.0
zsuraski authored
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++) ...).
132
8a5402c Fixed some spelling errors.
Egon Schmid authored
133 [5] Variable names should be in lowercase. Use underscores to separate
aceaabc @zsuraski PHP 4.0
zsuraski authored
134 between words.
135
2a8300e All technical reasons that prevented us from studlyCaps are solved
Marcus Boerger authored
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.
140
141 Good:
142 'connect()'
143 'getData()'
144 'buildSomeWidget()'
145
146 Bad:
147 'get_Data()'
148 'buildsomewidget'
149 'getI()'
150
9aebeaa - MFH Synch with what we decided for 5 and what we are practicing sin…
Marcus Boerger authored
151 [7] Classes should be given descriptive names. Avoid using abbreviations where
152 possible. Each word in the class name should start with a capital letter,
153 without underscore delimiters (CampelCaps starting with a capital letter).
154 The class name should be prefixed with the name of the 'parent set' (e.g.
155 the name of the extension).
b94bd05 - Update codinf standards with the posted RFC (results from PEAR Meet…
Derick Rethans authored
156
157 Good:
158 'Curl'
9aebeaa - MFH Synch with what we decided for 5 and what we are practicing sin…
Marcus Boerger authored
159 'FooBar'
b94bd05 - Update codinf standards with the posted RFC (results from PEAR Meet…
Derick Rethans authored
160
161 Bad:
162 'foobar'
163 'foo_bar'
aceaabc @zsuraski PHP 4.0
zsuraski authored
164
165 Syntax and indentation
166 ----------------------
167
168 [1] Never use C++ style comments (i.e. // comment). Always use C-style
169 comments instead. PHP is written in C, and is aimed at compiling
170 under any ANSI-C compliant compiler. Even though many compilers
171 accept C++-style comments in C code, you have to ensure that your
172 code would compile with other compilers as well.
173 The only exception to this rule is code that is Win32-specific,
174 because the Win32 port is MS-Visual C++ specific, and this compiler
175 is known to accept C++-style comments in C code.
176
177 [2] Use K&R-style. Of course, we can't and don't want to
45807e6 @jparise Added a brief section documenting the preference of tabs over spaces.
jparise authored
178 force anybody to use a style he or she is not used to, but,
aceaabc @zsuraski PHP 4.0
zsuraski authored
179 at the very least, when you write code that goes into the core
180 of PHP or one of its standard modules, please maintain the K&R
181 style. This applies to just about everything, starting with
8a5402c Fixed some spelling errors.
Egon Schmid authored
182 indentation and comment styles and up to function declaration
aceaabc @zsuraski PHP 4.0
zsuraski authored
183 syntax.
7d220af small clarification
Hartmut Holzgraefe authored
184
29fa203 Update URL.
Sebastian Bergmann authored
185 (see also http://www.catb.org/~esr/jargon/html/I/indent-style.html)
aceaabc @zsuraski PHP 4.0
zsuraski authored
186
45807e6 @jparise Added a brief section documenting the preference of tabs over spaces.
jparise authored
187 [3] Be generous with whitespace and braces. Always prefer:
188
612d5b9 - spaces instead of tabs
Derick Rethans authored
189 if (foo) {
190 bar;
191 }
45807e6 @jparise Added a brief section documenting the preference of tabs over spaces.
jparise authored
192
612d5b9 - spaces instead of tabs
Derick Rethans authored
193 to:
45807e6 @jparise Added a brief section documenting the preference of tabs over spaces.
jparise authored
194
612d5b9 - spaces instead of tabs
Derick Rethans authored
195 if(foo)bar;
45807e6 @jparise Added a brief section documenting the preference of tabs over spaces.
jparise authored
196
8a5402c Fixed some spelling errors.
Egon Schmid authored
197 Keep one empty line between the variable declaration section and
aceaabc @zsuraski PHP 4.0
zsuraski authored
198 the statements in a block, as well as between logical statement
199 groups in a block. Maintain at least one empty line between
200 two functions, preferably two.
201
45807e6 @jparise Added a brief section documenting the preference of tabs over spaces.
jparise authored
202 [4] When indenting, use the tab character. A tab is expected to represent
203 four spaces. It is important to maintain consistency in indenture so
204 that definitions, comments, and control structures line up correctly.
205
356e8f9 @wez word fix
wez authored
206 [5] Preprocessor statements (#if and such) MUST start at column one. To
bfed043 Include Sascha's indendation hint
Marcus Boerger authored
207 indent preprocessor directives you should put the # at the beginning
208 of a line, followed by any number of whitespace.
9a33556 Newer compilers don't need this so many people don't know. Hence we make
Marcus Boerger authored
209
8c4d236 - MFH Point to README.TESTING
Marcus Boerger authored
210 Testing
211 -------
212
3515689 \# Damn !
Marcus Boerger authored
213 [1] Extensions should be well tested using *.phpt tests. Read about that
8c4d236 - MFH Point to README.TESTING
Marcus Boerger authored
214 in README.TESTING.
215
aceaabc @zsuraski PHP 4.0
zsuraski authored
216 Documentation and Folding Hooks
217 -------------------------------
218
219 In order to make sure that the online documentation stays in line with
220 the code, each user-level function should have its user-level function
221 prototype before it along with a brief one-line description of what the
222 function does. It would look like this:
223
224 /* {{{ proto int abs(int number)
8a5402c Fixed some spelling errors.
Egon Schmid authored
225 Returns the absolute value of the number */
8e7147a - Use PHP_ instead of ZEND_
Derick Rethans authored
226 PHP_FUNCTION(abs)
585e338 php4ize a bit.
Sterling Hughes authored
227 {
aceaabc @zsuraski PHP 4.0
zsuraski authored
228 ...
229 }
230 /* }}} */
231
232 The {{{ symbols are the default folding symbols for the folding mode in
25c3a3a @rlerdorf vim-6 does folding - clean up a bunch of missing folding tags plus
rlerdorf authored
233 Emacs and vim (set fdm=marker). Folding is very useful when dealing with
234 large files because you can scroll through the file quickly and just unfold
235 the function you wish to work on. The }}} at the end of each function marks
236 the end of the fold, and should be on a separate line.
aceaabc @zsuraski PHP 4.0
zsuraski authored
237
238 The "proto" keyword there is just a helper for the doc/genfuncsummary script
239 which generates a full function summary. Having this keyword in front of the
240 function prototypes allows us to put folds elsewhere in the code without
241 messing up the function summary.
242
243 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]]])
8a5402c Fixed some spelling errors.
Egon Schmid authored
246 Returns a header object with the defined parameters */
aceaabc @zsuraski PHP 4.0
zsuraski authored
247
5cc6344 Updated to reflect recent discussions on php-dev.
Ron Chmara authored
248 And yes, please keep the prototype on a single line, even if that line
249 is massive.
250
251 New and Experimental Functions
252 -----------------------------------
253 To reduce the problems normally associated with the first public
254 implementation of a new set of functions, it has been suggested
255 that the first implementation include a file labeled 'EXPERIMENTAL'
256 in the function directory, and that the functions follow the
257 standard prefixing conventions during their initial implementation.
258
7966ff1 Fixed typo
Ilia Alshanetsky authored
259 The file labeled 'EXPERIMENTAL' should include the following
5cc6344 Updated to reflect recent discussions on php-dev.
Ron Chmara authored
260 information:
8a5402c Fixed some spelling errors.
Egon Schmid authored
261 Any authoring information (known bugs, future directions of the module).
5cc6344 Updated to reflect recent discussions on php-dev.
Ron Chmara authored
262 Ongoing status notes which may not be appropriate for CVS comments.
aceaabc @zsuraski PHP 4.0
zsuraski authored
263
d47e483 As per andi, similar names are for legacy reasons only.
Ron Chmara authored
264 Aliases & Legacy Documentation
265 -----------------------------------
266 You may also have some deprecated aliases with close to duplicate
aa20347 Updated naming standards as per 9/12 dev/doc discussion.
Ron Chmara authored
267 names, for example, somedb_select_result and somedb_selectresult. For
8a5402c Fixed some spelling errors.
Egon Schmid authored
268 documentation purposes, these will only be documented by the most
d47e483 As per andi, similar names are for legacy reasons only.
Ron Chmara authored
269 current name, with the aliases listed in the documentation for
aa20347 Updated naming standards as per 9/12 dev/doc discussion.
Ron Chmara authored
270 the parent function. For ease of reference, user-functions with
271 completely different names, that alias to the same function (such as
272 highlight_file and show_source), will be separately documented. The
273 proto should still be included, describing which function is aliased.
274
d47e483 As per andi, similar names are for legacy reasons only.
Ron Chmara authored
275 Backwards compatible functions and names should be maintained as long
276 as the code can be reasonably be kept as part of the codebase. See
8a5402c Fixed some spelling errors.
Egon Schmid authored
277 /phpdoc/README for more information on documentation.
Something went wrong with that request. Please try again.