Spylook Editions inc.
PHP Programming Standard
Version 1.0 - June 16th, 2002 rev 12:10 ET

0- Abstract
1- Naming convention
2- Code layout
3- Commenting
4- General Guidelines

0- Abstract

This document is intended to give PHP programmers guidelines to program neat, easy to understand efficient code in a standard way. There are many ways to do the same thing in PHP and it can get confusing for the reader - this document is aimed at giving writers and readers a reference as to how to write and read the PHP code. A program respecting this standard should state it in the header, as shown below, so readers and potential contributors can easily understand the code and continue programming in a consistent way.

This document was based on existing conventions to ensure easy standardization.

1- Naming convention

Always use explicit English names for your variables and functions. Use all lowercase letters and replace spaces by underscores. Don't use too long names, but make your names descriptive anyway.

For a variable, $database_server would be good, while $dbserv, $databaseServer or $the_database_server_for_this_site wouldn't.

Try to include verbs in function names, as it is more descriptive. authenticate_user is more explicit than auth_user and doesn't take much more time to type - especially compared to the time saved in understanding. Function arguments should be just as explicit as variables.

Loop indices are the only variables that don't have to be explicit. You can use $i and the following as counters in your loops, but something like $row_count is always better anyway.

2- Code layout

Always include the braces, even if you have one-line statements. This makes it much easier for the reader to understand.

Code between the opening and closing brace of a statement should be indented by one tab. Braces should be on their own lines and the opening and closing braces of a statement should be on the same column.

As example:


if ($display_list == 1)
{
	print 'The program wants us to display the list.<br>';
	foreach ($list_items as $k=>$v)
	{
		print "$k corresponds to $v<br>";
	}
} 
  

SQL code should be split on different lines, one per statement. SQL operators should be written in caps. As example:


$user_authentication="SELECT id
                      FROM users
                      WHERE username='$username' AND password='$user_password'";

Whenever you combine AND and OR operators, use parenthesis to clearly demonstrate the operators precedence.

Finally, put spaces between tokens so people can more easily read what you've written. As example,
1 + 1 = 2
is easier to read than
1+1=2.

3- Commenting

File identification

Each file should contain a header of the following format specifying all necessary info on the file:


// +----------------------------------------------------------------------+
// | PACKAGE: [name of package]                                           |
// +----------------------------------------------------------------------+
// | FILENAME VERSION                                                     |
// | PURPOSE: [program purposes]                                          |
// +----------------------------------------------------------------------+
// | REQUIRES: [files that are required, optional]                        |
// +----------------------------------------------------------------------+
// | CODING STANDARD: Spylook Editions PHP coding standard 1.0            |
// |                  http://www.spylookeditions.com/standard/            |
// +----------------------------------------------------------------------+
// | COMMENTS: [comments, optional]                                       |
// +----------------------------------------------------------------------+
// | Copyright (c) YEAR [business]  <[business site URL, without http://]>|
// | Developed by: [list of the program authors]                          |
// +----------------------------------------------------------------------+
// | LICENSE: [license information]                                       |
// +----------------------------------------------------------------------+
// | For support concerning this program, contact [your tech support]     |
// +----------------------------------------------------------------------+

As example:


// +----------------------------------------------------------------------+
// | PACKAGE: Mediatheque                                                 |
// +----------------------------------------------------------------------+
// | index.php version 2002-06-05 20:15 ET                                |
// | PURPOSE: displays documents that are part of the mediatheque         |
// +----------------------------------------------------------------------+
// | REQUIRES: class mediatheque (mediatheque.php)                        |
// +----------------------------------------------------------------------+
// | CODING STANDARD: Spylook Editions PHP coding standard 1.0            |
// |                  http://www.spylookeditions.com/standard/            |
// +----------------------------------------------------------------------+
// | COMMENTS: This program was developped for free for the Polyvalente   |
/  |           Hyacinthe-Delorme <http://tux.phd.cssh.qc.ca>              |
// +----------------------------------------------------------------------+
// | Copyright (c) 2002 Crealabs  <www.crealabs.com>                      |
// | Developed by: Pierre-Luc Soucy                                       |
// +----------------------------------------------------------------------+
// | LICENSE: This program is free software; you can redistribute it      |
// | and/or modify it under the terms of the GNU General Public License as|
// | published by the Free Software Foundation; either version 2 of the   |
// | License, or (at your option) any later version.                      |
// +----------------------------------------------------------------------+
// | For support concerning this program, contact webmaster@crealabs.com  |
// +----------------------------------------------------------------------+

Functions should be explicitly commented: description, input parameters and output parameters:


/**
 * [description]
 * @param   [input parameter name	description (repeat this line for each parameter)]
 *
 * @return  [type of data returned]	[description of the data returned]
 */

As example:


/**
 * Generate greeting for the user
 * @param 	$username       the user username (e.g. jsmith)
 * @param	$user_full_name the user full name (e.g. John Smith)	
 *
 * @return 	string          the message to be shown to the user
 */

Finally, pieces of code can be commented by using the // code at the beginning of a line when judge necessary. Variables should also be commented when declared if an explanation might be needed. When in doubt, comment.

4- General guidelines

When there are no variables to parse in a string you want to display, use single quotes instead of double quotes as it prevents PHP from uselessly parsing the string for variables.

When retrieving an array element whose key is a string, put the key name between single quotes to avoid any confusion:
$array['key']

Associative arrays should be represented with one tab of indent for each new sub-array, and elements should be aligned:


$array_name=array('element1'=>'value1',
				  'element2'=>'value2',
				  'element3'=>array('sub_element1'=>'sub_value1',
				                    'sub_element2'=>'sub_value2'),
				  'element4'=>'value4');

To summarize, do all you can to write clear, easy-to-understand code.