README

TransliterableBundle

一个用于简化 Doctrine 实体字符串字段转写的 Symfony 扩展包。

概述

TransliterableBundle 提供了一个 可嵌入实体，Transliterable，以便将单个 Doctrine 实体字段映射到相应的 _original 和 _transliteration 字段。

例如，一个 Doctrine 实体类，Person，其中 $firstname 属性映射到 Transliterable 嵌入实体，将导致表中出现 firstname_original 和 firstname_transliteration 列。

安装

1. 从您的 Symfony 项目根目录运行以下控制台命令，以要求安装最新稳定的 TransliterableBundle 版本：

   $ composer require tomchkk/transliterable-bundle

2. 通过在 config/bundles.php 中添加对它的引用来启用扩展包

   // config/bundles.php
   
   return [
       // ...
       Tomchkk\TransliterableBundle\TomchkkTransliterableBundle::class => ['all' => true],
   ];

使用方法

嵌入实体

可以通过包含一个 Doctrine Embedded 注解，并设置 class 值为完全限定的 Transliterable 类名，将实体字段变为可转写。

// src/Entity/Person.php

use Doctrine\ORM\Mapping as ORM;

/**
 * @ORM\Entity()
 */
class Person
{
    /**
     * @ORM\Embedded(class="Tomchkk\TransliterableBundle\Embeddable\Transliterable")
     */
    private $firstname;
}

正如 Doctrine 嵌入实体的文档中所述，Transliterable 字段应该被初始化，以确保返回一个嵌入的 Transliterable 实例 - 例如：

// src/Entity/Person.php

use Doctrine\ORM\Mapping as ORM;
use Tomchkk\TransliterableBundle\Embeddable\Transliterable;

/**
 * @ORM\Entity()
 */
class Person
{
    public function __construct()
    {
        $this->firstname = new Transliterable();
    }

转写

带有 original 值但无 transliteration 值的嵌入 Transliterable 字段将在实体首次持久化或更新时进行转写。

转写器

默认情况下，TransliterableBundle 使用 PHP 内置的 Transliterator 类 作为转写引擎，并添加了简单的缓存机制。可以通过配置中实现 Tomchkk\TransliterableBundle\Service\TransliteratorInterface 的自定义服务来覆盖默认转写器，例如：

// config/packages/tomchkk_transliterable.yaml

tomchkk_transliterable:
    transliterator:       App\Service\CustomTransliterator

规则集

为了执行转写，转写器需要一个 规则集 标识符，用于创建特定的转写器实例。有关规则集标识符的更多信息。

全局规则集

默认转写器提供了一个规则集，如果未提供其他规则集，则将应用于所有转写。可以通过在配置中设置 global_ruleset 值来覆盖此默认值 - 例如：

// config/packages/tomchkk_transliterable.yaml

tomchkk_transliterable:
    global_ruleset:       Any-Latin

注解规则集

还有一个 Transliterable 注解可用于在类或属性级别设置 规则集，最具体的规则集将应用于字段的转写，并覆盖全局规则集。

// src/Entity/Person.php

use Doctrine\ORM\Mapping as ORM;
use Tomchkk\TransliterableBundle\Annotation as Tomchkk;

/**
 * @ORM\Entity()
 * @Tomchkk\Transliterable(ruleset="Any-Latin")
 */
class Person
{
    /**
     * @ORM\Embedded(class="Tomchkk\TransliterableBundle\Embeddable\Transliterable")
     */
    private $firstname;

    /**
     * @ORM\Embedded(class="Tomchkk\TransliterableBundle\Embeddable\Transliterable")
     * @Tomchkk\Transliterable(ruleset="Russian-Latin/BGN; Any-Latin")
     */
    private $lastname;

在上面的例子中，$firstname 将根据类规则集进行转写；$lastname 将根据属性规则集进行转写。

前端

表单类型

包含了一个 TransliterableType 表单类型，提供 original 和 transliteration 字段 - 每个字段都扩展了 Symfony 的 TextType。默认情况下，transliteration 字段的 required 选项设置为 false，因为如果该字段为空，当实体持久化时，该字段将被填充。

以下是为 TransliterableType 可用的配置选项

Twig 扩展

transliterate twig 过滤器允许在 twig 模板中直接进行字符串的转写 - 例如：

Firstname: {{ 'Илья'|transliterate }}
<!-- Firstname: Ilʹâ -->

可选的 ruleset 参数可以针对每个转写使用，否则将使用 Transliterator 服务器的 global_ruleset

Firstname: {{ 'Илья'|transliterate('Russian-Latin/BGN') }}
<!-- Firstname: Ilʹya -->