xref: /PHP-7.0/CODING_STANDARDS (revision cf842f10)
1========================
2  PHP Coding Standards
3========================
4
5This file lists several standards that any programmer adding or changing
6code in PHP should follow.  Since this file was added at a very late
7stage of the development of PHP v3.0, the code base does not (yet) fully
8follow it, but it's going in that general direction.  Since we are now
9well into version 5 releases, many sections have been recoded to use
10these rules.
11
12Code Implementation
13-------------------
14
150.  Document your code in source files and the manual. [tm]
16
171.  Functions that are given pointers to resources should not free them
18
19For instance, ``function int mail(char *to, char *from)`` should NOT free
20to and/or from.
21
22Exceptions:
23
24- The function's designated behavior is freeing that resource.  E.g. efree()
25
26- The function is given a boolean argument, that controls whether or not
27  the 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
332.  Functions that are tightly integrated with other functions within the
34    same module, and rely on each other non-trivial behavior, should be
35    documented as such and declared 'static'.  They should be avoided if
36    possible.
37
383.  Use definitions and macros whenever possible, so that constants have
39    meaningful names and can be easily manipulated.  The only exceptions
40    to this rule are 0 and 1, when used as false and true (respectively).
41    Any other use of a numeric constant to specify different behavior
42    or actions should be done through a #define.
43
444.  When writing functions that deal with strings, be sure to remember
45    that PHP holds the length property of each string, and that it
46    shouldn't be calculated with strlen().  Write your functions in such
47    a way so that they'll take advantage of the length property, both
48    for efficiency and in order for them to be binary-safe.
49    Functions that change strings and obtain their new lengths while
50    doing so, should return that new length, so it doesn't have to be
51    recalculated with strlen() (e.g. php_addslashes())
52
535.  NEVER USE strncat().  If you're absolutely sure you know what you're doing,
54    check its man page again, and only then, consider using it, and even then,
55    try avoiding it.
56
576.  Use ``PHP_*`` macros in the PHP source, and ``ZEND_*`` macros in the Zend
58    part of the source. Although the ``PHP_*`` macro's are mostly aliased to the
59    ``ZEND_*`` macros it gives a better understanding on what kind of macro
60    you're calling.
61
627.  When commenting out code using a #if statement, do NOT use 0 only. Instead
63    use "<git username here>_0". For example, #if FOO_0, where FOO is your
64    git user foo.  This allows easier tracking of why code was commented out,
65    especially in bundled libraries.
66
678.  Do not define functions that are not available.  For instance, if a
68    library is missing a function, do not define the PHP version of the
69    function, and do not raise a run-time error about the function not
70    existing.  End users should use function_exists() to test for the
71    existence of a function
72
739.  Prefer emalloc(), efree(), estrdup(), etc. to their standard C library
74    counterparts.  These functions implement an internal "safety-net"
75    mechanism that ensures the deallocation of any unfreed memory at the
76    end of a request.  They also provide useful allocation and overflow
77    information while running in debug mode.
78
79    In almost all cases, memory returned to the engine must be allocated
80    using emalloc().
81
82    The use of malloc() should be limited to cases where a third-party
83    library may need to control or free the memory, or when the memory in
84    question needs to survive between multiple requests.
85
86User Functions/Methods Naming Conventions
87------------------
88
891.  Function names for user-level functions should be enclosed with in
90    the PHP_FUNCTION() macro. They should be in lowercase, with words
91    underscore delimited, with care taken to minimize the letter count.
92    Abbreviations should not be used when they greatly decrease the
93    readability of the function name itself::
94
95    Good:
96    'mcrypt_enc_self_test'
97    'mysql_list_fields'
98
99    Ok:
100    'mcrypt_module_get_algo_supported_key_sizes'
101    (could be 'mcrypt_mod_get_algo_sup_key_sizes'?)
102    'get_html_translation_table'
103    (could be 'html_get_trans_table'?)
104
105    Bad:
106    'hw_GetObjectByQueryCollObj'
107    'pg_setclientencoding'
108    'jf_n_s_i'
109
1102.  If they are part of a "parent set" of functions, that parent should
111    be included in the user function name, and should be clearly related
112    to the parent program or function family. This should be in the form
113    of ``parent_*``::
114
115    A family of 'foo' functions, for example:
116
117    Good:
118    'foo_select_bar'
119    'foo_insert_baz'
120    'foo_delete_baz'
121
122    Bad:
123    'fooselect_bar'
124    'fooinsertbaz'
125    'delete_foo_baz'
126
1273.  Function names used by user functions should be prefixed
128    with ``_php_``, and followed by a word or an underscore-delimited list of
129    words, in lowercase letters, that describes the function.  If applicable,
130    they should be declared 'static'.
131
1324.  Variable names must be meaningful.  One letter variable names must be
133    avoided, except for places where the variable has no real meaning or
134    a trivial meaning (e.g. for (i=0; i<100; i++) ...).
135
1365.  Variable names should be in lowercase.  Use underscores to separate
137    between words.
138
1396.  Method names follow the 'studlyCaps' (also referred to as 'bumpy case'
140    or 'camel caps') naming convention, with care taken to minimize the
141    letter count. The initial letter of the name is lowercase, and each
142    letter that starts a new 'word' is capitalized::
143
144    Good:
145    'connect()'
146    'getData()'
147    'buildSomeWidget()'
148
149    Bad:
150    'get_Data()'
151    'buildsomewidget'
152    'getI()'
153
1547.  Classes should be given descriptive names. Avoid using abbreviations where
155    possible. Each word in the class name should start with a capital letter,
156    without underscore delimiters (CamelCaps starting with a capital letter).
157    The class name should be prefixed with the name of the 'parent set' (e.g.
158    the name of the extension)::
159
160    Good:
161    'Curl'
162    'FooBar'
163
164    Bad:
165    'foobar'
166    'foo_bar'
167
168Internal Function Naming Convensions
169----------------------
170
1711.  Functions that are part of the external API should be named
172    'php_modulename_function()' to avoid symbol collision. They should be in
173    lowercase, with words underscore delimited. Exposed API must be defined
174    in 'php_modulename.h'.
175
176    PHPAPI char *php_session_create_id(PS_CREATE_SID_ARGS);
177
178    Unexposed module function should be static and should not be defined in
179    'php_modulename.h'.
180
181    static int php_session_destroy()
182
1832.  Main module source file must be named 'modulename.c'.
184
1853.  Header file that is used by other sources must be named 'php_modulename.h'.
186
187
188Syntax and indentation
189----------------------
190
1911.  Never use C++ style comments (i.e. // comment).  Always use C-style
192    comments instead.  PHP is written in C, and is aimed at compiling
193    under any ANSI-C compliant compiler.  Even though many compilers
194    accept C++-style comments in C code, you have to ensure that your
195    code would compile with other compilers as well.
196    The only exception to this rule is code that is Win32-specific,
197    because the Win32 port is MS-Visual C++ specific, and this compiler
198    is known to accept C++-style comments in C code.
199
2002.  Use K&R-style.  Of course, we can't and don't want to
201    force anybody to use a style he or she is not used to, but,
202    at the very least, when you write code that goes into the core
203    of PHP or one of its standard modules, please maintain the K&R
204    style.  This applies to just about everything, starting with
205    indentation and comment styles and up to function declaration
206    syntax. Also see Indentstyle.
207
208    Indentstyle: http://www.catb.org/~esr/jargon/html/I/indent-style.html
209
2103.  Be generous with whitespace and braces.  Keep one empty line between the
211    variable declaration section and the statements in a block, as well as
212    between logical statement groups in a block.  Maintain at least one empty
213    line between two functions, preferably two.  Always prefer::
214
215    if (foo) {
216        bar;
217    }
218
219    to:
220
221    if(foo)bar;
222
2234.  When indenting, use the tab character.  A tab is expected to represent
224    four spaces.  It is important to maintain consistency in indenture so
225    that definitions, comments, and control structures line up correctly.
226
2275.  Preprocessor statements (#if and such) MUST start at column one. To
228    indent preprocessor directives you should put the # at the beginning
229    of a line, followed by any number of whitespace.
230
231Testing
232-------
233
2341.  Extensions should be well tested using *.phpt tests. Read about that
235    in README.TESTING.
236
237Documentation and Folding Hooks
238-------------------------------
239
240In order to make sure that the online documentation stays in line with
241the code, each user-level function should have its user-level function
242prototype before it along with a brief one-line description of what the
243function does.  It would look like this::
244
245  /* {{{ proto int abs(int number)
246     Returns the absolute value of the number */
247  PHP_FUNCTION(abs)
248  {
249     ...
250  }
251  /* }}} */
252
253The {{{ symbols are the default folding symbols for the folding mode in
254Emacs and vim (set fdm=marker).  Folding is very useful when dealing with
255large files because you can scroll through the file quickly and just unfold
256the function you wish to work on.  The }}} at the end of each function marks
257the end of the fold, and should be on a separate line.
258
259The "proto" keyword there is just a helper for the doc/genfuncsummary script
260which generates a full function summary.  Having this keyword in front of the
261function prototypes allows us to put folds elsewhere in the code without
262messing up the function summary.
263
264Optional arguments are written like this::
265
266  /* {{{ proto object imap_header(int stream_id, int msg_no [, int from_length [, int subject_length [, string default_host]]])
267     Returns a header object with the defined parameters */
268
269And yes, please keep the prototype on a single line, even if that line
270is massive.
271
272New and Experimental Functions
273-----------------------------------
274To reduce the problems normally associated with the first public
275implementation of a new set of functions, it has been suggested
276that the first implementation include a file labeled 'EXPERIMENTAL'
277in the function directory, and that the functions follow the
278standard prefixing conventions during their initial implementation.
279
280The file labelled 'EXPERIMENTAL' should include the following
281information::
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
287there are specific reasons for directly adding it to the core distribution.
288
289Aliases & Legacy Documentation
290-----------------------------------
291You may also have some deprecated aliases with close to duplicate
292names, for example, somedb_select_result and somedb_selectresult. For
293documentation purposes, these will only be documented by the most
294current name, with the aliases listed in the documentation for
295the parent function. For ease of reference, user-functions with
296completely different names, that alias to the same function (such as
297highlight_file and show_source), will be separately documented. The
298proto should still be included, describing which function is aliased.
299
300Backwards compatible functions and names should be maintained as long
301as the code can be reasonably be kept as part of the codebase. See
302/phpdoc/README for more information on documentation.
303