PHP coding style guide


The PHP coding style guide at Outlast is based on the existing coding style implemented within the Outlast Framework. All developers must follow this when developing in PHP at Outlast. Some of the text below is used from CodeIgniter’s style guide but updated as needed.

File formats, encoding, line endings

All files must use the .php extension.

Files should be saved with Unicode UTF-8 encoding. The BOM should not be used. Unlike UTF-16 and UTF-32, there’s no byte order to indicate in a UTF-8 encoded file, and the BOM can have a negative side effect in PHP of sending output, preventing the application from being able to set its own headers.

Unix line endings should be used (LF). Be careful, Windows users usually need to set this up in their editor manually!

PHP tags

The full PHP opening tag <?php should be used in all files.

Closing tags should not be used at the end of PHP files because they can cause errors if accidental spaces are added after the closing tag. This includes most PHP files in OFW – typically they are only PHP with no HTML output mixed in, so there will be no closing tag.

Here is a proper example:

INCORRECT:
<?php

echo "Here's my code!";

?>

CORRECT:
<?php

echo "Here's my code!";

/* End of file myfile.php, no closing tag. */

Class and method naming

Classes should be CamelCase with no underscores. Model classes should be defined as singular nouns, such as User instead of Users.

INCORRECT:
class My_class
class myclass

CORRECT:
class MyClass

Method names should be_lowercase_and_use_underscores. They should also always include public or private.

INCORRECT:
function fileproperties()		// not descriptive and needs underscore separator and private/public
public function fileProperties()		// not descriptive and uses CamelCase
public function getfileproperties()		// Better!  But still missing underscore separator
private function getFileProperties()		// wrong, uses CamelCase
public function get_the_file_properties_from_the_file()	// too wordy

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

Static and magic methods

Static methods are used in OFW to create and fetch objects. They should be styled exactly as any other method with underscores and lowercase:

CORRECT:
public static function fetch_by_user()

Magic methods are used in OFW as triggers when certain actions occur. A common example is __afterFetch() in models where caching of certain data can occur. It is important that unlike other methods, magic methods use __lowerCamelCase() and are always preceded by two underscores.

INCORRECT:
public function __AfterFetch()    // Wrong! Capitalized first letter.
public function __after_fetch()   // Wrong! Not CamelCase.
public function afterFetch()      // Wrong! No underscore preceding.
public function _afterFetch()     // Wrong! Only a single underscore preceding.

CORRECT:
public function __beforeSave()      // Correct!

Variable and method properties

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

Method properties should use the same logic and should always be declared!

class RandomExample{
  public $example_property = true;

  public function random_method(){
    // Below is WRONG! It is a non-declared property.
      $this->some_other_property = false;
    // Below is CORRECT! It is using the declared property from above.
      $this->example_property = false;
  }
}

Constants

Constants follow the same guidelines as do variables, except constants should always be fully uppercase and need to be declared at the top of each PHP file.

declare('EXAMPLE_CONSTANT', 25);  // CORRECT!

Comments and documentation

In-code documentation and lengthy commenting is an essential part of coding style at Outlast. You MUST use comments and you MUST use it more often than you think you should. 🙂

Here’s a correct example:

function add_numbers($number1, $number2 = false){
  // Number2 defaults to the same value as number1 if it is false
    if($number2 === false) $number2 = $number1;
  // Now add and return
    return $number1 + $number2;
}

You don’t have to comment on every line, but you do have to comment each code block (every few lines). Even obvious code segments should be commented. Why? Because it makes code review and code debug much easier by others (and by yourself if you come back to the code in a few months).

Another important facet is to always use DOCBLOCK comments for each class, method, and variable. This helps software such as PHPStorm autocomplete and suggest code properly. It also helps us standardize and generate documentation.

Here’s a correct example of using DOCBLOCK:

/**
 * Returns an error message and exists. Useful for fatal errors.
 * @param string $message The error message to display and/or log.
 * @return bool Does not return anything.
 * @link http://www.externallink.com/only/if/needed/
 **/
public function error($message){
	// Manually load error reporting lib
		/* @var zajlib_error $error */
		$error = $this->load->library('error');
	// Now report the error and send 500 error
		if(!$this->output_started) header('HTTP/1.1 500 Internal Server Error');
		$error->error($message);
		exit;
}

Notice that each @param is documented as is the @return value. Also, notice how @var is used within the code to tell the compiler what return value it should expect from the method. Unlike the method DOCBLOCK, this is not required but it is quite helpful for autocomplete and code validation.

Finally, notice how every few lines are commented (and the code is indented – more about that later). Such commenting is required, even if the code segment logic is obvious to you as you are writing it.

Helpful tip For reusable models (such as those used in plugins or the OFW system) you should create a separate doc.php file to document the various fields available in that model. See OFW’s /system/doc/doc.php as an example.

Helpful tip For a full list of DOCBLOCK tags, see the documentation.

Booleans and null

Always use the lower case version.

INCORRECT:
$variable = TRUE;
CORRECT:
$variable = false;

Logical Operators

Always use the symbol version.

INCORRECT:
if($var1 == 1 AND $var2 == 2) echo "woo!";
CORRECT:
if($var1 == 1 && $var2 == 2) echo "woo!";

Always use the strict type comparison (===, !==, etc.) where possible.

INCORRECT:
if(strpos($str, 'foo') == false)
CORRECT:
if(strpos($str, 'foo') === false)

Error handling

Do not use exceptions within the context of Outlast Framework. Instead use the notice(), warning(), and error() and return its values.

Here’s an example:

function do_something(){
  // ....
  // If I failed
    if($failed) return $this->zajlib->warning("Failed to do something");
}

Warnings will continue execution, errors are fatal and halt execution. Warning and errors are only displayed in debug mode. If you want to display the error in live mode as well (which is usually not recommended) then you can use set the second parameter to true:

return $this->zajlib->error("Fatally failed to do something", true);

Brackets and code blocks

Short code blocks can be placed on a single line:

if($is_true) echo "It's true!";

Longer lines or multi-line code blocks require brackets and else blocks are on separate lines:

if($is_true){
  echo "Indeed, I must say that this is rather true";
}
else{
  echo "Nope, it is not true.";
}

There is no space before opening brackets.

Indentation and whitespace

Do not place any whitespace before the opening php tag and just skip using the closing tag (see above). Whitespace before the <?php tag will cause errors!

For indentation, set your IDE to use tabs instead of spaces. If you must use spaces, you should set it to 4 spaces.

Although not always the case in OFW core code currently, indentation should generally follow the Stroustrup variant of K&R style but with some modifications.

Here are some proper examples:

public function redirect($url, $frame_breakout = false){  // Opening bracket on same line, no preceding space
	// Comments are on the first level of indentation, code is indented further
		if(!$this->url->valid($url)) $url = $this->baseurl.$url; // If statements can be on the same line if simple, single line logic
	// If test is running, return url
		if($this->test->is_running()) return $url;
	// Frame breakout or standard?
		if($frame_breakout){
			// You can also have multi-line if statements, with brackets. Again, bracket on same line, no space.
			exit("<script>window.top.location='".addslashes($url)."';</script>");
		}
		else{  // Else is not nested, bracket is the same as before.
			header("Location: ".$url);
		}
	exit;
}

Spacing is also quite limited:

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

CORRECT:
foreach($query->result() as $row)  // No space after foreach, no space after or before parenthesis

SQL Queries

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

IMPORTANT! Always use the dbo library and properly escape all variables.

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

Strings and concatenation

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->var"				// needs braces
'SELECT foo FROM bar WHERE baz = \'bag\''	// ugly

CORRECT:
'My String'
"My String $var"     // correct with or without braces
"My String {$var}"
"My string {$foo->var}"
"SELECT foo FROM bar WHERE baz = 'bag'"

When concatenating, do not use spaces between dots:

INCORRECT:
$string = 'Lorem ipsum, ' . $var . ' More...';

CORRECT:
$string = 'Lorem ipsum, '.$var.' More...';

Version control

All code must use version control (Git). Never leave old code segments in /** comments **/ – instead commit often and rely on Git to have quick access to all previous versions of your code.

For more on version control see the Outlast Git and deployment workflow.

Autoformatting

Autoformatting is not recommended because it can change lots of rows all at once (which causes confusion during code review) and can sometimes mess things up. Instead, programmers should manually follow all rules in this document.

Outlast Web & Mobile Development (c) 2018 | Privacy Policy |