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
- Code
- Documentation
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¶m1=aaa¶m2=bbb¶m3=cccVariant 2:
http://hostname/page/controller/action?param1=aaa¶m2=bbb¶m3=cccVariant 3:
http://hostname/page/controller/action/param1/aaa/param2/bbb/param3/cccYou 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 ¶
StringWhen 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 IndexesNegative 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 ¶
- Variables should use lowerCamelCase naming without spaces (e.g.
$basePath
,$dbName
, etc).
Classes Naming ¶
Class Declaration- Framework classes should use prefix "C" (classes) or "I" (interfaces) to avoid name conflict with applications classes.
- Application classes must be named in some unique way to avoid name conflict with third-party classes.
- Classes and interfaces should use UpperCamel naming.
- Methods and class properties should use lowerCamelCase naming without spaces.
- Controllers should use suffix "Controller", e.g. called "MyClassController".
- Models may use (optional) suffix "Model", e.g. "MyClassModel" or "MyClass".
- Protected or private properties and methods should use an underscore prefix. e.g:
private $_db;
orprotected function _get(){...}
.
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 includeif
, 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
- All numneric fields must have default value (generally '0')
- All date/datetime fields default value must be NULL (not '0000-00-00' or '1970-00-02' or something else)
Inline Documentation ¶
Documentation FormatWe 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 */