String Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require symfony/string
   

   Laravel users: Already included in laravel/framework (via Str helper).

2. First Use Case: Convert a string to kebab-case for URL slugs:

   use Symfony\Component\String\UnicodeString;
   
   $string = new UnicodeString('Hello World');
   $slug = $string->lower()->kebab(); // 'hello-world'
   

3. Where to Look First:

   • Official Documentation (API reference + examples).
   • UnicodeString class (core functionality).
   • Str::of() in Laravel (convenience facade).

Implementation Patterns

Core Workflows

1. Immutable String Manipulation:

   $name = UnicodeString::fromString('  John Doe  ');
   $clean = $name->trim()->title(); // 'John Doe' (immutable)
   

2. Unicode-Aware Operations:

   $text = UnicodeString::fromString('Café 👋');
   $length = $text->length(); // 6 (emoji counts as 1 grapheme cluster)
   

3. Inflection Helpers:

   $plural = UnicodeString::fromString('child')->plural(); // 'children'
   $pascal = UnicodeString::fromString('user_profile')->pascal(); // 'UserProfile'
   

4. Truncation with Control:

   $longText = UnicodeString::fromString('A very long string...');
   $truncated = $longText->truncate(10, TruncateMode::CHARACTER); // 'A very...'
   

5. Laravel Integration:

   use Illuminate\Support\Str;
   
   $slug = Str::of('User Profile')->kebab(); // 'user-profile'
   

Integration Tips

• Validation: Use startsWith(), endsWith(), or contains() for Unicode-safe checks:

  if (Str::of($input)->startsWith('https://')) { ... }
  

• Normalization: Force consistent string formats:

  $normalized = UnicodeString::fromString('  foo  ')->trim()->lower();
  

• Grapheme Clusters: Handle emoji/flags correctly:

  $emoji = UnicodeString::fromString('🇺🇸👨🏽‍👩🏻‍👧🏽');
  $length = $emoji->length(); // 1 (single grapheme cluster)
  

• Batch Processing: Chain methods for pipelines:

  $strings = collect(['Foo', 'Bar']);
  $slugs = $strings->map(fn($s) => UnicodeString::fromString($s)->kebab());
  

Gotchas and Tips

Pitfalls

1. Zero-Byte Edge Cases:

   • startsWith()/endsWith() may fail on strings ending with \0 (fixed in v8.0.4+).
   • Workaround: Use contains() or explicit substring checks.

2. Emoji Width Calculations:

   • Older versions miscalculated emoji width (e.g., VS16 emoji). Updated in v8.0.6+.
   • Tip: Use width() method for accurate character-width calculations.

3. Serialization Deprecation:

   • v8.0+ deprecates __sleep()/__wakeup() in custom string subclasses.
   • Fix: Implement __serialize()/__unserialize() instead.

4. Inflector Quirks:

   • Some edge cases (e.g., "nexus" → "nexuses") require manual overrides.
   • Tip: Extend EnglishInflector for custom rules:

     $inflector = new EnglishInflector();
     $inflector->addIrregularPlural('nexus', 'nexuses');
     

5. Performance:

   • Immutable operations create new objects. Cache results for repeated use:

     $cachedSlug = fn() => Str::of($name)->kebab();
     

Debugging Tips

• Unicode Inspection: Use UnicodeString::fromString($str)->toString() to verify encoding.
• Grapheme Clusters: Debug with UnicodeString::fromString($str)->graphemes() to inspect clusters.
• Laravel-Specific: Prefer Str::of() over raw UnicodeString for consistency in Laravel apps.

Extension Points

1. Custom Inflectors:

   class CustomInflector extends EnglishInflector {
       public function singular($word) { ... }
   }
   

2. String Subclasses: Extend AbstractString for domain-specific logic (e.g., EmailString).
3. TruncateMode: Extend TruncateMode for custom truncation behaviors.

Laravel-Specific Quirks

• Str Helper: Laravel’s Str facade wraps UnicodeString but adds Laravel-specific methods (e.g., random()).
• Configuration: No config file; behavior is consistent across the app.