Style Guide¶
For the most part, we follow PSR-12, this should be enforced by PHP CS Fixer. There are some exceptions to this, which are listed below.
- Space after casts
- Space after unary operators
The PHP CS Fixer configuration can be found under laravel/.php-cs-fixer.php
. Each section of rules contains a link to the relevant PHP CS Fixer documentation.
Type hinting¶
Whenever possible, type hinting should be used. This includes return types, parameters, and properties. Do not use docblocks for type hinting.
class Foo
{
public string $name;
public function setName(string $value): void
{
$this->name = $value;
}
}
Enums¶
Values in enums should use PascalCase
.
enum UserType: string
{
case Customer = 'customer';
case Staff = 'staff';
}
Docblocks¶
Do not use docblocks for methods that can be fully type hinted (unless you need to add additional comments).
Prefer
class UserService
{
public function findByName(string $name): User
{
// ...
}
}
Avoid
class UserService
{
/**
* Find a user by its name.
*
* @param string $name
*
* @return User
*/
public function findByName(string $name): User
{
// ...
}
}
Always import classnames in docblocks.
Prefer
use App\Models\User;
/**
* @param User $user
*/
Avoid
/**
* @param \App\Models\User $user
*/
Docblocks for iterators¶
When an iterable type is used anywhere, always define the key and value type of the iterable.
/**
* @param \Illuminate\Support\Collection<int, User> $users
*/
If an array always has the same shape, you can type hint the keys like this:
/**
* @param array{type: string, message: string} $result
*/
Constructor property promotion¶
Whenever possible, use constructor promotion instead of manually assigning properties. This is especially useful for value objects and DTOs. It is also useful for classes that rely on dependency injection.
Prefer
class UserDTO
{
public function __construct(
public string $name,
public string $email,
) {
}
}
Avoid
class UserDTO
{
public string $name;
public string $email;
public function __construct(string $name, string $email)
{
$this->name = $name;
$this->email = $email;
}
}
Updating PHPDocs on Eloquent Models¶
You should update the PHPDoc on a model when you change it in any of the following ways:
- Adding a new column
- Changing the name or type of a column
- Adding, changing or removing a relationship
- Adding, changing or removing a mutator
- Adding, changing or removing a scope
- Adding, changing or removing a cast
Updating the PHPDoc can be automatically done using the php artisan ide-helper:models -RW
command.