1# PHP coding standards 2 3This file lists several standards that any programmer adding or changing code in 4PHP should follow. Since this file was added at a very late stage of the 5development of PHP v3.0, the code base does not fully follow it, but new 6features are going in that general direction. Many sections have been recoded to 7use these rules. 8 9## Code implementation 10 111. Document your code in source files and the manual. (tm) 12 132. Functions that are given pointers to resources should not free them. 14 15 For instance, `function int mail(char *to, char *from)` should NOT free to 16 and/or from. 17 18 Exceptions: 19 20 * The function's designated behavior is freeing that resource. E.g. 21 `efree()` 22 23 * The function is given a boolean argument, that controls whether or not the 24 function may free its arguments (if true - the function must free its 25 arguments, if false - it must not) 26 27 * Low-level parser routines, that are tightly integrated with the token 28 cache and the bison code for minimum memory copying overhead. 29 303. Functions that are tightly integrated with other functions within the same 31 module, and rely on each other non-trivial behavior, should be documented as 32 such and declared `static`. They should be avoided if possible. 33 344. Use definitions and macros whenever possible, so that constants have 35 meaningful names and can be easily manipulated. The only exceptions to this 36 rule are 0 and 1, when used as `false` and `true` (respectively). Any other 37 use of a numeric constant to specify different behavior or actions should be 38 done through a `#define`. 39 405. When writing functions that deal with strings, be sure to remember that PHP 41 holds the length property of each string, and that it shouldn't be 42 calculated with `strlen()`. Write your functions in such a way so that 43 they'll take advantage of the length property, both for efficiency and in 44 order for them to be binary-safe. Functions that change strings and obtain 45 their new lengths while doing so, should return that new length, so it 46 doesn't have to be recalculated with `strlen()` (e.g. `php_addslashes()`). 47 486. NEVER USE `strncat()`. If you're absolutely sure you know what you're doing, 49 check its man page again, and only then, consider using it, and even then, 50 try avoiding it. 51 527. Use `PHP_*` macros in the PHP source, and `ZEND_*` macros in the Zend part of 53 the source. Although the `PHP_*` macros are mostly aliased to the `ZEND_*` 54 macros it gives a better understanding on what kind of macro you're calling. 55 568. When commenting out code using a `#if` statement, do NOT use `0` only. 57 Instead use `"<git username here>_0"`. For example, `#if FOO_0`, where `FOO` 58 is your git user `foo`. This allows easier tracking of why code was 59 commented out, especially in bundled libraries. 60 619. Do not define functions that are not available. For instance, if a library is 62 missing a function, do not define the PHP version of the function, and do 63 not raise a run-time error about the function not existing. End users should 64 use `function_exists()` to test for the existence of a function. 65 6610. Prefer `emalloc()`, `efree()`, `estrdup()`, etc. to their standard C library 67 counterparts. These functions implement an internal "safety-net" mechanism 68 that ensures the deallocation of any unfreed memory at the end of a request. 69 They also provide useful allocation and overflow information while running 70 in debug mode. 71 72 In almost all cases, memory returned to the engine must be allocated using 73 `emalloc()`. 74 75 The use of `malloc()` should be limited to cases where a third-party library 76 may need to control or free the memory, or when the memory in question needs 77 to survive between multiple requests. 78 79## User functions/methods naming conventions 80 811. Function names for user-level functions should be enclosed with in the 82 `PHP_FUNCTION()` macro. They should be in lowercase, with words underscore 83 delimited, with care taken to minimize the letter count. Abbreviations 84 should not be used when they greatly decrease the readability of the 85 function name itself: 86 87 Good: 88 89 ```php 90 str_word_count 91 array_key_exists 92 ``` 93 94 Ok: 95 96 ```php 97 date_interval_create_from_date_string 98 // Could be 'date_intvl_create_from_date_str'? 99 get_html_translation_table() 100 // Could be 'html_get_trans_table'? 101 ``` 102 103 Bad: 104 105 ```php 106 hw_GetObjectByQueryCollObj 107 pg_setclientencoding 108 jf_n_s_i 109 ``` 110 1112. If they are part of a "parent set" of functions, that parent should be 112 included in the user function name, and should be clearly related to the 113 parent program or function family. This should be in the form of `parent_*`: 114 115 A family of `foo` functions, for example: 116 117 Good: 118 119 ```php 120 foo_select_bar 121 foo_insert_baz 122 foo_delete_baz 123 ``` 124 125 Bad: 126 127 ```php 128 fooselect_bar 129 fooinsertbaz 130 delete_foo_baz 131 ``` 132 1333. Function names used by user functions should be prefixed with `_php_`, and 134 followed by a word or an underscore-delimited list of words, in lowercase 135 letters, that describes the function. If applicable, they should be declared 136 `static`. 137 1384. Variable names must be meaningful. One letter variable names must be avoided, 139 except for places where the variable has no real meaning or a trivial 140 meaning (e.g. `for (i=0; i<100; i++) ...`). 141 1425. Variable names should be in lowercase. Use underscores to separate between 143 words. 144 1456. Method names follow the *studlyCaps* (also referred to as *bumpy case* or 146 *camel caps*) naming convention, with care taken to minimize the letter 147 count. The initial letter of the name is lowercase, and each letter that 148 starts a new `word` is capitalized: 149 150 Good: 151 152 ```php 153 connect() 154 getData() 155 buildSomeWidget() 156 ``` 157 158 Bad: 159 160 ```php 161 get_Data() 162 buildsomewidget() 163 getI() 164 ``` 165 1667. Class names should be descriptive nouns in *PascalCase* and as short as 167 possible. Each word in the class name should start with a capital letter, 168 without underscore delimiters. The class name should be prefixed with the 169 name of the "parent set" (e.g. the name of the extension) if no namespaces 170 are used. Abbreviations and acronyms as well as initialisms should be 171 avoided wherever possible, unless they are much more widely used than the 172 long form (e.g. HTTP or URL). Abbreviations start with a capital letter 173 followed by lowercase letters, whereas acronyms and initialisms are written 174 according to their standard notation. Usage of acronyms and initialisms is 175 not allowed if they are not widely adopted and recognized as such. 176 177 Good: 178 179 ```php 180 Curl 181 CurlResponse 182 HTTPStatusCode 183 URL 184 BTreeMap // B-tree Map 185 Id // Identifier 186 ID // Identity Document 187 Char // Character 188 Intl // Internationalization 189 Radar // Radio Detecting and Ranging 190 ``` 191 192 Bad: 193 194 ```php 195 curl 196 curl_response 197 HttpStatusCode 198 Url 199 BtreeMap 200 ID // Identifier 201 CHAR 202 INTL 203 RADAR // Radio Detecting and Ranging 204 ``` 205 206## Internal function naming conventions 207 2081. Functions that are part of the external API should be named 209 `php_modulename_function()` to avoid symbol collision. They should be in 210 lowercase, with words underscore delimited. Exposed API must be defined in 211 `php_modulename.h`. 212 213 ```c 214 PHPAPI char *php_session_create_id(PS_CREATE_SID_ARGS); 215 ``` 216 217 Unexposed module function should be static and should not be defined in 218 `php_modulename.h`. 219 220 ```c 221 static int php_session_destroy() 222 ``` 223 2242. Main module source file must be named `modulename.c`. 225 2263. Header file that is used by other sources must be named `php_modulename.h`. 227 228## Syntax and indentation 229 2301. Never use C++ style comments (i.e. `//` comment). Always use C-style comments 231 instead. PHP is written in C, and is aimed at compiling under any ANSI-C 232 compliant compiler. Even though many compilers accept C++-style comments in 233 C code, you have to ensure that your code would compile with other compilers 234 as well. The only exception to this rule is code that is Win32-specific, 235 because the Win32 port is MS-Visual C++ specific, and this compiler is known 236 to accept C++-style comments in C code. 237 2382. Use K&R-style. Of course, we can't and don't want to force anybody to use a 239 style he or she is not used to, but, at the very least, when you write code 240 that goes into the core of PHP or one of its standard modules, please 241 maintain the K&R style. This applies to just about everything, starting with 242 indentation and comment styles and up to function declaration syntax. Also 243 see [Indentstyle](http://www.catb.org/~esr/jargon/html/I/indent-style.html). 244 2453. Be generous with whitespace and braces. Keep one empty line between the 246 variable declaration section and the statements in a block, as well as 247 between logical statement groups in a block. Maintain at least one empty 248 line between two functions, preferably two. Always prefer: 249 250 ```c 251 if (foo) { 252 bar; 253 } 254 ``` 255 256 to: 257 258 ```c 259 if(foo)bar; 260 ``` 261 2624. When indenting, use the tab character. A tab is expected to represent four 263 spaces. It is important to maintain consistency in indenture so that 264 definitions, comments, and control structures line up correctly. 265 2665. Preprocessor statements (`#if` and such) MUST start at column one. To indent 267 preprocessor directives you should put the `#` at the beginning of a line, 268 followed by any number of whitespace. 269 270## Testing 271 2721. Extensions should be well tested using `*.phpt` tests. Read about that at 273 [qa.php.net](https://qa.php.net/write-test.php) documentation. 274 275## Documentation and folding hooks 276 277In order to make sure that the online documentation stays in line with the code, 278each user-level function should have its user-level function prototype before it 279along with a brief one-line description of what the function does. It would look 280like this: 281 282```c 283/* {{{ proto int abs(int number) 284 Returns the absolute value of the number */ 285PHP_FUNCTION(abs) 286{ 287 ... 288} 289/* }}} */ 290``` 291 292The `{{{` symbols are the default folding symbols for the folding mode in Emacs 293and vim (`set fdm=marker`). Folding is very useful when dealing with large files 294because you can scroll through the file quickly and just unfold the function you 295wish to work on. The `}}}` at the end of each function marks the end of the 296fold, and should be on a separate line. 297 298The `proto` keyword there is just a helper for the `doc/genfuncsummary` script 299which generates a full function summary. Having this keyword in front of the 300function prototypes allows us to put folds elsewhere in the code without 301messing up the function summary. 302 303Optional arguments are written like this: 304 305```c 306/* {{{ proto object imap_header(int stream_id, int msg_no [, int from_length [, int subject_length [, string default_host]]]) 307 Returns a header object with the defined parameters */ 308``` 309 310And yes, please keep the prototype on a single line, even if that line is 311massive. 312 313## New and experimental functions 314 315To reduce the problems normally associated with the first public implementation 316of a new set of functions, it has been suggested that the first implementation 317include a file labeled `EXPERIMENTAL` in the function directory, and that the 318functions follow the standard prefixing conventions during their initial 319implementation. 320 321The file labelled `EXPERIMENTAL` should include the following information: 322 323* Any authoring information (known bugs, future directions of the module). 324* Ongoing status notes which may not be appropriate for Git comments. 325 326In general new features should go to PECL or experimental branches until there 327are specific reasons for directly adding it to the core distribution. 328 329## Aliases & legacy documentation 330 331You may also have some deprecated aliases with close to duplicate names, for 332example, `somedb_select_result` and `somedb_selectresult`. For documentation 333purposes, these will only be documented by the most current name, with the 334aliases listed in the documentation for the parent function. For ease of 335reference, user-functions with completely different names, that alias to the 336same function (such as `highlight_file` and `show_source`), will be separately 337documented. The proto should still be included, describing which function is 338aliased. 339 340Backwards compatible functions and names should be maintained as long as the 341code can be reasonably be kept as part of the codebase. See the `README` in the 342PHP documentation repository for more information on documentation. 343
