Over Util Laravel Package

Getting Started

This release is a maintenance bump (v5.4.1) on an ext-iconv-backed helper that recursively converts strings inside arrays between character encodings — the kind of thing you reach for when ingesting legacy CSVs, Shift_JIS exports, or Windows-1252 data from third-party systems into a UTF-8 Laravel app.

Minimal steps:

1. composer require the package, then confirm ext-iconv is actually enabled in the CLI and FPM SAPIs (php -m | grep iconv). The package is a thin layer; without the extension nothing works and you get an unhelpful failure deep in a job.
2. Publish config (php artisan vendor:publish --tag=...) — it typically carries a default source/target encoding pair and a transliteration flag. Read this file before the README's advanced examples; most day-to-day confusion is a config default overriding an explicit argument.
3. Look first at the facade/helper signature and its return type. The single most important thing to learn on day one is how it reports failure: does it throw, return false, or return partially-converted data?
4. First use case: a one-off php artisan tinker conversion of a known-good fixture array (['こんにちは' => 'テスト']) in both directions. Verify byte equality against a mb_convert_encoding call you trust, then wire it into a real importer.

Implementation Patterns

Import pipeline sanitisation. Convert at the boundary, not in the model. Read the raw file/response, run the array converter once over the decoded payload, then hand clean UTF-8 to your DTOs and validators. Converting inside accessors scatters encoding concerns across the domain and makes failures non-deterministic.

Export for legacy consumers. The reverse direction (UTF-8 → target charset) belongs in a dedicated export/serialiser class, not inline in a controller. Pair it with //TRANSLIT-style fallback only for human-readable exports; never for machine-to-machine interchange where silent substitution corrupts keys.

Queued conversion for bulk arrays. Large arrays (thousands of rows) should be chunked into jobs. Convert per chunk and persist, so a single invalid byte sequence fails one job rather than the whole import — and you get retry semantics for free.

Middleware or FormRequest for inbound request payloads. If legacy clients POST non-UTF-8 bodies, normalise in middleware before validation and $request->validate(), otherwise the validator rejects strings that are fine once converted, and error messages themselves come back mojibake.

Pair with a validation rule / assertion in tests. Assert on round-trip identity (convert(convert($x))) for anything that must survive both directions, and assert explicit byte sequences for the lossy cases you accept.

Wrap it, don't sprinkle it. A single EncodingConverter service injected via the container gives you one place to change defaults, add metrics, or swap in mb_convert_encoding if iconv proves troublesome on a target platform.

Gotchas and Tips

• Return-value ambiguity is the main trap. iconv() returns false on an illegal character; recursive wrappers sometimes swallow that into null or an empty string. Decide explicitly whether partial output is acceptable, and log the offending offset — do not let a silent false reach your database layer.
• //IGNORE and //TRANSLIT are not portable. Their exact behaviour varies by libc and glibc version, so the same code converts differently on macOS dev machines and Alpine/Debian production containers. Pin expectations in tests run in a container matching production, or avoid the suffixes for anything correctness-critical.
• Locale sensitivity. Some conversion paths depend on setlocale(LC_CTYPE, ...). If results differ between a queue worker and an HTTP request, check for a locale change elsewhere in the app before blaming the package.
• Keys vs values. Recursive converters frequently convert values only. If your legacy data uses non-UTF-8 keys (common in Japanese CSV headers), verify key handling explicitly or normalise keys yourself first.
• Non-string scalars. Floats, null, booleans and DateTime objects in the array should pass through untouched. Any cast-to-string inside the recursion will quietly turn null into '' and 1.10 into 1.1 — a classic silent data corruption bug in importers.
• Double conversion. Converting already-UTF-8 input as if it were Shift_JIS produces garbage that still looks like valid text in logs. Always carry the source encoding as explicit metadata alongside the payload rather than re-detecting.
• Detection is unreliable. Don't rely on the package (or mb_detect_encoding) to guess the source charset reliably. Take it from the file header, the API contract, or a per-tenant config value.
• Database and column charset are separate concerns. Converting in PHP does not fix a latin1 column or a misconfigured connection charset; verify config/database.php charset/collation and the column definitions before adding more conversion layers.
• Extension point: if the package exposes a converter contract or macroable facade, bind your own implementation for observability (timing, failure counts) rather than forking — that keeps you upgradeable across 5.x patch releases like this one.