Menu ▾ ▴

Coding Guidelines

Sean Callaway

PEBDesk PHP Coding Guidelines

This document is still under construction and is, by no means, complete.

Files and Folders

Folder Structure and Organization

From the root of the project, the following folders will exist:

  • "includes" - for PHP include files
  • "script" - for JavaScript files
  • "sql" - for SQL files
  • "style" - for CSS
  • "templates" - for PHP template files

File Naming

File Extensions

All PHP pages will have the ".php" extension. All PHP include files will have the ".inc.php" extension. All PHP template files will have the ".tpl.php" extension.

All SQL files will have the ".sql" extension.

All CSS files will have the ."css" extension.

All JavaScript files will have the ".js" extension.

PHP Coding Style

PHP Closing Tag

In files that are pure PHP, the closing tag on a PHP document will be commented out.

INCORRECT:
~~~~

**CORRECT:**

## Class and Method Naming

Class names will be CamelCased.

All other class methods should be entirely lowercased and named to clearly indicate their function, preferably including a verb. Multiple words should be separated with an underscore, and not CamelCased. Try to avoid overly long and verbose names.

**INCORRECT:**

class myclass
class my_class

**CORRECT:**

class MyClass

**INCORRECT:**

function fileproperties() // not descriptive and needs underscore separator
function fileProperties() // not descriptive and uses CamelCase
function getfileproperties() // Better! But still missing underscore separator
function getFileProperties() // uses CamelCase
function get_the_file_properties_from_the_file() // wordy

**CORRECT:**

function get_file_properties() // descriptive, underscore separator, and all lowercase letters

## Variable Names

The guidelines for variable naming is very similar to that used for class methods. Namely, variables should contain only lowercase letters, use underscore separators, and be reasonably named to indicate their purpose and contents. Very short, non-word variables should only be used as iterators in for() loops.

**INCORRECT:**

$j = 'foo'; // single letter variables should only be used in for() loops
$Str // contains uppercase letters
$bufferedText // uses CamelCasing, and could be shortened without losing semantic meaning
$groupid // multiple words, needs underscore separator
$name_of_last_city_used // too long

**CORRECT:**

for ($j = 0; $j < 10; $j++)
$str
$buffer
$group_id
$last_city

## Commenting

In general, code should be commented prolifically. It not only helps describe the flow and intent of the code for less experienced programmers, but can prove invaluable when returning to your own code months down the line. There is not a required format for comments, but the following are recommended.

[DocBlock](http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#basics.docblock) style comments preceding class and method declarations so they can be picked up by IDEs:

/**

/**

  • Encodes string for use in XML
    *
  • @access public
  • @param string
  • @return string
    */
    function xml_encode($str)
    {
Use single line comments within code, leaving a blank line between large comment blocks and code.

// break up the string by newlines
$parts = explode("\n", $str);

// A longer comment that needs to give greater detail on what is
// occurring and why can use multiple single-line comments. Try to
// keep the width reasonable, around 70 characters is the easiest to
// read. Don't hesitate to link to permanent external resources
// that may provide greater detail:
//
// http://example.com/information_about_something/in_particular/
$parts = $this->foo($parts);

## Constants

Constants follow the same guidelines as do variables, except constants should always be fully uppercase. This includes built-in constants, like TRUE, FALSE, and NULL.

## Logical Operators

A space should always precede and follow **!**.

## Whitespace in Files

No whitespace can precede the opening PHP tag or follow the closing PHP tag (which should be commented out anyway).

Use tabs for whitespace in your code, not spaces. This may seem like a small thing, but using tabs instead of whitespace allows the developer looking at your code to have indentation at levels that they prefer and customize in whatever application they use.

## Code Indenting

Use Allman-style indenting. Braces are always placed on a line by themselves and indented at the same level of the control statement that "owns" them.

**INCORRECT:**

function foo($bar) {
// ...
}

foreach ($arr as $key => $val) {
// ...
}

if ($foo == $bar) {
// ...
} else {
// ...
}

for ($i = 0; $i < 10; $i++)
{
for ($j = 0; $j < 10; $j++)
{
// ...
}
}

**CORRECT:**

function foo($bar)
{
// ...
}

foreach ($arr as $key => $val)
{
// ...
}

if ($foo == $bar)
{
// ...
}
else
{
// ...
}

for ($i = 0; $i < 10; $i++)
{
for ($j = 0; $j < 10; $j++)
{
// ...
}
}

## Bracket and Parenthetic Spacing

In general, parenthesis and brackets should not use any additional spaces. The exception is that a space should always follow PHP control structures that accept arguments with parenthesis (declare, do-while, elseif, for, foreach, if, switch, while), to help distinguish them from functions and increase readability.

**INCORRECT:**

$arr[ $foo ] = 'foo';

**CORRECT:**

$arr[$foo] = 'foo'; // no spaces around array keys

**INCORRECT:**

function foo ( $bar )
{
//...
}

**CORRECT:**

function foo($bar) // no spaces around parenthesis in function declarations
{

}

**INCORRECT:**

foreach( $query->result() as $row )

**CORRECT:**

foreach ($query->result() as $row) // single space following PHP control structures, but not in interior parenthesis

## One Class Per File

Use separate files for each class, unless the classes are closely related. For example, the Database class and the DBCache class might exist in the same file.

## Private Methods and Variables

Methods and variables that are only accessed internally by your class, such as utility and helper functions that your public methods use for code abstraction, should be prefixed with an underscore.

## Short Open Tags

Always use full PHP opening tags, in case a server does not have short_open_tag enabled.

## Strings

Always use single quoted strings unless you need variables parsed, and in cases where you do need variables parsed, use braces to prevent greedy token parsing. You may also use double-quoted strings if the string contains single quotes, so you do not have to use escape characters.

**INCORRECT:**

"My String" // no variable parsing, so no use for double quotes
"My string $foo" // needs braces
'SELECT foo FROM bar WHERE baz = \'bag\'' // ugly

**CORRECT:**

'My String'
"My string {$foo}"
"SELECT foo FROM bar WHERE baz = 'bag'"
~~~~~~

SQL Queries

MySQL keywords are always capitalized: SELECT, INSERT, UPDATE, WHERE, AS, JOIN, ON, IN, etc.

Break up long queries into multiple lines for legibility, preferably breaking for each clause.

MongoDB Logo MongoDB