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;
    }
}

Do not use Dispatchable

Using the MyEvent::dispatch() helper hides the event's (or job's) constructor method signature from the IDE, making it harder to follow code paths and refactor code.

Prefer

event(new UserCreated($user));

dispatch(new SendWelcomeEmail($user));

Avoid

UserCreated::dispatch($user);

SendWelcomeEmail::dispatch($user);

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.