Php Mb String Laravel Package

Getting Started

Install the package via Composer: composer require jfcherng/php-mb-string. Begin by wrapping long UTF-8 strings in MbString when you need frequent random access or mutation (e.g., new MbString($content)). Start with literal indexing like $str[0] or $str[5] = '許'—these work safely without byte-offset miscalculations. The README’s example and test suite are the first places to look for practical usage.

Implementation Patterns

• Performance-critical loops: Wrap large UTF-8 strings once and iterate with $mbStr[$i] instead of mb_substr() inside loops—avoiding repeated decoding overhead.
• In-place mutations: Treat MbString as mutable: $str[3] = '你好'; replaces at the 4th codepoint (not byte), enabling safe multi-byte character insertion.
• Batch replacements: Prefer $str->replace($from, $to) over str_replace() on raw UTF-8—internally leverages fast index-based operations via UTF-32 conversion.
• Diff & text-edit workflows: Ideal for text comparison/editing pipelines (e.g., collaboration tools, diff engines), where character-level edits dominate and memory overhead is acceptable.
• CLI/data processing jobs: Use for batch processing logs, markdown, or i18n content where strings are large and operations repetitive (e.g., linting, normalization, tokenization).

Gotchas and Tips

• Hard dependency on ext-iconv: Ensure it’s enabled—no graceful fallback if missing.
• Memory cost: UTF-32 storage multiplies memory ~4× over raw UTF-8 (e.g., 1M chars → ~4MB); monitor in long-running processes or with massive strings.
• Indexing is codepoint-based: $str[0] = first character, not byte—confusing if expecting substr()-style byte offsets.
• Mutable by default: Assignments like $str[2] = 'x' modify in-place; use clone $str for immutability.
• Avoid mixing types: Don’t interleave MbString with native strings in logic—e.g., comparing $mbStr[0] === $nativeStr[0] may yield false positives due to encoding mismatches.
• Debugging: Use (string)$mbStr or $mbStr->toString() only at final output stages—casting mid-flow adds overhead and defeats performance goals.
• PHP 8.1+ required: Not usable in legacy environments; verify target runtime compatibility.
• Benchmark first: Performance gains only manifest for large strings (>1KB) with many operations; for small strings, overhead may outweigh benefits.