1======================== 2 PHP Coding Standards 3======================== 4 5This file lists several standards that any programmer adding or changing 6code in PHP should follow. Since this file was added at a very late 7stage of the development of PHP v3.0, the code base does not (yet) fully 8follow it, but it's going in that general direction. Since we are now 9well into version 5 releases, many sections have been recoded to use 10these rules. 11 12Code Implementation 13------------------- 14 150. Document your code in source files and the manual. [tm] 16 171. Functions that are given pointers to resources should not free them 18 19For instance, ``function int mail(char *to, char *from)`` should NOT free 20to and/or from. 21Exceptions: 22 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 322. Functions that are tightly integrated with other functions within the 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 373. Use definitions and macros whenever possible, so that constants have 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 434. When writing functions that deal with strings, be sure to remember 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 50 recalculated with strlen() (e.g. php_addslashes()) 51 525. NEVER USE strncat(). If you're absolutely sure you know what you're doing, 53 check its man page again, and only then, consider using it, and even then, 54 try avoiding it. 55 566. 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. 60 617. When commenting out code using a #if statement, do NOT use 0 only. Instead 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, 64 especially in bundled libraries. 65 668. 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 71 729. 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. 77 78 In almost all cases, memory returned to the engine must be allocated 79 using emalloc(). 80 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. 84 85Naming Conventions 86------------------ 87 881. Function names for user-level functions should be enclosed with in 89 the PHP_FUNCTION() macro. They should be in lowercase, with words 90 underscore delimited, with care taken to minimize the letter count. 91 Abbreviations should not be used when they greatly decrease the 92 readability of the function name itself:: 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' 102 (could be 'html_get_trans_table'?) 103 104 Bad: 105 'hw_GetObjectByQueryCollObj' 106 'pg_setclientencoding' 107 'jf_n_s_i' 108 1092. 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' 119 120 Bad: 121 'fooselect_bar' 122 'fooinsertbaz' 123 'delete_foo_baz' 124 1253. Function names used by user functions should be prefixed 126 with ``_php_``, and followed by a word or an underscore-delimited list of 127 words, in lowercase letters, that describes the function. If applicable, 128 they should be declared 'static'. 129 1304. Variable names must be meaningful. One letter variable names must be 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 1345. Variable names should be in lowercase. Use underscores to separate 135 between words. 136 1376. Method names follow the 'studlyCaps' (also referred to as 'bumpy case' 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 140 letter that starts a new 'word' is capitalized:: 141 142 Good: 143 'connect()' 144 'getData()' 145 'buildSomeWidget()' 146 147 Bad: 148 'get_Data()' 149 'buildsomewidget' 150 'getI()' 151 1527. 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):: 157 158 Good: 159 'Curl' 160 'FooBar' 161 162 Bad: 163 'foobar' 164 'foo_bar' 165 166Syntax and indentation 167---------------------- 168 1691. 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. 177 1782. 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 184 syntax. Also see Indentstyle_. 185 186.. _Indentstyle: http://www.catb.org/~esr/jargon/html/I/indent-style.html 187 1883. 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:: 192 193 if (foo) { 194 bar; 195 } 196 197 to: 198 199 if(foo)bar; 200 2014. When indenting, use the tab character. A tab is expected to represent 202 four spaces. It is important to maintain consistency in indenture so 203 that definitions, comments, and control structures line up correctly. 204 2055. Preprocessor statements (#if and such) MUST start at column one. To 206 indent preprocessor directives you should put the # at the beginning 207 of a line, followed by any number of whitespace. 208 209Testing 210------- 211 2121. Extensions should be well tested using *.phpt tests. Read about that 213 in README.TESTING. 214 215Documentation and Folding Hooks 216------------------------------- 217 218In order to make sure that the online documentation stays in line with 219the code, each user-level function should have its user-level function 220prototype before it along with a brief one-line description of what the 221function does. It would look like this:: 222 223 /* {{{ proto int abs(int number) 224 Returns the absolute value of the number */ 225 PHP_FUNCTION(abs) 226 { 227 ... 228 } 229 /* }}} */ 230 231The {{{ symbols are the default folding symbols for the folding mode in 232Emacs and vim (set fdm=marker). Folding is very useful when dealing with 233large files because you can scroll through the file quickly and just unfold 234the function you wish to work on. The }}} at the end of each function marks 235the end of the fold, and should be on a separate line. 236 237The "proto" keyword there is just a helper for the doc/genfuncsummary script 238which generates a full function summary. Having this keyword in front of the 239function prototypes allows us to put folds elsewhere in the code without 240messing up the function summary. 241 242Optional arguments are written like this:: 243 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 */ 246 247And yes, please keep the prototype on a single line, even if that line 248is massive. 249 250New and Experimental Functions 251----------------------------------- 252To reduce the problems normally associated with the first public 253implementation of a new set of functions, it has been suggested 254that the first implementation include a file labeled 'EXPERIMENTAL' 255in the function directory, and that the functions follow the 256standard prefixing conventions during their initial implementation. 257 258The file labelled 'EXPERIMENTAL' should include the following 259information:: 260 261 Any authoring information (known bugs, future directions of the module). 262 Ongoing status notes which may not be appropriate for SVN comments. 263 264Aliases & Legacy Documentation 265----------------------------------- 266You may also have some deprecated aliases with close to duplicate 267names, for example, somedb_select_result and somedb_selectresult. For 268documentation purposes, these will only be documented by the most 269current name, with the aliases listed in the documentation for 270the parent function. For ease of reference, user-functions with 271completely different names, that alias to the same function (such as 272highlight_file and show_source), will be separately documented. The 273proto should still be included, describing which function is aliased. 274 275Backwards compatible functions and names should be maintained as long 276as the code can be reasonably be kept as part of the codebase. See 277/phpdoc/README for more information on documentation. 278
