Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 241 lines (187 sloc) 9.994 kb
aceaabce »
1999-04-07 PHP 4.0
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
45807e6d »
2000-11-26 Added a brief section documenting the preference of tabs over spaces.
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.
aceaabce »
1999-04-07 PHP 4.0
11
12
13 Code Implementation
14 -------------------
15
6d10159e »
2002-08-13 comments & php_error_docref
16 [0] Document your code in source files and the manual. [tm]
17
aceaabce »
1999-04-07 PHP 4.0
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
585e338e »
2000-09-10 php4ize a bit.
49 recalculated with strlen() (e.g. php_addslashes())
aceaabce »
1999-04-07 PHP 4.0
50
a0729141 »
2003-04-04 both these entries are bad, and were never agreed upon.
51 [5] NEVER USE strncat(). If you're absolutely sure you know what you're doing,
aceaabce »
1999-04-07 PHP 4.0
52 check its man page again, and only then, consider using it, and even then,
53 try avoiding it.
54
a0729141 »
2003-04-04 both these entries are bad, and were never agreed upon.
55 [6] Use PHP_* macros in the PHP source, and ZEND_* macros in the Zend
612d5b99 »
2002-09-09 - spaces instead of tabs
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.
aceaabce »
1999-04-07 PHP 4.0
59
a0729141 »
2003-04-04 both these entries are bad, and were never agreed upon.
60 [7] When commenting out code using a #if statement, do NOT use 0 only. Instead
6c132995 »
2002-10-29 rewrite paragraph 9
61 use "<cvs username here>_0". For example, #if FOO_0, where FOO is your
2e6d7711 »
2002-08-13 As per the suggestion on php-dev, now please #ifdef 0_<username here>
62 cvs user foo. This allows easier tracking of why code was commented out,
63 especially in bundled libraries.
64
a0729141 »
2003-04-04 both these entries are bad, and were never agreed upon.
65 [8] Do not define functions that are not available. For instance, if a
d6b4462a »
2002-09-08 Reword item 10 for greater clarity.
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
ab0da7dc »
2002-09-08 It seems we're better to mention about missing functions.
70
a0729141 »
2003-04-04 both these entries are bad, and were never agreed upon.
71 [9] Prefer emalloc(), efree(), estrdup(), etc. to their standard C library
e79772d6 »
2002-10-10 Adding a new item (number 11) that explains why it's important to use
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
aceaabce »
1999-04-07 PHP 4.0
84 Naming Conventions
85 ------------------
86
5cc6344e »
2000-12-19 Updated to reflect recent discussions on php-dev.
87 [1] Function names for user-level functions should be enclosed with in
8e7147a1 »
2002-09-09 - Use PHP_ instead of ZEND_
88 the PHP_FUNCTION() macro. They should be in lowercase, with words
aa203477 »
2000-10-18 Updated naming standards as per 9/12 dev/doc discussion.
89 underscore delimited, with care taken to minimize the letter count.
5cc6344e »
2000-12-19 Updated to reflect recent discussions on php-dev.
90 Abbreviations should not be used when they greatly decrease the
91 readability of the function name itself.
aa203477 »
2000-10-18 Updated naming standards as per 9/12 dev/doc discussion.
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'
5cc6344e »
2000-12-19 Updated to reflect recent discussions on php-dev.
106 'jf_n_s_i'
107
108
109 [2] 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'
aceaabce »
1999-04-07 PHP 4.0
119
5cc6344e »
2000-12-19 Updated to reflect recent discussions on php-dev.
120 Bad:
121 'fooselect_bar'
122 'fooinsertbaz'
123 'delete_foo_baz'
124
125 [3] Function names used by user functions should be prefixed
585e338e »
2000-09-10 php4ize a bit.
126 with "_php_", and followed by a word or an underscore-delimited list of
aceaabce »
1999-04-07 PHP 4.0
127 words, in lowercase letters, that describes the function. If applicable,
128 they should be declared 'static'.
129
5cc6344e »
2000-12-19 Updated to reflect recent discussions on php-dev.
130 [4] Variable names must be meaningful. One letter variable names must be
aceaabce »
1999-04-07 PHP 4.0
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
8a5402c2 »
2001-10-14 Fixed some spelling errors.
134 [5] Variable names should be in lowercase. Use underscores to separate
aceaabce »
1999-04-07 PHP 4.0
135 between words.
136
137
138 Syntax and indentation
139 ----------------------
140
141 [1] Never use C++ style comments (i.e. // comment). Always use C-style
142 comments instead. PHP is written in C, and is aimed at compiling
143 under any ANSI-C compliant compiler. Even though many compilers
144 accept C++-style comments in C code, you have to ensure that your
145 code would compile with other compilers as well.
146 The only exception to this rule is code that is Win32-specific,
147 because the Win32 port is MS-Visual C++ specific, and this compiler
148 is known to accept C++-style comments in C code.
149
150 [2] Use K&R-style. Of course, we can't and don't want to
45807e6d »
2000-11-26 Added a brief section documenting the preference of tabs over spaces.
151 force anybody to use a style he or she is not used to, but,
aceaabce »
1999-04-07 PHP 4.0
152 at the very least, when you write code that goes into the core
153 of PHP or one of its standard modules, please maintain the K&R
154 style. This applies to just about everything, starting with
8a5402c2 »
2001-10-14 Fixed some spelling errors.
155 indentation and comment styles and up to function declaration
aceaabce »
1999-04-07 PHP 4.0
156 syntax.
7d220af2 »
2002-01-04 small clarification
157
158 (see also http://www.tuxedo.org/~esr/jargon/html/entry/indent-style.html)
aceaabce »
1999-04-07 PHP 4.0
159
45807e6d »
2000-11-26 Added a brief section documenting the preference of tabs over spaces.
160 [3] Be generous with whitespace and braces. Always prefer:
161
612d5b99 »
2002-09-09 - spaces instead of tabs
162 if (foo) {
163 bar;
164 }
45807e6d »
2000-11-26 Added a brief section documenting the preference of tabs over spaces.
165
612d5b99 »
2002-09-09 - spaces instead of tabs
166 to:
45807e6d »
2000-11-26 Added a brief section documenting the preference of tabs over spaces.
167
612d5b99 »
2002-09-09 - spaces instead of tabs
168 if(foo)bar;
45807e6d »
2000-11-26 Added a brief section documenting the preference of tabs over spaces.
169
8a5402c2 »
2001-10-14 Fixed some spelling errors.
170 Keep one empty line between the variable declaration section and
aceaabce »
1999-04-07 PHP 4.0
171 the statements in a block, as well as between logical statement
172 groups in a block. Maintain at least one empty line between
173 two functions, preferably two.
174
45807e6d »
2000-11-26 Added a brief section documenting the preference of tabs over spaces.
175 [4] When indenting, use the tab character. A tab is expected to represent
176 four spaces. It is important to maintain consistency in indenture so
177 that definitions, comments, and control structures line up correctly.
178
aceaabce »
1999-04-07 PHP 4.0
179 Documentation and Folding Hooks
180 -------------------------------
181
182 In order to make sure that the online documentation stays in line with
183 the code, each user-level function should have its user-level function
184 prototype before it along with a brief one-line description of what the
185 function does. It would look like this:
186
187 /* {{{ proto int abs(int number)
8a5402c2 »
2001-10-14 Fixed some spelling errors.
188 Returns the absolute value of the number */
8e7147a1 »
2002-09-09 - Use PHP_ instead of ZEND_
189 PHP_FUNCTION(abs)
585e338e »
2000-09-10 php4ize a bit.
190 {
aceaabce »
1999-04-07 PHP 4.0
191 ...
192 }
193 /* }}} */
194
195 The {{{ symbols are the default folding symbols for the folding mode in
25c3a3a3 »
2001-06-05 vim-6 does folding - clean up a bunch of missing folding tags plus
196 Emacs and vim (set fdm=marker). Folding is very useful when dealing with
197 large files because you can scroll through the file quickly and just unfold
198 the function you wish to work on. The }}} at the end of each function marks
199 the end of the fold, and should be on a separate line.
aceaabce »
1999-04-07 PHP 4.0
200
201 The "proto" keyword there is just a helper for the doc/genfuncsummary script
202 which generates a full function summary. Having this keyword in front of the
203 function prototypes allows us to put folds elsewhere in the code without
204 messing up the function summary.
205
206 Optional arguments are written like this:
207
208 /* {{{ proto object imap_header(int stream_id, int msg_no [, int from_length [, int subject_length [, string default_host]]])
8a5402c2 »
2001-10-14 Fixed some spelling errors.
209 Returns a header object with the defined parameters */
aceaabce »
1999-04-07 PHP 4.0
210
5cc6344e »
2000-12-19 Updated to reflect recent discussions on php-dev.
211 And yes, please keep the prototype on a single line, even if that line
212 is massive.
213
214 New and Experimental Functions
215 -----------------------------------
216 To reduce the problems normally associated with the first public
217 implementation of a new set of functions, it has been suggested
218 that the first implementation include a file labeled 'EXPERIMENTAL'
219 in the function directory, and that the functions follow the
220 standard prefixing conventions during their initial implementation.
221
222 The file labelled 'EXPERIMENTAL' should include the following
223 information:
8a5402c2 »
2001-10-14 Fixed some spelling errors.
224 Any authoring information (known bugs, future directions of the module).
5cc6344e »
2000-12-19 Updated to reflect recent discussions on php-dev.
225 Ongoing status notes which may not be appropriate for CVS comments.
aceaabce »
1999-04-07 PHP 4.0
226
d47e4832 »
2000-10-18 As per andi, similar names are for legacy reasons only.
227 Aliases & Legacy Documentation
228 -----------------------------------
229 You may also have some deprecated aliases with close to duplicate
aa203477 »
2000-10-18 Updated naming standards as per 9/12 dev/doc discussion.
230 names, for example, somedb_select_result and somedb_selectresult. For
8a5402c2 »
2001-10-14 Fixed some spelling errors.
231 documentation purposes, these will only be documented by the most
d47e4832 »
2000-10-18 As per andi, similar names are for legacy reasons only.
232 current name, with the aliases listed in the documentation for
aa203477 »
2000-10-18 Updated naming standards as per 9/12 dev/doc discussion.
233 the parent function. For ease of reference, user-functions with
234 completely different names, that alias to the same function (such as
235 highlight_file and show_source), will be separately documented. The
236 proto should still be included, describing which function is aliased.
237
d47e4832 »
2000-10-18 As per andi, similar names are for legacy reasons only.
238 Backwards compatible functions and names should be maintained as long
239 as the code can be reasonably be kept as part of the codebase. See
8a5402c2 »
2001-10-14 Fixed some spelling errors.
240 /phpdoc/README for more information on documentation.
Something went wrong with that request. Please try again.