Stringy Laravel Package

Getting Started

Begin by installing the package via Composer:

composer require statamic/stringy

Since it’s a low-dependency utility, no service provider registration is needed—just import the Stringy class directly:

use Stringy\Stringy as S;

// Basic usage
$greeting = S::create('hello world')->upper()->toString(); // 'HELLO WORLD'

Start with core methods like upper(), lower(), slugify(), contains(), startsWith(), and truncate()—these are the most frequently used for day-to-day tasks like preparing titles, slugs, and search snippets.

Implementation Patterns

• Chain methods fluently for inline string transformations in controllers or services:

  $slug = S::create($title)
      ->lower()
      ->slugify('-')
      ->lowercaseFirst()
      ->toString();
  

• Use in Laravel helpers or services: Wrap reusable string logic in a dedicated StringFormatter service class or Laravel macro (e.g., on Str) to maintain consistency across the app:

  Str::macro('safeTruncate', function ($string, $length = 100, $end = '...') {
      return S::create($string)->truncate($length, $end)->toString();
  });
  

• Template-friendly formatting in Blade via custom directives or helper functions (especially useful in Statamic contexts):

  // helpers.php
  function format_excerpt($text, $length = 160) {
      return S::create(strip_tags($text))->truncate($length, '…')->toString();
  }
  

• Validation and normalization pipelines: Pre-clean user input before saving or comparing:

  $cleanTitle = S::create($request->title)
      ->trim()
      ->collapseWhitespace()
      ->titleize()
      ->toString();
  

Gotchas and Tips

• Multibyte safety: Methods like substr() and strlen() in the class use mb_* internally—never assume ASCII behavior. For strict byte-level operations, fall back to PHP’s native functions.
• null handling: Stringy::create(null) throws an exception. Always validate or default input first: S::create($input ?? '').
• Case methods aren’t locale-aware: upper(), lower(), titleize() use standard Unicode case mappings—but for language-specific rules (e.g., Turkish dotless ı), prefer mb_strtoupper() + custom logic.
• Extensibility: You can extend Stringy with custom methods by subclassing or wrapping via PHP’s __call() if needed—but avoid over-engineering; favor composability with native helpers (e.g., combine with Str).
• Performance: Chain-heavy operations create new instances each time. For hot paths or very long strings, prefer in-place transforms using PHP’s mb_* or Laravel’s Str if performance is critical.
• Laravel Str compatibility: Many methods mirror Illuminate\Support\Str, but statamic/stringy often provides more nuanced options (e.g., slugify($separator) vs Str::slug()’s fixed -). Use it when you need explicit control.