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. 21 22Exceptions: 23 24- The function's designated behavior is freeing that resource. E.g. efree() 25 26- The function is given a boolean argument, that controls whether or not 27 the function may free its arguments (if true - the function must free its 28 arguments, if false - it must not) 29 30- Low-level parser routines, that are tightly integrated with the token 31 cache and the bison code for minimum memory copying overhead. 32 332. Functions that are tightly integrated with other functions within the 34 same module, and rely on each other non-trivial behavior, should be 35 documented as such and declared 'static'. They should be avoided if 36 possible. 37 383. Use definitions and macros whenever possible, so that constants have 39 meaningful names and can be easily manipulated. The only exceptions 40 to this rule are 0 and 1, when used as false and true (respectively). 41 Any other use of a numeric constant to specify different behavior 42 or actions should be done through a #define. 43 444. When writing functions that deal with strings, be sure to remember 45 that PHP holds the length property of each string, and that it 46 shouldn't be calculated with strlen(). Write your functions in such 47 a way so that they'll take advantage of the length property, both 48 for efficiency and in order for them to be binary-safe. 49 Functions that change strings and obtain their new lengths while 50 doing so, should return that new length, so it doesn't have to be 51 recalculated with strlen() (e.g. php_addslashes()) 52 535. NEVER USE strncat(). If you're absolutely sure you know what you're doing, 54 check its man page again, and only then, consider using it, and even then, 55 try avoiding it. 56 576. Use ``PHP_*`` macros in the PHP source, and ``ZEND_*`` macros in the Zend 58 part of the source. Although the ``PHP_*`` macro's are mostly aliased to the 59 ``ZEND_*`` macros it gives a better understanding on what kind of macro 60 you're calling. 61 627. When commenting out code using a #if statement, do NOT use 0 only. Instead 63 use "<git username here>_0". For example, #if FOO_0, where FOO is your 64 git user foo. This allows easier tracking of why code was commented out, 65 especially in bundled libraries. 66 678. Do not define functions that are not available. For instance, if a 68 library is missing a function, do not define the PHP version of the 69 function, and do not raise a run-time error about the function not 70 existing. End users should use function_exists() to test for the 71 existence of a function 72 739. Prefer emalloc(), efree(), estrdup(), etc. to their standard C library 74 counterparts. These functions implement an internal "safety-net" 75 mechanism that ensures the deallocation of any unfreed memory at the 76 end of a request. They also provide useful allocation and overflow 77 information while running in debug mode. 78 79 In almost all cases, memory returned to the engine must be allocated 80 using emalloc(). 81 82 The use of malloc() should be limited to cases where a third-party 83 library may need to control or free the memory, or when the memory in 84 question needs to survive between multiple requests. 85 86User Functions/Methods Naming Conventions 87------------------ 88 891. Function names for user-level functions should be enclosed with in 90 the PHP_FUNCTION() macro. They should be in lowercase, with words 91 underscore delimited, with care taken to minimize the letter count. 92 Abbreviations should not be used when they greatly decrease the 93 readability of the function name itself:: 94 95 Good: 96 'mcrypt_enc_self_test' 97 'mysql_list_fields' 98 99 Ok: 100 'mcrypt_module_get_algo_supported_key_sizes' 101 (could be 'mcrypt_mod_get_algo_sup_key_sizes'?) 102 'get_html_translation_table' 103 (could be 'html_get_trans_table'?) 104 105 Bad: 106 'hw_GetObjectByQueryCollObj' 107 'pg_setclientencoding' 108 'jf_n_s_i' 109 1102. If they are part of a "parent set" of functions, that parent should 111 be included in the user function name, and should be clearly related 112 to the parent program or function family. This should be in the form 113 of ``parent_*``:: 114 115 A family of 'foo' functions, for example: 116 117 Good: 118 'foo_select_bar' 119 'foo_insert_baz' 120 'foo_delete_baz' 121 122 Bad: 123 'fooselect_bar' 124 'fooinsertbaz' 125 'delete_foo_baz' 126 1273. Function names used by user functions should be prefixed 128 with ``_php_``, and followed by a word or an underscore-delimited list of 129 words, in lowercase letters, that describes the function. If applicable, 130 they should be declared 'static'. 131 1324. Variable names must be meaningful. One letter variable names must be 133 avoided, except for places where the variable has no real meaning or 134 a trivial meaning (e.g. for (i=0; i<100; i++) ...). 135 1365. Variable names should be in lowercase. Use underscores to separate 137 between words. 138 1396. Method names follow the 'studlyCaps' (also referred to as 'bumpy case' 140 or 'camel caps') naming convention, with care taken to minimize the 141 letter count. The initial letter of the name is lowercase, and each 142 letter that starts a new 'word' is capitalized:: 143 144 Good: 145 'connect()' 146 'getData()' 147 'buildSomeWidget()' 148 149 Bad: 150 'get_Data()' 151 'buildsomewidget' 152 'getI()' 153 1547. Classes should be given descriptive names. Avoid using abbreviations where 155 possible. Each word in the class name should start with a capital letter, 156 without underscore delimiters (CamelCaps starting with a capital letter). 157 The class name should be prefixed with the name of the 'parent set' (e.g. 158 the name of the extension):: 159 160 Good: 161 'Curl' 162 'FooBar' 163 164 Bad: 165 'foobar' 166 'foo_bar' 167 168Internal Function Naming Conventions 169---------------------- 170 1711. Functions that are part of the external API should be named 172 'php_modulename_function()' to avoid symbol collision. They should be in 173 lowercase, with words underscore delimited. Exposed API must be defined 174 in 'php_modulename.h'. 175 176 PHPAPI char *php_session_create_id(PS_CREATE_SID_ARGS); 177 178 Unexposed module function should be static and should not be defined in 179 'php_modulename.h'. 180 181 static int php_session_destroy() 182 1832. Main module source file must be named 'modulename.c'. 184 1853. Header file that is used by other sources must be named 'php_modulename.h'. 186 187 188Syntax and indentation 189---------------------- 190 1911. Never use C++ style comments (i.e. // comment). Always use C-style 192 comments instead. PHP is written in C, and is aimed at compiling 193 under any ANSI-C compliant compiler. Even though many compilers 194 accept C++-style comments in C code, you have to ensure that your 195 code would compile with other compilers as well. 196 The only exception to this rule is code that is Win32-specific, 197 because the Win32 port is MS-Visual C++ specific, and this compiler 198 is known to accept C++-style comments in C code. 199 2002. Use K&R-style. Of course, we can't and don't want to 201 force anybody to use a style he or she is not used to, but, 202 at the very least, when you write code that goes into the core 203 of PHP or one of its standard modules, please maintain the K&R 204 style. This applies to just about everything, starting with 205 indentation and comment styles and up to function declaration 206 syntax. Also see Indentstyle. 207 208 Indentstyle: http://www.catb.org/~esr/jargon/html/I/indent-style.html 209 2103. Be generous with whitespace and braces. Keep one empty line between the 211 variable declaration section and the statements in a block, as well as 212 between logical statement groups in a block. Maintain at least one empty 213 line between two functions, preferably two. Always prefer:: 214 215 if (foo) { 216 bar; 217 } 218 219 to: 220 221 if(foo)bar; 222 2234. When indenting, use the tab character. A tab is expected to represent 224 four spaces. It is important to maintain consistency in indenture so 225 that definitions, comments, and control structures line up correctly. 226 2275. Preprocessor statements (#if and such) MUST start at column one. To 228 indent preprocessor directives you should put the # at the beginning 229 of a line, followed by any number of whitespace. 230 231Testing 232------- 233 2341. Extensions should be well tested using *.phpt tests. Read about that 235 in README.TESTING. 236 237Documentation and Folding Hooks 238------------------------------- 239 240In order to make sure that the online documentation stays in line with 241the code, each user-level function should have its user-level function 242prototype before it along with a brief one-line description of what the 243function does. It would look like this:: 244 245 /* {{{ proto int abs(int number) 246 Returns the absolute value of the number */ 247 PHP_FUNCTION(abs) 248 { 249 ... 250 } 251 /* }}} */ 252 253The {{{ symbols are the default folding symbols for the folding mode in 254Emacs and vim (set fdm=marker). Folding is very useful when dealing with 255large files because you can scroll through the file quickly and just unfold 256the function you wish to work on. The }}} at the end of each function marks 257the end of the fold, and should be on a separate line. 258 259The "proto" keyword there is just a helper for the doc/genfuncsummary script 260which generates a full function summary. Having this keyword in front of the 261function prototypes allows us to put folds elsewhere in the code without 262messing up the function summary. 263 264Optional arguments are written like this:: 265 266 /* {{{ proto object imap_header(int stream_id, int msg_no [, int from_length [, int subject_length [, string default_host]]]) 267 Returns a header object with the defined parameters */ 268 269And yes, please keep the prototype on a single line, even if that line 270is massive. 271 272New and Experimental Functions 273----------------------------------- 274To reduce the problems normally associated with the first public 275implementation of a new set of functions, it has been suggested 276that the first implementation include a file labeled 'EXPERIMENTAL' 277in the function directory, and that the functions follow the 278standard prefixing conventions during their initial implementation. 279 280The file labelled 'EXPERIMENTAL' should include the following 281information:: 282 283 Any authoring information (known bugs, future directions of the module). 284 Ongoing status notes which may not be appropriate for Git comments. 285 286In general new features should go to PECL or experimental branches until 287there are specific reasons for directly adding it to the core distribution. 288 289Aliases & Legacy Documentation 290----------------------------------- 291You may also have some deprecated aliases with close to duplicate 292names, for example, somedb_select_result and somedb_selectresult. For 293documentation purposes, these will only be documented by the most 294current name, with the aliases listed in the documentation for 295the parent function. For ease of reference, user-functions with 296completely different names, that alias to the same function (such as 297highlight_file and show_source), will be separately documented. The 298proto should still be included, describing which function is aliased. 299 300Backwards compatible functions and names should be maintained as long 301as the code can be reasonably be kept as part of the codebase. See 302/phpdoc/README for more information on documentation. 303
