ddeboer / transcoder
Better encoding conversion for PHP
Installs: 638 636
Dependents: 12
Suggesters: 0
Security: 0
Stars: 9
Watchers: 3
Forks: 15
Open Issues: 5
Requires
- php: >=5.4.0
Requires (Dev)
- phpunit/phpunit: ~4.0
Suggests
- ext-iconv: For using the IconvTranscoder
- ext-mbstring: For using the MbTranscoder
This package is auto-updated.
Last update: 2024-11-06 09:00:12 UTC
README
Introduction
This is a wrapper around PHP’s mb_convert_encoding
and iconv
functions.
This library adds:
- fallback from
mb
toiconv
for unknown encodings - conversion of warnings to proper exceptions.
Installation
The recommended way to install the Transcoder library is through Composer:
$ composer require ddeboer/transcoder
This command requires you to have Composer installed globally, as explained in the installation chapter of the Composer documentation.
Usage
Basics
Create the right transcoder for your platform and translate some strings:
use Ddeboer\Transcoder\Transcoder; $transcoder = Transcoder::create(); $result = $transcoder->transcode('España');
You can also manually instantiate a transcoder of your liking:
use Ddeboer\Transcoder\MbTranscoder; $transcoder = new MbTranscoder();
Or:
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:
$transcoder->transcode('España', 'iso-8859-1');
Target encoding
Specify a default target encoding as the first argument to create()
:
use Ddeboer\Transcoder\Transcoder; $isoTranscoder = Transcoder::create('iso-8859-1');
Alternatively, specify a target encoding as the third argument in a
transcode()
call:
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:
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.
So, the Transcoder returned from create()
: