PhpStorm新建PHP文件命名空间为空，主因是未配置文件模板与源码根目录：需保留#parse("PHP File Header.php")、确保该文件在Includes下、将src等目录标记为Sources Root，并为interface/trait单独配置模板。
新建 PHP 文件时命名空间为空、没 PHPDoc、接口写成 class ——不是 PhpStorm 抽风，是文件模板根本没配对。
PHP Class 模板里 $NAMESPACE$ 为空或不替换
这是最常卡住的点：你写了 namespace ${NAMESPACE}，生成文件里却空着，或者直接显示文字 ${NAMESPACE}。
- 必须保留第一行
#parse("PHP File Header.php")，否则${NAMESPACE}永远为空；这个#parse是 PhpStorm 解析命名空间的唯一入口 -
PHP File Header.php要在 Includes 标签下存在（哪怕内容为空），不能只在 Files 下有PHP Class模板 - 项目根目录下对应源码路径（比如
src/）必须右键 → Mark Directory as → Sources Root，否则 IDE 不知道从哪推导命名空间 - 改完模板后不重启 PhpStorm，缓存会继续输出原始变量名，比如
$DATE$不变日期、$NAME$不替换成类名
Interface / Trait 新建后语法错误（class UserServiceInterface）
默认 PHP Class 模板不区分语言结构，interface 和 trait 全套复用 class 模板，结果生成非法语法。
- 去 File and Code Templates → Files，复制一份
PHP Class，重命名为PHP Interface - 把
class ${NAME}改成interface ${NAME}，删掉extends \Exception、implements等类专属内容 - 同理新建
PHP Trait模板，只留trait ${NAME}，别加extends或implements -
${NAME}可用，但${CLASS_NAME}是弃用变量，别用
PHPDoc 块换行错乱或不生效
你加了 /** @package ${NAMESPACE} */，结果注释贴在 class 同一行，或者生成后多出空行、缩进崩坏。
立即学习“PHP免费学习笔记（深入）”；
- 必须用块级写法：
/**开头 + 换行 +*+ 换行 +*/结尾，别写成单行/** @package */ - PHPDoc 要放在
namespace声明之后、class声明之前，顺序错就可能被 IDE 当作普通注释处理 - 如果用了
#parse("xxx")引入其他模板，被引入的文件也得在 Files 分类下（不是 Includes），否则变量不传递 -
@inheritdoc不会自动加到接口方法文档里，得手动补进PHP Interface模板的 PHPDoc 中
${DATE} 格式固定，想改 YYYY-MM-DD 怎么办
${DATE} 在 PhpStorm 里硬编码为 YYYY/MM/DD，没法通过变量配置改；${YEAR}-${MONTH}-${DAY} 这种写法也不支持。
- 可用组合：
${YEAR}-${MONTH}-${DAY} ${HOUR}:${MINUTE}，它们是独立变量，能拼出2026-05-08 12:32 -
${TIME}格式取决于系统当前时间（资料日期为 2026 年 5 月 8 日） - 改完 PHP File Header 模板后必须点 Apply，仅点 OK 不生效
文件模板只管「新建文件」那一刻的骨架，它不响应快捷键、不插入选中代码、不生成函数体——那些是 Live Templates 的事。很多人调了半天 $NAMESPACE$ 却发现新建类还是没命名空间，最后发现根本没标记 src/ 为 Sources Root，这种路径识别问题最容易被忽略。
