如何在Doctrine中重命名实体属性同时保留/别名旧属性名？

我完全理解你的痛点——维护跨多个项目的遗留Doctrine库时，属性命名规范整改最怕的就是破坏现有DQL查询和findBy这类方法的调用。你一开始想到的魔术方法思路其实很合理，但确实Doctrine的核心机制是直接通过反射操作属性，会绕过PHP的魔术方法。不过咱们有几个可行的方案来解决这个问题：

方案1：自定义Doctrine属性访问器（适配findBy/直接属性操作） #

Doctrine的PropertyAccessor负责实体属性的读写，我们可以扩展它，让它自动识别旧的蛇形属性名并映射到新的驼峰属性，同时触发废弃通知。

步骤1：修改实体属性（保留数据库映射兼容） #

先把实体属性改成符合PSR-12的驼峰命名，同时通过Doctrine映射保持数据库字段名不变（如果不需要修改数据库结构的话）：

use Doctrine\ORM\Mapping as ORM;

class DummyEntity
{
    use DeprecatedEntityPropertyNames;

    /**
     * @ORM\Column(name="new_name", type="string") // 数据库字段名保持旧的蛇形
     */
    private string $newName;

    public function getNewName(): string
    {
        return $this->newName;
    }

    public function setNewName(string $newName): static
    {
        $this->newName = $newName;
        return $this;
    }
}

步骤2：编写自定义属性访问器 #

use Doctrine\Common\PropertyAccess\PropertyAccessor;

class DeprecatedPropertyAccessor extends PropertyAccessor
{
    private function snakeToCamel(string $input): string
    {
        return lcfirst(str_replace('_', '', ucwords($input, '_')));
    }

    public function getValue(object $object, string $propertyPath)
    {
        // 处理单个属性的场景（比如findBy、直接属性引用）
        if (strpos($propertyPath, '.') === false) {
            $camelCaseProp = $this->snakeToCamel($propertyPath);
            if (property_exists($object, $camelCaseProp)) {
                trigger_deprecation(
                    'my-library', 
                    'x.x', 
                    "属性 %s 使用了废弃的蛇形命名，请改用 %s", 
                    $propertyPath, 
                    $camelCaseProp
                );
                $propertyPath = $camelCaseProp;
            }
        }
        return parent::getValue($object, $propertyPath);
    }

    public function setValue(object &$object, string $propertyPath, mixed $value): void
    {
        if (strpos($propertyPath, '.') === false) {
            $camelCaseProp = $this->snakeToCamel($propertyPath);
            if (property_exists($object, $camelCaseProp)) {
                trigger_deprecation(
                    'my-library', 
                    'x.x', 
                    "属性 %s 使用了废弃的蛇形命名，请改用 %s", 
                    $propertyPath, 
                    $camelCaseProp
                );
                $propertyPath = $camelCaseProp;
            }
        }
        parent::setValue($object, $propertyPath, $value);
    }
}

步骤3：替换Doctrine默认访问器 #

在你的Doctrine配置中替换默认实现：

• 如果是Symfony项目，在services.yaml中配置：

services:
    Doctrine\Common\PropertyAccess\PropertyAccessorInterface:
        class: App\Doctrine\DeprecatedPropertyAccessor

• 纯Doctrine ORM使用时，初始化EntityManager手动设置：

$config = Setup::createAnnotationMetadataConfiguration(...);
$config->setPropertyAccessor(new DeprecatedPropertyAccessor());
$entityManager = EntityManager::create($dbParams, $config);

方案2：元数据事件监听器（适配DQL查询） #

如果有大量DQL查询直接使用旧属性名，我们可以通过LoadClassMetadata事件为旧属性名添加映射别名，让Doctrine自动识别：

步骤1：编写事件监听器 #

use Doctrine\ORM\Event\LoadClassMetadataEventArgs;

class DeprecatedPropertyMetadataListener
{
    private function camelToSnake(string $input): string
    {
        return strtolower(preg_replace('/([a-z])([A-Z])/', '$1_$2', $input));
    }

    public function loadClassMetadata(LoadClassMetadataEventArgs $eventArgs): void
    {
        $classMetadata = $eventArgs->getClassMetadata();
        // 为每个驼峰属性添加蛇形别名
        foreach ($classMetadata->getFieldNames() as $fieldName) {
            $snakeCaseName = $this->camelToSnake($fieldName);
            if ($snakeCaseName !== $fieldName && !$classMetadata->hasField($snakeCaseName)) {
                $classMetadata->mapField([
                    'fieldName' => $snakeCaseName,
                    'columnName' => $classMetadata->getColumnName($fieldName),
                    'type' => $classMetadata->getTypeOfField($fieldName),
                ]);
                trigger_deprecation(
                    'my-library', 
                    'x.x', 
                    "实体 %s 的属性别名 %s 已废弃，请改用 %s", 
                    $classMetadata->getName(), 
                    $snakeCaseName, 
                    $fieldName
                );
            }
        }
    }
}

步骤2：注册监听器 #

把监听器绑定到Doctrine事件管理器：

$eventManager = $entityManager->getEventManager();
$eventManager->addEventListener(['loadClassMetadata'], new DeprecatedPropertyMetadataListener());

方案3：优化你的Trait（覆盖PHP直接属性访问） #

你原来的Trait可以保留，用于处理PHP代码中直接访问$entity->new_name的场景，优化后更简洁可靠：

trait DeprecatedEntityPropertyNames
{
    private function snakeToCamel(string $input): string
    {
        return lcfirst(str_replace('_', '', ucwords($input, '_')));
    }

    public function __get(string $name): mixed
    {
        $candidateName = $this->snakeToCamel($name);
        if (property_exists($this, $candidateName)) {
            trigger_deprecation('my-library', 'x.x', "属性 %s 使用了废弃命名，请改用 %s", $name, $candidateName);
            return $this->$candidateName;
        }
        throw new \Error(sprintf("%s 中不存在属性 %s", static::class, $name));
    }

    public function __set(string $name, mixed $value): void
    {
        $candidateName = $this->snakeToCamel($name);
        if (property_exists($this, $candidateName)) {
            trigger_deprecation('my-library', 'x.x', "属性 %s 使用了废弃命名，请改用 %s", $name, $candidateName);
            $this->$candidateName = $value;
            return;
        }
        throw new \Error(sprintf("%s 中不存在属性 %s", static::class, $name));
    }

    public function __isset(string $name): bool
    {
        $candidateName = $this->snakeToCamel($name);
        if (property_exists($this, $candidateName)) {
            if ($name !== $candidateName) {
                trigger_deprecation('my-library', 'x.x', "属性 %s 使用了废弃命名，请改用 %s", $name, $candidateName);
            }
            return isset($this->$candidateName);
        }
        return false;
    }
}

总结建议 #

• 若主要是findBy等方法用旧属性名，方案1最直接；
• 若有大量DQL查询依赖旧属性名，方案2更适配；
• 结合方案3的Trait，可以覆盖PHP代码中直接访问属性的场景，确保所有旧用法都触发废弃通知，方便逐个项目清理。

等所有项目都迁移到新的驼峰命名后，再逐步移除这些兼容代码即可，全程不会产生破坏性变更。

内容来源于stack exchange