Coding Guidelines - PHP

=Note=


 * What's mentioned in the naming conventions are 'recommendations'. You do not neccessarly have to follow them, but it is highly recommended as it will help everyone when they work together on a project.

=Get a decent IDE (Integrated Development Environment)=

Software can be written with the most basic text editor but on bigger projects it helps a lot if you have a somewhat professional IDE. A good IDE provides class browsing, variable checking and pretty much a better overall overview. As we don't have a compiler in PHP, a really good IDE tries to do some of that work by warning you if you do silly things or provide available functions/variables.

The IDE I recommend to use is Zend Studio 5. It's very powerful and saves a lot of time and effort in many ways, including listing and searching for functions or code, and debugging. Another good and free alternative IDE is Eclipse, that has been been deployed on a range of development workstations including Linux, HP-UX, AIX, Solaris, QNX, Mac OS X and Windows based systems. Although developed primarily for use with the Java programming language and frameworks, a nice PHP plug-in is available that makes it suitable for PHP development. There is also a SVN plug-in, that integrates an SNV client.

Another recommended free IDE is the Quanta+ IDE. It's based on QT, and integrates well with KDE if you're a Linux/KDE user.

As for web development, I highly recommend Dreamweaver CS3. It's extremely powerful, has built in text and design editor, SVN managing, FTP managing, and so on. I have yet to find an alternative that has both a text and design editor, which is worth using at a production level. If anyone finds one, please tell me and i'll include it here.

=External Documentation=

A good set of documentation is the developers best friend. No one needs to (or should) learn all instructions by heart. As the proverb goes: "You don't need to know everything, just where it's written".

The PHP website has a good set of online documentation and search function. Still you should always keep a local copy because it is faster and in case you have network problems, you can keep on working.

If you're using Mozilla Firefox, there is a PHP lookup function that will really help you.

=Think and get structured=

Before you write a single line of code, you should have prepared the basic structure on a piece of paper. Seriously, professional programming doesn't start with someone hacking in hundreds of lines of code and then noticing they have no structure or concept at all. This happens more often than it should and in the end it often means a complete rewrite.

=Do it object oriented =

Get familiar with the concepts of object oriented programming. OOP is a buzzword like others and it doesn't necessarily make software better. Still it makes (can make) development and maintenance of big software projects a lot easier.

=Naming Conventions=

Variables
Variable names should start in lower case, and words be separated in Capital.

GOOD $var myVariable = 'hi'; $var resultAfterComputation;

BAD $var my_variable; $var resultaftercomputation;

Variable names should start with lowercase, and each word separated with an underline ( _ ). Variable names should be indicate the purpose or use of the variable, not what it contains. None of that incorrect Hungrarian notation.

When variables will be used in a global context, just as HTML forms, care must be exercised not to have name clashes. This is especially easy when creating plugins. For HTML forms, it is recommended that variable names have either frm_ prepended to the name, or an appropriate abbreviation indicating which plugin, class or function created or will use the variable. When creating iterators, the standard i, j and k are acceptable, however when creating deeply nested loops that do not use recursion, consider making the iterator names reflect their purpose. E.g. foreach($inventory as $books) { foreach($books as $book) { foreach($book as $meta) { echo $meta['author']; }     }  } Instead of  for($i = count($inventory); $i > 0; $i--) { for($j = count($inventory[$i]); $j > 0; $j--) { for($k = count($inventory[$i][$j]); $k > 0; $k--) { echo $inventory[$i][$j][$k]['author']; }     }  }

Functions
Function names should start with lowercase, separating each word with an underscore ( _ ).

GOOD function my_function_that_crashes {

BAD

function MyFunctionThatCrashes {

function myfunctionthatcrashes {

Classes
Class names should start with uppercase, separating each word with a Capital letter.

GOOD class MyClass {

BAD

class my_class {

class myclass {

=Comments=

I highly recommend using PHPDoc style comments. It is strongly recommended to use this style of commenting in all projects, because projects usually use a generator to grab all the comments from the code and create a comment API.

Single Line Comments
Single line comments can be done using C++ style comments ( //... )

// this is a single line comment

// similarly, this has two lines, so you can still // use it.. but if you have several lines, don't.

Multiple Line Comments
Multiple line comments should be done using the C style comment, ( /* ... */ )

/** * this is a multiline comment. you can write a lot of * text here bla bla bla and describe what you're trying * to tell us. notice how the stars are alligned on the * right. */

Function Comments
Function comments should be done as follows.

/** * functionName - description of what the function does * * @param type $parm_name - description of what the parameter does * @param type $parm_name - description of what the parameter does * @return type $return_name - what you return */

The @param is a description of the parameters you pass into the function, and the @return is the return and its description. For example, here is a live comment for a function we use. Notice how you start the comment with /** and end it with */

/** * downloadFile - downloads the requested file from the server * * @param var $serverdir_data - the full url to the server + file * @param var $clientdir_data - the full path to the local file * @return var $content - the resulting content */ function downloadFile($serverdir_data, $clientdir_data) { $received_data = file_get_contents($serverdir_data); file_put_contents($clientdir_data, $received_data);

return $received_data; }

File based comments
This section is very important.

Each file you create has to have the following comment structure. Please make sure you added the following comment lines at the top of new source files written by you before adding them to the project. It consists of two sections.


 * An introduction about the file and who wrote it.
 * The license information.

/**   * Class/File name - Short description of what your code provides *  * A longer description of the project that can contain many lines. Feel * free to express yourself here......................... *   * @package {this will mostly be related to the project} * @author [your real name],<[email address]> http://indemajtech.com/ * @copyright &copy 2007 Indemaj Technology. * @license http://gnu.org/licenses/gpl.html GNU General Public License */

/** This file is part of {PROJECT NAME}. *   * {PROJECT NAME} 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. *   * {PROJECT NAME}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 {PROJECT NAME} if not, write to the Free Software * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA */

Notes


 * The license is different depending on the nature of the project. Please consult before writing it. The above example uses the GPL v2.


 * If you don't like to give your real name, use a nick, but please be sure you always give the same name and email address.

Below is an example of a File comment we use.

 * @copyright &copy 2007 Indemaj Technology * */

=Security=

If you don't trust the source of your data (and mostly you shouldn't), you need to cast it, as PHP is not a typed language.

For example you expect a value to be an int but someone is evil and inserts a string. If we query our database with it, we have a security breach. That easy.

=Links=

Java Programming Style Guide As the name says about Java but mostly applys to PHP as well.

=Tabs & Spaces=

To achieve a consistency that improves code readability, the following guidelines need followed by all Indemaj Technology Project Members.

Tabs and Spaces
Tabs and indents must be four(4) spaces. Use spaces rather than the tab character.

Code Blocks
Code blocks are indicated by the opening and closing braces '{}' The opening brace must come on the same line as the statement that begins a code block. E.g.:

if (is_null($var)) { //... code statements in the block } ...  function myFunction { //... code statements } ...  class myClass { //...class definition }

If your code is very nested, try using comments at the closing brackets to indicate which block they belong to. For example

foreach($inventory as $books) { while (....) { if (.....) { echo $meta['author']; } // end if    } // end while } // end foreach

Single Statement code blocks
These must still be split into two lines, with the appropriate braces. E.g. if ($var) { $foo = 1; }

=Adding files written by you=

Copywrite Notice
Please make sure you added the following comment lines at the top of new source files (not templates to be parsed by Smarty) written by you before adding them to Loquacity: /**   * Short description of what your code provides *   * @package {this will mostly be Loquacity} * @author [your rl name],<[email address]> http://www.loquacity.info/ - last modified by $LastChangedBy: $ * @version $Id: $ * @copyright 2006 [your rl name],<[email address]> * @license http://www.gnu.org/licenses/gpl.html GNU General Public License */ /** This file is part of Loquacity. *   * Loquacity 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. *   * Loquacity 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 Loquacity; if not, write to the Free Software * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA */

If you don't like to give your real name, use a nick, but please be sure you always give the same name and email address. Alternatively: Files that likely won't be documented with phpdoc should include this comment lines:

/** Loquacity - A web blogging application with simplicity in mind - http://www.loquacity.info/ * Copyright (C) 2006 [rl name] <[your email address]> *   * This file is part of Loquacity. *   * Loquacity 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. *   * Loquacity 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 Loquacity; if not, write to the Free Software * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA */

As for use of your real name: see above.

Adding files written by someone else
Make sure the licenses from files of other projects are compatible with the GNU General Public License. Follow this link for more information about compatible licenses.

Editing Loquacity's files
When modifying files originated by Loquacity significantly, you may add your name and email adress to the authors and copyright holders.

Editing files orignated by another project
When modifying files originated by another project, you may do this two. But you also have to mark your changes and with their date. See GNU General Public License or rather the license of the specific source.

Editing files orignated by bBlog
As in the 2 cases before, you may add your name and email address to the authors and copyright holders. But instead of marking your changes and writing their dates to the source file itself, you should refer to the CHANGELOG in the source tree and specify the date of your change and what you changed there.