xref: /PHP-8.4/CODING_STANDARDS.md (revision 631bab42)
1# PHP coding standards
2
3This file lists standards that any programmer adding or changing code in
4PHP should follow. The code base does not yet fully follow it, but new
5features are going in that general direction. Many sections have been
6rewritten to comply with these rules.
7
8## Code implementation
9
101. Document your code in source files and the manual. (tm)
11
121. PHP is implemented in C11.
13    For instance, the optional fixed-width integers from
14    stdint.h (int8_t, int16_t, int32_t, int64_t and their unsigned
15    counterparts) are supposed to be available.
16
171. Functions that are given pointers to resources should not free them.
18
19    For instance, `function int mail(char *to, char *from)` should NOT free `to`
20    and/or `from`.
21
22    Exceptions:
23
24    * The function's designated behavior is freeing that resource. E.g.
25      `efree()`
26
27    * The function is given a boolean argument, that controls whether or not the
28      function may free its arguments (if true, the function must free its
29      arguments; if false, it must not)
30
31    * Low-level parser routines, that are tightly integrated with the token
32      cache and the bison code for minimum memory copying overhead.
33
341. Functions that are tightly integrated with other functions within the same
35    module, and rely on each other's non-trivial behavior, should be documented as
36    such and declared `static`. They should be avoided if possible.
37
381. Use definitions and macros whenever possible, so that constants have
39    meaningful names and can be easily manipulated. Any use of a numeric
40    constant to specify different behavior or actions should be done through
41    a `#define`.
42
431. When writing functions that deal with strings, be sure to remember that PHP
44    holds the length property of each string, and that it shouldn't be
45    calculated with `strlen()`. Write your functions in such a way so that
46    they'll take advantage of the length property, both for efficiency and in
47    order for them to be binary-safe. Functions that change strings and obtain
48    their new lengths while doing so, should return that new length, so it
49    doesn't have to be recalculated with `strlen()` (e.g. `php_addslashes()`).
50
511. NEVER USE `strncat()`. If you're absolutely sure you know what you're doing,
52    check its man page again, and only then, consider using it, and even then,
53    try avoiding it.
54
551. Use `PHP_*` macros in the PHP source, and `ZEND_*` macros in the Zend part of
56    the source. Although the `PHP_*` macros are mostly aliased to the `ZEND_*`
57    macros it gives a better understanding on what kind of macro you're calling.
58
591. Do not define functions that are not available. For instance, if a library is
60    missing a function, do not define the PHP version of the function, and do
61    not raise a run-time error about the function not existing. End users should
62    use `function_exists()` to test for the existence of a function.
63
641. Prefer `emalloc()`, `efree()`, `estrdup()`, etc. to their standard C library
65    counterparts. These functions implement an internal "safety-net" mechanism
66    that ensures the deallocation of any unfreed memory at the end of a request.
67    They also provide useful allocation and overflow information while running
68    in debug mode.
69
70    In almost all cases, memory returned to the engine must be allocated using
71    `emalloc()`.
72
73    The use of `malloc()` should be limited to cases where a third-party library
74    may need to control or free the memory, or when the memory in question needs
75    to survive between multiple requests.
76
771. The return type of "is" or "has" style functions should be `bool`,
78    which return a "yes"/"no" answer.  `zend_result` is an appropriate
79    return value for functions that perform some operation that may
80    succeed or fail.
81
82## User functions/methods naming conventions
83
841. Function names for user-level functions should be enclosed with in the
85    `PHP_FUNCTION()` macro. They should be in lowercase, with words underscore
86    delimited, with care taken to minimize the letter count. Abbreviations
87    should not be used when they greatly decrease the readability of the
88    function name itself:
89
90    Good:
91
92    ```php
93    str_word_count
94    array_key_exists
95    ```
96
97    Ok:
98
99    ```php
100    date_interval_create_from_date_string
101    // Could be 'date_intvl_create_from_date_str'?
102    get_html_translation_table()
103    // Could be 'html_get_trans_table'?
104    ```
105
106    Bad:
107
108    ```php
109    hw_GetObjectByQueryCollObj
110    pg_setclientencoding
111    jf_n_s_i
112    ```
113
1141. If they are part of a "parent set" of functions, that parent should be
115    included in the user function name, and should be clearly related to the
116    parent program or function family. This should be in the form of `parent_*`:
117
118    A family of `foo` functions, for example:
119
120    Good:
121
122    ```php
123    foo_select_bar
124    foo_insert_baz
125    foo_delete_baz
126    ```
127
128    Bad:
129
130    ```php
131    fooselect_bar
132    fooinsertbaz
133    delete_foo_baz
134    ```
135
1361. Function names used by user functions should be prefixed with `_php_`, and
137    followed by a word or an underscore-delimited list of words, in lowercase
138    letters, that describes the function. If applicable, they should be declared
139    `static`.
140
1411. Variable names must be meaningful. One letter variable names must be avoided,
142    except for places where the variable has no real meaning or a trivial
143    meaning (e.g. `for (i=0; i<100; i++) ...`).
144
1451. Variable names should be in lowercase. Use underscores to separate between
146    words.
147
1481. Method names follow the *studlyCaps* (also referred to as *bumpy case* or
149    *camel caps*) naming convention, with care taken to minimize the letter
150    count. The initial letter of the name is lowercase, and each letter that
151    starts a new "word" is capitalized.
152
1531. Class names should be descriptive nouns in *PascalCase* and as short as
154    possible. Each word in the class name should start with a capital letter,
155    without underscore delimiters. The class name should be prefixed with the
156    name of the "parent set" (e.g. the name of the extension) if no namespaces
157    are used.
158
1591.  Abbreviations and acronyms as well as initialisms should be avoided wherever
160    possible, unless they are much more widely used than the long form (e.g. HTTP
161    or URL). Abbreviations, acronyms, and initialisms should be treated like
162    regular words, thus they should be written with an uppercase first character,
163    followed by lowercase characters.
164
1651.  Diverging from this policy is allowed to keep internal consistency within a
166    single extension, if the name follows an established, language-agnostic
167    standard, or for other reasons, if those reasons are properly justified
168    and voted on as part of the RFC process.
169
170
171    Good method names:
172
173    ```php
174    connect()
175    getData()
176    buildSomeWidget()
177    performHttpRequest()
178    ```
179
180    Bad method names:
181
182    ```php
183    get_Data()
184    buildsomewidget()
185    getI()
186    performHTTPRequest()
187    ```
188
189    Good class names:
190
191    ```php
192    Curl
193    CurlResponse
194    HttpStatusCode
195    Url
196    BtreeMap // B-tree Map
197    UserId // User Identifier
198    Char // Character
199    Intl // Internationalization
200    Ssl\Certificate
201    Ssl\Crl // Certificate Revocation List
202    Ssl\CrlUrl
203    ```
204
205    Bad class names:
206
207    ```php
208    curl
209    curl_response
210    HTTPStatusCode
211    URL
212    BTreeMap
213    UserID // User Identifier
214    CHAR
215    INTL
216    SSL\Certificate
217    SSL\CRL
218    SSL\CRLURL
219    ```
220
221## Internal function naming conventions
222
2231. Functions that are part of the external API should be named
224    `php_modulename_function()` to avoid symbol collision. They should be in
225    lowercase, with words underscore delimited. Exposed API must be defined in
226    `php_modulename.h`.
227
228    ```c
229    PHPAPI char *php_session_create_id(PS_CREATE_SID_ARGS);
230    ```
231
232    Unexposed module function should be static and should not be defined in
233    `php_modulename.h`.
234
235    ```c
236    static int php_session_destroy()
237    ```
238
2391. Main module source file must be named `modulename.c`.
240
2411. Header file that is used by other sources must be named `php_modulename.h`.
242
243## Syntax and indentation
244
2451. Use K&R-style. Of course, we can't and don't want to force anybody to use a
246    style he or she is not used to, but, at the very least, when you write code
247    that goes into the core of PHP or one of its standard modules, please
248    maintain the K&R style. This applies to just about everything, starting with
249    indentation and comment styles and up to function declaration syntax. Also
250    see [Indentstyle](http://www.catb.org/~esr/jargon/html/I/indent-style.html).
251
2521. Be generous with whitespace and braces. Keep one empty line between the
253    variable declaration section and the statements in a block, as well as
254    between logical statement groups in a block. Maintain at least one empty
255    line between two functions, preferably two. Always prefer:
256
257    ```c
258    if (foo) {
259        bar;
260    }
261    ```
262
263    to:
264
265    ```c
266    if(foo)bar;
267    ```
268
2691. When indenting, use the tab character. A tab is expected to represent four
270    spaces. It is important to maintain consistency in indentation so that
271    definitions, comments, and control structures line up correctly.
272
2731. Preprocessor statements (`#if` and such) MUST start at column one. To indent
274    preprocessor directives you should put the `#` at the beginning of a line,
275    followed by any number of spaces.
276
2771. The length of constant string literals should be calculated via ``strlen()``
278   instead of using ``sizeof()-1`` as it is clearer and any modern compiler
279   will optimize it away. Legacy usages of the latter style exists within the
280   codebase but should not be refactored, unless larger refactoring around that
281   code is taking place.
282
283## Testing
284
2851. Extensions should be well tested using `*.phpt` tests. Read more at
286    [qa.php.net](https://qa.php.net/write-test.php) documentation.
287
288## New and experimental functions
289
290To reduce the problems normally associated with the first public implementation
291of a new set of functions, it has been suggested that the first implementation
292include a file labeled `EXPERIMENTAL` in the function directory, and that the
293functions follow the standard prefixing conventions during their initial
294implementation.
295
296The file labelled `EXPERIMENTAL` should include the following information:
297
298* Any authoring information (known bugs, future directions of the module).
299* Ongoing status notes which may not be appropriate for Git comments.
300
301In general, new features should go to PECL or experimental branches until there
302are specific reasons for directly adding them to the core distribution.
303
304## Aliases & legacy documentation
305
306You may also have some deprecated aliases with close to duplicate names, for
307example, `somedb_select_result` and `somedb_selectresult`. For documentation
308purposes, these will only be documented by the most current name, with the
309aliases listed in the documentation for the parent function. For ease of
310reference, user-functions with completely different names, that alias to the
311same function (such as `highlight_file` and `show_source`), will be separately
312documented.
313
314Backwards compatible functions and names should be maintained as long as the
315code can be reasonably be kept as part of the codebase. See the `README` in the
316PHP documentation repository for more information on documentation.
317