CodingStyle

Agavi Coding Standards / Style

Encoding

All files must be encoded as UTF-8, without a Byte Order Mark. Unix line endings are mandatory.

PHP Code

Case

Use CamelCase for class and interface names. Do not use more than one uppercase character in succession, i.e. AgaviMysqlSessionStorage, not AgaviMySQLSessionStorage, and AgaviPhpRenderer, not AgaviPHPRenderer. The only exception is when defining interfaces, where the uppercase I is followed by an uppercase character. Only begin a new uppercase segment if it makes sense, i.e. AgaviAndoperatorValidator, not AgaviAndOperatorValidator.

studlyCaps are used for method names, e.g. setHttpHeader(), and for class variables.

For array key names, or parameters, use underscores, e.g.

$this->getParameter('foo_bar');

$array['some_key'] = $someValue;

All keywords are lowercase, without exception. Examples:

if($foo !== false) {
⇥foreach($foo as $bar) {
⇥⇥echo $bar;
⇥}
}

Constants shouldn't be used. If you use Class Constants, they should, of course, be all uppercase, with words separated by an underscore:

class Foo
{
⇥const SOME_NONSENSE_CONSTANT = 4;
}

Indent

Use Tabs, not Spaces, to indent blocks. The first level (i.e. the class declaration) is not indented). Setting your editor to two spaces per tab makes tabs easier to use and more visually appealing.

Alignment

However, you should use spaces to align code on several lines, for instance when defining an array:

$foo = array(
⇥'one'   => 1,
⇥'two'   => 2,
⇥'three' => 3,
);

That way, even with different tab sizes in different IDEs, code will always look reasonable.

Definitions

Class, Interface, Method and Function definitions should have a curly brace on the next line:

class AgaviFoo
{
⇥public function getBar()
⇥{
⇥⇥return;
⇥}
}

All classes and interface names begin with Agavi, e.g. AgaviWebRouting. The file names follow this convention and use either a class or interface part before the .php extension to indicate the type of the content, e.g. AgaviController.class.php, AgaviIRenderingFilter.interface.php

Interfaces have an I in their name, e.g. AgaviIGlobalFilter

Methods and functions that return a reference must not have a space between the ampersand and the function name.

The order of keywords in declarations is:

1. final
2. abstract
3. public/protected/private
4. static
5. function examples:

abstract public function &getFoo()

final protected static function getBar(&$baz)

Blocks

Curly braces go on the same line as the code construct they belong to. Even it the block is just one line long, use curly braces, separated from the preceding statement by a space character:

if(true) {
⇥someCodeHere();
} elseif($bar) {
⇥// more code
}

Do not use spaces after a construct name (if, foreach etc), and do not use a space before the opening parentheses that follow the function name in a declaration or call.

For switch statements, indent logically and put the break on the same level as the calling code. Example:

switch($zomg) {
⇥case 'lol':
⇥⇥if($noob == 'kthx') {
⇥⇥⇥lolz();
⇥⇥} else {
⇥⇥⇥rofl();
⇥⇥}
⇥⇥break;
⇥case 'woot':
⇥⇥kthxbai();
⇥⇥break;
⇥default:
⇥⇥orly();
⇥⇥break;
}

PHPDoc

We like them. This should appear at the top of each file:

<?php

// +---------------------------------------------------------------------------+
// | This file is part of the Agavi package.                                   |
// | Copyright (c) 2005-2007 the Agavi Project.                                |
// |                                                                           |
// | For the full copyright and license information, please view the LICENSE   |
// | file that was distributed with this source code. You can also view the    |
// | LICENSE file online at http://www.agavi.org/LICENSE.txt                   |
// |   vi: set noexpandtab:                                                    |
// |   Local Variables:                                                        |
// |   indent-tabs-mode: t                                                     |
// |   End:                                                                    |
// +---------------------------------------------------------------------------+

This should appear before each class (example for AgaviAutoloadConfigHandler, which is in the "config" subpackage):

/**
 * AgaviAutoloadConfigHandler allows you to specify a list of classes that will
 * automatically be included for you upon first use.
 *
 * @package    agavi
 * @subpackage config
 *
 * @author     David Zuelke <dz@bitxtender.com>
 * @author     Another Author <another_author@xmpl.org>
 * @copyright  (c) Authors
 * @since      0.11.0
 *
 * @version    $Id$
 */

and then something like this for each method in your class:

⇥/**
⇥ * Get a configuration value.
⇥ *
⇥ * @param      string The name of the configuration directive.
⇥ * @param      array  An array of parameters.
⇥ *
⇥ * @return     mixed The value of the directive, or null if not set.
⇥ *
⇥ * @author     David Zülke <dz@bitxtender.com>
⇥ * @author     Another Author <another_author@xmpl.org>
⇥ * @since      0.11.0
⇥ */

Please respect the 11 character gap between an @ and the value:

/**
 * @var        FooBar
 * @deprecated :)
 */