RoundCube Development Guidelines

Here are a few rules and explanations that should make it easier for new contributors to understand the structure and guidelines of the RoundCube code base. See PHP Commons for common functions and classes available in the RoundCube framework.

Directory structure

The root folder of a RoundCube installation contains the following folders:

config/

Home of the local configurations files

program/

All application files are stored in this folder.
These files will be replaced when upgrading the installation.

program/js/

Client JavaScript files

program/lib/

External libraries used for RoundCube

program/include/

Classes and core functions

program/localization/

Contains subfolders with localization files.

program/steps/

Include files for every task/action

bin/

Commandline tools and shell scripts for internal use

logs/

Contains log files. This folder has to be writable for the webserver.

temp/

Location of temporary saved files such as attachments and cache files
This folder has to be writable for the webserver.

skins/

Contains skin subfolders

SQL/

SQL files for database initialization and update. Only needed for installations or upgrades.

Important files

All requests from the client are sent to index.php. This index file loads all core components and establishes connections to the database and the IMAP server. It analyzes the request and then includes one of the step files. Direct access to config, log and temp folders should not be permitted.

For Apache webservers which allow local overrides, the .htaccess file includes some PHP configuration settings as well as file access directives. More .htaccess files are located in the protected folders mentioned above.

Naming conventions

File names

In general all files should have the appropriate extension such as .php, .js, etc. For PHP include files that are not meant to be executed directly please use the extension .inc. This prevents them from being executed directly in case that the access restrictions do not work as intended.

All files should be named with lower case letters and underlines (for word separation).

Functions and variables

Function and variable names should only contain lower case letters and numbers and use underlines for word separation. In classes, private methods usually start with an underline.

Functions providing RoundCube specific functionality should start with either rcmail_ (webmail specific functions) or rcube_ (global/framework functions).

Code style

All code (PHP and JavaScript) obeys the same code style guidelines:

• Opening and closing brackets for function and class definitions are on a new line
• Never write control-flow code on a line
• Code should not exceed a limit of 80 characters per line
• Never omit brackets for blocks containing only one statement
• Indentation consists of 4 spaces per level and no tabs!
• Conventional operators should be surrounded by a space
• Commas should be followed by a space
• Semi-colons in for statements should be followed by a space
• All names should be written in English
• Logical units within a block should be separated by at least one blank line
• Iterator variables should be called "i", "j", "k", etc.
• Globals vars (PHP) should be named in upper case
• Variables should be initialized where they are declared and they should be declared in the smallest scope possible
• In general, we adhere to ​PEAR CS

Good code:

function foo_bar($aa, $bb)
{
    $out = '';

    if ($aa == 1 || $aa > 10) {
        $out .= "Case one\n";
        write_log("Foo: $aa");
    }

    for ($i=0; $i < $bb; $i++) {
        $out .= $i."a";
    }
    return $out;
}

The bracket indentation of the existing code differs from this example but I guess we should move towards this more common indentation style.

Bad code:

function fooBar($aa,$bb) {
  if ($aa==1 || $aa>10){
    $out.="Case one\n";
    write_log("Foo: $aa");
  }
  for ($i=0;$i<$bb;$i++)
  {
    $out.=$i."a";
  }
  return $out;
}

PHP Coding

All code should be functional in PHP 4.3.x and PHP 5.x. Especially for classes, you need to write constructors that work in both PHP versions. When working with files please also make sure that the code works with safe_mode enabled. Set error reporting to E_NOTICE to see if all variables are properly declared.

For security reasons NEVER access GET/POST variables directly but use get_input_value() instead. See PHP Commons for details.

Comments/Documentation?

Please add comments to logical code blocks giving a short description what this part is intended to do. For PHP classes, please add ​PHPDoc styled descriptions for public methods. Private method descriptions are optional.