README

TransliterableBundle

A Symfony bundle to facilitate the transliteration of Doctrine entity string fields.

Overview

TransliterableBundle provides an embeddable entity, Transliterable, to enable mapping of a single Doctrine entity field to corresponding _original and _transliteration fields.

For example, a Doctrine entity class, Person, with a $firstname property mapped to the Transliterable embedded entity will result in a table with firstname_original and firstname_transliteration columns.

Installation

1. Require the latest stable version of TransliterableBundle by running the following console command from the root of your Symfony project:

   $ composer require tomchkk/transliterable-bundle

2. Enable the bundle by adding a reference to it in the array returned by config/bundles.php:

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

Usage

Embeddable Entity

An entity field can be made transliterable by including a Doctrine Embedded annotation with a class value of the fully-qualified Transliterable class name.

// src/Entity/Person.php

use Doctrine\ORM\Mapping as ORM;

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

For the same reasons indicated in the documentation for Doctrine Embeddables, Transliterable fields should be initialized to guarantee returning an embedded Transliterable instance - e.g.:

// 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();
    }

Transliteration

An embbedded Transliterable field with an original value but without a transliteration value will be transliterated when the entity is first persisted, or when updated.

Transliterator

By default TransliterableBundle uses PHP's built-in Transliterator class - decorated with a simple caching mechanism - as the transliteration engine. The default transliterator can be overridden in configuration by a custom service implementing Tomchkk\TransliterableBundle\Service\TransliteratorInterface - e.g.:

// config/packages/tomchkk_transliterable.yaml

tomchkk_transliterable:
    transliterator:       App\Service\CustomTransliterator

Rulesets

In order to perform a transliteration the transliterator requires a ruleset identifier, which is used to create a particular transliterator instance. More on ruleset identifiers.

Global ruleset

The default transliterator provides a ruleset which will be applied to all transliterations if no other ruleset is provided; this default can be overridden by setting the global_ruleset value in configuration - e.g.:

// config/packages/tomchkk_transliterable.yaml

tomchkk_transliterable:
    global_ruleset:       Any-Latin

Annotation rulesets

A Transliterable annotation is also available to enable a ruleset to be set at class- or property-level, the most specific of which will be applied to the transliteration of a field's value, overriding the global ruleset.

// 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;

In the above example $firstname would be transliterated according by the class ruleset; $lastname by the property ruleset.

Frontend

Form Type

A TransliterableType form type is included, providing an original and transliteration field - each extending Symfony's TextType. By default the required option of the transliteration field is set to false since this field, if empty, will be populated when the entity is persisted.

The following configuration options are available for TransliterableType:

Twig Extension

The transliterate twig filter enables direct transliteration of strings within twig templates - e.g.:

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

The optional ruleset argument can be used per transliteration, otherwise the Transliterator service's global_ruleset will be used:

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