Transcoder

, _(*1)

Introduction

This is a wrapper around PHP’s mb_convert_encoding and iconv functions. This library adds:, _(*2)

fallback from mb to iconv for unknown encodings
conversion of warnings to proper exceptions.

Installation

The recommended way to install the Transcoder library is through Composer:, _(*3)

$ composer require ddeboer/transcoder

This command requires you to have Composer installed globally, as explained in the installation chapter of the Composer documentation., _(*4)

Usage

Basics

Create the right transcoder for your platform and translate some strings:, _(*5)

use Ddeboer\Transcoder\Transcoder;

$transcoder = Transcoder::create();
$result = $transcoder->transcode('España');

You can also manually instantiate a transcoder of your liking:, _(*6)

use Ddeboer\Transcoder\MbTranscoder;

$transcoder = new MbTranscoder();

Or:, _(*7)

use Ddeboer\Transcoder\IconvTranscoder;

$transcoder = new IconvTranscoder();

Source encoding

By default, the source encoding is detected automatically. However, you get much more reliable results when you specify it explicitly:, _(*8)

$transcoder->transcode('España', 'iso-8859-1');

Target encoding

Specify a default target encoding as the first argument to create():, _(*9)

use Ddeboer\Transcoder\Transcoder;

$isoTranscoder = Transcoder::create('iso-8859-1');

Alternatively, specify a target encoding as the third argument in a transcode() call:, _(*10)

use Ddeboer\Transcoder\Transcoder;

$transcoder->transcode('España', null, 'UTF-8');

Error handling

PHP’s mv_convert_encoding and iconv are inconvenient to use because they generate notices and warnings instead of proper exceptions. This library fixes that:, _(*11)

use Ddeboer\Transcoder\Exception\UndetectableEncodingException;
use Ddeboer\Transcoder\Exception\UnsupportedEncodingException;
use Ddeboer\Transcoder\Exception\IllegalCharacterException;

$input = 'España';

try {
    $transcoder->transcode($input);
} catch (UndetectableEncodingException $e) {
    // Failed to automatically detect $input’s encoding 
}

try {
    $transcoder->transcode($input, null, 'not-a-real-encoding');
} catch (UnsupportedEncodingException $e) {
    // ‘not-a-real-encoding’ is an unsupported encoding 
}

try {
    $transcoder->transcode('Illegal quotes: ‘ ’', null, 'iso-8859-1');
} catch (IllegalCharacterException $e) {
    // Curly quotes ‘ ’ are illegal in ISO-8859-1
}

Transcoder fallback

In general, mb_convert_encoding is faster than iconv. However, as iconv supports more encodings than mb_convert_encoding, it makes sense to combine the two., _(*12)

So, the Transcoder returned from create():, _(*13)

uses mb_convert_encoding if the mbstring PHP extension is installed;
if not, it uses iconv instead if the iconv extension is installed;
if both the mbstring and iconv extension are available, the Transcoder will first try mb_convert_encoding and fall back to iconv.