Improve Laravel code readability using PHPDoc

If you're writing PHP lately, very likely to know the Laravel framework, very easy to get started, and more likely, you can develop the same MVP app at the lowest time in compared to other frameworks. It has rich built-in and ready-to-use packages and easy configuration and huge community support, and all while you don't have to compromise the performance.

If you're writing Laravel applications, you know how extensively Laravel uses PHP's magic methods, especially in Eloquent.

You never explicitly mention a Model's properties except making some fields guarded and mass-assignable. When you try to access that property, the __get method looks for database columns with the same name or return null; you access any defined relation as property in the same way.

Even $user->is_avaiable is a boolean property, IDE shows mixed because you never declared that and your IDE can't help with auto-completion or if you mistyped a character.

And, how you know a property is available in that model class? Well, in your head, because you created the migration, database schema; What about the new developers or your future-self?

Your model is not so readable, and no one can guess $user->is_available or $users->projects exists or type until looking into columns and parent classes.

So, why not make your code self-explanatory and let your IDE help you avoid making a mistake and help your future self?

PHPDoc can help you add a piece of information in a code block like file, class, properties, methods, and variables.

PHPDoc is the same as multiline comments but starts with a forward-slash and two asterisks(/**) and ends with an asterisk and forward-slash(*/), in-between you add those missing information in PHPDoc DSL language.

<?php

namespace App\Domain\User;

use Illuminate\Database\Eloquent\Relations\HasMany;
use Illuminate\Foundation\Auth\User as Authenticatable;

/**
 * User Model
 *
 * @property bool $is_available
 * @property-read Project[] $projects
 * @method static User create(array $attributes = [])
 * @method static \Illuminate\Database\Eloquent\Builder where($column, $operator = null, $value = null, $boolean = 'and')
 */
class User extends Authenticatable
{
    protected $guarded = [
        'id', 'email_verified_at', 'remember_token',
    ];

    protected $hidden = [
        'password', 'remember_token',
    ];

    public function projects(): HasMany
    {
        return $this->hasMany(Project::class);
    }
}

Now, those missing properties and methods are self-explanatory, and you know precisely what their type and return value.

Declaring return type for create method in the User model, let you avoid re-declaring return type every-time you call create and it makes your code clean and maintainable.

$user = User::create($data);

// instead

/** @var User $user */
$user = User::create($data);

Comments

[PatricNox]

I find PHPDoc to be too aggressive when it comes to prop comments.

In my opinion it would be against the DRY principle to have both propdoc and docblock. Specially, specially, when also typehinting the method.

I mean that something like this is a no-no for me.

/**
 * Method title.
 *
 * Method description.
 * 
 * @param  type  $var
 * @return type
 */
protected function method_title(type $arg): type
{
    /** @var type $arg */
    $type = type::create($arg);

    /** @var type $arg */
    return $type;
}

[Meathanjay Baidya]

I would not use PHPDoc for this method here. when you declared the $arg type and return type, it's self-explanatory and any modern IDE can catch that, PHPDoc here just makes unnecessarily noisy.

If you add a return type to create method via either PHPDoc or method itself, $type = type::create($arg); prop comments is unnecessary.

[PatricNox]

Exactly my point.

And mixing use cases when and when not to include phpdoc syntax is even worse: It removes the whole concept of code style when it's not even followed.