feat: Add StringEncoder and StringHelper for encoding utilities

- Introduced StringEncoder for converting various encodings to UTF-8.
- Added StringHelper with methods for string manipulation and transliteration.
This commit is contained in:
Jérémy Munsch 2026-10-05 12:59:08 +02:00
parent 3e4732bcb4
commit a7354cb051
No known key found for this signature in database
GPG key ID: 2AAECDA6B7330F91
3 changed files with 528 additions and 2 deletions

View file

@ -4,6 +4,7 @@ declare(strict_types=1);
namespace Domain\Models\ValueObjects;
use Shared\Helpers\StringHelper;
use Webmozart\Assert\Assert;
final readonly class Slug implements \Stringable
@ -17,8 +18,7 @@ final readonly class Slug implements \Stringable
public static function fromString(string $string): self
{
$transliterated = iconv('UTF-8', 'ASCII//TRANSLIT//IGNORE', $string);
$cleanString = $transliterated !== false ? $transliterated : $string;
$cleanString = StringHelper::transliterate($string);
$slug = strtolower(trim($cleanString));
$slug = preg_replace('/[^a-z0-9]+/i', '-', $slug) ?? '';

View file

@ -0,0 +1,330 @@
<?php
declare(strict_types=1);
namespace Shared\Helpers;
/**
* Converts strings from Western European single-byte encodings to UTF-8.
*
* Supported source encodings:
* - UTF-8 (passthrough with validation)
* - Windows-1252 (superset of ISO-8859-1, covers Latin-1 in practice)
* - ISO-8859-15 (Latin-9: Latin-1 + €, œ, Œ, Š, š, Ž, ž, Ÿ)
*
* Auto-detection is inherently unreliable for single-byte encodings.
* Always prefer toUtf8() with an explicit encoding.
*/
final class StringEncoder
{
/** UTF-8 BOM sequence (EF BB BF). */
private const string UTF8_BOM = "\xEF\xBB\xBF";
/**
* Canonical encodings supported by this class.
*
* @var list<string>
*/
private const array CANONICAL_ENCODINGS = [
'UTF-8',
'Windows-1252',
'ISO-8859-15',
];
/**
* Lowercase alias -> canonical name.
*
* Windows-1252 absorbs ISO-8859-1/Latin-1 because it is a strict superset:
* bytes 0xA0-0xFF are identical, and 0x80-0x9F are defined in Win-1252
* but undefined (and useless) in ISO-8859-1.
*
* @var array<string, string>
*/
private const array ENCODING_ALIASES = [
// UTF-8
'utf8' => 'UTF-8',
'utf-8' => 'UTF-8',
// Windows-1252 (absorbs Latin-1 / ISO-8859-1)
'win1252' => 'Windows-1252',
'windows1252' => 'Windows-1252',
'cp1252' => 'Windows-1252',
'latin1' => 'Windows-1252',
'latin-1' => 'Windows-1252',
'iso-8859-1' => 'Windows-1252',
// ISO-8859-15 (Latin-9)
'latin9' => 'ISO-8859-15',
'latin-9' => 'ISO-8859-15',
'iso-8859-15' => 'ISO-8859-15',
];
/**
* Windows-1252 specific codepoints (0x80-0x9F) absent from ISO-8859-1.
*
* Bytes 0x81, 0x8D, 0x8F, 0x90, 0x9D are officially undefined in Windows-1252.
* They are intentionally absent - encountering them triggers the
* Latin-1 fallback (Unicode codepoint = byte value).
*
* @var array<int, string> Byte value -> UTF-8 character.
*/
private const array WIN1252_SPECIAL_BYTES = [
0x80 => "\u{20AC}", // €
0x82 => "\u{201A}", // ‚
0x83 => "\u{0192}", // ƒ
0x84 => "\u{201E}", // „
0x85 => "\u{2026}", // …
0x86 => "\u{2020}", // †
0x87 => "\u{2021}", // ‡
0x88 => "\u{02C6}", // ˆ
0x89 => "\u{2030}", // ‰
0x8A => "\u{0160}", // Š
0x8B => "\u{2039}", // ‹
0x8C => "\u{0152}", // Œ
0x8E => "\u{017D}", // Ž
0x91 => "\u{2018}", // '
0x92 => "\u{2019}", // '
0x93 => "\u{201C}", // "
0x94 => "\u{201D}", // "
0x95 => "\u{2022}", // •
0x96 => "\u{2013}", // –
0x97 => "\u{2014}", // —
0x98 => "\u{02DC}", // ˜
0x99 => "\u{2122}", // ™
0x9A => "\u{0161}", // š
0x9B => "\u{203A}", // ›
0x9C => "\u{0153}", // œ
0x9E => "\u{017E}", // ž
0x9F => "\u{0178}", // Ÿ
];
/**
* ISO-8859-15 bytes that differ from ISO-8859-1.
* Only 8 codepoints differ between Latin-1 and Latin-9.
*
* @var array<int, string> Byte value -> UTF-8 character.
*/
private const array LATIN9_OVERRIDES = [
0xA4 => "\u{20AC}", // € (replaces ¤)
0xA6 => "\u{0160}", // Š (replaces ¦)
0xA8 => "\u{0161}", // š (replaces ¨)
0xB4 => "\u{017D}", // Ž (replaces ´)
0xB8 => "\u{017E}", // ž (replaces ¸)
0xBC => "\u{0152}", // Œ (replaces ¼)
0xBD => "\u{0153}", // œ (replaces ½)
0xBE => "\u{0178}", // Ÿ (replaces ¾)
];
private function __construct()
{
// Static class
}
/**
* Converts a string from a known encoding to UTF-8.
*
* @param bool $stripBom Remove UTF-8 BOM from the result if present.
*
* @throws \ValueError If encoding is unsupported or the string is invalid.
*/
public static function toUtf8(
string $string,
string $sourceEncoding,
bool $stripBom = true,
): string {
if ($string === '') {
return '';
}
$canonical = self::resolveEncoding($sourceEncoding);
$result = match ($canonical) {
'UTF-8' => self::ensureValidUtf8($string),
'Windows-1252' => self::fromSingleByte($string, self::WIN1252_SPECIAL_BYTES),
'ISO-8859-15' => self::fromSingleByte($string, self::LATIN9_OVERRIDES),
default => throw new \ValueError(sprintf(
'Unsupported encoding "%s". Supported: %s',
$canonical,
implode(', ', self::supportedEncodings()),
))
};
return $stripBom ? self::stripUtf8Bom($result) : $result;
}
/**
* Attempts to detect the encoding and convert to UTF-8.
*
* Detection strategy:
* 1. If the string is valid UTF-8, it is treated as UTF-8.
* 2. Otherwise, the configured fallback encoding is used.
*
* This two-step approach is more reliable than mb_detect_encoding
* for single-byte encodings (which accept any byte sequence).
*
* @param string $fallbackEncoding Encoding to assume when the string is not valid UTF-8.
* Defaults to 'Windows-1252' (covers most Western European legacy data).
* @param bool $stripBom Remove UTF-8 BOM from the result if present.
*
* @throws \ValueError If fallbackEncoding is unsupported or is 'UTF-8'.
*/
public static function detectAndConvertToUtf8(
string $string,
string $fallbackEncoding = 'Windows-1252',
bool $stripBom = true,
): string {
if ($string === '') {
return '';
}
$canonical = self::resolveEncoding($fallbackEncoding);
if ($canonical === 'UTF-8') {
throw new \ValueError(
'Fallback encoding cannot be UTF-8. Use toUtf8() for explicit UTF-8 validation.',
);
}
// UTF-8 is the only encoding we can reliably detect:
// it has strict byte sequence rules that reject invalid sequences.
if (mb_check_encoding($string, 'UTF-8')) {
$result = $string;
} else {
$result = self::toUtf8($string, $canonical, stripBom: false);
}
return $stripBom ? self::stripUtf8Bom($result) : $result;
}
/**
* Converts an array of strings to UTF-8 from a known encoding.
*
* @param list<string> $strings
* @return list<string>
*/
public static function arrayToUtf8(
array $strings,
string $sourceEncoding,
bool $stripBom = true,
): array {
return array_map(
static fn (string $s): string => self::toUtf8($s, $sourceEncoding, $stripBom),
$strings,
);
}
/**
* Returns all supported encoding names (canonical + aliases).
*
* @return list<string>
*/
public static function supportedEncodings(): array
{
return array_values(array_unique([
...self::CANONICAL_ENCODINGS,
...array_keys(self::ENCODING_ALIASES),
]));
}
/**
* Resolves a user-supplied encoding name to its canonical form.
*
* @throws \ValueError If encoding is unknown.
*/
private static function resolveEncoding(string $encoding): string
{
$normalized = strtolower(trim($encoding));
if (isset(self::ENCODING_ALIASES[$normalized])) {
return self::ENCODING_ALIASES[$normalized];
}
$match = array_find(
self::CANONICAL_ENCODINGS,
static fn (string $canonical): bool => strtolower($canonical) === $normalized,
);
if ($match !== null) {
return $match;
}
throw new \ValueError(sprintf(
'Unsupported encoding "%s". Supported: %s',
$encoding,
implode(', ', self::supportedEncodings()),
));
}
/**
* Validates that a string is well-formed UTF-8.
*
* @throws \ValueError If the string contains invalid UTF-8 sequences.
*/
private static function ensureValidUtf8(string $string): string
{
if (! mb_check_encoding($string, 'UTF-8')) {
throw new \ValueError('String is not valid UTF-8.');
}
return $string;
}
/**
* Converts a single-byte encoded string to UTF-8.
*
* All supported single-byte encodings share the same base:
* - 0x00-0x7F: ASCII (identity)
* - 0x80-0xFF: Encoding-specific - use overrides map first, then Latin-1 identity.
*
* @param array<int, string> $overrides Byte -> UTF-8 mapping for encoding-specific codepoints.
* For Windows-1252: the 0x80-0x9F special range.
* For ISO-8859-15: the 8 bytes that differ from Latin-1.
*/
private static function fromSingleByte(string $string, array $overrides): string
{
/** @var array<int, int> $bytes keyed from 1 (unpack behavior) */
$bytes = unpack('C*', $string);
$parts = [];
foreach ($bytes as $byte) {
$parts[] = match (true) {
$byte >= 0 && $byte <= 0x7F => chr($byte),
isset($overrides[$byte]) => $overrides[$byte],
default => self::encodeLatin1ByteAsUtf8($byte),
};
}
return implode('', $parts);
}
/**
* Encodes a single byte (0x80-0xFF) as a two-byte UTF-8 sequence.
*
* For Latin-1 / ISO-8859-1, the Unicode codepoint equals the byte value,
* so the UTF-8 encoding is: 110xxxxx 10xxxxxx.
*
* @throws \ValueError If the byte is outside the expected range.
*/
private static function encodeLatin1ByteAsUtf8(int $byte): string
{
if ($byte < 0x80 || $byte > 0xFF) {
throw new \ValueError(
sprintf('Byte must be in range 0x80-0xFF, got 0x%02X.', $byte),
);
}
return chr(0xC0 | ($byte >> 6)) . chr(0x80 | ($byte & 0x3F));
}
/**
* Strips the UTF-8 BOM (EF BB BF) if present at the start of the string.
*/
private static function stripUtf8Bom(string $string): string
{
if (str_starts_with($string, self::UTF8_BOM)) {
return substr($string, 3);
}
return $string;
}
}

View file

@ -0,0 +1,196 @@
<?php
declare(strict_types=1);
namespace Shared\Helpers;
final readonly class StringHelper
{
private function __construct()
{
// Static class
}
/**
* Transliterates UTF-8 text to ASCII using ICU Transliterator with iconv fallback.
*/
public static function transliterate(string $value): string
{
if (\function_exists('transliterator_transliterate')) {
$transliterated = \transliterator_transliterate('Any-Latin; Latin-ASCII', $value);
if ($transliterated !== false) {
return $transliterated;
}
}
return (string) iconv('UTF-8', 'ASCII//TRANSLIT//IGNORE', $value);
}
public static function mbStrtok(string $delimiters, ?string $str = null): string | false
{
/** @var int $pos */
static $pos = 0;
/** @var string $string */
static $string = '';
if ($str !== null) {
$pos = 0;
$string = $str;
}
$token = '';
$len = mb_strlen($string, 'UTF-8');
while ($pos < $len) {
$char = mb_substr($string, $pos, 1, 'UTF-8');
$pos++;
if (mb_strpos($delimiters, $char, 0, 'UTF-8') === false) {
$token .= $char;
} else {
if ($token !== '') {
return $token;
}
}
}
if ($token !== '') {
return $token;
}
return false;
}
/**
* Transliterates and formats a string into a URL-friendly slug.
*/
public static function slugify(string $value, string $separator = '-'): string
{
$transliterated = self::transliterate($value);
$cleaned = preg_replace('/[^a-zA-Z0-9]+/u', $separator, $transliterated) ?? '';
return strtolower(trim($cleaned, $separator));
}
/**
* Convert a string to snake_case.
*/
public static function snakeCase(string $value): string
{
return mb_strtolower(implode('_', self::splitWords($value)));
}
/**
* Convert a string to kebab-case.
*/
public static function kebabCase(string $value): string
{
return mb_strtolower(implode('-', self::splitWords($value)));
}
/**
* Convert a string to Title Case.
*/
public static function titleCase(string $value): string
{
$trimmed = trim($value);
if ($trimmed === '') {
return '';
}
return mb_convert_case(
mb_strtolower($trimmed, 'UTF-8'),
\MB_CASE_TITLE,
'UTF-8'
);
}
/**
* Convert a string to PascalCase (StudlyCase).
*/
public static function pascalCase(string $value): string
{
$words = array_map(
static fn (string $word): string => mb_ucfirst(mb_strtolower($word)),
self::splitWords($value)
);
return implode('', $words);
}
/**
* Convert a string to camelCase.
*/
public static function camelCase(string $value): string
{
return mb_lcfirst(self::pascalCase($value));
}
/**
* Split a string into words, respecting Unicode word boundaries.
*/
public static function words(string $value, int $words = 100, string $end = ' ...'): string
{
preg_match('/^\s*+(?:\S+\s*+){1,' . $words . '}/u', $value, $matches);
if (! isset($matches[0]) || mb_strlen($value) === mb_strlen($matches[0])) {
return $value;
}
return rtrim($matches[0]) . $end;
}
/**
* Sanitizes and normalizes a text string (strips HTML, removes non-printable control characters, ensures valid UTF-8).
*/
public static function sanitize(?string $value): ?string
{
if ($value === null || $value === '') {
return $value;
}
// Decode HTML entities then strip tags
$value = html_entity_decode($value, ENT_QUOTES | ENT_HTML5, 'UTF-8');
$value = strip_tags($value);
// Normalize newlines, temporarily convert to <br /> to preserve paragraph breaks
$value = str_replace(["\r\n", "\r"], "\n", $value);
$value = str_replace("\n", '<br />', $value);
// Ensure valid UTF-8 (handling Windows-1252 / ISO-8859-1 legacy strings)
$value = StringEncoder::detectAndConvertToUtf8($value);
// Remove astral symbols (4-byte UTF-8) that may break storage/processing
$value = preg_replace('/[\x{10000}-\x{10FFFF}]/u', '', $value) ?? '';
// Remove control/non-printable characters but keep TAB(0x09), LF(0x0A) and CR(0x0D)
$value = preg_replace('/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F\xA0\xAD]/u', '', $value) ?? '';
// Revert <br /> back to newlines and final strip_tags as safety
$value = str_replace('<br />', "\n", $value);
return strip_tags($value);
}
/**
* Split an arbitrary string into individual word tokens.
*
* @return list<string>
*/
private static function splitWords(string $value): array
{
// 1. Separate camelCase transitions (e.g., "fooBar" -> "foo Bar")
$value = preg_replace('/(?<=[a-z0-9])([A-Z])/u', ' $1', $value) ?? $value;
// 2. Separate acronyms followed by regular words (e.g., "HTTPResponse" -> "HTTP Response")
$value = preg_replace('/(?<=[A-Z])([A-Z][a-z])/u', ' $1', $value) ?? $value;
// 3. Replace non-alphanumeric characters with whitespace
$value = preg_replace('/[^\p{L}\p{N}]+/u', ' ', $value) ?? $value;
return array_values(array_filter(
explode(' ', trim($value)),
static fn (string $word): bool => $word !== ''
));
}
}