geometrus

indentation

• Always 2 spaces and not using tabs, to avoid problems in different text editors and users.
• Align when possible:

        $aColors = array( array( #FFF, #FFF, #FFF ),
                          array( #0FF, #F0F, #FF0 ),
                          array( #00F, #F00, #0F0 ),
                          array( #000, #000, #000 ) );
  

  or another example:

        $sName          = "";
        $iMaxFileSizeKb = 128;
        $aTypeAllowed   = array( "jpg", "gif", "png" );
  

naming convention

classes

Capital first letter, underscore between words. Class name must match controller's and file name (except first letter). That means that each class must go in a different file. Models add "_model" at the end, as Dataset_model. Use of acronyms is allowed but without caps: Document_pdf and Document_pdf_model. Even if a word is an acronym, it must not be written in all caps (HTML, for example, would become Html).

functions and methods

Begin with small caps, then words begin with caps. No underscore between words. If suitable, use "Get" or "Set" as beginning. Explain what they do: getErrorCode, calcEmissions, showPdf, loadDataset.

variables

Since PHP vars can be of any type, even change in the same script, I prefer using the hungarian notation for stating the type with the first lower letter, then same as functions. Always initialized before used: $aColors = array();, $bEndFile = false;. Exceptions:

• Short loops: $i, $j.
• Coordinates: $x, $y, $z.
• Database: $sql, $query, $db, $rs.

I do not use global vars. When needed, either a regular var in config or a session one.

constants

All caps and underscore between words: MAX_FILES_ALLOWED.

coding style

parenthesis

I do know that language constructs as if are different than functions as str_replace. But both work the same way and return values, so I try to keep same style with these calls. Always put spaces when using parenthesis, it is much easier to read:

 if( $sUserType === "admin" )

 $iLastUser = count( $aUsers ) - 1;

 $sLastUser = $aUsers[ $iLastUser ];

 $oDataset->loadPdf( $fName, $iFileSize, $sUrl );

braces

I always use braces in their own line:

  for( $i = 0; $i <= $iLastUser; $i ++ )
  {
    if( ! empty( $aUsers[ $i ] ) )
    {
      echo( "user: ", $aUsers[ $i ], "<br/>" );
    }
  }

strings

I prefer double quotes, but never rely on magic quotes. Single quotes are used inside.

$sql = "SELECT id FROM users WHERE name = 'Pau' ";

When using concatenation, the . operator is placed under the assignment. Concatenation and caps are used in queries as follow:

        $sql = "SELECT field1, field2 "
             . "  FROM table "
             . " WHERE field3 = 'somevalue' "
             . " ORDER BY field1 " ;

switch

Use continue and break sparingly, as they are masked go to. Always use a default. The switch follows this model:

switch( $erCode )
{
  case 1:
    ...
    break;
  case 2:
    ...
    break;
  default:
}

other

• Never use global vars. Use session vars instead.
• Use of echo( 1, " .- ", $var ); instead of echo 1 . " .- " . $var; or print.
• Use of if instead of the ternary operator ? :.
• The return clause never uses parents. And it helps debugging if there is a simple variable to return. Any calculations or function calls must be done earlier:

        function getTableValue( $sTable, $sField )
        {
            $sql = 'SELECT ' . $sField
                 . '  FROM ' . $sTable;
            $db->query( $sql );
            $val = $db->row[ $sField ];
            return $val;
        }
  

• No use of magical numbers like if( $i > 15 ). Use variables and document them.
• One statement per line. If possible, avoid embedded assignments like if( $file = fopen( $url ) )
• Space after commas, as when writing.
• Do not use abort or die, or the evil @ operator. Use a error handler, like:

        function exception_handler( $exception )
        {
          echo 'Uncaught exception: ',
               $exception->getMessage(), '\n';
        }
  
        set_exception_handler( 'exception_handler' );
  
        throw new Exception( 'Uncaught Exception' );
  

• Use of operators like ===, !== (value & type) instead of ==, != (just value, type is casted).
• Do not rely on the default values like zero, null or false; always check if( $bGeneratePdf === true ).
• Do not call functions in checking the end of a loop; assign them before:

        $iNumUsers = count( $aUsers );
        for( $i = 0; $i < $iLastUser; $i++ )
  

example

bad code

function copy($url,$dirname){
@$file = fopen ($url, "rb");
if (!$file) {
echo '<font color=red>Failed to copy
$url!</font><br<';
return false;
}else {
$filename = basename($url);
$fc = fopen($dirname."$filename", "wb");
while (!feof ($file)) {
$line = fread ($file, 1028);
fwrite($fc,$line);
}
fclose($fc);
echo "<font color=blue>File $url saved to
PC!</font><br>";
return true;
}
}

my code

function copyFile( $sUrl, $sDirName )
{
  $iBufferRead = 1024;
  try
  {
    $fIni = fopen( $sUrl, "rb");
  }
  catch(Exception $e) //this does not handle fatal errors, though
  {
    print("Couldn't open file");
  }
  if( !$fIni )
  {
    echo '<p class="error">Failed to copy',
         $sUrl, '</p>';
    return false;
  }
  else
  {
    $sFileName = basename( $sUrl );
    $fEnd = fopen( $sDirName . $sFileName, "wb" );
    while( ! feof( $fIni ) )
    {
      $sLine = fread( $fIni, $iBufferRead );
      fwrite( $fEnd, $sLine );
    }
    fclose( $fEnd );
    fclose( $fIni );
    echo '<p class="succeed">File',
         $sUrl, 'saved to PC!</p>";
    return true;
  }
}

documentation

Documentation must be compatible with phpDocumentor.

file

Each file starts with...

<?php
/**
 * some_file.php
 *
 * Explains what it is inside the file.
 *
 * @copyright 2009 geometrus all rights reserved
 * @license http://geometrus.com/license
 * @version $Id$  (cvs keyword)
 * @link (where the file is placed)
 * @author Fulgencio Sanmartin <f@geometrus.com>
 * @since File available since Release 1.5.0
 *
 * Audit:
 * 23/01/2009 [fulgen] created
 * 25/01/2009 [other]  added some functionality
 * 26/02/2009 [fulgen] solved bug #3341
 */

class

Apart from previous tags (see file), each class adds and is preceded of...

 * @package sample
 * @subpackage classes

function, method

Apart from previous tags (see file), each function or method adds and is preceded of...

 * @param string $param1 name to declare
 * @param string $param2 value of the name
 * @return integer