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