如何让PhpStorm识别Blade模板中来自View Composer的变量？

问题场景 #

我有一个sidebar.blade.php模板，用于展示数据库获取的内容，核心代码如下：

@php
    $syncLogsCountPending = $sidebarCounters['sync_logs']['pending'];
    $syncLogsCountCompleted = $sidebarCounters['sync_logs']['completed'];
@endphp

<nav id="sidebar" class="col-md-3 col-lg-2">
   <!-- 省略其他内容 -->
</nav>

IDE将$sidebarCounters标红提示“变量未定义”，但该变量实际是通过View Composer注入到模板中的，对应的Composer代码：

<?php

namespace App\Http\Composers\Backend;

use App\Repositories\Sync\SyncLogRepository;
use Illuminate\View\View;

class SidebarComposer
{
    public function __construct(
        private readonly SyncLogRepository $syncLogRepository
    ) {}

    public function compose(View $view): void
    {
        $view->with('sidebarCounters', $this->getSidebarCounters());
    }

    private function getSidebarCounters(): array
    {
        return [
            'sync_logs' => [
                'pending' => 0,
                'completed' => $this->syncLogRepository->getFinishedCount(),
            ],
        ];
    }
}

解决方案 #

1. 在Blade模板中添加PHPDoc注解 #

直接在@php块开头添加类型注解，明确告知IDE变量的存在和结构：

@php
    /** @var array{sync_logs: array{pending: int, completed: int}} $sidebarCounters */
    $syncLogsCountPending = $sidebarCounters['sync_logs']['pending'];
    $syncLogsCountCompleted = $sidebarCounters['sync_logs']['completed'];
@endphp

如果不需要精确的结构提示，也可以用简单的数组类型注解：

@php
    /** @var array $sidebarCounters */
    $syncLogsCountPending = $sidebarCounters['sync_logs']['pending'];
    $syncLogsCountCompleted = $sidebarCounters['sync_logs']['completed'];
@endphp

2. 利用Laravel IDE Helper生成元数据 #

如果项目已安装Laravel IDE Helper包，运行以下命令生成辅助文件，让IDE自动识别View Composer注入的变量：

php artisan ide-helper:generate
php artisan ide-helper:meta

注意：需确保View Composer已在应用中正确注册。

3. IDE手动配置（以PHPStorm为例） #

通过IDE的忽略功能消除错误提示：

• 右键点击标红的$sidebarCounters，选择Mark as -> Not Undefined
• 或进入Settings -> Languages & Frameworks -> PHP -> Undefined Symbols，将$sidebarCounters添加到忽略列表

内容的提问来源于stack exchange，提问作者Matt Komarnicki