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. Limit the number of characters per line between 80-100 characters.

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

1. 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();

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

Example:

/**
 * This function adds 1 to the given parameter.
 *
 * Long Description Goes here...take the variable p_value,
 * and apply the addition operator ('+'), thereby increasing
 * the original value by 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
 * @return int
 */
function addOne($p_value) {
    return $p_value++;
} // fn addOne

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

ASSIGNMENT

Use spaces around assignments and between operators:

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

REASON: Easy to read.

SQL

In SQL statements, capitalize keywords.

REASON: easy distinction between keywords and non-keywords.

CONTROL STRUCTURES (IF, WHILE, DO, SWITCH, FOR, FOREACH)

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.

Examples:

IF

  if ( ($x == 0) || ($y == 0) ) {
      $x = 1;
  } else {
      $x = 2;
  }
  $a = $b ? $c : $d;

SWITCH

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

FOR

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