Preface

This document is part of the LiveSupport project, Copyright © 2004 Media Development Loan Fund, under the GNU GPL.

Scope

This document describes the PHP script file conventions for the LiveSupport project. See also the generic description of the file conventions in the LiveSupport project.

Introduction

PHP scripts are text-based files containing PHP class definitions and/or commands.
They should adhere to the PEAR coding standards conventions.
As text based files, they should adhere to the generic text-based conventions.

Naming

A PHP script containing only class definition should have filename which reflects the class, it is implementing. Class names begin with a capital letter, followed by lower case letters. In case of a multiple word file name, the first letter of each word is capitalized.
Other PHP scripts should have name starting with lowecase letter.
PHP script files are named by the following rules:

Structure

PHP scripts are partitioned by using the following 80 column wide partitioning comments:
/* ==================================================== name of the partition */
and 
/* ------------------------------------------------- name of the subpartition */
The file has the following mandatory structure:
Because PHP is in-HTML embedable script language, it is possible to mix PHP and HTML code using PHP tags <?php and ?>. This mixing approach is little bit obsolete and it is better to use pure PHP (with structure described above) and some template system to generate HTML.

Header

The header holds all information mandated by the generic guidelines, but are enclosed in the PHP multiline comments /* */. Note the 80 column wide partitioning delimiter enclosing the header.
/*------------------------------------------------------------------------------
    Copyright (c) 2004 Media Development Loan Fund
 
    This file is part of the LiveSupport project.
    http://livesupport.campware.org/
    To report bugs, send an e-mail to bugs@campware.org
 
    LiveSupport 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.
 
    LiveSupport is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.
 
    You should have received a copy of the GNU General Public License
    along with LiveSupport; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
 
    Author   : $Author: tomas $
    Version  : $Revision: 1.1 $
    Location : $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/doc/developmentEnvironment/phpFileConventions.html,v $

------------------------------------------------------------------------------*/

Defines

This section contains all the constant defines, similar as:

define('CONSTAT_NAME', 10);

Include files

This section contains all the include files that the script needs to include. The include files are listed in a most generic to most specific order: first PEAR classes, then other LiveSupport module include files, and finally include files from the same module / product are listed.
Is much safer to use include_once or require_once, not the original versions of this statement.

Code sections

This sections contain class definitions, function definitions or runable PHP commands.

Template

See a generic template for PHP scripts. You may freely download and copy this template when starting to create a new script.