Code formatting used in Yii 3 packages is based on PSR-1 and PSR-12 with extra rules added on top of it.
- Use English only.
- Use camelCase notation, including abbreviations (e.g.,
enableIdn). - Use the shortest possible, but an explanatory name.
- Never trim or abbreviate name.
- Postfix classes, interfaces, traits and variables, which is a collection, with
Collection.
- Declare argument and return types where possible.
- Use types for properties.
- Use strict typing. Avoid mixed and union types where possible except compatible types such as
string|Stringable.
Inline comments are to be avoided unless code couldn't be understood without them. A good example is a workaround for a bug in a certain PHP version.
Method comment is necessary except it adds nothing to what method name and signature already has.
Class comment should describe the purpose of the class.
Property, variable and constant value assignments shouldn't be aligned. The same applies to phpdoc tags. The reason is that aligned statements often cause larger diff and even conflicts.
final class X
{
const A = 'test';
const BBB = 'test';
private int $property = 42;
private int $test = 123;
/**
* @param int $number Just a number.
* @param array $options Well... options!
*/
public function doIt(int $number, array $options): void
{
$test = 123;
$anotherTest = 123;
}
}Chained calls should be formatted for better readability. If it's a long chain that doesn't fit the line length of 120 characters, then each call should on a new line:
$object
->withName('test')
->withValue(87)
->withStatus(Status::NEW)
->withAuthor($author)
->withDeadline($deadline);If it's a short chain, it's alright for it to be on a single line:
$object = $object->withName('test');- When no variables involved, use
'Hello!' - To get variables into string prefer
"Hello, $username!"
Classes should be final by default.
Constants, properties and methods should be private by default.
Prefer composition to inheritance.
Order should be the following:
- Constants
- Properties
- Methods
Within each category, items should be sorted by visibility:
- public
- protected
- private
Abstract classes shouldn't be prefixed or postfixed with Abstract.
Immutable method convention is the following:
public function withName(string $name): self
{
$new = clone $this;
$new->name = $name;
return $new;
}- Cloned object name is
$new. - Return type is
self.
Methods that are there to check if something is true should be named like the following:
public function isDeleted(): bool;
public function hasName(): bool;
public function canDoIt(): bool;Boolean flags in methods are better to be avoided. It's a sign the method may be doing too much, and there should be two methods instead of one.
public function login(bool $refreshPage = true): void;Is better to be two methods:
public function login(): void;
public function refreshPage(): void;Add an underscore (_) prefix for unused variables. For example:
foreach ($items as $key => $_value) {
echo $key;
}Prefer importing classes and functions to using fully qualified names:
use Yiisoft\Arrays\ArrayHelper;
use Yiisoft\Validator\DataSetInterface;
use Yiisoft\Validator\HasValidationErrorMessage;
use Yiisoft\Validator\Result;
use function is_iterable;