WebsiteCodingPractices

Common standards on how to write php pages for the website

This is up for discussion. If anyone would find it useful to see a particular standard implemented to make it easier for anyone to edit any page, please suggest it.

If anyone things that any of the standards suggested do not help, please comment.

Purpose

• Make it easier for other people to edit your code
• Ensure that pages are written securely
• Encourage compatibility with future changes
• Derived from pear coding standard http://pear.php.net/manual/en/standards.php

Standard

Header

• Optional $page_title

• All pages that require authentication start with
  

wscauth_requirepriv(PRIV); or
if(!wscauth_haspriv(PRIV)){return;}

• Optional includes
  • Use include_once or require_once
  • Any includes that are not used on every page should be included at the start of the page using them

• All pages that are passed variables should declare the variables after the authentication
  • Newer versions of php disable register_globals, which means that this is required
    

eg.
$var=$_REQUEST['var']; for url, post and cookie or
$var=$_GET['var']; for URL only
$var=$_POST['var']; for POST only
$var=$_COOKIE['var']; for cookie only

• Optional check vars passed to the page for expected string format

eg. $pid=preg_match(/^[0-9]+/, $_GET['pid'],$match) ? $match[0] : false;
This will assign $pid to the value of pid in the url if it is a number.

Block statments

• Use tabs to indent block code

• Avoid nested or long if statements

eg. instead of if(COND){Do lots of code}
use if(!COND){return;}Do lots of code

Functions

• Use functions to make the structure of a page clear
  • If the page performs lots of actions use a switch statment to call functions that perform the actions. Do not use lots of if statments throughout the page
  • If functions are used on more than one page, put them in an include
  • Where possible use existing functions even if it is slightly less efficient. This will make the website more reliable and have a negligable impact on performance.

Database

• All database queries are to be performed in functions specifically for that task

• Database queries should use PEAR or string formatting functions

eg. $query=sprintf("SELECT * FROM table WHERE id='%d' AND string='%s'",
mysql_real_escape_string($id),
mysql_real_escape_string($string))

Syntax

• Use <?php and ?> not <? and ?> which is not standards compliant

Comments

• All functions should be preceded with a comment block so that docmentation can be automatically built

The comment block should have to following format

/**
 * A description of the function
 * @param string $param A description of the parameter
 *
 */
function example ($param) { ...

• Comments used within the code should have a dimilar format

• Documentation on comment syntax is available at http://www.phpdoc.org

Example php page

<?php
$page_title="Example php page";
wscauth_requrepriv(PRIV_VIEW_EXAMPLE);
include_once("include/members.inc");
include_once("include/strings.inc");

$pid=preg_match(/^[0-9]+/, $_REQUEST['pid'],$match) ? $match[0] : false;

//This if statement may not actually be required as person_by_id does a similar thing.
//Consider what the effect of not passing $pid would be and only use a statment like this if the page would break.
if(!$pid){
 print "Person not found";
 include_once("another_page.php");
 return;
}
$person=person_by_id($pid);
print "Name ".$person['fullname'];

//Only put a function in this page, if it cannot be used in other pages.
function exampleFunction($var1, $var2, $var3="default"){
 //Only do database queries in this page, if this will be the only page where the database table is used.
 $query=sprintf("SELECT * FROM example_table WHERE
   pid='%d' AND expired="
   .stringNull($date).
   ")",
  mysql_real_escape_string($pid));

 return wscdb_fetchresults($query,0,0);
}
?>