Coding Standards and Conventions

We favors conventions over configurations. Follow the conventions and you can create sophisticated applications without writing and managing large and complex configurations.

Content


URL

By default, ApPHP Framework recognizes URLs with the following formats:

Variant 1 (The url GET variable can be retrives in a standard way): 
http://hostname/index.php?url=controller/action&param1=aaa&param2=bbb&param3=ccc
Variant 2: 
http://hostname/page/controller/action?param1=aaa&param2=bbb&param3=ccc
Variant 3: 
http://hostname/page/controller/action/param1/aaa/param2/bbb/param3/ccc
You may also specify a custom format for URL by creating definitions in configuration files. For more details click here.


PHP Code Tags

We always use <?php ?> to delimit PHP code, not the shorthand, <? ?>. This is required because it's the most portable way to include PHP code on differing operating systems, projects and set-ups. There is only one exclusion from this rule, when you may use shorthand tags: is that using of short syntax for output as: <?= $var; ?> instead of <?= $var; ?>

The ?> at the end of code files is purposely omitted. The reasons for this is we want to remove the possibility for unwanted whitespace at the end of files which can cause "header already sent" errors, XHTML/XML validation issues, and other problems.


Indentation and Whitespace

Use an indent of 4 spaces, with no tabs. Lines should have no trailing whitespace at the end.


Operators

All binary operators (the operators that come between two values), such as +, -, =, !=, ==, >, etc. should have a space before and after the operator, for readability. For example, an assignment should be formatted as $aaa = $bbb; rather than $aaa=$bbb;. Unary operators (the operators that operate on only one value), such as ++, should not have a space between the operator and the variable or number they are operating on. For example: $aaa++;


Strings

String
When a string is literal value only (contains no variables), the "single quote" should always be used to demarcate the string: 
$string = 'This a text';
String Containing Apostrophes
When a string itself contains apostrophes or "single quotes", it is permitted to demarcate the string with quotation marks or "double quotes". This is especially useful for SQL statements: 
$sql = "SELECT `id`, `first_name`, `last_name` FRON `users` WHERE email = 'admin@email.me'";
Variable Substitution
Variable substitution is permitted for using in following ways only: 
$welcome = "Hello $firstName $lastName!";
$welcome = "Hello {$firstName} {$lastName}!";
String Concatenation
Strings must be concatenated using the "." operator only. Adding a space before and after the "." is very desirable, but not required: 
$company = 'ApPHP'.' - '.'web solutions';
$company = 'ApPHP' . ' - ' . 'web solutions';
When you concatenate long strings with the "." operator, it is encouraged to break the statement into multiple lines to improve the readability. In these cases operator "." must be is aligned under the "=" operator: 
$sql = "SELECT `id`, `first_name`, `last_name` "
     . "FROM `people` "
     . "WHERE `is_active` = 1 "
     . "ORDER BY `last_name` ASC";


Arrays

Arrays with Numerical Indexes
Negative numbers are not permitted as indexes, an indexed array may start with any non-negative number, base index must be 0.

When declaring indexed arrays with the array function, a trailing space must be added after each comma delimiter to improve readability: 
$sampleArray = [1, 2, 3, 'ApPHP', 'People', 99];


We recommend to use square brackets [] for arrays.
Associative Arrays
When declaring associative arrays with the array construct, breaking the statement into multiple lines is encouraged, for example: 
$sampleArray = [
    'firstKey'  => 'firstValue',
    'secondKey' => 'secondValue',
];


Variables Naming



Classes Naming

Class Declaration
The brace should always be written on the line underneath the class name.
Every class must have a documentation block according to PHPDocumentor standards.
Only one class is permitted in each PHP file.

The following is an example of an acceptable class declaration:
/**
* Documentation block here
*/
class TheSampleClass
{
    // All contents of class
    // Must be indented four spaces
}
Class that extends other classes or which implement interfaces should declare their dependencies on the same line when possible. 
class TheSampleClass extends AbstractClass implements ClassInterface
{
    // All contents of class
}
Class Member Variables
Any variables declared in a class must be listed at the top of the class, above the declaration of any methods. The var construct is not permitted. Member variables always declare their visibility by using one of the private, protected, or public modifiers. Giving access to member variables directly by declaring them as public is permitted but discouraged in favor of accessor methods (__set and __get).


Functions and Methods

Methods inside classes must always declare their visibility by using one of the private, protected, or public modifiers. Functions in the global scope are strongly discouraged.

The following is an example of an acceptable function declaration in a class: 
/**
* Documentation block here
*/
class TheSampleClass
{
    /**
    * Documentation block here
    */
    public function myFunctionName()
    {
        // All contents of function
        // Must be indented four spaces
    }
}


Control Statements

These statements include if, for, while, switch, etc.
Putting a space before and after the control statement in brackets is very desirable, but not required.
Separating the operators by spaces within the brackets is very desirable, but not required.
Always indent with four spaces.
Here is an example of if statement, since it is the most complicated of them: 
if ($x == $y) {
    $a = $b;
} elseif ($x == $z) {
    $a = $c;
} else {
    $a = $d;
}


Files and Folders

Files are named with lower case or CamelCase (AaaBbbCcc or ABbbCcc) and folders are always named with lower case and underscore (if needed).

SQL

We always use lower case for all table names and column names. This is because different databases handle case-sensitivity differently. For example, PostgreSQL treats column names as case-insensitive by default, and we must quote a column in a query condition if the column contains mixed-case letters. Using lower case would help us to eliminate this problem.

Tables generally must be named in plural, excluding the cases when it's not possible, for example: customers, accounts, news, info, etc.

Tables with One-To-Many relation type usually named using a "singular_plural" naming format, for example:: booking_descriptions, customer_translations, account_settings, etc. Tables with Many-To-Many relation type usually named using a "plural_plural" naming format, for example: customers_addresses, menus_pages, flights_customers etc.

Translation tables generally named in singular with adding suffix "_translations", for example: customer_translations, hotel_translations, news_translations, etc.

Default Values


Inline Documentation

Documentation Format
We recommend to use format that is compatible with the phpDocumentor format. For more information, please visit: http://phpdoc.org/

Files documentation example: 
/**
* The short description for the file
*
* Long description for file (if any)...
*
* LICENSE: Some license information
*
* @product    ApPHP Framework
* @copyright  Copyright (c) 2006-2013 ApPHP. (http:⁄⁄www.apphp.com)
* @license    http:⁄⁄www.apphpframework.com/license/   LGPL License
* @version    $Id:$
* @link       http:⁄⁄www.apphpframework.com/product/
* @since      File available since Release 1.1.0
*/
Classes documentation example: 
/**
* The short description for the class
*
* Long description for class (if any)...
*
* @product    ApPHP Framework
* @copyright  Copyright (c) 2006-2013 ApPHP. (http:⁄⁄www.apphp.com)
* @license    http:⁄⁄www.apphpframework.com/license/   LGPL License
* @version    Release: @package_version@
* @link       http:⁄⁄www.apphpframework.com/product/
* @since      Class available since Release 1.2.0
* @deprecated Class deprecated in Release 2.0.0
*/