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.