Laravel注释用PHPDoc吗

本文目录导读：

1. 为什么 Laravel 用 PHPDoc？
2. Laravel 中常见的 PHPDoc 应用场景
3. PHPDoc 标签在 Laravel 中的常用写法
4. 是否必须用 PHPDoc？

是的，Laravel 官方推荐使用 PHPDoc 注释，这是 Laravel 社区的标准实践，也是提升代码可读性和 IDE 智能提示的关键工具。

为什么 Laravel 用 PHPDoc？

1. IDE 智能提示：Laravel 大量使用魔术方法（如 __call、__get、门面 Facades、动态属性），没有 PHPDoc 的话，IDE 无法识别返回类型。

   // 没有 PHPDoc，IDE 不知道 $user 有哪些属性
   $user = User::find(1);
   $user->email; // IDE 无法自动补全

2. Laravel 专有功能：如 Eloquent 模型中的 @property 用于声明数据库字段、@mixin 用于 Trait、@method 用于动态方法。

3. 静态分析工具：PHPStan、Psalm 等工具依赖 PHPDoc 进行类型检查,减少运行时错误。

Laravel 中常见的 PHPDoc 应用场景

Eloquent 模型

/**
 * Class User
 *
 * @package App\Models
 * @property int $id
 * @property string $name
 * @property string $email
 * @property \Carbon\Carbon $email_verified_at
 * @property string $password
 * @property \Carbon\Carbon $created_at
 * @property \Carbon\Carbon $updated_at
 * @method static \Illuminate\Database\Eloquent\Builder|User query()
 * @method static \Illuminate\Database\Eloquent\Builder|User whereId($value)
 * @method static \Illuminate\Database\Eloquent\Builder|User whereName($value)
 * @mixin \Illuminate\Database\Eloquent\Builder
 */
class User extends Authenticatable
{
    // ...
}

门面 Facades

/**
 * @method static \Illuminate\Support\Collection pluck($column, $key = null)
 * @method static \Illuminate\Support\Collection map(callable $callback)
 * @see \Illuminate\Support\Collection
 */
class Cache extends Facade
{
    // ...
}

控制器方法

/**
 * 显示用户列表
 *
 * @param Request $request
 * @return \Illuminate\Contracts\View\View
 *
 * @throws \Illuminate\Auth\Access\AuthorizationException
 */
public function index(Request $request): View
{
    // ...
}

自定义辅助函数

/**
 * 获取用户全名
 *
 * @param string $firstName
 * @param string $lastName
 * @return string
 *
 * @throws \InvalidArgumentException
 */
function fullName(string $firstName, string $lastName): string
{
    // ...
}

PHPDoc 标签在 Laravel 中的常用写法

是否必须用 PHPDoc？

• 不是强制要求，但强烈推荐，Laravel 本身的内核代码大量使用 PHPDoc,官方文档也建议这样做。
• 小项目/原型：可以省略,但生产中建议加上。
• 使用 Laravel IDE Helper：可以自动生成模型的 PHPDoc，减少手动编写工作：

  composer require --dev barryvdh/laravel-ide-helper
  php artisan ide-helper:models

• Laravel 推荐使用 PHPDoc,且这是社区标准。
• 主要解决 IDE 智能提示 和 静态类型检查 问题。
• 在模型、门面、控制器、自定义方法中优先使用。
• 配合 laravel-ide-helper 可以自动化部分工作。

如果你想让代码更专业、更易维护，建议养成写 PHPDoc 的习惯。