Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 224 lines (175 sloc) 9.224 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
16 [1] Functions that are given pointers to resources should not free them
17
18 For instance, function int mail(char *to, char *from) should NOT free
19 to and/or from.
20 Exceptions:
21
22 - The function's designated behavior is freeing that resource. E.g. efree()
23 - The function is given a boolean argument, that controls whether or not
24 the function may free its arguments (if true - the function must free its
25 arguments, if false - it must not)
26 - Low-level parser routines, that are tightly integrated with the token
27 cache and the bison code for minimum memory copying overhead.
28
29 [2] Functions that are tightly integrated with other functions within the
30 same module, and rely on each other non-trivial behavior, should be
31 documented as such and declared 'static'. They should be avoided if
32 possible.
33
34 [3] Use definitions and macros whenever possible, so that constants have
35 meaningful names and can be easily manipulated. The only exceptions
36 to this rule are 0 and 1, when used as false and true (respectively).
37 Any other use of a numeric constant to specify different behavior
38 or actions should be done through a #define.
39
40 [4] When writing functions that deal with strings, be sure to remember
41 that PHP holds the length property of each string, and that it
42 shouldn't be calculated with strlen(). Write your functions in a such
43 a way so that they'll take advantage of the length property, both
44 for efficiency and in order for them to be binary-safe.
45 Functions that change strings and obtain their new lengths while
46 doing so, should return that new length, so it doesn't have to be
585e338 php4ize a bit.
Sterling Hughes authored
47 recalculated with strlen() (e.g. php_addslashes())
aceaabc @zsuraski PHP 4.0
zsuraski authored
48
585e338 php4ize a bit.
Sterling Hughes authored
49 [5] Use php_error() to report any errors/warnings during code execution.
aceaabc @zsuraski PHP 4.0
zsuraski authored
50 Use descriptive error messages, and try to avoid using identical
51 error strings for different stages of an error. For example,
52 if in order to obtain a URL you have to parse the URL, connect,
53 and retreive the text, assuming something can go wrong at each
54 of these stages, don't report an error "Unable to get URL"
55 on all of them, but instead, write something like "Unable
56 to parse URL", "Unable to connect to URL server" and "Unable
57 to fetch URL text", respectively.
58
59 [6] NEVER USE strncat(). If you're absolutely sure you know what you're doing,
60 check its man page again, and only then, consider using it, and even then,
61 try avoiding it.
62
a0c2def Recommend ZEND_* macro over PHP_* macro as discussed in php-dev.
Yasuo Ohgaki authored
63 [7] Use ZEND_* macro instead of PHP_* macro. Use of PHP_* macros are
64 not recommended. Since most of PHP_* macros are ZEND_* macro alias, use of
65 PHP_* macro makes browsing source with tag search harder.
aceaabc @zsuraski PHP 4.0
zsuraski authored
66
67 Naming Conventions
68 ------------------
69
5cc6344 Updated to reflect recent discussions on php-dev.
Ron Chmara authored
70 [1] Function names for user-level functions should be enclosed with in
aa20347 Updated naming standards as per 9/12 dev/doc discussion.
Ron Chmara authored
71 the PHP_FUNCTION() macro. They should be in lowercase, with words
72 underscore delimited, with care taken to minimize the letter count.
5cc6344 Updated to reflect recent discussions on php-dev.
Ron Chmara authored
73 Abbreviations should not be used when they greatly decrease the
74 readability of the function name itself.
aa20347 Updated naming standards as per 9/12 dev/doc discussion.
Ron Chmara authored
75
76 Good:
77 'mcrypt_enc_self_test'
78 'mysql_list_fields'
79
80 Ok:
81 'mcrypt_module_get_algo_supported_key_sizes'
82 (could be 'mcrypt_mod_get_algo_sup_key_sizes'?)
83 'get_html_translation_table'
84 (could be 'html_get_trans_table'?)
85
86 Bad:
87 'hw_GetObjectByQueryCollObj'
88 'pg_setclientencoding'
5cc6344 Updated to reflect recent discussions on php-dev.
Ron Chmara authored
89 'jf_n_s_i'
90
91
92 [2] If they are part of a "parent set" of functions, that parent should
93 be included in the user function name, and should be clearly related
94 to the parent program or function family. This should be in the form
95 of parent_*.
96
97 A family of 'foo' functions, for example:
98 Good:
99 'foo_select_bar'
100 'foo_insert_baz'
101 'foo_delete_baz'
aceaabc @zsuraski PHP 4.0
zsuraski authored
102
5cc6344 Updated to reflect recent discussions on php-dev.
Ron Chmara authored
103 Bad:
104 'fooselect_bar'
105 'fooinsertbaz'
106 'delete_foo_baz'
107
108 [3] Function names used by user functions should be prefixed
585e338 php4ize a bit.
Sterling Hughes authored
109 with "_php_", and followed by a word or an underscore-delimited list of
aceaabc @zsuraski PHP 4.0
zsuraski authored
110 words, in lowercase letters, that describes the function. If applicable,
111 they should be declared 'static'.
112
5cc6344 Updated to reflect recent discussions on php-dev.
Ron Chmara authored
113 [4] Variable names must be meaningful. One letter variable names must be
aceaabc @zsuraski PHP 4.0
zsuraski authored
114 avoided, except for places where the variable has no real meaning or
115 a trivial meaning (e.g. for (i=0; i<100; i++) ...).
116
8a5402c Fixed some spelling errors.
Egon Schmid authored
117 [5] Variable names should be in lowercase. Use underscores to separate
aceaabc @zsuraski PHP 4.0
zsuraski authored
118 between words.
119
120
121 Syntax and indentation
122 ----------------------
123
124 [1] Never use C++ style comments (i.e. // comment). Always use C-style
125 comments instead. PHP is written in C, and is aimed at compiling
126 under any ANSI-C compliant compiler. Even though many compilers
127 accept C++-style comments in C code, you have to ensure that your
128 code would compile with other compilers as well.
129 The only exception to this rule is code that is Win32-specific,
130 because the Win32 port is MS-Visual C++ specific, and this compiler
131 is known to accept C++-style comments in C code.
132
133 [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
134 force anybody to use a style he or she is not used to, but,
aceaabc @zsuraski PHP 4.0
zsuraski authored
135 at the very least, when you write code that goes into the core
136 of PHP or one of its standard modules, please maintain the K&R
137 style. This applies to just about everything, starting with
8a5402c Fixed some spelling errors.
Egon Schmid authored
138 indentation and comment styles and up to function declaration
aceaabc @zsuraski PHP 4.0
zsuraski authored
139 syntax.
7d220af small clarification
Hartmut Holzgraefe authored
140
141 (see also http://www.tuxedo.org/~esr/jargon/html/entry/indent-style.html)
aceaabc @zsuraski PHP 4.0
zsuraski authored
142
45807e6 @jparise Added a brief section documenting the preference of tabs over spaces.
jparise authored
143 [3] Be generous with whitespace and braces. Always prefer:
144
145 if (foo) {
aceaabc @zsuraski PHP 4.0
zsuraski authored
146 bar;
147 }
45807e6 @jparise Added a brief section documenting the preference of tabs over spaces.
jparise authored
148
149 to:
150
aceaabc @zsuraski PHP 4.0
zsuraski authored
151 if(foo)bar;
45807e6 @jparise Added a brief section documenting the preference of tabs over spaces.
jparise authored
152
8a5402c Fixed some spelling errors.
Egon Schmid authored
153 Keep one empty line between the variable declaration section and
aceaabc @zsuraski PHP 4.0
zsuraski authored
154 the statements in a block, as well as between logical statement
155 groups in a block. Maintain at least one empty line between
156 two functions, preferably two.
157
45807e6 @jparise Added a brief section documenting the preference of tabs over spaces.
jparise authored
158 [4] When indenting, use the tab character. A tab is expected to represent
159 four spaces. It is important to maintain consistency in indenture so
160 that definitions, comments, and control structures line up correctly.
161
aceaabc @zsuraski PHP 4.0
zsuraski authored
162 Documentation and Folding Hooks
163 -------------------------------
164
165 In order to make sure that the online documentation stays in line with
166 the code, each user-level function should have its user-level function
167 prototype before it along with a brief one-line description of what the
168 function does. It would look like this:
169
170 /* {{{ proto int abs(int number)
8a5402c Fixed some spelling errors.
Egon Schmid authored
171 Returns the absolute value of the number */
585e338 php4ize a bit.
Sterling Hughes authored
172 PHP_FUNCTION(abs)
173 {
aceaabc @zsuraski PHP 4.0
zsuraski authored
174 ...
175 }
176 /* }}} */
177
178 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
179 Emacs and vim (set fdm=marker). Folding is very useful when dealing with
180 large files because you can scroll through the file quickly and just unfold
181 the function you wish to work on. The }}} at the end of each function marks
182 the end of the fold, and should be on a separate line.
aceaabc @zsuraski PHP 4.0
zsuraski authored
183
184 The "proto" keyword there is just a helper for the doc/genfuncsummary script
185 which generates a full function summary. Having this keyword in front of the
186 function prototypes allows us to put folds elsewhere in the code without
187 messing up the function summary.
188
189 Optional arguments are written like this:
190
191 /* {{{ 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
192 Returns a header object with the defined parameters */
aceaabc @zsuraski PHP 4.0
zsuraski authored
193
5cc6344 Updated to reflect recent discussions on php-dev.
Ron Chmara authored
194 And yes, please keep the prototype on a single line, even if that line
195 is massive.
196
197 New and Experimental Functions
198 -----------------------------------
199 To reduce the problems normally associated with the first public
200 implementation of a new set of functions, it has been suggested
201 that the first implementation include a file labeled 'EXPERIMENTAL'
202 in the function directory, and that the functions follow the
203 standard prefixing conventions during their initial implementation.
204
205 The file labelled 'EXPERIMENTAL' should include the following
206 information:
8a5402c Fixed some spelling errors.
Egon Schmid authored
207 Any authoring information (known bugs, future directions of the module).
5cc6344 Updated to reflect recent discussions on php-dev.
Ron Chmara authored
208 Ongoing status notes which may not be appropriate for CVS comments.
aceaabc @zsuraski PHP 4.0
zsuraski authored
209
d47e483 As per andi, similar names are for legacy reasons only.
Ron Chmara authored
210 Aliases & Legacy Documentation
211 -----------------------------------
212 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
213 names, for example, somedb_select_result and somedb_selectresult. For
8a5402c Fixed some spelling errors.
Egon Schmid authored
214 documentation purposes, these will only be documented by the most
d47e483 As per andi, similar names are for legacy reasons only.
Ron Chmara authored
215 current name, with the aliases listed in the documentation for
aa20347 Updated naming standards as per 9/12 dev/doc discussion.
Ron Chmara authored
216 the parent function. For ease of reference, user-functions with
217 completely different names, that alias to the same function (such as
218 highlight_file and show_source), will be separately documented. The
219 proto should still be included, describing which function is aliased.
220
d47e483 As per andi, similar names are for legacy reasons only.
Ron Chmara authored
221 Backwards compatible functions and names should be maintained as long
222 as the code can be reasonably be kept as part of the codebase. See
8a5402c Fixed some spelling errors.
Egon Schmid authored
223 /phpdoc/README for more information on documentation.
Something went wrong with that request. Please try again.