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:
parent
3e4732bcb4
commit
a7354cb051
3 changed files with 528 additions and 2 deletions
|
|
@ -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) ?? '';
|
||||
|
|
|
|||
330
shared/Helpers/StringEncoder.php
Normal file
330
shared/Helpers/StringEncoder.php
Normal 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;
|
||||
}
|
||||
}
|
||||
196
shared/Helpers/StringHelper.php
Normal file
196
shared/Helpers/StringHelper.php
Normal 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 !== ''
|
||||
));
|
||||
}
|
||||
}
|
||||
Loading…
Add table
Reference in a new issue