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