Wiki Navigation

Back to DeveloperDocs

PHP Coding Standards for Campware Products

Please use the following conventions when writing code for Campware products.

GENERAL FORMATTING

1. Use a tab of four (4) characters, and set your editor to insert spaces instead of tabs.

REASON: This will align the code correctly when you email around code snippets, or otherwise export the code.

2. Use full "<?php" tags.

REASON: The php.ini file may not have short_tags turned on.

3. Try to limit the number of characters per line between 80-100 characters.

4. There should be only one statement per line. Once you type the ending semi-colon, go to the next line. For example:

WRONG:

$x = 0; $y = 0;

RIGHT:

$x = 0;
$y = 0;

INCLUDE / REQUIRE STATEMENTS

1. Use parenthesis around the file names.

WRONG:

require"foo.php";

RIGHT:

require("foo.php");

ALL FUNCTION DEFINITIONS

1. Function braces appear on a line of their own. Example:

function fooFunction($p_arg1, $p_arg2 = '')
{
    if (condition) {
        statement;
    }
    return $val;
}

2. 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.

3. Functions that return boolean values should work well (grammatically) in an IF statement.

Bad:

function FigureOutIfValid() { }

Good:

function IsValid() { }

STATIC FUNCTION DEFINITIONS

Static (global) function names should have the prefix "camp_".

REASON: You will be able to tell the difference between built-in functions and campware functions. Example:

camp_run();

Static function names should use lower case letters and separate words

with an underscore.

REASON: This is how built-in static function calls in PHP are written.

Example:

camp_array_get_value();

STATIC FUNCTION CALLS

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:

$var = camp_foo($bar, $baz, $quux);

VARIABLES

Prefixes for variable names:

Global: "g_"
Parameter: "p_"
Member variable: "m_"
Form variable: "f_"

REASON: So you can easily tell where a variable is from.

Example:

global $g_config;
class Input {
    var $m_count;

    function process($p_request) {
        $tmp = $p_request["f_name"];
        if (!empty($tmp)) {
            $this->m_count++;
        }
    } // fn process

} // class Input

CLASSES

Capitalize the name of each word in a class name. Example:

class MyClassName { }

The file name should match the class name with ".php" at the end.

There should be one class per file, unless there are performance

considerations to take into account.

Example:

MyClassName.php

Use single quotes(') in classes for strings.

MEMBER FUNCTIONS

Member functions names begin with a lowercase letter and otherwise

follow the same conventions as class names.

STATIC MEMBER FUNCTIONS

Static member function names start with an uppercase character and begin

each word with a capital letter, just like class names. This only

applies to functions that are exclusively static, and not functions that

can also be called as member functions.

COMMENTS

1. Don't use "#" for comments.

REASON: Consistent look for comments, and rumors of deprecating "#".

2. Use PHPDocumentor (http://www.phpdoc.org/) conventions to comment the code.

REASON: It's the most advanced PHP documentation system that exists.

PHPDoc is way behind (uses 'grep' to parse instead of a parsing engine),

and Doxygen does not fully support PHP.

3. Only ONE space between the star ("*") and the beginning of the comment.

WRONG:

/**
 *  Class Foo
 */

RIGHT:

/**
 * Class Foo
 */

4. Put parameter descriptions one line below the parameter type description, indented by two tabs, which is 6 spaces away from the star ("*") character.

WRONG:

/**
 * @param string $p_name - The name of the file.
 */

RIGHT:

/**
 * @param string $p_name
 *      The name of the file.
 */

5. How to indicate optional parameters: you dont have to because PHPDocumentor does it for you by looking for an assignment in the parameter list.

6. How to indicate that a parameter or return value can be more than one type: use a vertical bar ("|") to separate the types. This is how PEAR documentation works.

EXAMPLE:

/**
 * @return boolean|PEAR_Error
 */

7. File headers. Each file of significance should specify the @package, @subpackage, @version, @license, @copyright, and @author tags. If you modify a file and you name is not in the author list, add it to the top of the file.

Example:

/**
 * @package Campsite
 * @subpackage Subscriptions
 * @author Paul Baranowski <paul@paulbaranowski.org>
 * @author Mugur Rus <mugur1973@yahoo.com>
 * @copyright 2006 MDLF, Inc.
 * @license http://www.gnu.org/licenses/gpl.txt
 * @version $Revision$
 * @link http://www.campware.org
 */

Example using all the comment rules:

/**
 * This function adds two numbers together.
 *
 * Long Description Goes here...take the variable $p_value,
 * and apply the addition operator ('+'), thereby increasing
 * the original value by the amount given in the parameter
 * $p_byHowMuch, which defaults to one (1).  This is also known as
 * 'incrementing' a variable.  As an example, you could use this
 * operation in a loop when you know how many times you have
 * to iterate.
 *
 * @param int $p_value
 *      The value to increment.
 * @param int $p_byHowMuch
 *      How much to increment the value.  Default is one (1).
 * @return int
 *      The given value increased by the increment amount.
 */
function increment($p_value, $p_byHowMuch = 1) {
    return $p_value+$p_byHowMuch;
} // fn increment

See the manual here: http://manual.phpdoc.org/HTMLframesConverter/DOM/default/

ASSIGNMENT

1. Use spaces around assignments and between operators:

$a = 5;
$b = $a + 4;

REASON: Easy to read.

2. Do NOT line up the right side of assignment statements.

WRONG:

$a                        = 0;
$myReallyLongVariableName = 1;
$foo                      = abracadabra();
$bar                      = $a;

RIGHT:

$a = 0;
$myReallyLongVariableName = 1;
$foo = abracadabra();
$bar = $a;

Reason: Maintenance. If you line them up, then you have to adjust every single line around the line you are editing if you suddenly add in a long variable name.

SQL

In SQL statements, capitalize keywords.

REASON: easy distinction between keywords and non-keywords.

CONTROL STRUCTURES (IF, WHILE, DO, SWITCH, FOR, FOREACH) - GENERAL RULES

1. Always use braces, even for single statements.

REASON: prevent bugs during maintenance, readability.

Example:

  if ($x == 0) {
      $x++;
  }

2. Always parenthesis boolean expressions.

Example:

  if ( ($x == 0) || ($y == 0)) { }

3. Control statements should have one space between the control keyword

and opening parenthesis, to distinguish them from function calls.

Example:

  if (true)

4. Always explicitly state what you are checking for in a boolean expression.

REASON: This helps others to know what you are checking for.

Example:

  Instead of:
    if ($x) { }
  do:
    if (!empty($x)) { }
  or:
    if ($x == 0) { }

5. Use space characters to separate tokens as in the following examples.

IF

1. For IF statement conditions that span multiple lines, put the operator at the beginning of the next line.

WRONG:

if ($this->isWidget() &&
    $this->isLocked()) {
    ... do something ...
}

RIGHT:

if ($this->isWidget()
    && $this->isLocked()) {
    ... do something ...
}

Some examples of IF statments:

  if ( ($x == 0) || ($y == 0) ) {
      $x = 1;
  } else {
      $x = 2;
  }

  $a = $b ? $c : $d;

SWITCH

  switch ($foo) {
      case "hello":
          $x = $x + 1;
          break;
      case "world":
          $x = $x - 1;
          break;
  }

FOR

  for ($i = 0; $i < 10; $i++) {
      echo $i;
  }

SEMANTICS

SQL

If you are using SQL strings, put the string into a variable before you call the database query function. This makes it easier to debug SQL statements when you are using a debugger. Example:

$sql = "SELECT * FROM foo";
$dbConnection->GetAll($sql);

Incorrect:

$dbConnection->GetAll("SELECT * FROM foo");

Download in other formats:

Plain Text