# 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
  - PHP Code Tags
  - Indentation and Whitespace
  - Operators
  - Strings
  - Arrays
  - Variables
  - Classes
  - Functions and Methods
  - Control Statements
  - Files and Folders
  - SQL
- Documentation
  - Inline 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&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 `<?php echo $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 optional:

    $company = 'ApPHP'.' - '.'web solutions';
    $company = 'ApPHP' . ' - ' . 'web solutions';

When you concatinate 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 = array(1, 2, 3, 'ApPHP', 'People', 99);

Associative Arrays
When declaring associative arrays with the array construct, breaking the statement into multiple lines is encouraged, for example:

    $sampleArray = array(
        '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;` or `protected function _get(){...}`.

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 desirable, but not required.
Separating the operators by spaces within the brackets is 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;
    }else if($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.

### 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
    */