xref: /PHP-8.2/CODING_STANDARDS.md (revision 5d37cd97)
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
122. Functions that are given pointers to resources should not free them.
13
14    For instance, `function int mail(char *to, char *from)` should NOT free `to`
15    and/or `from`.
16
17    Exceptions:
18
19    * The function's designated behavior is freeing that resource. E.g.
20      `efree()`
21
22    * The function is given a boolean argument, that controls whether or not the
23      function may free its arguments (if true, the function must free its
24      arguments; if false, it must not)
25
26    * Low-level parser routines, that are tightly integrated with the token
27      cache and the bison code for minimum memory copying overhead.
28
293. Functions that are tightly integrated with other functions within the same
30    module, and rely on each other's non-trivial behavior, should be documented as
31    such and declared `static`. They should be avoided if possible.
32
334. Use definitions and macros whenever possible, so that constants have
34    meaningful names and can be easily manipulated. Any use of a numeric
35    constant to specify different behavior or actions should be done through
36    a `#define`.
37
385. When writing functions that deal with strings, be sure to remember that PHP
39    holds the length property of each string, and that it shouldn't be
40    calculated with `strlen()`. Write your functions in such a way so that
41    they'll take advantage of the length property, both for efficiency and in
42    order for them to be binary-safe. Functions that change strings and obtain
43    their new lengths while doing so, should return that new length, so it
44    doesn't have to be recalculated with `strlen()` (e.g. `php_addslashes()`).
45
466. NEVER USE `strncat()`. If you're absolutely sure you know what you're doing,
47    check its man page again, and only then, consider using it, and even then,
48    try avoiding it.
49
507. Use `PHP_*` macros in the PHP source, and `ZEND_*` macros in the Zend part of
51    the source. Although the `PHP_*` macros are mostly aliased to the `ZEND_*`
52    macros it gives a better understanding on what kind of macro you're calling.
53
548. When commenting out code using a `#if` statement, do NOT use `0` only.
55    Instead use `"<git username here>_0"`. For example, `#if FOO_0`, where `FOO`
56    is your git user `foo`. This allows easier tracking of why code was
57    commented out, especially in bundled libraries.
58
599. 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
6410. 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
77## User functions/methods naming conventions
78
791. Function names for user-level functions should be enclosed with in the
80    `PHP_FUNCTION()` macro. They should be in lowercase, with words underscore
81    delimited, with care taken to minimize the letter count. Abbreviations
82    should not be used when they greatly decrease the readability of the
83    function name itself:
84
85    Good:
86
87    ```php
88    str_word_count
89    array_key_exists
90    ```
91
92    Ok:
93
94    ```php
95    date_interval_create_from_date_string
96    // Could be 'date_intvl_create_from_date_str'?
97    get_html_translation_table()
98    // Could be 'html_get_trans_table'?
99    ```
100
101    Bad:
102
103    ```php
104    hw_GetObjectByQueryCollObj
105    pg_setclientencoding
106    jf_n_s_i
107    ```
108
1092. If they are part of a "parent set" of functions, that parent should be
110    included in the user function name, and should be clearly related to the
111    parent program or function family. This should be in the form of `parent_*`:
112
113    A family of `foo` functions, for example:
114
115    Good:
116
117    ```php
118    foo_select_bar
119    foo_insert_baz
120    foo_delete_baz
121    ```
122
123    Bad:
124
125    ```php
126    fooselect_bar
127    fooinsertbaz
128    delete_foo_baz
129    ```
130
1313. Function names used by user functions should be prefixed with `_php_`, and
132    followed by a word or an underscore-delimited list of words, in lowercase
133    letters, that describes the function. If applicable, they should be declared
134    `static`.
135
1364. Variable names must be meaningful. One letter variable names must be avoided,
137    except for places where the variable has no real meaning or a trivial
138    meaning (e.g. `for (i=0; i<100; i++) ...`).
139
1405. Variable names should be in lowercase. Use underscores to separate between
141    words.
142
1436. Method names follow the *studlyCaps* (also referred to as *bumpy case* or
144    *camel caps*) naming convention, with care taken to minimize the letter
145    count. The initial letter of the name is lowercase, and each letter that
146    starts a new `word` is capitalized:
147
148    Good:
149
150    ```php
151    connect()
152    getData()
153    buildSomeWidget()
154    ```
155
156    Bad:
157
158    ```php
159    get_Data()
160    buildsomewidget()
161    getI()
162    ```
163
1647. Class names should be descriptive nouns in *PascalCase* and as short as
165    possible. Each word in the class name should start with a capital letter,
166    without underscore delimiters. The class name should be prefixed with the
167    name of the "parent set" (e.g. the name of the extension) if no namespaces
168    are used. Abbreviations and acronyms as well as initialisms should be
169    avoided wherever possible, unless they are much more widely used than the
170    long form (e.g. HTTP or URL). Abbreviations start with a capital letter
171    followed by lowercase letters, whereas acronyms and initialisms are written
172    according to their standard notation. Usage of acronyms and initialisms is
173    not allowed if they are not widely adopted and recognized as such.
174
175    Good:
176
177    ```php
178    Curl
179    CurlResponse
180    HTTPStatusCode
181    URL
182    BTreeMap // B-tree Map
183    Id // Identifier
184    ID // Identity Document
185    Char // Character
186    Intl // Internationalization
187    Radar // Radio Detecting and Ranging
188    ```
189
190    Bad:
191
192    ```php
193    curl
194    curl_response
195    HttpStatusCode
196    Url
197    BtreeMap
198    ID // Identifier
199    CHAR
200    INTL
201    RADAR // Radio Detecting and Ranging
202    ```
203
204## Internal function naming conventions
205
2061. Functions that are part of the external API should be named
207    `php_modulename_function()` to avoid symbol collision. They should be in
208    lowercase, with words underscore delimited. Exposed API must be defined in
209    `php_modulename.h`.
210
211    ```c
212    PHPAPI char *php_session_create_id(PS_CREATE_SID_ARGS);
213    ```
214
215    Unexposed module function should be static and should not be defined in
216    `php_modulename.h`.
217
218    ```c
219    static int php_session_destroy()
220    ```
221
2222. Main module source file must be named `modulename.c`.
223
2243. Header file that is used by other sources must be named `php_modulename.h`.
225
226## Syntax and indentation
227
2281. Never use C++ style comments (i.e. `//` comment). Always use C-style comments
229    instead. PHP is written in C, and is aimed at compiling under any ANSI-C
230    compliant compiler. Even though many compilers accept C++-style comments in
231    C code, you have to ensure that your code would compile with other compilers
232    as well. The only exception to this rule is code that is Win32-specific,
233    because the Win32 port is MS-Visual C++ specific, and this compiler is known
234    to accept C++-style comments in C code.
235
2362. Use K&R-style. Of course, we can't and don't want to force anybody to use a
237    style he or she is not used to, but, at the very least, when you write code
238    that goes into the core of PHP or one of its standard modules, please
239    maintain the K&R style. This applies to just about everything, starting with
240    indentation and comment styles and up to function declaration syntax. Also
241    see [Indentstyle](http://www.catb.org/~esr/jargon/html/I/indent-style.html).
242
2433. Be generous with whitespace and braces. Keep one empty line between the
244    variable declaration section and the statements in a block, as well as
245    between logical statement groups in a block. Maintain at least one empty
246    line between two functions, preferably two. Always prefer:
247
248    ```c
249    if (foo) {
250        bar;
251    }
252    ```
253
254    to:
255
256    ```c
257    if(foo)bar;
258    ```
259
2604. When indenting, use the tab character. A tab is expected to represent four
261    spaces. It is important to maintain consistency in indentation so that
262    definitions, comments, and control structures line up correctly.
263
2645. Preprocessor statements (`#if` and such) MUST start at column one. To indent
265    preprocessor directives you should put the `#` at the beginning of a line,
266    followed by any number of spaces.
267
268## Testing
269
2701. Extensions should be well tested using `*.phpt` tests. Read more at
271    [qa.php.net](https://qa.php.net/write-test.php) documentation.
272
273## New and experimental functions
274
275To reduce the problems normally associated with the first public implementation
276of a new set of functions, it has been suggested that the first implementation
277include a file labeled `EXPERIMENTAL` in the function directory, and that the
278functions follow the standard prefixing conventions during their initial
279implementation.
280
281The file labelled `EXPERIMENTAL` should include the following information:
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 there
287are specific reasons for directly adding them to the core distribution.
288
289## Aliases & legacy documentation
290
291You may also have some deprecated aliases with close to duplicate names, for
292example, `somedb_select_result` and `somedb_selectresult`. For documentation
293purposes, these will only be documented by the most current name, with the
294aliases listed in the documentation for the parent function. For ease of
295reference, user-functions with completely different names, that alias to the
296same function (such as `highlight_file` and `show_source`), will be separately
297documented.
298
299Backwards compatible functions and names should be maintained as long as the
300code can be reasonably be kept as part of the codebase. See the `README` in the
301PHP documentation repository for more information on documentation.
302