CakePhp Coding Standards

This document is somewhat based on PHP.PL DevTeam Coding standards.

Note: It is always good to look at some HTML markup reference.

Contents:

1. Coding standards for Cake
2. Purpose of this document
3. Indentation
4. Method definition
5. Commenting code
6. Including files
7. PHP tags
8. Naming convention
   1. Functions
   2. Classes
   3. Variables
   4. Member visibility
   5. Files
   6. Variable types
   7. Constants
9. SQL Guidelines

Purpose of this document

I’ve been coding in cakephp for almost a year now and I am starting to learn the value of documentation and coding standards in a team. I know since college that it’s really important that programmers, specially in a team, follows some kind of guidelines to mak e a better and readable software. But only thru experience that I saw that. Still, a lot of old programmers do not even mention this to new ones. I don’t know why but in my point of view, it’s a must. Because of that, I post here the guidelines that I suggested to use in our group. Most of the standards here came from the cakePhp code standards and I just added a few things that applies in the development outside the core lib. I would probably add more as time goes by but these are the most important ones in my development. Please use or redistribute this in anyway you want. I hope it’ll be helpful to others.

Indentation

One tab will be used for indentation. Tab-width: 4

So, indentation should look like this:

<?php

// base level

    // level 1

        // level 2

    // level 1

// base level

?>

Method definition

Example of a function definition:

 

<?php

function someFunction($arg1, $arg2 = '') {

    if (expr) {

        statement;

    }

    return $var;

}

?>

Parameters with a default value, should be placed last in function
definition. Try to make your functions return something, at least true
or false – so it can be determined whether the function call was
successful.

 

<?php

function connection(&$dsn, $persistent = false) {

    if (is_array($dns)) {

        $dns_info = &$dns;

    } else {

        $dns_info = BD::parseDNS(dns);

    }    if (!($dns_info) || !($dns_info['phpType'])) {

        return $this->addError();

    }

    return true;

}

?>

Note that there are spaces on both side of the equals sign.

Commenting code

All comments should be written in English, and should in a clear way describe the commented block of code.

Comments can include the following phpDocumentator tags:

• @access
• @author
• @copyright
• @deprecated
• @example
• @ignore
• @internal
• @link
• @see
• @since
• @tutorial
• @version
• inline {@internal}}
• inline {@inheritdoc}}
• inline {@link}}

The most important part is the description and author.

PhpDoc tags are very much like JavaDoc tags in Java. Tags
are only processed if they are the first thing in a DocBlock line, for
example:

 

<?php

/**

 * Tag example.

 * @author this tag is parsed, but this @version is ignored

 * @version 1.0 this tag is also parsed

 */

?>

There are 3 inline tags ({@internal}}, {@inheritdoc}} and {@link}}). Example:

 

<?php

/**

 * Example of inline phpDoc tags.

 *

 * This function works hard with {@link foo()} to rule the world.

 */

function bar() {

}function foo() {

}

?>

Including files

When including files with classes or libraries, use only and always the require_once function.

In making includes in the app folder, use the bootstrap to call general functions and use vendor() instead of require_once(). All included files should then be placed in the vendors folder.

Example call in the /core/bootstrap.php

 

vendor('functions');

PHP tags

Always use long tags:

 

<?php

?>

Never use short tags:

 

<?

?>

You can also use the ffg tag but not recommended.

 

<?=

?>

Naming convention

Functions

Function names should be written in camelBack?, for example:

 

<?php

function longFunctionName() {

}

?>

For functions that are used as views pages, use underscores to break words. Also use all lower caps. Example:

 

<?php

function long_functio_name() {

}

?>

Classes

Class names should be written in CamelCase, for example:

 

<?php

class ExampleClass {

}

?>

Variables

Variable names should be as descriptive as possible, but also as
short as possible. Normal variables should start with a lowercase
letter, and should be written in camelBack?
in case of multiple words. Variables containing objects should start
with a capital letter, and in some way associate to the class the
variable is an object of. Example:

 

<?php

$user = 'John';

$users = array('John', 'Hans', 'Arne');$Dispatcher = new Dispatcher();

?>

Member visibility

As we cannot use PHP5’s private and protected keywords for methods or variables, we agree on following rules:

• A protected method or variable name start with a single underscore (“_“).
  Example:

   

  <?php
  
  class A {
  
      var _iAmAProtectedVariable;    function _iAmAProtectedMethod() {
  
          /*...*/
  
      }
  
  }
  
  ?>

• A private method or variable name start with double underscore (“__“).
  Example:

   

  <?php
  
  class A {
  
      var __iAmAPrivateVariable;    function __iAmAPrivateMethod() {
  
          /*...*/
  
      }
  
  }
  
  ?>

Files

File names should be created with lower case. If a file name consist
of multiple words, they should be divided by an underscore character,
for example:

• long_file_name.php

Variable types

Variable types for use in DocBlocks:

Type	Description
mixed	A variable with undefined (or multiple) type.
integer	Integer type variable (whole number).
float	Float type (point number).
boolean	Logical type (true or false).
string	String type (any value in “” or ‘ ‘).
array	Array type.
object	Object type.
resource	Resource type (returned by for example mysql_connect()).

Remember that when you specify the type as mixed, you should indicate whether it is unknown, or what the possible types are.

Constants

Constants should be defined in capital letters:

 

<?php

define('CONSTANT', 1);

?>

If a constant name consists of multiple words, they should be separated by an underscore character, for example:

 

<?php

define('LONG_NAMED_CONSTANT', 2);

?>

All global constants should be declared in the /config/core.php

SQL Guidelines

SQL Queries can be convoluted and obfuscated. As with PHP code, you shouldn’t be afraid of using whitespace and line breaks in SQL code. You can improve its organization in a number of ways, including the ffg:

• Capitalize keywords
• Break lines on keywords
• Use cakePhp table aliases to keep the code clean

Example query that implements this changes.

 

 $this->Agency->findBySql("

 SELECT *

 FROM tAgencies AS Agency

 LEFT JOIN tApplications AS Application

   ON Agency.AgId=Application.AgId

 LEFT JOIN tApplicationTechRequests AS ApplicationTechrequest

   ON ApplicationTechrequest.ApId=Application.ApId

 WHERE $cond

 ORDER BY Agency.AgName

 LIMIT 100

 ");