PHP Coding Specification

Coding | specification

Indent

Indents use 4 spaces instead of tab. If you use Emacs to edit the PEAR code, you should set Indent-tabs-mode to nil. The following is an example of mode hook that sets Emacs to conform to the indentation criteria (you must make sure that these settings work when editing the PHP file):

(Defun Php-mode-hook ()
(Setq tab-width 4
C-basic-offset 4
C-hanging-comment-ender-p Nil
Indent-tabs-mode
(not
(String-match "/\\ (pear\\|pear\\)/" (Buffer-file-name))
(String-match "\.php$" (Buffer-file-name))))

Here is the same effect as the VIM rule:

Set Expandtab
Set shiftwidth=4
Set softtabstop=4
Set tabstop=4

--------------------------------------------------------------------------------

Control structure

The control structure includes if, for, while, switch, and so on. Here is an example of an if statement and an example of a switch statement:

Examples of IF statements:

<?php
if ((condition1) | | (Condition2)) {
Action1;
} elseif ((Condition3) && (Condition4)) {
Action2;
} else {
DefaultAction;
}
?>

Example of a switch statement:

<?php
Switch (condition) {
Case 1:
Action1;
Break
Case 2:
Action2;
Break
Default
DefaultAction;
Break
}
?>

The control statement should have a space between the control keyword and the opening parentheses, which distinguishes it from the function call.

It is strongly recommended that you always use curly braces to identify parts of the control structure. Even where it is technically possible to not use curly braces. This can increase the readability of your code while avoiding the introduction of logical errors after adding new rows to the structure section.

Original code:

if (condition)
return true;
Else
return false;

Modified code:

if (condition)
Do something; A logical error occurred
return true;
Else
return false;

The right approach:

if (condition) {
Do something;
return true;
} else {
return false;
}

--------------------------------------------------------------------------------

Function call

When calling a function, there should be no white-space characters between the number of functions and the opening parentheses. There should be no space between the argument and the opening and closing parentheses. In addition to the first argument, all other parameters should be separated by a single space. Here's an example:

<?php
$var = foo ($bar, $baz, $quux);
?>

As in the example code above, the assignment operator should use a space on both sides of the equal sign. If it is a related assignment operation, the following form should be used to provide better readability:

<?php
$short = foo ($bar);
$long _variable = foo ($baz);
?>

--------------------------------------------------------------------------------

function definition

Declare a function according to the "one True brace" convention:

<?php
function Foofunction ($arg 1, $arg 2 = ')
{
if (condition) {
Statement
}
return $val;
}
?>

The "One true brace" Convention is a separate line of curly braces, not followed by other statements.

Parameters with default values should be behind the argument list (as is the case with the PHP language definition). If appropriate, the function should always return a meaningful value. Here's a slightly longer example:

<?php
Function Connect (& $DSN, $persistent = False)
{
if (Is_array ($DSN)) {
$dsninfo = & $dsn;
} else {
$dsninfo = DB::p arsedsn ($DSN);
}

if (! $dsninfo | |! $dsninfo [' Phptype ']) {
return $this->raiseerror ();
}
return true;
}
?>

--------------------------------------------------------------------------------

Comments

The online documentation for type (class) should conform to the PHPDOC (similar to JAVADOC) conventions. More information about PHPDOC can be accessed by http://www.phpdoc.de/access.

In addition, the use of non-documentation annotations is strongly encouraged. The general rule is to add short introductory comments to code that is easily forgotten.

C-style annotations (*/* *) and standard C + + annotations (//) are recommended instead of Perl/shell-style annotations (#).

--------------------------------------------------------------------------------

Include code

The require_once () should be used wherever there is an unconditional inclusion of a type file in any place. If a conditional contains a type file (for example, using a factory method), you should use Include_once (). Using either of these can ensure that the type file is included only once. They share a list of files, so you don't have to worry about confusing them--a file that is included with require_once () will not be included again in Include_once ().

Note: include_once () and require_once () are declarations, not functions. You do not need to use parentheses to expand the file name (although there is no error with parentheses).

--------------------------------------------------------------------------------

PHP Code Tags

Always use <?php?> to define your PHP code instead of using the?> shorthand method. This is required to conform to PEAR consistency and also to migrate PHP code under different operating systems and different installation settings.

--------------------------------------------------------------------------------

Header comment Block

All source-code files published by PEAR should contain the following comment block:

<?php
/* Vim:set expandtab tabstop=4 softtabstop=4 shiftwidth=4: * *
// +----------------------------------------------------------------------+
// | PHP Version 4 |
// +----------------------------------------------------------------------+
// | Copyright (c) 1997-2002 the PHP Group |
// +----------------------------------------------------------------------+
// | This source file is subject to version 2.0 of the PHP license, |
// | That's bundled with this package in the file LICENSE, and is |
// | Available at through the World-wide-web at | |
// |                                 Http://www.php.net/license/2_02.txt. |
// | If you don't receive a copy of the PHP license and are unable to | did
// | Obtain it through the World-wide-web, please send a note to |
// |               License@php.net so we can mail you a copy immediately. |
// +----------------------------------------------------------------------+
// | Authors:original Author <author@example.com> |
// | Your Name <you@example.com> |
// +----------------------------------------------------------------------+
//
$ ID $
?>

There is no hard rule to add the name of a code contributor to the author list of a file comment. In general, their changes are in the "substantial" directory (meaning that approximately 10% to 20% of the code is overwritten). One exception is that a code contributor rewrites a function or contributes a new program logic.

Simple code reorganization and bug fixes should not add new authors, which is inappropriate.

Files that are not in the core PEAR warehouse should have a similar annotation block to describe the copyright, license Agreement, and author. All files should contain a pattern line (Modeline, for Vim and Emacs) to ensure consistency.

--------------------------------------------------------------------------------

Using CVS

The content of this section applies only to CVS-only packages used on cvs.php.net.

In each file contains $Id $ (two $ symbol between the keyword can not have spaces, but because this document is also managed with CVS, so have to add a space to avoid being replaced by CVS) CVS keyword, in order to see the file current status and last modified time information. If information such as "Last Modified:" already exists, replace with $ID $ tag.

The rest of this section assumes that you have a basic knowledge of CVS tagging and branching (branches).

The CVS tag is used to identify the revisions made prior to the release of the files in your package. The following list is the required and recommended CVS tag:

Release_n_n

(required) To mark a release version. If you don't use this tag, there's no way for someone to get your package from a CVS server when you release a release version.

Qa_n_n

(branch, optional) A good idea is to add a branch if you feel you want to provide a release release version before releasing it. This branch allows you to isolate release releases and apply updates to these branches separately before releasing the release version formally. During the period, normal development work can continue on the backbone.

Maint_n_n

(branch, optional) If you need to create a release version of a minor modification (for example, post 1.2.1 after 1.2). Then you can create a branch to achieve the goal.

Only the release marks are required, others are marked for the convenience of recommending you to use.

Here is an example of how to add markup for the release version of the "Money_fast" package 1.2:

$ CD Pear/money_fast
$ CVS Tag release_1_2
T fast.php
T README
T package.xml

With the above, you can get a series of release versions of your version on the PEAR Web site.

Here is an example of how to build a QA branch:

$ CVS Tag qa_2_0_bp
...
$ CVS Rtag-b-R qa_2_0_bp qa_2_0
$ CVS Update-r qa_2_0
$ CVS Tag Release_2_0rc1
... and then the actual release, from the same branch:
$ CVS Tag Release_2_0

The "QA_2_0_BP" tag is a "branch point" tag that marks the beginning of a branch. It is a good idea to always use such markers to indicate the beginning of a branch. The Maint branch can use the release mark as its branch start.

--------------------------------------------------------------------------------

The URL in the example

The URL addresses used in all the examples should be "example.com", "example.org", "example.net".

--------------------------------------------------------------------------------

Naming conventions

In general, the names of classes, functions, and variables should always be able to describe the role that the code reader can easily know about the code.

Classes

Class should have a descriptive name. You should avoid using abbreviations when possible. Class names should always start with an uppercase letter. The class name can also reflect the level of the PEAR class. Each level in the hierarchy is delimited by an underscore. Examples of good class names are as follows:

Log
Net_finger
Html_upload_error

Functions and methods

Functions and methods should be named using the "studly caps" style. The function should prefix the name of the package in order to avoid naming conflicts with functions of other packages. The name of the letter (after the prefix) should be lowercase, each new word should start with a capital letter. Here are some examples:

Connect ()
GetData ()
Buildsomewidget ()
Xml_rpc_serializedata ()

Private class members and attributes (meaning that class members and attributes should be used only by members declared in the same class.) PHP does not support mandatory private namespaces, however, and should begin with an underscore. Example:

_sort ()
_inittree ()
$this->_status

Constant

Constants should always be named with all uppercase letters, with underscores to separate the words. Prefixes of literal names should use uppercase class/package names. For example: DB:: All constants used by the package have been db_ beginning.

Global variables

If your package needs to define a global variable, you should use an underscore to start with the name of the package and another underline. For example, the PEAR package uses a global variable named $_pear_destructor_object_list.

Predefined values True, FALSE, and NULL

PHP's built-in values true, FALSE, and Null must all be written in lowercase letters.