使用 PHPDoc 来提高 Laravel 代码的可读性

如果你最近正在使用PHP，很可能知道Laravel，它非常容易入门，更赞的是，与其他框架相比，你可以在最低的时间开发相同的mvp应用程序。它具有丰富的内置和现成的软件包，易于配置和活跃的社区支持，让你不必花费过多的精力和时间。

如果你正在使用Laravel，你会知道在Laravel中广泛使用了PHP的魔术方法，特别是在Eloquent中。

除了使某些字段受保护和可批量分配外，你永远不会明确提及模型中的属性。 当你尝试访问该属性时，_get方法将查找具有相同名称的数据库列或返回NULL；你可以用相同的方式访问任何定义的关系作为属性。

即使$ user-> is_avaiable是一个布尔属性，IDE也会混合显示，因为你从未声明过，并且IDE无法帮助自动完成或输入错误的字符。

而且，你如何知道该模型类中有哪些可用的属性呢？ 好吧，如果这都在记在你脑子里了，因为你已经创建了迁移，但是新开发者或你以后回想的时候应该怎么办呢？

你的Model可读性不强，没有人能猜到$user->is_available，或者$users>projects是否存在，直到一步一步去追溯到查看列和父类为止。

那么，为什么不让你的代码能够自我表达意义，让你的IDE帮助你避免犯错误并帮助以后的你？

PHPDoc可以帮助你在代码块中添加一条信息，如文件、类、属性、方法和变量。

PHPDoc与多行注释相同，以一个正斜杠和两个星号（/ **）开头，以一个星号和正斜杠（* /）结尾，在它们之间将这些你未曾记录的信息添加到PHPDoc中的DSL (译者:领域特定语言domain-specific language、DSL)。

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

现在，那些丢失的属性和方法是不言而喻的，并且你也可以确切地知道它们的类型和返回值。

在用户模型中声明create方法的返回类型，这样可以避免每次调用create时都重新声明返回类型，并使代码干净且可维护。

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

// instead

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

本文中的所有译文仅用于学习和交流目的，转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议，如果我们的工作有侵犯到您的权益，请及时联系我们。

原文地址：https://dev.to/meathanjay/improve-larave...

译文地址：https://learnku.com/laravel/t/43646