Coding Standards of WebFiori Framework
In this page:
Autoload
The framework has its own autoloader implementation which follows PSR-4 in almost all aspects of autoload. There are some differences which are:
- The autoloader will throw
ClassLoaderException
if a class was not found. - It is recommended that a fully qualified class name to have the following form:
vendorName\subNamespaceNames\ClassName
(names uses camleCase).
The framework can be configured to not throw an exception. This can be performed during the process of initializing the autoloader AutoLoader .
Coding Style
Recommended coding style is driven from PHP's recommended style and PSR, but it does not strictly follow it. For this reason, there are few differences. The rules are divided into two types, styles that must always be followed and recommended styles.
Must Follow
- Always use
<?php
instead of<?
for PHP tags. - In case of templates, use the short-hand
echo
command (e.g.<?= 'A a string' ?>
instead of<?php echo 'A a string' ?>
). - Namespaces must be all
lower\case
. - Class constants and global constants names must be declared in
ALL_CAPS
.
Code
define('MY_CONST', 44);
const CLASS_CONSTANT = 44;
- Methods names, non-static class attributes must be declared in
camelCase
.
Code
class Hello {
private $fullName;
private $email;
public function helloWorld() {
}
}
- Classed names, static attributes names must be declared in
PascalCase
.
Code
class HelloWorldClass {
public static $HelloString;
}
- An opening braces
{
must be on the same line for functions, method and class declaration. - Never use
elseif
. Always useelse if
. - Always include access modifiers for class methods, even if they are public.
- Do not use aliases for imported classes or class constants (e.g.
use webfiori\MyClass as XYZ
). - Method names and attributes must be defined as follows, first include access modifier followed by
static
or/thenfinal
.
Code
public static final function myFunc() {
}
- For comparison, always use strict comparison (
===
or!==
) when comparingbool
ornull
. - Do not use the construct
empty()
to check fornull
values. - Use 'null coalescing operator' when needing to use a ternary in conjunction with
isset()
Code
//Wrong
$nextLine = isset($traceEntry['line']) ? $traceEntry['line'] : 'X';
//Accepted
$nextLine = $traceEntry['line'] ?? 'X';
Recommendations
- Always place PHP code in classes.
- Always specify method parameter's data type.
- Always specify method's return type.
Unit Tests Style
- The name of test classes should always follow this syntax:
class XXXTest {
}
Code
In this context, the `XXX` should be replaced by entity name that test class represent. (e.g. `GenerateReportTest`).
* Name of test methods should always follow this syntax:
``` php
public function testXXX00() {
}
In this context, the XXX
should be replaced by functionality name that test class represent. (e.g. public function testGetData00{}
).
@test
annotation should be included on top of every test method.
Documentation Style
The PHPDoc block must be similar to the following style:
Code
/**
* SHORT_DESC.
*
* LONG_DESC.
*
* @annotation1 DETAILS
*
* @annotation2 DETAILS
*/
Where:
SHORT_DESC
is a short description of the class or method. Must be ended by a dot.LONG_DESC
is a big paragraph that contains more details.@annotation1
and@annotation2
are simple PHPDoc annotations such as@return
or@param
.
Notice that each part of the doc block must be followed by an empty space. This helps in improving readability.