PHP7.4升级后Doctrine AnnotationReader无法解析含重音字符的注释

问题概述 #

升级至PHP 7.4后，所有继承Repo\Entity的Doctrine实体（如Site\Entities\MyEntity）均报错：

class "Site\Entities\MyEntity" sub class of "Repo\Entity" is not a valid entity or mapped super class.

排查后确认：Doctrine的AnnotationReader无法读取实体类注解，原因是注释中存在重音字符（例如hérite中的é），替换为普通字符后恢复正常。但此类注释大量存在于Composer依赖中，手动修改成本过高。

已知情况与可行解决方案 #

该问题属于PHP 7.4编码处理逻辑调整与旧版Doctrine Annotation组件的兼容性问题，目前无官方配置项直接修复，但有两种可行解决方式：

1. 升级Doctrine Annotation组件 #

Doctrine Annotation组件在后续版本中修复了PHP 7.4+的非ASCII字符注释解析问题，执行以下命令升级到最新稳定版：

composer require doctrine/annotations:^1.13

（可根据项目依赖兼容性调整具体版本，优先选择最新稳定版）

2. 自定义AnnotationReader处理编码 #

若无法升级组件，可自定义AnnotationReader，强制将注释转换为UTF-8后再解析：

use Doctrine\Common\Annotations\AnnotationReader;
use Doctrine\Common\Annotations\Reader;

class Utf8AnnotationReader extends AnnotationReader implements Reader
{
    protected function getClassAnnotations(\ReflectionClass $class)
    {
        $docComment = $class->getDocComment();
        // 自动检测并转换注释编码为UTF-8
        if ($docComment !== false) {
            $docComment = mb_convert_encoding($docComment, 'UTF-8', mb_detect_encoding($docComment));
        }
        // 利用反射重新构建类注释并解析
        $reflection = new \ReflectionClass($class->getName());
        $reflection->setDocComment($docComment);
        return parent::getClassAnnotations($reflection);
    }

    // 按需覆盖方法、属性注释的解析逻辑
    protected function getMethodAnnotations(\ReflectionMethod $method)
    {
        $docComment = $method->getDocComment();
        if ($docComment !== false) {
            $docComment = mb_convert_encoding($docComment, 'UTF-8', mb_detect_encoding($docComment));
        }
        $reflection = new \ReflectionMethod($method->class, $method->getName());
        $reflection->setDocComment($docComment);
        return parent::getMethodAnnotations($reflection);
    }

    protected function getPropertyAnnotations(\ReflectionProperty $property)
    {
        $docComment = $property->getDocComment();
        if ($docComment !== false) {
            $docComment = mb_convert_encoding($docComment, 'UTF-8', mb_detect_encoding($docComment));
        }
        $reflection = new \ReflectionProperty($property->class, $property->getName());
        $reflection->setDocComment($docComment);
        return parent::getPropertyAnnotations($reflection);
    }
}

之后在Doctrine配置中替换默认的AnnotationReader为自定义的Utf8AnnotationReader即可。

补充说明 #

PHP 7.4对字符串编码的内部处理逻辑做了调整，导致旧版Doctrine Annotation组件无法正确识别含非ASCII字符的注释。升级组件是最彻底的解决方案，自定义Reader则适用于无法升级依赖的场景。

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