xref: /PHP-7.4/CODING_STANDARDS.md (revision 8069e152)
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