This document in intended to provide the reader with the programming styles 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.
Table of Contents |
---|
PHP File Formatting
Tags
PHP code must always begin with the long form opening tag. If a file contains only PHP code, the end tag may optionally be omitted from the end of the file.
<?php ?>
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.
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).
Character Encoding
All PHP files should be encoded using UTF-8, with no byte-order-mark (BOM).
Programming Styles
Strings
Literals
Strings consisting of more than one character should be surrounded with double-quotes ("). Strings consisting of only a single character may be surrounded with single-quotes (').
$str = "This is a long string"; $chr = 'a';
Concatenation
Run-on Strings
A string whose length requires it to wrap multiple lines should be concatenated with the concatenation character (.) appended at the end of the line, with the carry-over line indented below it.
$str = "This is a string that needs to " . "wrap onto another line.";
Variable Substitution
When a variable needs to be added to a string the string should be broken open and concatenated together to improve readability.
$name = "Hefo Quient Esbit"; $str = "Hello " . $name . "! How are you?"
Arrays
Numerically Index Arrays
Associative Arrays
Multidimensional Arrays
Constants
Constants should always be capitalized.
Incorrect
define("myConstant", "some value");
Correct
define("MY_CONSTANT", "some value");
Statements
Blesta uses Compact Control Readability style. Each statement should begin on its own line.
Correct
if ($foo > $bar) { echo "foo is greater"; } else { echo "bar is greater"; }
Classes
Methods
Comments
There are three types of comments that may be used in PHP. They are block comments (/* */), inline comments (//), and shell comments (#).
Block Comments
Block comments are used for doc commenting and commenting out large sections of code. Blesta uses PHPDoc syntax for all doc comments. Block comments may not be used as a substitute for inline comments.
Incorrect
/* This is a comment. */ if ($foo > $bar) { return $bar }
Correct
/** * This is a DocBlock comment */ function foo() { }
Inline Comments
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.
Incorrect
/* Calculate the circumference */ $c = 2*pi()*$r;
Correct, but discouraged
$c = 2*pi()*$r; // Calculate the circumference
Correct
// Calculate the circumference $c = 2*pi()*$r;
Shell Comments
These comments should only be used to identify TODO comments.
Incorrect
# Calculate the circumference $c = 2*pi()*$r;
Correct
<?php class MyClass { # # TODO: Finish this class. # } ?>