Improve Laravel code readability using PHPDoc

Meathanjay Baidya — Fri, 17 Apr 2020 21:36:04 +0000

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

DEV Community: Meathanjay Baidya

Improve Laravel code readability using PHPDoc