General PHP coding standards for Elxis CMS

The instructions listed here are important in order for the source code to be clear, easy to understand, well organized and be able to function under all enviroments and web servers. So we suggest to everyone who would like to be a part of elxis developers keep this notes as guidelines.

PHP File headers

On the very top of all Elxis php file we place the following code:

	<?php
	/**
	* @version        $Id$
	* @package        Elxis
	* @subpackage     If any, write the subpackage here, else ommit this line
	* @copyright      Copyright (c) 2006-2012 Elxis CMS (http://www.elxis.org). All rights reserved.
	* @license        Elxis Public License ( http://www.elxis.org/elxis-public-license.html )
	* @author         Elxis Team ( http://www.elxis.org )
	* @description    Elxis CMS is free software. Read the license for copyright notices and details
	*/	

	defined('_ELXIS_') or die ('Direct access to this location is not allowed.');

Important note
We do not set Id property on files encoded as UTF-8 such as language files! We write instead the Elxis version the file is for (for example ''2011.0'')

Subpackage

The subpackage line can be ommitted if it is a general file that has a global scope and not specific area of interest. ''subpackage'' values can be strings like this: ''Database'' (for a database related file), ''Component Documentor'' for a files belonging to component Documentor'', etc.

Coding guidelines

• Elxis requires PHP 5.2 or newer while it is compatible to PHP 6.
• We follow the strict PHP 5/6 coding standards and style.
• No shortcuts, asp style tags or shortopen tags are allowed (i.e. <?= )
• No usage of functions and classes that rely on non built-in PHP extensions
• Tab space should be 4 spaces. So set your PHP editor program to leave 4 spaces for each tab.
• Closing PHP tags at the bottom of all PHP only files.
• No white space or empty lines after closing PHP tags at the end of the file.
• Arrays should be declared before they are used.

Wrong example:

	    $test[] = 5;
	    $test[] = 6;

Correct example:

	    $test = array();
	    $test[] = 5;
	    $test[] = 6;

• - We destroy everything we don't need any more with unset in order to free up memory.

	    $test = new myClass($arg1, $arg2);
	    $test->doSomething();
	    unset($test);

• - Inorder to push elements into an array don't use array_push as it is slower.

Slower method:

	    $test = array();
	    array_push($test, 'mercedes');
	    array_push($test, 'bmw');

Faster method:

	    $test = array();
	    $test[] = 'mercedes';
	    $test[] = 'bmw';

• - We leave 2 empty lines between functions.
• - The first bracket of a function is within the same line as the function name. The second bracket is alone at the end of the function. Example:

	    function test($arguments) {
	        //function contents
	    }

• - Avoid the usage of include_once and recuire_once as they are slow.
• - Functions arguments should have a space between them. Example:

	    function test($argument1, $argument2, $argument3) {
	    }

• - KISS: Keep It Simple and Stupid
• - index.php: single point of access
• - All class names methods and variables are lowercase. If a name is more than a word we capitalize the first caracter of the second, third, etc, word. Example:

	    function testName() {}
	    function otherTestName() {}

• - Visibility should be declared in all functions within classes, even on the public ones. Examples:

	    private function test() {}
	    public function test2() {}
	    static public function test3() {}

• - We use PHPDocumentor style tags on the top of each file.
• - We don't use PHPDocumentor style tags on top of the functions.Instead we add a very short description of what the function does surrounded with comments. The description should be written with CAPITAL characters. Example:

	    /*******************/
	    /* RESIZE AN IMAGE */
	    /*******************/
	    function resizeImage($arguments) {
	        //function contents
	    }

• - All files shoule have the following line bellow the PHPDocumentor style tags. This will prevent direct access of the files.

	defined('_ELXIS_') or die ('Direct access to this location is not allowed.');

• - Inside all folders that there is no index.php file it is recommended to put an empty index.html file in order to prevent directory browsing.