String Laravel Package

Getting Started

Install via Composer: composer require opis/string. The package provides a single OpisString class (aliased as Opis\String\StringObject) that wraps any string in an immutable, multibyte-aware object. Start by replacing basic string operations (e.g., strlen, strpos, substr) with method calls on the object—for example:

use Opis\String\StringObject;

$s = new StringObject('Café');
echo $s->length(); // 4 (not 5, handles UTF-8 correctly)
echo $s->substring(0, 3); // 'Caf'

Look at the class methods first—especially length(), substring(), strpos(), lower(), upper(), trim(), and contains()—which all handle multibyte characters natively without needing the mb_* extension (though it’s used if available).

Implementation Patterns

• Immutable Chaining: All mutators (e.g., upper(), trim()) return a new StringObject, enabling fluent chains:

  $result = (new StringObject('hello world'))
      ->upper()
      ->substring(0, 5)
      ->trim();
  // $result is 'HELLO'
  

• Type Safety & Clarity: Use StringObject in method signatures to enforce multibyte-safe string handling:

  public function process(StringObject $title): StringObject { ... }
  

• Fallback Helpers: Wrap raw strings via StringObject::of($str) before operations. Useful in value objects or DTOs where string integrity matters (e.g., user names, titles with accents, emojis).
• Comparison & Validation: Leverage equals(), startsWith(), endsWith(), matches() for robust conditional logic (e.g., validating localized prefixes/suffixes).

Gotchas and Tips

• Immutability Surprise: Assigning $str = $str->upper() is required—chaining without assignment discards changes silently.
• No __toString() by default: Convert back to string explicitly with (string)$obj or $obj->toString(). Forgetting this causes silent failures or "Object of class Opis\String\StringObject could not be converted to string" errors.
• Performance: Instances are lightweight, but avoid excessive wrapping/unwrapping in hot loops (e.g., inside for iterations over large arrays). Prefer bulk operations (e.g., map with StringObject::of($str) once per element).
• Unicode Edge Cases: While multibyte-aware, it doesn’t handle all Unicode edge cases (e.g., grapheme clusters, emoji skin tones). For complex needs, fall back to grapheme_* functions or external libraries.
• IDE Hinting: Use StringObject in docblocks to prevent auto-completion fatigue: /** @var StringObject $title */.