PHP Coding Standards (2) – Naming Conventions

1. The Zend Framework employs a class naming convention whereby the names of the classes directly map to the directories in which they are stored.

 

Based on PEAR Coding Standards, we can easily find the right place where the file stored from the class name.

 

For example :

Zend_Acl_Role stands for Zend/Acl/Role.php

 

 

[codesyntax lang=”php”]

require_once 'Zend/Acl/Role/Interface.php';
class Zend_Acl_Role implements Zend_Acl_Role_Interface
{
......
}

[/codesyntax]

 

This rule has provided a pseudo-namespace mechanism which will become real in php5.3 and php6.

 

 

2. Class names may only contain alphanumeric characters. Numbers are permitted in class names but are discouraged. Underscores are only permitted in place of the path separator.

 

Also came from PEAR Coding Standards, but Zend Framework has redefined it to become more stringent.

 

Examples are :

Zend_Db_Table is permitted.

Zend_Db_Table2 is not discouraged.

Zend-Db-Table is not allowed.

 

 

3. When creating an API for use by application developers (as opposed to Zend Framework internal developers), if application developers must identify abstractions using a compound name, separate the names using underscores, not camelCase.

 

It’s hard to understand this rule. So let’s take am example here. When we want to initialize an instance of Zend_Db_Adapter_xxx, we usually pass the adapter as string into Zend_Db::factory() in order to get the product of database adapter.

 

First we can initialize the MySQL PDO driver :

[codesyntax lang=”php”]

$db = Zend_Db::factory('PDO_MYSQL', $config);

[/codesyntax]

 

We can also make MsSQL PDO driver:

[codesyntax lang=”php”]

$db = Zend_Db::factory('PDO_MSSQL', $config);

[/codesyntax]

 

 

4. If a class name is comprised of more than one word, the first letter of each new word must be capitalized. Successive capitalized letters are not allowed.

 

For example :

Zend_PDF is not allowed.

Zend_Pdf is right.

 

 

5. Zend Framework classes that are authored by Zend or one of the participating partner companies and distributed with the Framework must always start with "Zend_" and must be stored under the "Zend/" directory hierarchy accordingly.

 

For example :

Zend_Db is authored by Zend, and it’s stored like "Zend/Db.php".

My_Db is authored by user so never start with "Zend_" and usually stored like "My/Db.php".

 

 

6. Interface classes must follow the same conventions as other classes (see above), but must end with "_Interface".

 

For example :

Zend_Controller_Dispatcher_Interface stands for Zend/Controller/Dispatcher/Interface.php

 

 

 

7. For all other files, only alphanumeric characters, underscores, and the dash character ("-") are permitted. Spaces are prohibited.

 

For example :

Zend/Controller/Front.php is right.

My/Controller/Common-Action_2.php is also allowed.

My/Controller/Common Action.php is not allowed.

 

 

8. Any file that contains any PHP code must end with the extension ".php" except for those view scripts which extension ".phtml" or ".html".

 

For example :

Zend/Controller/Front.php is the standard way that name php while index.phtml is the default view script name.

 

You must have seen these kind of extensions for php file :

.php4

.php5

.phpx

.class.php

.include.php

html (joking?)

 

But in Zend Framework you will see only one style, that is ".php".

 

 

9. Function names may only contain alphanumeric characters and start with a lowercase letter. Underscores and numbers are not allowed in function names. When consisted of more than one word, the first letter of each new word must be capitalized which is commonly called the "camelCaps" method.

 

For example :

[codesyntax lang=”php”]

filterInput()
getElementById()
widgetFactory()

[/codesyntax]

 

They are all right way to name the functions.

 

But :

[codesyntax lang=”php”]

FilterInput3()
getelementbyid()
widget_factory()

[/codesyntax]

 

These all are not allowed.

 

 

10. Verbosity is encouraged. Function names should be as illustrative as is practical to enhance understanding.

 

For example :

[codesyntax lang=”php”]

getOne($id) // is not clear.
getOneRecordById($id) // is perfect.

[/codesyntax]

 

 

11. For object-oriented programming, accessors for object members should always be prefixed with either "get" or "set".

 

For example :

 

[codesyntax lang=”php”]

class Foo
{
    protected $_testObj;

    public function getTestObj()
    {
        return $this->_testObj;
    }

    public function setTestObj($testObj)
    {
        $this->_testObj = $testObj;
    }
}

[/codesyntax]

 

 

12. When using design patterns, such as the Singleton or Factory patterns, the name of the method should contain the pattern name where practical to make the pattern more readily recognizable.

 

For example :

[codesyntax lang=”php”]

abstract class Zend_Cache
{
    // ......

    public static function factory($frontend, $backend,
        $frontendOptions = array(), $backendOptions = array(), 
        $customFrontendNaming = false, $customBackendNaming = false, 
        $autoload = false)
    {
        // ......
    }
}

[/codesyntax]

 

 

13. Though function names may not contain the underscore character, class methods that are declared as protected or private must begin with a single underscore.

 

For example :

[codesyntax lang=”php”]

class Zend_Foo
{
    protected function _fooBar()
    {
        // ...
    }
}

[/codesyntax]

 

 

14. Functions in the global scope, or "floating functions," are permitted but heavily discouraged. It is recommended that these functions be wrapped in a class and declared static.

 

For example :

[codesyntax lang=”php”]

class Zend_Debug
{
    // ......

    public static function dump($var, $label = null, $echo = true)
    {
        // ......
    }
}

[/codesyntax]

 

 

15. Functions or variables declared with a "static" scope in a class generally should not be "private", but protected instead. Use "final" if the function should not be extended.

 

For example :

[codesyntax lang=”php”]

class Foo
{
    final public static function fooFinally()
    {
    }
}

class Bar extends Foo
{
}

// This is wrong
Bar::fooFinally();

// Use Foo::fooFinally() instead
Foo::fooFinally();

[/codesyntax]

 

 

16. The opening brace of functions and methods has to be in the next line.

 

For example :

[codesyntax lang=”php”]

function Myfunction($parameter1)
{
}

[/codesyntax]

 

 

17. Use "null" as the default value instead of "false" when $optional does not have or need a particular default value. However, if an optional parameter is boolean, and its logical default value should be true, or false, then using true or false is acceptable.

 

Consider the code below :

[codesyntax lang=”php”]

public function foo($required, $optional = null)
{
    if (isset($optional)) {
        echo 'Echo something only when $optional is set and != null';
    }
}

public function foo($required, $optional = false)
{
    if (isset($optional)) {
        echo 'Always echo something';
    }
}

[/codesyntax]

 

 

18. Variable names may only contain alphanumeric characters. Underscores or numbers are not permitted.

 

For example : 

[codesyntax lang=”php”]

$foo // is right
$foo_foo // is wrong
$foo2 // is also wrong

[/codesyntax]

 

 

19. For class member variables that are declared with the private or protected construct, the first character of the variable name must be a single underscore. This is the only acceptable usage of an underscore in a variable name. Member variables declared as "public" may never start with an underscore.

 

For example :

[codesyntax lang=”php”]

class Zend_Foo
{
    private $_barPrivate;
    protected $_barProtected;
    public $barPublic;
}

[/codesyntax]

 

 

20. Like function names, variable names must always start with a lowercase letter and follow the "camelCaps" capitalization convention.

 

For example :

[codesyntax lang=”php”]

$compatibilityMode
$registryClassName

[/codesyntax]

 

 

21. Verbosity is encouraged. Variable names should always be as verbose as practical. Terse variable names such as "$i" and "$n" are discouraged for anything other than the smallest loop contexts. If a loop contains more than 20 lines of code, variables for such indices or counters need to have more descriptive names.

 

For example the code below came from Zend_Search_Lucene :

[codesyntax lang=”php”]

// read segmentInfos
for ($count = 0; $count < $segments; $count++) {
$segName = $segmentsFile->readString();
......
}

[/codesyntax]

 

 

22. Constants may contain both alphanumeric characters and the underscore. Numbers are permitted in constant names. Constant names must always have all letters capitalized. Words in constant names must be separated by underscore characters.

 

For example :

[codesyntax lang=”php”]

"MY_CONSTANT_ONE" // is allowed
"MYCONSTANTTWO" // is not allowed
"my_constant_two" // also not allowed

[/codesyntax]

 

 

23. Constants must be defined as class members by using the "const" construct. Defining constants in the global scope with "define" is permitted but heavily discouraged.

 

For example :

 

[codesyntax lang=”php”]

class Zend_Acl
{
const TYPE_ALLOW = 'TYPE_ALLOW';
const TYPE_DENY  = 'TYPE_DENY';
......
}

[/codesyntax]

 

 

24. Unlike PHP’s documentation, the Zend Framework uses lowercase for both boolean values and the "null" value.

 

Code came from Zend_Mail :

[codesyntax lang=”php”]

public function setMessageId($id = true)
{
if ($id === null || $id === false) {
return $this;
} elseif ($id === true) {
$id = $this->createMessageId();
}
......
}

[/codesyntax]

 

Posted in Coding Standards | Tagged , | Leave a comment