首页 >后端开发 >php教程 >如何来正确注释@return来让PHPstorm动态返回类

如何来正确注释@return来让PHPstorm动态返回类

不言原创: 2018-08-01 11:33:583924浏览

这篇文章给大家介绍的内容是关于正确注释@return让PHPstorm动态返回类，有一定的参考价值，有需要的朋友可以参考一下，希望对你有所帮助。

场景是这样的，有一个BaseModel（继承自ActionRecord），所有的其他model都继承自它，然后其中有一个方法，简单贴下这个类的代码：

class BaseModel extends ActiveRecord
{
    protected $temp_model;
    
    public function getCacheModel()
    {
        return $this->temp_model;
    }
}

这个方法的作用是取得在做参数验证时，从数据库查出的，缓存下来的实例对象。
这个时候，问题来了，我在取出这个对象的时候，PHPstorm没有了提示（如方法提示，属性提示等），按照一般的情况，只需要在方法前面加上@return注释就可以了。

/**
 * @return static
 */
public function getCacheModel()
{
    return $this->temp_model;
}

我们继续深入研究一下，关于这个static的意思，我特地在PHPDoc上查阅了一下，

static
An object of the class where this value was consumed, if inherited it will represent the child class. (see late static binding in the PHP manual).

Google翻译一下，大意如下：
消耗此值的类的对象，如果继承它将表示子类。
（参见PHP手册中的后期静态绑定）。

大概意思就是就会返回调用这个方法的类，如果是父类方法子类调用，那么将返回子类。

类似的还有2个

self
An object of the class where this type was used, if inherited it will still represent the class where it was originally defined.
$this
This exact object instance, usually used to denote a fluent interface.

直译如下，
self:使用此类型的类的对象，如果继承它，它仍将表示最初定义它的类。
大意就是和static差不多，但是父类方法子类调用，仍然返回父类。
$this:这个确切的对象实例，通常用于表示流畅的界面。
和self差不多。

但是到了这里，我的问题仍然没有解决，无论我@return的值改成什么，仍然返回的是BaseModel，尽管我在这个getCacheModel()方法里打印 self::className() 时，出现的是子类名。

于是我们继续往上面看，我是在controller调用的，controller的代码如下：

public function actionCommitReward()
{
    $model=$this->goCheck(new TakeRewards(['scenario'=>'commit_reward']));

    //获取实际要修改的数据
    $reward = $model->getCacheModel();
}

看起来没有什么问题，这个时候我们要注意了， $model 是由$this->goCheck()调用得到的，我们去看一下goCheck方法：

//验证参数是否合法
public function goCheck($model, $dada = '')
{
    $data = $this->postData;//post传入的数据
    if ($model->load($data, '') && $model->validate())//数据效验

return $model;

    else (new PublicFunction())->returnWayTip('1001', PublicFunction::getModelError($model));//这里理解成抛异常
}

这里不规范的地方出现了，由于这里传入的是model（对象类型），所以PHPstorm并没法知道我们具体传入的是什么类，加上注释后：

/**
 * @param object $model
 * @param string $dada
 * @return model1|model2
 */

这样后，问题“勉强解决”。只是每增加一个表，会需要在@return里增加表相对应的类名，而且会有类本来不应该存在的属性被提示。

为什么这里不能用static呢？因为这里是$this调用的，返回controller类，并没有什么用，而这个也导致了后面使用$model->getCacheModel()方法时，没有办法正常识别应该返回的类（返回什么类取决与goCheck的@return注释是什么）。

当然你可以不写注释，那么你会发现，所以的提示都没有了。
这次我才真正意识到了注释的重要性。。。原来PHPstorm之所以都提示，都是因为大家按PHPDoc的规范写了注释啊！

最后可能有同学会问了，为什么不把goChekc方法放到BaseModel里呢？对的，实际上规范的做法是应该这样的，但是因为我这样把Yii::$app->request->post()赋值在controller里的$this->postData里（虽然这样方便一丢丢），而且在做token换id的一些操作了进行了手动赋值，所以没有办法，因为在model获取不到这个postData，当然你一定要挪进去也是可以的，只不过每次都需要传参$this->postData，见仁见智吧。

但是，这2个方法都并不规范，$this->postData = Yii::$app->request->post(); 把全局的变量变成了一个局部变量，规范的做法应该是使用Yii::$app->request->post($name,$dafaultValue)来给post数据赋值。

最后，因为并不是我一个人在写，所以没有办法进行大刀阔斧地改动，只能尽可能地优化。

如何来正确注释@return来让PHPstorm动态返回类

相关文章