自定义Doctrine Type必须实现getSQLType()和convertToPHPValue()，否则schema更新时报“Unknown column type”；需通过Column注解传参而非实例状态，加密Type须在convertToPHPValue()中抛出ConversionException。
Doctrine自定义Type必须实现getSQLType()和convertToPHPValue()
Doctrine不接受只重写convertToDatabaseValue()的类——它会在schema更新或数据库内省时直接报错Unknown column type。核心原因是Type注册后，Doctrine需要知道该类型映射到哪一种底层SQL类型（如varchar、text、json），才能生成正确的DDL语句。
常见错误现象：执行php bin/console doctrine:schema:update --dump-sql时抛出Unknown column type "encrypted_string"，即使你已在config/packages/doctrine.yaml里声明了type映射。
-
getSQLType()必须返回一个Doctrine内置SQL类型字符串，例如'string'、'text'、'json'（Symfony 5.3+原生支持） -
convertToPHPValue()和convertToDatabaseValue()负责双向转换逻辑，但不能缺失任一方向 - 若需支持数据库函数（如
JSON_EXTRACT），还需实现convertToDatabaseValueSQL()和convertToPHPValueSQL()
注册自定义Type时，doctrine.dbal.types配置仅在首次加载生效
你在config/packages/doctrine.yaml中写的types映射，只在容器编译期被读取一次。如果之后想动态修改Type实例状态（比如设置密钥、IV），不能靠$type->setKey()——因为每次数据库操作都可能拿到全新实例。
典型踩坑场景：在Kernel::boot()里调用Type::getType('my_type')->setKey(...)，第二次请求就失效，甚至引发并发问题。
- 正确做法是把运行时参数通过
Column注解传入：@ORM\Column(type="encrypted_string", options={"cipher": "AES-256-CBC", "key": "env:APP_ENCRYPTION_KEY"}) - 然后在Type类的
__construct()或getMappedDatabaseTypes()中解析$platform->getDatabasePlatform()->getDoctrineTypeMapping('my_type')获取options - 避免在Type实例上保存状态；所有配置应从
$column->getCustomSchemaOptions()或环境变量中按需提取
使用convertToDatabaseValueSQL()拼接SQL函数时，字段名不可硬编码
当你想让Doctrine在INSERT/UPDATE时自动调用数据库函数（如MD5(CONCAT(email, username))），不能在convertToDatabaseValueSQL()里写死列名。因为这个方法接收的是SQL表达式字符串（如?或t0_.email），不是PHP实体属性值。
错误示例：return 'MD5(CONCAT(' . $sqlExpr . ', username))';——这里的username是未知列，且无法跨表引用。
- 正确方式是依赖Doctrine的
AbstractPlatform提供上下文：$platform->getConcatExpression($sqlExpr, 'username') - 若需关联另一列，应在DQL或Repository层处理，而不是在Type里尝试跨字段计算
- 对MSSQL等平台，注意函数语法差异：
[dbo].[myfunc]($sqlExpr, 'username')需确保username是合法标识符或参数占位符
加密类Type务必区分convertToPHPValue()与convertToDatabaseValue()的异常边界
加密型Type（如EncryptedStringType）最容易在解密失败时静默返回null或原始密文，导致业务逻辑误判。Doctrine不会拦截这些异常，也不会回滚事务——它只关心“是否成功转成PHP值”。
真实项目中，解密失败往往意味着密钥变更、数据损坏或迁移遗漏，必须显式暴露。
- 在
convertToPHPValue()中，捕获OpenSSLException等并抛出ConversionException（来自Doctrine\DBAL\Types\ConversionException） - 不要用
try/catch吞掉异常后返回''或$value——这会让坏数据持续写入，排查成本陡增 - 测试时用无效密文触发解密失败，确认异常能穿透到控制器层，而非被表单或API响应忽略
最常被忽略的一点：自定义Type的requiresSQLCommentHint()返回true时，Doctrine会在生成的SQL中添加注释，但这在MySQL 8.0.19+和PostgreSQL 12+可能触发语法错误。除非你明确控制所有目标平台版本，否则默认返回false更稳妥。
