This document describes the programming style and best practices used in Blesta. Programmers wishing to certify their plugin, module, or gateway, with the Marketplace must conform to these guidelines regardless of whether or not their source code is made available to end users.
Blesta primarily follows a PSR-2 coding style guide.
Table of Contents |
---|
Table of Contents |
---|
maxLevel | 4 |
---|
minLevel | 2 |
---|
outline | true |
---|
class | toc |
---|
|
|
...
Indentation
Tabs should always be used for indentation. Spaces should never be used for indentation. We live in a world where IDEs can be configured to display tabs at variable lengths, so configure your tab width to what you feel comfortable with. This author prefers tabs to be represented as 4 spaces.
Line Length
Lines should be designed such that a reader can avoid horizontal scrolling, except in cases where scrolling offers improved readability over word-wrapping. As the resolution and width of monitors has increased the standard width of 80 characters (previously the width of a punch card) no longer holds any relevance. Use your best judgement to determine where lines should wrap. Blesta uses a 120-character limit for *.php files and best judgement for *.pdt files.
EOL
Every line should terminate with a Unix-style line-feed (LF) character only. That is '\n', also known as hex value 0x0A. Do not use CRLF (Windows systems) or CR (Mac systems).
...
Tip |
---|
|
Code Block |
---|
| $year_days = 365;
$leap_year_days = 366; |
|
Strings
Literals
Strings consisting of more than one character should be surrounded with doublesingle-quotes ("). Strings consisting of only a single character may be surrounded with single'), except where double-quotes ('") are necessary in php.
Code Block |
---|
|
$str = "'This is a long string"';
$chr = 'a';
$double_str = "Double-quoted string to include a new line\n"; |
Concatenation
Run-on Strings
A string whose length requires it to wrap multiple lines should may be concatenated with the concatenation character (.) appended prepended at the end beginning of the next line to be concatenated, indented accordingly. A single string with the carry-over line indented below itnew lines within the string is also acceptable.
Code Block |
---|
|
$str = "'This is a string that needs to'
" .
. ' "wrap onto another line."';
$str2 = 'This is a string that
spans multiple lines, but
the new-line white-space
is not relevant'; |
Variable Substitution
When a variable needs to be added to a string the string should be broken open and concatenated together to improve readability.
Code Block |
---|
|
$name = "'Hefo Quent Esbit"';
$str = "'Hello "' . $name . "'! How are you?"'; |
Arrays
Numerically Index Arrays
...
Tip |
---|
|
Code Block |
---|
| $shapes = array("circle"['circle', "'square"', "'triangle"', "'hexagon")'];
$colors = array([
"'red"', "
'pink"',
"'green"', "
'purple"'
)]; |
|
Associative Arrays
Associative arrays should have a space before and after the => assignment . Array indexes operator, just like all operators should. Strings should be quoted using single quotes ('). Short arrays can contain all elements on a single line, but it's recommend to set each index on its own line.
Tip |
---|
|
Code Block |
---|
| $blocks = array([
'circle' => "'red"',
'square' => "'pink"',
'triangle' => "'green"',
'hexagon' => "'purple"'
)]; |
|
Multidimensional Arrays
Each array depth should be indented one level. The ending parenthesis of the array should be indented such that it aligns with the indent level of its defining index.
Tip |
---|
|
Code Block |
---|
| $polygons = array([
'triangles' => array([
"'obtuse"',
"'acute"',
"'right"'
)],
'quadrilaterals' => array([
"'square"',
"'rhombus"',
"'rectangle"'
)]
)]; |
|
Constants
Constants should always be capitalized.
Warning |
---|
|
Code Block |
---|
| define("'myConstant"', "'some value"'); |
|
Tip |
---|
|
Code Block |
---|
| define("'MY_CONSTANT"', "'some value"'); |
|
Statements
Blesta uses Compact Control Readability style PSR-2 control structure styles. Each statement should begin on its own line. The exception to this rule is do-while.
Warning |
---|
|
Code Block |
---|
| if ($foo > $bar)
{
echo "'foo is greater"';
} else
{
echo "'bar is greater"';
} |
|
Tip |
---|
|
Code Block |
---|
| if ($foo > $bar) {
echo "'foo is greater"';
}
else {
echo "'bar is greater"';
}
$i = 5;
do {
echo $i--;
} while ($i > 0); |
|
...
Warning |
---|
|
Code Block |
---|
language | php |
---|
title | my_class.php |
---|
linenumbers | true |
---|
| <?php
// Class name starts with a lower case letter
class myClass
{
// Constructor should be named __construct()
public function myClass()
{
// Do stuff
}
}
?> |
|
Tip |
---|
|
Code Block |
---|
language | php |
---|
title | my_class.php |
---|
linenumbers | true |
---|
| <?php
class MyClass
{
public function __construct()
{
// Do stuff
}
}
?> |
|
Member Variables
All member variables should be declared at the top of the class, before any methods are declared. Variables must always declare their visibility using public, private, or protected.
Warning |
---|
|
Code Block |
---|
language | php |
---|
linenumbers | true |
---|
| <?php
class MyClass {
// Can not use var, must use public, private, or protected
var $foo;
public function __construct()
{
// Do stuff
}
// Must be declared at the top of the class
private $bar = "baz";
}
?> |
|
Tip |
---|
|
Code Block |
---|
language | php |
---|
linenumbers | true |
---|
| <?php
class MyClass
{
public $foo;
private $bar = "'baz"';
public function __construct()
{
// Do stuff
}
}
?> |
|
Methods
Method names should begin with a lowercase letter and be camelCased. Type hinting should be used whenever possible, but must conform to PHP 5.1 4 syntax (i.e. only objects, arrays, and arrays callables may be defined using type hints).
Warning |
---|
|
Code Block |
---|
| public function CalcDistance($time, $velocity)
{
return $time * $velocity;
} |
|
Tip |
---|
|
Code Block |
---|
| public function calcDistance($time, $velocity)
{
return $time * $velocity;
} |
|
There are three types of comments that may be used in PHP. They are block comments (/* */), inline comments (//), and shell comments (#).
...
Tip |
---|
|
Code Block |
---|
| /**
* This is a doc block comment
*
* @param string $bar The value
*/
function foo($bar)
{
} |
|
Inline comments should be used to clarify code. You are discouraged from using inline comments at the end of a line as this creates run-on lines and your comment is unlikely to be read.
Warning |
---|
|
Code Block |
---|
| /*
Calculate the circumference
*/
$c = 2 * pi() * $r; |
|
Note |
---|
title | Correct, but discouraged |
---|
|
Code Block |
---|
| $c = 2 * pi() * $r; // Calculate the circumference |
|
...
Tip |
---|
|
Code Block |
---|
| // Calculate the circumference
$c$circumference = 2 * pi() * $r; |
|
These comments should only be used to identify TODO comments.
Warning |
---|
|
Code Block |
---|
| # Calculate the circumference
$c = 2 * pi() * $r; |
|
Tip |
---|
|
Code Block |
---|
language | php |
---|
firstline | 1 |
---|
linenumbers | true |
---|
| <?php
class MyClass
{
#
# TODO: Finish this class.
#
}
?> |
|