Improve Laravel code readability using PHPDoc
Tags: php, laravel, phpdoc, typehint
Published: 2020-04-17 21:36:04

---
title: Improve Laravel code readability using PHPDoc
published: true
description: Improve Laravel code readability using PHPDoc
tags: PHP, laravel, phpdoc, type-hint
---
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.

![Property accessed via magic method](https://dev-to-uploads.s3.amazonaws.com/i/mx1zu0h895rtwioo98fb.png)

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
<?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.

![IDE suggestion](https://dev-to-uploads.s3.amazonaws.com/i/ua5izk328lkvsf9lm4mc.png)


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.

```php

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

// instead

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