PHPackages                             ducks-project/encoding-repair - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Parsing & Serialization](/categories/parsing)
4. /
5. ducks-project/encoding-repair

ActiveLibrary[Parsing & Serialization](/categories/parsing)

ducks-project/encoding-repair
=============================

A robust, immutable, and extensible PHP library to handle charset conversion, detection, and repair (Double Encoding) with safe JSON wrappers. Optimized for Legacy ISO-8859-1 to UTF-8 migrations.

v1.2.1(1mo ago)15MITPHPPHP >=7.4CI passing

Since Jan 21Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/ducks-project/encoding-repair)[ Packagist](https://packagist.org/packages/ducks-project/encoding-repair)[ Docs](https://github.com/ducks-project/encoding-repair/)[ GitHub Sponsors](https://github.com/donaldinou)[ Fund](https://opencollective.com/ducks-project)[ RSS](/packages/ducks-project-encoding-repair/feed)WikiDiscussions main Synced today

READMEChangelog (10)Dependencies (22)Versions (19)Used By (0)

CharsetHelper
=============

[](#charsethelper)

[![Github Action Status](https://github.com/ducks-project/encoding-repair/actions/workflows/ci.yml/badge.svg)](https://github.com/ducks-project/encoding-repair)[![Coverage Status](https://camo.githubusercontent.com/19ad75a587098eb86747a575fbe43311d88cd6f72b47d15bb630dcdcccac893e/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f6475636b732d70726f6a6563742f656e636f64696e672d7265706169722f62616467652e737667)](https://coveralls.io/github/ducks-project/encoding-repair)

[![Build Status](https://camo.githubusercontent.com/b0c6c6845a74cb65a7f0a32bdcfd8fbf80eeb40026c4029af424ab371c94b8bd/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6275696c642d70617373696e672d627269676874677265656e)](https://github.com/ducks-project/encoding-repair)[![Coverage](https://camo.githubusercontent.com/08f9e2cc3cc2ac54c1a3318cd1fc74d87e564fe653e479f69ca8a42ee4821c98/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f636f7665726167652d39352532352d627269676874677265656e)](https://github.com/ducks-project/encoding-repair)[![codecov](https://camo.githubusercontent.com/4dbb02080d2866c0ca2c440767c488b3b775dedbcfaac74b6e600900bca54744/68747470733a2f2f636f6465636f762e696f2f67682f6475636b732d70726f6a6563742f656e636f64696e672d7265706169722f6272616e63682f6d61696e2f67726170682f62616467652e737667)](https://codecov.io/gh/ducks-project/encoding-repair)

[![Psalm Type Coverage](https://camo.githubusercontent.com/93a703169005c120fbc9f7b6895a5a406097a0ff4c509f49fba47fce6030d98b/68747470733a2f2f73686570686572642e6465762f6769746875622f6475636b732d70726f6a6563742f656e636f64696e672d7265706169722f636f7665726167652e737667)](https://shepherd.dev/github/ducks-project/encoding-repair)[![Psalm Level](https://camo.githubusercontent.com/648071da3d47bdc3ca6fed7c9bebecff2a4d2e362688e58d51cc38e9aa70c808/68747470733a2f2f73686570686572642e6465762f6769746875622f6475636b732d70726f6a6563742f656e636f64696e672d7265706169722f6c6576656c2e737667)](https://shepherd.dev/github/ducks-project/encoding-repair)

[![License](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)](LICENSE)[![Latest Stable Version](https://camo.githubusercontent.com/306ac2cac9f930fccdffb8e678707a659637b98a3346e0bc20c38e01ee530740/68747470733a2f2f706f7365722e707567782e6f72672f6475636b732d70726f6a6563742f656e636f64696e672d7265706169722f762f737461626c65)](https://packagist.org/packages/ducks-project/encoding-repair)[![PHP Version Require](https://camo.githubusercontent.com/81376117c6699a8b287b1bac083200f36087f9fd3f32afb64af47ee322200365/68747470733a2f2f706f7365722e707567782e6f72672f6475636b732d70726f6a6563742f656e636f64696e672d7265706169722f726571756972652f706870)](https://packagist.org/packages/ducks-project/encoding-repair)

[![Total Downloads](https://camo.githubusercontent.com/806206497300ab86433e0cd81a8111e5bc910f21a49431658440c6118a5c899b/68747470733a2f2f706f7365722e707567782e6f72672f6475636b732d70726f6a6563742f656e636f64696e672d7265706169722f646f776e6c6f616473)](https://packagist.org/packages/ducks-project/encoding-repair)[![Monthly Downloads](https://camo.githubusercontent.com/aaa4009aabef3eb0245f2c143ad100f1b8cf263374d3d21397bc19ce274d88ff/68747470733a2f2f706f7365722e707567782e6f72672f6475636b732d70726f6a6563742f656e636f64696e672d7265706169722f642f6d6f6e74686c79)](https://packagist.org/packages/ducks-project/encoding-repair)[![Daily Downloads](https://camo.githubusercontent.com/0a75aee1bf551aa86c9273eacb3296c3e7e05008dd33ff11b32186cd8bafd4be/68747470733a2f2f706f7365722e707567782e6f72672f6475636b732d70726f6a6563742f656e636f64696e672d7265706169722f642f6461696c79)](https://packagist.org/packages/ducks-project/encoding-repair)

[![Duck's Validated](https://camo.githubusercontent.com/55cd39dc9426a431b51194b4c9c571b67530390634276beab8244297a0d7788d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6475636b2d76616c6964617465642d6c6967687479656c6c6f77)](https://opencollective.com/ducks-project)[![Packagist online](https://camo.githubusercontent.com/f23247436d9616bc9045be6056671e2d96dd152901e3f29d0a8c78f12d96028f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7061636b61676973742d6f6e6c696e652d627269676874677265656e)](https://opencollective.com/ducks-project)[![Documentation Status](https://camo.githubusercontent.com/204704de4738c65e9b2f79ba72ce4cf9846203d287efa6d5f73147443d856501/68747470733a2f2f72656164746865646f63732e6f72672f70726f6a656374732f656e636f64696e672d7265706169722f62616467652f3f76657273696f6e3d6c6174657374)](https://encoding-repair.readthedocs.io/en/latest/?badge=latest)

Advanced charset encoding converter with **Chain of Responsibility** pattern, auto-detection, double-encoding repair, and JSON safety.

🆕 What's New in v1.2
--------------------

[](#-whats-new-in-v12)

### Type Interpreter System

[](#type-interpreter-system)

New optimized type-specific processing with Strategy + Visitor pattern:

```
// Custom property mapper for selective processing (60% faster!)
use Ducks\Component\EncodingRepair\Interpreter\PropertyMapperInterface;

class UserMapper implements PropertyMapperInterface
{
    public function map(object $object, callable $transcoder, array $options): object
    {
        $copy = clone $object;
        $copy->name = $transcoder($object->name);
        $copy->email = $transcoder($object->email);
        // password NOT transcoded (security)
        return $copy;
    }
}

$processor = new CharsetProcessor();
$processor->registerPropertyMapper(User::class, new UserMapper());
```

### Batch Processing API

[](#batch-processing-api)

New optimized batch processing methods for high-performance array conversion:

```
// Batch conversion with single encoding detection (40-60% faster!)
$rows = $db->query("SELECT * FROM users")->fetchAll();
$utf8Rows = CharsetHelper::toCharsetBatch($rows, 'UTF-8', CharsetHelper::AUTO);

// Detect encoding from array
$encoding = CharsetHelper::detectBatch($items);
```

### Service-Based Architecture

[](#service-based-architecture)

CharsetHelper now uses a service-based architecture following SOLID principles:

- **`CharsetProcessor`**: Instanciable service with fluent API
- **`CharsetProcessorInterface`**: Service contract for dependency injection
- **Multiple instances**: Different configurations for different contexts
- **100% backward compatible**: Existing code works unchanged

```
// New way: Service instance
$processor = new CharsetProcessor();
$processor->addEncodings('SHIFT_JIS')->resetDetectors();
$utf8 = $processor->toUtf8($data);

// Old way: Static facade (still works)
$utf8 = CharsetHelper::toUtf8($data);
```

### PSR-16 Cache Support

[](#psr-16-cache-support)

Optional external cache integration for improved performance:

```
// Use built-in InternalArrayCache (default, optimized)
use Ducks\Component\EncodingRepair\Detector\CachedDetector;
use Ducks\Component\EncodingRepair\Detector\MbStringDetector;

$detector = new CachedDetector(new MbStringDetector());
// InternalArrayCache used automatically (no TTL overhead)

// Or use ArrayCache for TTL support
use Ducks\Component\EncodingRepair\Cache\ArrayCache;

$cache = new ArrayCache();
$detector = new CachedDetector(new MbStringDetector(), $cache, 3600);

// Or use any PSR-16 implementation (Redis, Memcached, APCu)
// $redis = new \Symfony\Component\Cache\Psr16Cache($redisAdapter);
// $detector = new CachedDetector(new MbStringDetector(), $redis, 7200);
```

🌟 Why CharsetHelper?
--------------------

[](#-why-charsethelper)

Unlike existing libraries, CharsetHelper provides:

- ✅ **Extensible architecture** with Chain of Responsibility pattern
- ✅ **PSR-16 cache support** for Redis, Memcached, APCu (NEW in v1.2)
- ✅ **Type-specific interpreters** for optimized processing (NEW in v1.2)
- ✅ **Custom property mappers** for selective object conversion (NEW in v1.2)
- ✅ **Multiple fallback strategies** (UConverter → iconv → mbstring)
- ✅ **Smart auto-detection** with multiple detection methods
- ✅ **Double-encoding repair** for corrupted legacy data
- ✅ **Recursive conversion** for arrays AND objects (not just arrays!)
- ✅ **Safe JSON encoding/decoding** with automatic charset handling
- ✅ **Modern PHP** with strict typing (PHP 7.4+)
- ✅ **Minimal dependencies** (only PSR-16 interface for optional caching)

📖 Features
----------

[](#-features)

- **Robust Transcoding:** Implements a Chain of Responsibility pattern trying best providers first (`Intl/UConverter` -> `Iconv` -> `MbString`).
- **PSR-16 Cache Support:** Optional external cache (Redis, Memcached, APCu) for detection results (NEW in v1.2).
- **Type-Specific Interpreters:** Optimized processing strategies per data type (NEW in v1.2).
- **Custom Property Mappers:** Selective object property conversion for security and performance (NEW in v1.2).
- **Double-Encoding Repair:** Automatically detects and fixes strings like `été`back to `été`.
- **Recursive Processing:** Handles `string`, `array`, and `object` recursively.
- **Immutable:** Objects are cloned before modification to prevent side effects.
- **Safe JSON Wrappers:** Prevents `json_encode` from returning `false` on bad charsets.
- **Secure:** Whitelisted encodings to prevent injection.
- **Extensible:** Register your own transcoders, detectors, interpreters, or cache providers without modifying the core.
- **Modern Standards:** PSR-12 compliant, strictly typed, SOLID architecture.

📋 Requirements
--------------

[](#-requirements)

- **PHP**: 7.4, 8.0, 8.1, 8.2, or 8.3
- **Extensions** (required):
    - `ext-mbstring`
    - `ext-json`
- **Extensions** (recommended):
    - `ext-intl`

📦 Installation
--------------

[](#-installation)

```
composer require ducks-project/charset-helper
```

### Optional Extensions (for better performance)

[](#optional-extensions-for-better-performance)

```
# Ubuntu/Debian
sudo apt-get install php-intl php-iconv

# macOS (via Homebrew)
brew install php@8.2
# Extensions are included by default

# Windows
# Enable in php.ini:
extension=intl
extension=iconv
```

🚀 Quick Start
-------------

[](#-quick-start)

```