Last modified on 19 April 2014, at 10:54

PHP Programming/Coding Standards

Indenting and Line LengthEdit

Use an indent of one tab (no spaces! good IDEs can convert this to pseudo spaces - 2 or 4 etc). If you use Emacs to edit your code, you should set indent-tabs-mode to nil. It is recommended that you break lines at approximately 75-85 characters. There is no standard rule for the best way to break a line; use your judgement. This applies to all file types: PHP, HTML, CSS, Javascript, etc.

Indentation rules should be applied in the source file that will be edited by others. The visual appeal of HTML output should not be taken into consideration when writing code that generates HTML.

HTML StandardsEdit

ValidationEdit

As of September 2006, the DocType on our documents will be XHTML 1.0 Transitional. Therefore, compliant HTML according to the XHTML 1.0 standard should be used at all times. Exceptions should be just that. A good reference for the XHTML elements can be found at DevGuru.

Also, to ensure that the box model is done correctly by IE 6, we must use the following DocType on all pages. Only this doc type is to be used. No other information should be placed before it.

Example DocType
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


Element UsageEdit

When at all possible, try and use standard HTML elements properly. "Div Soup" should be avoided at all times. "Div Soup" refers to HTML where a div (or span) is used when it is not needed. For example, if you need a word to be bolded, do not use a <span> tag and apply a style. Instead, use the <strong> tag.

Tables should be used only when data needs to be displayed in columns. One cell tables should never be used.

One common exception is needing to use <div> tags in place of <p> tags when the contents of the tag will be other block level elements such as <ul>.

Example HTML
<div class="article">
    <h4>this is the headline</h4>
    <p>This is the body with an <strong>important word</strong>.</p>
    <small>Posted 2 days ago</small>
</div>


CSS StandardsEdit

Inline styles should be avoided

Styles in CSS files should be as specific as possible. One should always try to avoid using a bare class name. If you are styling an object that has a container, your style should reference the continer as well as the element being styled. The more verbose your styles in your CSS the less likely you will mess up another element on another page accidentally.

The most efficient way to style an element is by styling that type of element inside a container. If only one element needs to be styled in a special way, it should be assigned and id and styled using the id and preferably a container.


Here is some HTML from our sidebar:

Example Article HTML
<div id="sidebar">

    <ul class="blue" id="categories">
        <label><a href="/categories/">Categories</a></label>
        <li class="current"><a href="/categories/Computer/39.html">Computer</a></li>
        <li><a href="/categories/Electronics/142.html">Electronics</a></li>
        <li><a href="/categories/Gaming-Toys/186.html">Gaming & Toys</a></li>
        <li><a href="/categories/Office-Supplies/182.html">Office & Supplies</a></li>
        <li><a href="/categories/DVDs-Music-Books/178.html">DVDs, Music, Books</a></li>
        <li><a href="/categories/Clothing-Accessories/202.html">Clothing & Accessories</a></li>
        <li><a href="/categories/Home-Garden/196.html">Home & Garden</a></li>
        <li><a href="/categories/Everything-Else/231.html">Everything Else</a></li>
        <li><a href="/categories/Store-Events/40.html">Store Events</a></li>
        <li><a href="http://dealnews.com/coupons/">Coupons</a></li>
        <li><a href="http://dealnews.com/deals/The-new-dealnews-Gift-Finder-sort-by-price-/101164.html">Gift Ideas</a></li>
    </ul>

    <ul class="gray">
        <label>Stores</label>
        <li><a href="/online-stores/Amazon-com/313/">Amazon.com</a></li>
        <li><a href="/online-stores/Buy-com/233/">Buy.com</a></li>
        <li><a href="/online-stores/Circuit-City-com/296/">CircuitCity.com</a></li>
        <li><a href="/online-stores/Dell-Home/638/">Dell Home</a></li>
        <li><a href="/online-stores/Best-Buy-com/560/">BestBuy.com</a></li>
        <li><a href="/online-stores/Comp-USA-com/595/">CompUSA.com</a></li>
        <li><a href="/online-stores/Dell-Small-Business/604/">Dell Small Business</a></li>
        <li><a href="/online-stores/Newegg-com/504/">Newegg.com</a></li>
        <li><a href="/online-stores/Meritline/303/">Meritline</a></li>
    </ul>

</div>


And here is a small bit of how we style those elements.

Example CSS
#sidebar ul {
    list-style: none;
    margin: 0 0 15px 0;
    padding: 0 0 4px 0;
}
 
#sidebar ul label {
    color: White;
    display: block;
    font-weight: bold;
    font-size: 100%;
    margin: 0 0 4px 0;
    padding: 6px 8px 4px 10px;
}
 
#sidebar ul label a, #sidebar ul label a:visited {
    color: White;
    text-decoration: none;
    display: block;
}
 
#sidebar ul li {
    font-size: 95%;
    margin: 0 0 4px 0;
    padding: 2px 8px 2px 12px;
}
 
#sidebar ul li a {
    display: block;
    color: Black;
    text-decoration: none;
}
 
#sidebar ul.gray {
    background: #DDDDE2 url('http://images.dealnews.com/dealnews/backgrounds/sidebar/footer_light_gray.png') no-repeat 0 100%;
}
 
#sidebar ul.gray label {
    color: White;
    background: #75758A url('http://images.dealnews.com/dealnews/backgrounds/sidebar/header_dark_gray.png') no-repeat 0 0;
}
 
#sidebar ul.blue {
    background: #EBEBFA url('http://images.dealnews.com/dealnews/backgrounds/sidebar/footer_light_blue.png') no-repeat 0 100%;
}
 
#sidebar ul.blue label {
    color: White;
    background: #2E2E6B url('http://images.dealnews.com/dealnews/backgrounds/sidebar/header_dark_blue.png') no-repeat 0 0;
}
 
#sidebar #categories li.current {
    color: #FF9A00;
    font-weight: bold;
}


This verbosity ensures that other elements are not accidentially styled.

Javascript SyntaxEdit

See PHP Syntax Below. The languages are similar enough that the same rules should apply in most cases.

PHP SyntaxEdit

Request VarsEdit

Although our servers currently have register_globals enabled, PHP6 will remove this option. Therefore, in new code, you should always use the super globals $_GET, $_POST, and $_COOKIE. $_REQUEST should be used only when it is known for sure that a variable could be supplied using multiple methods.

PHP & HTMLEdit

No "template system" such as Smarty will be used. PHP itself is a templating language. A best effort should be made to arrange your code by putting logic at the top of file and output at the bottom of the file. Sometimes that will require looping the same information twice. However, this will make the code much more maintainable.

Example PHP/HTML Mix
<?php

$sql = "select * from publications";
$PHEWSDB->query($sql);
while($rec = $PHEWSDB->fetch_array()){
    $publications[] = $rec;
}

?>

<ul>
    <label>Publications</label>
    <?php foreach($publications as $pub) { ?>
        <li><?=$pub["name"]?></li>
    <?php } ?>
</ul>


Control StructuresEdit

These include if, for, while, switch, etc.

Example if statement
if (condition1 || condition2) {
    action1;
} elseif (condition3 && (condition4 || condition5)) {
    action2;
} else {
    defaultaction;
}


Control statements should have one space between the control keyword and opening parenthesis, to distinguish them from function calls.

You are strongly encouraged to always use curly braces even in situations where they are technically optional. Having them increases readability and decreases the likelihood of logic errors being introduced when new lines are added.

Example switch statement
switch (condition) {
    case 1:
        action1;
        break;
    case 2:
        action2;
        break;
    
    default:
        defaultaction;
        break;
}


Function CallsEdit

Functions should be called with no spaces between the function name, the opening parenthesis, and the first parameter; spaces between commas and each parameter, and no space between the last parameter, the closing parenthesis, and the semicolon.

Example function call
$var = foo($bar, $baz, $quux);


As displayed above, there should be one space on either side of an equals sign used to assign the return value of a function to a variable. In the case of a block of related assignments, more space may be inserted to promote readability:

$short         = foo($bar);
$long_variable = foo($baz);


Function DefinitionsEdit

Function declarations are similar to function calls with the beginning brace on the same line as the function declaration.

Example function definition
function foo_func($arg1, $arg2 = '') {
    if (condition) {
        statement;
    }
    return $val;
}


Arguments with default values go at the end of the argument list. Always attempt to return a meaningful value from a function if one is appropriate.

Longer function example
function connect(&$dsn, $persistent = false) {
    if (is_array($dsn)) {
        $dsninfo = &$dsn;
    } else {
        $dsninfo = DB::parseDSN($dsn);
    }

    if (!$dsninfo || !$dsninfo['phptype']) {
        return $this->raiseError();
    }

    return true;
}


CommentsEdit

Complete inline documentation comment blocks (docblocks) must be provided. Please read the Sample File and Header Comment Blocks sections to learn the specifics of writing docblocks for PHP. Further information can be found on the phpDocumentor website.

Non-documentation comments are strongly encouraged. A general rule of thumb is that if you look at a section of code and think "Wow, I don't want to try and describe that", you need to comment it before you forget how it works.

C style comments (/* */) and standard C++ comments (//) are both fine. The use of Perl / shell style comments (#) is strongly discouraged.


Including CodeEdit

Anywhere you are unconditionally including a class file, use require_once. Anywhere you are conditionally including a class file, use include_once. Either of these will ensure that class files are included only once. They share the same file list, so you don't need to worry about mixing them - a file included with require_once will not be included again by include_once.

[[#ref_include_once and require_once are statements, not functions. Parentheses should not surround the subject filename.|^]]

PHP Code TagsEdit

Always use <?php ?> to delimit PHP code, not the <? ?> shorthand. This is the most portable way to include PHP code on different operating systems and server setups.


Header Comment BlocksEdit

All source code files shall contain a "page-level" docblock at the top of each file and a "class-level" docblock immediately above each class or function.

Example docblocks
<?php

/**
 * Short description for file
 *
 * Long description for file (if any)...
 *
 * @category   CategoryName
 * @package    PackageName
 * @author     Original Author <author@example.com>
 * @author     Another Author <another@example.com>
 * @copyright  1997-2005 The PHP Group
 * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
 * @version    CVS: $Id:$
 * @link       http://pear.php.net/package/PackageName
 * @see        NetOther, Net_Sample::Net_Sample()
 * @since      File available since Release 1.2.0
 * @deprecated File deprecated in Release 2.0.0
 */

/*
 * Place includes, constant defines and $_GLOBAL settings here.
 * Make sure they have appropriate docblocks to avoid phpDocumentor
 * construing they are documented by the page-level docblock.
 */

/**
 * Short description for class
 *
 * Long description for class (if any)...
 *
 * @category   CategoryName
 * @package    PackageName
 * @author     Original Author <author@example.com>
 * @author     Another Author <another@example.com>
 * @copyright  1997-2005 The PHP Group
 * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
 * @version    Release: @package_version@
 * @link       http://pear.php.net/package/PackageName
 * @see        NetOther, Net_Sample::Net_Sample()
 * @since      Class available since Release 1.2.0
 * @deprecated Class deprecated in Release 2.0.0
 */
class foo
{
}

?>


Required Tags That Have Variable ContentEdit

Short DescriptionsEdit

Short descriptions must be provided for all docblocks. They should be a quick sentence, not the name of the item. Please read the Coding Standard's Sample File about how to write good descriptions.

@authorEdit

There's no hard rule to determine when a new code contributor should be added to the list of authors for a given source file. In general, their changes should fall into the "substantial" category (meaning somewhere around 10% to 20% of code changes). Exceptions could be made for rewriting functions or contributing new logic.

Simple code reorganization or bug fixes would not justify the addition of a new individual to the list of authors.

@sinceEdit

This tag is required when a file or class is added after the package's initial release. Do not use it in an initial release.

@deprecatedEdit

This tag is required when a file or class is no longer used but has been left in place for backwards compatibility.

Order and SpacingEdit

To ease long term readability of the source code, the text and tags must conform to the order and spacing provided in the example above. This standard is adopted from the JavaDoc standard.


Example URLsEdit

Use example.com, example.org and example.net for all example URLs and email addresses, per RFC 2606.


Naming ConventionsEdit

ClassesEdit

Classes should be given descriptive names. Avoid using abbreviations where possible. Class names should always begin with an uppercase letter and use mixed case to seperate words.

Examples of good class names are:

Log
NetFinger
HTMLUploadError

Functions, Methods and Variable NamesEdit

Functions, methods and variable names should be named using the Unix C style. If applicable, functions should have the package or library name as a prefix to avoid name collisions. Names should be all lowercase with each new "word" seperated by an underscore(_). Some Examples:

connect() 
get_data()
build_some_widget()

$i
$count
$temp_array

Private class members (meaning class members that are intended to be used only from within the same class in which they are declared are preceded by a single underscore. For example:

_sort()
_init_tree()
$this->_status

Constants and Global VariablesEdit

Constants and global variables should always be all-uppercase, with underscores to separate words. Prefix constant names with the uppercased name of the class/package they are used in. For example, the constants used by a package named DB begin with DB_.

Note: The true, false and null constants are excepted from the 
all-uppercase rule, and must always be lowercase.

File FormatsEdit

All scripts must:

  • Be stored as ASCII text
  • Use ISO-8859-1 character encoding
  • Be Unix formatted, which means:
    1. Lines must end only with a line feed (LF). Line feeds are represented as ordinal 10, octal 012 and hex 0A. Do not use carriage returns (CR) like Macintosh computers do or the carriage return/line feed combination (CRLF) like Windows computers do.
    2. It is recommended that the last character in the file is a line feed. This means that when the cursor is at the very end of the file, it should be one line below the last line of text. Some utilities, such as diff, will complain if the last character in the file is not a line feed.

Sample FileEdit

Each docblock in the example contains many details about writing Docblock Comments. Following those instructions is important for two reasons. First, when docblocks are easy to read, users and developers can quickly ascertain what your code does.

Please take note of the vertical and horizontal spacing. They are part of the standard.

<?php

/**
 * Short description for file
 *
 * Long description for file (if any)...
 *
 * @category   CategoryName
 * @package    PackageName
 * @author     Original Author <author@example.com>
 * @author     Another Author <another@example.com>
 * @copyright  1997-2005 The PHP Group
 * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
 * @version    CVS: $Id:$
 * @link       http://pear.php.net/package/PackageName
 * @see        NetOther, Net_Sample::Net_Sample()
 * @since      File available since Release 1.2.0
 * @deprecated File deprecated in Release 2.0.0
 */

/**
 * This is a "Docblock Comment," also known as a "docblock."  The class'
 * docblock, below, contains a complete description of how to write these.
 */
require_once 'PEAR.php';

/**
 * Methods return this if they succeed
 */
define('NET_SAMPLE_OK', 1);

/**
 * The number of objects created
 * @global int $GLOBALS['NET_SAMPLE_COUNT']
 */
$GLOBALS['NET_SAMPLE_COUNT'] = 0;

/**
 * An example of how to write code to PEAR's standards
 *
 * Docblock comments start with "/**" at the top.  Notice how the "/"
 * lines up with the normal indenting and the asterisks on subsequent rows
 * are in line with the first asterisk.  The last line of comment text
 * should be immediately followed on the next line by the closing asterisk
 * and slash and then the item you are commenting on should be on the next
 * line below that.  Don't add extra lines.  Please put a blank line
 * between paragraphs as well as between the end of the description and
 * the start of the @tags.  Wrap comments before 80 columns in order to
 * ease readability for a wide variety of users.
 *
 * Docblocks can only be used for programming constructs which allow them
 * (classes, properties, methods, defines, includes, globals).  See the
 * phpDocumentor documentation for more information.
 * http://phpdoc.org/docs/HTMLSmartyConverter/default/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html
 *
 * The Javadoc Style Guide is an excellent resource for figuring out
 * how to say what needs to be said in docblock comments.  Much of what is
 * written here is a summary of what is found there, though there are some
 * cases where what's said here overrides what is said there.
 * http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#styleguide
 *
 * The first line of any docblock is the summary.  Make them one short
 * sentence, without a period at the end.  Summaries for classes, properties
 * and constants should omit the subject and simply state the object,
 * because they are describing things rather than actions or behaviors.
 *
 * Below are the tags commonly used for classes. @category through @access
 * are required.  The remainder should only be used when necessary.
 * Please use them in the order they appear here.  phpDocumentor has
 * several other tags available, feel free to use them.
 *
 * @category   CategoryName
 * @package    PackageName
 * @author     Original Author <author@example.com>
 * @author     Another Author <another@example.com>
 * @copyright  1997-2005 The PHP Group
 * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
 * @version    Release: @package_version@
 * @link       http://pear.php.net/package/PackageName
 * @see        NetOther, Net_Sample::Net_Sample()
 * @since      Class available since Release 1.2.0
 * @deprecated Class deprecated in Release 2.0.0
 */
class Net_Sample
{
    /**
     * The status of foo's universe
     *
     * Potential values are 'good', 'fair', 'poor' and 'unknown'.
     *
     * @var string
     */
    var $foo = 'unknown';

    /**
     * The status of life
     *
     * Note that names of private properties or methods must be
     * preceeded by an underscore.
     *
     * @var bool
     * @access private
     */
    var $_good = true;

    /**
     * Registers the status of foo's universe
     *
     * Summaries for methods should use 3rd person declarative rather
     * than 2nd person imperative, begining with a verb phrase.
     *
     * Summaries should add description beyond the method's name. The
     * best method names are "self-documenting", meaning they tell you
     * basically what the method does.  If the summary merely repeats
     * the method name in sentence form, it is not providing more
     * information.
     *
     * Summary Examples:
     *   + Sets the label              (preferred)
     *   + Set the label               (avoid)
     *   + This method sets the label  (avoid)
     *
     * Below are the tags commonly used for methods.  A @param tag is
     * required for each parameter the method has.  The @return and
     * @access tags are mandatory.  The @throws tag is required if the
     * method uses exceptions.  @static is required if the method can
     * be called statically.  The remainder should only be used when
     * necessary.  Please use them in the order they appear here.
     * phpDocumentor has several other tags available, feel free to use
     * them.
     *
     * The @param tag contains the data type, then the parameter's
     * name, followed by a description.  By convention, the first noun in
     * the description is the data type of the parameter.  Articles like
     * "a", "an", and  "the" can precede the noun.  The descriptions
     * should start with a phrase.  If further description is necessary,
     * follow with sentences.  Having two spaces between the name and the
     * description aids readability.
     *
     * When writing a phrase, do not capitalize and do not end with a
     * period:
     *   + the string to be tested
     *
     * When writing a phrase followed by a sentence, do not capitalize the
     * phrase, but end it with a period to distinguish it from the start
     * of the next sentence:
     *   + the string to be tested. Must use UTF-8 encoding.
     *
     * Return tags should contain the data type then a description of
     * the data returned.  The data type can be any of PHP's data types
     * (int, float, bool, string, array, object, resource, mixed)
     * and should contain the type primarily returned.  For example, if
     * a method returns an object when things work correctly but false
     * when an error happens, say 'object' rather than 'mixed.'  Use
     * 'void' if nothing is returned.
     *
     * Here's an example of how to format examples:
     * <sample>
     * require_once 'Net/Sample.php';
     *
     * $s = new Net_Sample();
     * if (PEAR::isError($s)) {
     *     echo $s->getMessage() . "\n";
     * }
     * </sample>
     *
     * @param string $arg1  the string to quote
     * @param int    $arg2  an integer of how many problems happened.
     *                       Indent to the description's starting point
     *                       for long ones.
     *
     * @return int  the integer of the set mode used. FALSE if foo
     *               foo could not be set.
     * @throws exceptionclass  [description]
     *
     * @access public
     * @static
     * @see Net_Sample::$foo, Net_Other::someMethod()
     * @since Method available since Release 1.2.0
     * @deprecated Method deprecated in Release 2.0.0
     */
    function set_foo($arg1, $arg2 = 0) {
        /*
         * This is a "Block Comment."  The format is the same as
         * Docblock Comments except there is only one asterisk at the
         * top.  phpDocumentor doesn't parse these.
         */
        if ($arg1 == 'good' || $arg1 == 'fair') {
            $this->foo = $arg1;
            return 1;
        } else if ($arg1 == 'poor' && $arg2 > 1) {
            $this->foo = 'poor';
            return 2;
        } else {
            return false;
        }
    }

}

?>