Transcoder Laravel Package

Product Decisions This Supports

• Feature scoping — text ingestion robustness. This package is a thin Transcoder interface with Iconv, Mbstring, and Recode backends, plus an OneshotTranscoder that tries them in sequence. That is precisely the shape of a "accept files in whatever encoding the customer's legacy system produced" capability. It informs whether we ship charset conversion as a first-class feature or a hidden implementation detail.
• Build vs buy. The whole library is a few hundred lines of MIT-licensed glue around PHP extensions and a GNU binary. The decision this package actually drives is: do not take a runtime dependency — adopt the pattern in-house. The interface + ordered fallback chain is the valuable artifact; vendoring or reimplementing it costs roughly a day and removes an unmaintained dependency.
• Roadmap input — graceful degradation over hard failure. The OneshotTranscoder concept forces a product question we should answer explicitly: when mbstring is absent or iconv silently mangles a string, do we fail the import, or do we fall back and tell the user which engine won? This package argues for the latter, which maps to better error telemetry and clearer user-facing conversion reports.
• Validated use cases. Legacy data migration (customer records out of an old ERP), bulk CSV/XML onboarding, multilingual search indexing, document pipelines, and mojibake remediation in support tooling. It is evidence these are real, recurring problems worth a dedicated internal utility.
• Risk register entry. Last release Jan 2015, 16 stars, no evidence of PHP 8 compatibility, and the recode backend requires a system binary most container images don't ship. Treat as a reference implementation, not a dependency.

When to Consider This Package

Consider it when:

• You have a bounded legacy migration with a known set of input charsets (Windows-1252, ISO-8859-x, Shift-JIS, KOI8-R) and want a fallback chain across iconv, mbstring, and recode rather than a single hard-coded call.
• You need transliteration (//TRANSLIT) or charset pairs that mb_convert_encoding handles poorly.
• You're prototyping and want a quick MIT-licensed abstraction to validate the approach before writing your own.

Look elsewhere when:

• You target PHP 8.1+. The package predates modern PHP; verify version constraints before even prototyping.
• You can't guarantee system binaries. recode is rarely installed in containers, so the RecodeTranscoder is dead weight unless you control the image.
• You need encoding detection, Unicode normalization, or grapheme handling — use mb_detect_encoding with a strict allowlist, symfony/string, or a mojibake-specific library instead.
• You're greenfield. A ~50-line service class wrapping iconv with an mbstring fallback covers the large majority of real cases; recode only earns its place for exotic charsets.

How to Pitch It (Stakeholders)

Executives: "There's a small free library that shows how to convert legacy file encodings reliably by trying multiple conversion engines and falling back gracefully instead of failing. It's MIT-licensed, but it hasn't been updated since 2015 and has almost no adoption, so I don't recommend depending on it. Instead I recommend we adopt the pattern — roughly one engineering day — inside our import pipeline. That unblocks customers whose files come from older systems and de-risks legacy data migrations, with no new maintenance liability and no new vendor."

Engineering: "ddeboer/transcoder is a Transcoder interface with Iconv, Mbstring, and Recode implementations, and an OneshotTranscoder that chains them. Right shape for a text-ingestion service. Wrong lifecycle: PHP 5-era, unmaintained since 2015, and the recode backend needs a system binary we don't ship. Proposal: copy the interface and fallback chain into App\Support\Transcoding, keep only the iconv and mbstring backends, add explicit failure reporting and a charset allowlist, and write our own test matrix with fixture files. About a sprint day, zero new dependency, MIT-clean."