Helpers Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require laravel/helpers
   

   No additional configuration is required—autoloading handles the facade aliases automatically.

2. First Use Case: Replace deprecated Laravel 5.8 helpers with their modern equivalents without code changes:

   // Legacy (Laravel 5.8) → Works in Laravel 9+
   array_add($array, 'key', 'value');          // → Arr::set($array, 'key', 'value');
   str_limit('long string', 20);              // → Str::limit('long string', 20);
   Html::decode('&entity;');              // → html_entity_decode() or Str::of('...')->decode();
   

3. Where to Look First:

   • Laravel Docs: Arr, Str for modern equivalents.
   • Package Source: ArrHelper and StrHelper to verify supported methods.
   • Changelog: Check for Laravel version compatibility (e.g., v1.7.2+ supports Laravel 12).

Implementation Patterns

Usage Patterns

1. Facade-Based Replacement: Use facades like Arr, Str, or Html to call legacy helpers transparently:

   // Before (Laravel 5.8)
   $value = array_get($array, 'key.default');
   
   // After (Laravel 9+ with package)
   $value = Arr::get($array, 'key', 'default');  // Works via facade alias
   

2. Migration Workflow:

   • Phase 1: Install the package and verify all legacy helpers work.
   • Phase 2: Log warnings when deprecated helpers are used (via custom middleware or static analysis).
   • Phase 3: Gradually replace calls with modern equivalents (e.g., Arr::set() instead of array_add()).

3. Integration with Legacy Code:

   • Service Providers: Register aliases if needed (though the package auto-registers them):

     // config/app.php
     'aliases' => [
         'Arr' => Illuminate\Support\Facades\Arr::class,
         'Str' => Illuminate\Support\Facades\Str::class,
     ],
     

   • Testing: Use Arr::shouldReceive('get')->andReturn(...) in PHPUnit to mock legacy calls during migration.

4. Performance Considerations:

   • The package adds zero runtime overhead—it delegates calls to Laravel’s native Arr/Str classes.
   • Avoid mixing legacy and modern calls (e.g., array_add() + Arr::set()) to prevent confusion.

Workflows

1. Upgrade Path:

   Laravel 5.8 → [Install helpers package] → Laravel 9+ → [Refactor to modern helpers] → Remove package
   

2. Plugin/Third-Party Compatibility:

   • Use the package to isolate legacy dependencies (e.g., a Laravel 5.8 plugin) in a microservice or module.
   • Example: Wrap plugin code in a service container binding that uses the helpers package.

3. CI/CD Integration:

   • Add a deprecation check in static analysis (e.g., PHPStan/Psalm) to flag legacy helper usage:

     // phpstan.neon
     rules:
         Laravel\Helpers\DeprecatedHelperRule: true
     

Gotchas and Tips

Pitfalls

1. Infinite Loop Risks:

   • Methods like array_first(), array_last(), or str_contains() may cause infinite loops in edge cases (fixed in v1.8.0+). Test with:

     $result = Arr::first([], fn($item) => true);  // Returns null (safe)
     

2. Null Handling:

   • Some legacy helpers (e.g., array_get()) return null for missing keys, while modern Arr::get() uses a default value. Test edge cases:

     Arr::get($emptyArray, 'nonexistent', 'default');  // Returns 'default'
     

3. Facade Alias Conflicts:

   • If you’ve overridden Arr/Str facades, the package may not work. Ensure no custom aliases exist in config/app.php.

4. PHP 8.4+ Strict Typing:

   • Some methods (e.g., array_prepend()) may throw type errors. Use func_get_args() workarounds or update calls to match modern signatures.

5. No New Helpers:

   • The package does not add new functionality—only preserves deprecated methods. Requests for new helpers are ignored.

Debugging

1. Missing Helper Errors:

   • Check if the package is installed (composer show laravel/helpers).
   • Verify Laravel’s Arr/Str classes are autoloaded (run composer dump-autoload).

2. Method Not Found:

   • Consult the source code to confirm the helper exists (e.g., array_except → Arr::except()).

3. Performance Issues:

   • Use Xdebug to confirm calls are delegated to Laravel’s native classes (no double dispatch).

Tips

1. Modern Equivalents Cheat Sheet:

   Legacy Helper	Modern Equivalent
   array_add()	Arr::set()
   array_get()	Arr::get()
   str_limit()	Str::limit()
   Html::decode()	html_entity_decode()
   Arr::dot()	Arr::dot() (already modern)

2. Refactoring Strategy:

   • Use search/replace with exclusions to avoid touching tests or third-party code:

     # Replace array_add with Arr::set (exclude vendor/)
     grep -r "array_add(" --exclude-dir=vendor | xargs sed -i 's/array_add(/Arr::set(/g'
     

3. Testing Legacy Helpers:

   • Mock the Arr facade in tests to verify behavior:

     $this->mock(Arr::class)->shouldReceive('get')->andReturn('mocked');
     

4. Laravel Version Quirks:

   • Laravel 11+: Some helpers (e.g., array_first) may behave differently due to PHP 8.5+ changes. Test thoroughly.
   • Laravel 9: Use Arr::where() instead of array_where() (deprecated in L9).

5. Extension Points:

   • Custom Helpers: If you need a helper not covered, create a trait or macro (e.g., Str::macro('customLimit', ...)).
   • Override Behavior: Extend the ArrHelper trait to modify default logic:

     use Laravel\Helpers\ArrHelper;
     class CustomArr extends ArrHelper { ... }