Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 277 lines (217 sloc) 11.166 kb
d7b921c0 » Lukas Smith
2007-11-11 - MFH
1 ========================
2 PHP Coding Standards
3 ========================
aceaabce » zsuraski
1999-04-07 PHP 4.0
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 » jparise
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 » zsuraski
1999-04-07 PHP 4.0
11
12 Code Implementation
13 -------------------
14
d7b921c0 » Lukas Smith
2007-11-11 - MFH
15 0. Document your code in source files and the manual. [tm]
6d10159e » Marcus Boerger
2002-08-13 comments & php_error_docref
16
d7b921c0 » Lukas Smith
2007-11-11 - MFH
17 1. Functions that are given pointers to resources should not free them
aceaabce » zsuraski
1999-04-07 PHP 4.0
18
53c7b1c2 » Lukas Smith
2007-11-24 - MFH
19 For instance, ``function int mail(char *to, char *from)`` should NOT free
aceaabce » zsuraski
1999-04-07 PHP 4.0
20 to and/or from.
21 Exceptions:
22
d7b921c0 » Lukas Smith
2007-11-11 - MFH
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
32 2. Functions that are tightly integrated with other functions within the
aceaabce » zsuraski
1999-04-07 PHP 4.0
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
d7b921c0 » Lukas Smith
2007-11-11 - MFH
37 3. Use definitions and macros whenever possible, so that constants have
aceaabce » zsuraski
1999-04-07 PHP 4.0
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
d7b921c0 » Lukas Smith
2007-11-11 - MFH
43 4. When writing functions that deal with strings, be sure to remember
aceaabce » zsuraski
1999-04-07 PHP 4.0
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
585e338e » Sterling Hughes
2000-09-10 php4ize a bit.
50 recalculated with strlen() (e.g. php_addslashes())
aceaabce » zsuraski
1999-04-07 PHP 4.0
51
d7b921c0 » Lukas Smith
2007-11-11 - MFH
52 5. NEVER USE strncat(). If you're absolutely sure you know what you're doing,
aceaabce » zsuraski
1999-04-07 PHP 4.0
53 check its man page again, and only then, consider using it, and even then,
54 try avoiding it.
55
d7b921c0 » Lukas Smith
2007-11-11 - MFH
56 6. 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.
aceaabce » zsuraski
1999-04-07 PHP 4.0
60
d7b921c0 » Lukas Smith
2007-11-11 - MFH
61 7. When commenting out code using a #if statement, do NOT use 0 only. Instead
4fdd6bac » rlerdorf
2009-07-17 Multi-branch test commit to see if email notifications are working
62 use "<svn username here>_0". For example, #if FOO_0, where FOO is your
63 svn user foo. This allows easier tracking of why code was commented out,
d7b921c0 » Lukas Smith
2007-11-11 - MFH
64 especially in bundled libraries.
2e6d7711 » Dan Kalowsky
2002-08-13 As per the suggestion on php-dev, now please #ifdef 0_<username here>
65
d7b921c0 » Lukas Smith
2007-11-11 - MFH
66 8. 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
ab0da7dc » Yasuo Ohgaki
2002-09-08 It seems we're better to mention about missing functions.
71
d7b921c0 » Lukas Smith
2007-11-11 - MFH
72 9. 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.
e79772d6 » jparise
2002-10-10 Adding a new item (number 11) that explains why it's important to use
77
d7b921c0 » Lukas Smith
2007-11-11 - MFH
78 In almost all cases, memory returned to the engine must be allocated
79 using emalloc().
e79772d6 » jparise
2002-10-10 Adding a new item (number 11) that explains why it's important to use
80
d7b921c0 » Lukas Smith
2007-11-11 - MFH
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.
e79772d6 » jparise
2002-10-10 Adding a new item (number 11) that explains why it's important to use
84
aceaabce » zsuraski
1999-04-07 PHP 4.0
85 Naming Conventions
86 ------------------
87
d7b921c0 » Lukas Smith
2007-11-11 - MFH
88 1. Function names for user-level functions should be enclosed with in
8e7147a1 » Derick Rethans
2002-09-09 - Use PHP_ instead of ZEND_
89 the PHP_FUNCTION() macro. They should be in lowercase, with words
aa203477 » Ron Chmara
2000-10-18 Updated naming standards as per 9/12 dev/doc discussion.
90 underscore delimited, with care taken to minimize the letter count.
5cc6344e » Ron Chmara
2000-12-19 Updated to reflect recent discussions on php-dev.
91 Abbreviations should not be used when they greatly decrease the
d7b921c0 » Lukas Smith
2007-11-11 - MFH
92 readability of the function name itself::
aa203477 » Ron Chmara
2000-10-18 Updated naming standards as per 9/12 dev/doc discussion.
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'
d7b921c0 » Lukas Smith
2007-11-11 - MFH
102 (could be 'html_get_trans_table'?)
aa203477 » Ron Chmara
2000-10-18 Updated naming standards as per 9/12 dev/doc discussion.
103
104 Bad:
105 'hw_GetObjectByQueryCollObj'
106 'pg_setclientencoding'
5cc6344e » Ron Chmara
2000-12-19 Updated to reflect recent discussions on php-dev.
107 'jf_n_s_i'
b94bd055 » Derick Rethans
2003-05-23 - Update codinf standards with the posted RFC (results from PEAR Meet…
108
d7b921c0 » Lukas Smith
2007-11-11 - MFH
109 2. If they are part of a "parent set" of functions, that parent should
5cc6344e » Ron Chmara
2000-12-19 Updated to reflect recent discussions on php-dev.
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
d7b921c0 » Lukas Smith
2007-11-11 - MFH
112 of ``parent_*``::
113
5cc6344e » Ron Chmara
2000-12-19 Updated to reflect recent discussions on php-dev.
114 A family of 'foo' functions, for example:
115 Good:
116 'foo_select_bar'
117 'foo_insert_baz'
118 'foo_delete_baz'
aceaabce » zsuraski
1999-04-07 PHP 4.0
119
5cc6344e » Ron Chmara
2000-12-19 Updated to reflect recent discussions on php-dev.
120 Bad:
121 'fooselect_bar'
122 'fooinsertbaz'
123 'delete_foo_baz'
124
d7b921c0 » Lukas Smith
2007-11-11 - MFH
125 3. Function names used by user functions should be prefixed
126 with ``_php_``, and followed by a word or an underscore-delimited list of
aceaabce » zsuraski
1999-04-07 PHP 4.0
127 words, in lowercase letters, that describes the function. If applicable,
128 they should be declared 'static'.
b94bd055 » Derick Rethans
2003-05-23 - Update codinf standards with the posted RFC (results from PEAR Meet…
129
d7b921c0 » Lukas Smith
2007-11-11 - MFH
130 4. Variable names must be meaningful. One letter variable names must be
aceaabce » zsuraski
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
d7b921c0 » Lukas Smith
2007-11-11 - MFH
134 5. Variable names should be in lowercase. Use underscores to separate
aceaabce » zsuraski
1999-04-07 PHP 4.0
135 between words.
136
d7b921c0 » Lukas Smith
2007-11-11 - MFH
137 6. Method names follow the 'studlyCaps' (also referred to as 'bumpy case'
2a8300e0 » Marcus Boerger
2004-01-21 All technical reasons that prevented us from studlyCaps are solved
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
d7b921c0 » Lukas Smith
2007-11-11 - MFH
140 letter that starts a new 'word' is capitalized::
2a8300e0 » Marcus Boerger
2004-01-21 All technical reasons that prevented us from studlyCaps are solved
141
142 Good:
143 'connect()'
144 'getData()'
145 'buildSomeWidget()'
146
147 Bad:
148 'get_Data()'
149 'buildsomewidget'
150 'getI()'
151
d7b921c0 » Lukas Smith
2007-11-11 - MFH
152 7. 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 (CampelCaps 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)::
b94bd055 » Derick Rethans
2003-05-23 - Update codinf standards with the posted RFC (results from PEAR Meet…
157
158 Good:
159 'Curl'
9aebeaaf » Marcus Boerger
2005-11-27 - MFH Synch with what we decided for 5 and what we are practicing sin…
160 'FooBar'
b94bd055 » Derick Rethans
2003-05-23 - Update codinf standards with the posted RFC (results from PEAR Meet…
161
162 Bad:
163 'foobar'
164 'foo_bar'
aceaabce » zsuraski
1999-04-07 PHP 4.0
165
166 Syntax and indentation
167 ----------------------
168
d7b921c0 » Lukas Smith
2007-11-11 - MFH
169 1. Never use C++ style comments (i.e. // comment). Always use C-style
aceaabce » zsuraski
1999-04-07 PHP 4.0
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.
177
d7b921c0 » Lukas Smith
2007-11-11 - MFH
178 2. Use K&R-style. Of course, we can't and don't want to
45807e6d » jparise
2000-11-26 Added a brief section documenting the preference of tabs over spaces.
179 force anybody to use a style he or she is not used to, but,
aceaabce » zsuraski
1999-04-07 PHP 4.0
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
8a5402c2 » Egon Schmid
2001-10-14 Fixed some spelling errors.
183 indentation and comment styles and up to function declaration
9e218599 » Lukas Smith
2007-11-11 - MFH typo fix by Jon
184 syntax. Also see Indentstyle_.
d7b921c0 » Lukas Smith
2007-11-11 - MFH
185
9e218599 » Lukas Smith
2007-11-11 - MFH typo fix by Jon
186 .. _Indentstyle: http://www.catb.org/~esr/jargon/html/I/indent-style.html
7d220af2 » Hartmut Holzgraefe
2002-01-04 small clarification
187
d7b921c0 » Lukas Smith
2007-11-11 - MFH
188 3. Be generous with whitespace and braces. Keep one empty line between the
189 variable declaration section and the statements in a block, as well as
190 between logical statement groups in a block. Maintain at least one empty
191 line between two functions, preferably two. Always prefer::
45807e6d » jparise
2000-11-26 Added a brief section documenting the preference of tabs over spaces.
192
612d5b99 » Derick Rethans
2002-09-09 - spaces instead of tabs
193 if (foo) {
194 bar;
195 }
45807e6d » jparise
2000-11-26 Added a brief section documenting the preference of tabs over spaces.
196
612d5b99 » Derick Rethans
2002-09-09 - spaces instead of tabs
197 to:
45807e6d » jparise
2000-11-26 Added a brief section documenting the preference of tabs over spaces.
198
612d5b99 » Derick Rethans
2002-09-09 - spaces instead of tabs
199 if(foo)bar;
45807e6d » jparise
2000-11-26 Added a brief section documenting the preference of tabs over spaces.
200
d7b921c0 » Lukas Smith
2007-11-11 - MFH
201 4. When indenting, use the tab character. A tab is expected to represent
45807e6d » jparise
2000-11-26 Added a brief section documenting the preference of tabs over spaces.
202 four spaces. It is important to maintain consistency in indenture so
203 that definitions, comments, and control structures line up correctly.
204
d7b921c0 » Lukas Smith
2007-11-11 - MFH
205 5. Preprocessor statements (#if and such) MUST start at column one. To
bfed0430 » Marcus Boerger
2004-01-30 Include Sascha's indendation hint
206 indent preprocessor directives you should put the # at the beginning
207 of a line, followed by any number of whitespace.
9a335560 » Marcus Boerger
2004-01-30 Newer compilers don't need this so many people don't know. Hence we make
208
8c4d2365 » Marcus Boerger
2005-12-22 - MFH Point to README.TESTING
209 Testing
210 -------
211
d7b921c0 » Lukas Smith
2007-11-11 - MFH
212 1. Extensions should be well tested using *.phpt tests. Read about that
8c4d2365 » Marcus Boerger
2005-12-22 - MFH Point to README.TESTING
213 in README.TESTING.
214
aceaabce » zsuraski
1999-04-07 PHP 4.0
215 Documentation and Folding Hooks
216 -------------------------------
217
218 In order to make sure that the online documentation stays in line with
219 the code, each user-level function should have its user-level function
220 prototype before it along with a brief one-line description of what the
d7b921c0 » Lukas Smith
2007-11-11 - MFH
221 function does. It would look like this::
aceaabce » zsuraski
1999-04-07 PHP 4.0
222
d7b921c0 » Lukas Smith
2007-11-11 - MFH
223 /* {{{ proto int abs(int number)
224 Returns the absolute value of the number */
225 PHP_FUNCTION(abs)
226 {
227 ...
228 }
229 /* }}} */
aceaabce » zsuraski
1999-04-07 PHP 4.0
230
231 The {{{ symbols are the default folding symbols for the folding mode in
d7b921c0 » Lukas Smith
2007-11-11 - MFH
232 Emacs and vim (set fdm=marker). Folding is very useful when dealing with
233 large files because you can scroll through the file quickly and just unfold
234 the function you wish to work on. The }}} at the end of each function marks
25c3a3a3 » rlerdorf
2001-06-05 vim-6 does folding - clean up a bunch of missing folding tags plus
235 the end of the fold, and should be on a separate line.
aceaabce » zsuraski
1999-04-07 PHP 4.0
236
237 The "proto" keyword there is just a helper for the doc/genfuncsummary script
238 which generates a full function summary. Having this keyword in front of the
239 function prototypes allows us to put folds elsewhere in the code without
240 messing up the function summary.
241
d7b921c0 » Lukas Smith
2007-11-11 - MFH
242 Optional arguments are written like this::
aceaabce » zsuraski
1999-04-07 PHP 4.0
243
d7b921c0 » Lukas Smith
2007-11-11 - MFH
244 /* {{{ proto object imap_header(int stream_id, int msg_no [, int from_length [, int subject_length [, string default_host]]])
245 Returns a header object with the defined parameters */
aceaabce » zsuraski
1999-04-07 PHP 4.0
246
5cc6344e » Ron Chmara
2000-12-19 Updated to reflect recent discussions on php-dev.
247 And yes, please keep the prototype on a single line, even if that line
248 is massive.
249
250 New and Experimental Functions
251 -----------------------------------
252 To reduce the problems normally associated with the first public
253 implementation of a new set of functions, it has been suggested
254 that the first implementation include a file labeled 'EXPERIMENTAL'
255 in the function directory, and that the functions follow the
256 standard prefixing conventions during their initial implementation.
257
d7b921c0 » Lukas Smith
2007-11-11 - MFH
258 The file labelled 'EXPERIMENTAL' should include the following
259 information::
260
261 Any authoring information (known bugs, future directions of the module).
5e118fdc » rlerdorf
2009-07-13 cvs->svn
262 Ongoing status notes which may not be appropriate for SVN comments.
aceaabce » zsuraski
1999-04-07 PHP 4.0
263
d47e4832 » Ron Chmara
2000-10-18 As per andi, similar names are for legacy reasons only.
264 Aliases & Legacy Documentation
265 -----------------------------------
266 You may also have some deprecated aliases with close to duplicate
aa203477 » Ron Chmara
2000-10-18 Updated naming standards as per 9/12 dev/doc discussion.
267 names, for example, somedb_select_result and somedb_selectresult. For
8a5402c2 » Egon Schmid
2001-10-14 Fixed some spelling errors.
268 documentation purposes, these will only be documented by the most
d47e4832 » Ron Chmara
2000-10-18 As per andi, similar names are for legacy reasons only.
269 current name, with the aliases listed in the documentation for
aa203477 » Ron Chmara
2000-10-18 Updated naming standards as per 9/12 dev/doc discussion.
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
d47e4832 » Ron Chmara
2000-10-18 As per andi, similar names are for legacy reasons only.
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
8a5402c2 » Egon Schmid
2001-10-14 Fixed some spelling errors.
277 /phpdoc/README for more information on documentation.
Something went wrong with that request. Please try again.