Coding Standards
Coding standards have been defined to maintain a consistent programming style throughout the core code-base. Developers must follow this guide to make it easier for others to understand and to maintain what has been developed.
File Format
Each file must be saved in Unix format with Unix line-feeds.
Some editors add a line-feed to the bottom of the file after the last closing PHP tag. This is fine to have as long as a further character (including a space) does not get added to prevent "headers have already been sent" error messages when redirects occur.
The filename of the files must all be lowercase characters and contain no more than 31 characters to be Apple/Mac compatible.
Indentation
Indentation should be 2 whitespace characters.
TABs should not be used.
Starting And Ending PHP Logic
When starting PHP logic, the tag should be written as "<?php", not in the short form of "<?" or in ASP compatible tags such as "<%".
The end tag to mark the end of the PHP logic should be written as "?>".
A valid example:
<?php
echo 'Hello World!';
?>
Defining Constants
Constants must be defined before they are being used, which also include constants called from include()'d/require()'d files.
Variable Scope
All variables must be accessed and set within their scope as:
- $_GET['variable']
- $_POST['variable']
- $_COOKIE['variable']
- $_SESSION['variable']
include() vs require()
The use of include() will include the specified file when needed, whereas the use of require() will always include the specified file regardless if it is needed or not.
Example:
<?php
require('file.php');
if (condition) {
include('file.php'); }
?>
Instantiating Classes
When instantiating classes into objects, the following style must be used:
<?php
$osC_ClassName = new osC_ClassName();
?>
Displaying Strings
Strings or values should be displayed as:
<?php
echo 'Hello Mr. Anderson.';
?>
The following styles should be avoided:
<?php
print $variable;
?>
Singe-Quotes vs Double-Quotes
When displaying strings, single quote characters should be used.
Double quote characters should be used only when control characters are needed.
For example:
<?php
echo 'Hello Mr. Anderson.' . "\n";
?>
Custom Functions
All custom functions should start with osc_ so that the developer knows a native PHP function is not being called.
An example custom function style:
<?php
function osc_my_function($parameter, $optional = null) {
...
}
?>
Class Names
There are two types of styles to use when classes are used.
The first type of class set are static classes that can be found in the includes/classes directory.
If the class name contains more than one word the words in the filename are separated with an underscore character. The actual class name is one whole word where each word is capitalized and is prefixed by "osC_".
For example, a class name of osC_MyOwnClass has a filename of my_own_class.php.
The second type of classes are the dynamic modules that can be found in the includes/modules/* directories. These classes are also prefixed by the type of module and directory it is located in.
For example, a payment module that resides in includes/modules/payment with the class name of osC_Payment_my_payment_module has a filename of my_payment_module.php.
Class Structure
The class should be written in the following structure:
<?php
class osC_MyClass {
var $variable;
var $_priv_variable;
function osC_MyClass() {
...
}
function doSomething() {
$this->variable = 'set';
}
function getVariable() {
return $this->variable;
}
function _aPrivateMethod() {
...
}
}
$osC_MyClass = new osC_MyClass();
$osC_MyClass->doSomething();
echo $osC_MyClass->getVariable();
?>
Each public variable defined should have its own get() and set() class methods which are used outside the scope of the class. Class variables should only be accessed directly within the class itself.
Database Queries
Database queries are performed through the osC_Database class and $osC_Database object and uses a binding method to securely attach values to keywords.
An example of a single result set query is as follows:
<?php
$Qresult = $osC_Database->query('select configuration_value from :table_configuration where configuration_key = :configuration_key');
$Qresult->bindTable(':table_configuration', TABLE_CONFIGURATION);
$Qresult->bindValue(':configuration_key', 'key_value');
$Qresult->execute();
echo $Qresult->value('configuration_value');
?>
An example of a multiple result set query is as follows:
<?php
$Qresult = $osC_Database->query('select configuration_value from :table_configuration');
$Qresult->bindTable(':table_configuration', TABLE_CONFIGURATION);
$Qresult->execute();
while ($Qresult->next()) {
echo $Qresult->value('configuration_value');
}
?>
The following is used to return the number of rows:
<?php
echo $Qresult->numberOfRows();
?>
Table names should not be directly entered in the query, instead the constant definition assigned to that table should be used. A list of defined constant table names can be found in includes/database_tables.php.
Function Output
All custom functions should return strings; not directly via echo().
For example:
<?php
function osc_my_function($string) {
return $string;
}
?>
and not:
<?php
function osc_my_function($string) {
echo $string;
}
?>
Condition Statements
"if" statements should be written as:
<?php
if (condition) {
...
} elseif (condition) {
...
} else {
...
}
?>
If the condition is to check a variable for a boolean value the variable type should also be verified:
<?php
if ($variable === true) {
...
}
?>
To see if a variable exists use the following structure:
<?php
if (isset($variable)) {
...
}
?>
and not:
<?php
if ($variable) {
...
}
?>
Multiple conditions should reside in their own parenthesis:
<?php
if ( (condition) && (condition) ) {
...
}
?>
Functions do not need to be checked with a true/false statement:
<?php
if (empty($variable)) {
...
}
if ( isset($variable) && ($variable === true) ) {
...
}
?>
Switch-Case statements should be written as:
<?php
switch ($variable) {
case '1':
...
break;
case '2':
...
break;
default:
...
break;
}
?>
Repetitive Statements
"while" loops should be written as:
<?php
while (condition) {
...
}
?>
Walking through an array should be written as:
<?php
foreach ($array as $key => $value) {
...
}
?>
"for" loops should be written as:
<?php
for ($i=0, $n=sizeof($array); $i<$n; $i++) {
...
}
?>
Mixing HTML And PHP
Common HTML tags started in HTML must end in HTML and tags started in PHP must end in PHP.
Wrong:
<td><?php echo "Hello</td>"; ?>
Correct:
<td><?php echo "Hello"; ?></td>
Correct:
<?php
echo '<td>Hello</td>';
?>
