Helpers Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require laravel/helpers
   

   No additional configuration is required—helpers are globally available after installation.

2. First Use Case: Replace deprecated global helpers (e.g., array_get()) with their modern equivalents while maintaining backward compatibility:

   // Legacy helper (still works)
   $value = array_get($array, 'key.default');
   
   // Modern equivalent (recommended for new code)
   $value = Arr::get($array, 'key.default');
   

3. Where to Look First:

   • Laravel Docs: Official documentation for Arr and Str classes (Laravel Helpers Docs).
   • Package Changelog: Check for Laravel/PHP version compatibility (e.g., v1.8.3 supports Laravel 12 and PHP 8.5).
   • Deprecated Helpers List: Refer to the Laravel 5.8 Helpers for a full list of supported functions.

Implementation Patterns

Usage Patterns

1. Legacy Code Migration:

   • Use the package as a temporary bridge during upgrades. Example:

     // Old code (works with package)
     $firstItem = head($collection);
     
     // New code (modern alternative)
     $firstItem = $collection->first();
     

   • Gradually replace helpers in small, testable batches (e.g., per feature or module).

2. Third-Party Package Compatibility:

   • If a legacy package fails due to missing helpers, install laravel/helpers to restore functionality without forking:

     // Example: Old package using `str_contains()`
     if (str_contains($string, 'search')) { ... }
     

   • Monitor for deprecation warnings in logs to prioritize refactoring.

3. Testing:

   • Write feature tests to verify helper behavior matches Laravel 5.8:

     public function test_array_get_returns_default()
     {
         $array = ['key' => null];
         $this->assertEquals('default', array_get($array, 'key.default'));
     }
     

   • Use phpunit with --coverage to track helper usage in legacy tests.

4. IDE Integration:

   • Configure your IDE (PHPStorm, VSCode) to recognize global helpers by adding:

     // phpstorm.meta.php
     {
       "laravel/helpers": {
         "functions": ["array_get", "str_contains", ...]
       }
     }
     

Workflows

1. Upgrade Workflow:

   • Step 1: Install laravel/helpers and upgrade Laravel core.
   • Step 2: Run tests to identify failing helper-dependent code.
   • Step 3: Replace helpers in low-risk areas first (e.g., utility classes, non-critical routes).
   • Step 4: Remove the package once all helpers are migrated to Arr/Str.

2. CI/CD Integration:

   • Add a deprecation warning check to your pipeline:

     # .github/workflows/test.yml
     - run: php artisan test -- --filter="DeprecationWarningTest"
     

   • Use roave/security-advisories to scan for Laravel version conflicts.

3. Documentation:

   • Maintain a migration checklist in your project’s UPGRADING.md:

     [ ] Replace `array_get()` with `Arr::get()`
     [ ] Replace `str_contains()` with `Str::contains()`
     

Integration Tips

• Avoid Mixing Helpers: Prefer Arr::get() over array_get() in new code to reduce future migration effort.
• Use Arr/Str Directly: For new projects, skip the package entirely and use Laravel’s built-in classes:

  // Preferred (no package needed)
  use Illuminate\Support\Arr;
  Arr::get($array, 'key');
  

• Leverage Aliases: The package registers helpers as global functions, but you can also use them via the Helper facade:

  use Illuminate\Support\Facades\Helper;
  Helper::array_get($array, 'key');
  

Gotchas and Tips

Pitfalls

1. Infinite Loops:

   • Older versions (<1.8.0) had bugs in array_first(), array_last(), and str_contains() that could cause infinite loops.
   • Fix: Upgrade to >=1.8.0 and ensure PHP 8.1+ is used.

2. Deprecated Function Warnings:

   • Laravel may emit deprecation warnings for helpers even with the package installed.
   • Solution: Suppress warnings temporarily during migration:

     error_reporting(E_ALL & ~E_DEPRECATED);
     

   • Long-term: Replace helpers to eliminate warnings entirely.

3. PHP Version Mismatches:

   • The package drops support for PHP <8.1 in newer releases (e.g., v1.8.2 requires PHP 8.5).
   • Workaround: Pin to an older version (e.g., 1.7.2 for PHP 8.1) if needed.

4. Array Prepend/Append Issues:

   • array_prepend() and array_append() may not pass all arguments correctly in older versions (<1.4.1).
   • Fix: Update to >=1.4.1 or manually call Arr::prepend():

     Arr::prepend($array, ...$values);
     

5. Testing Edge Cases:

   • Helpers may behave differently than Laravel 5.8 for edge cases (e.g., nested arrays, null values).
   • Tip: Write comprehensive tests for critical helper usage:

     public function test_nested_array_get()
     {
         $array = ['user' => ['name' => 'John']];
         $this->assertEquals('John', array_get($array, 'user.name'));
     }
     

Debugging

1. Helper Not Found:

   • Ensure laravel/helpers is listed in composer.json and autoloaded.
   • Debug: Run composer dump-autoload and verify the vendor/autoload.php includes the package.

2. Behavior Mismatches:

   • Compare output with Laravel 5.8’s behavior using a test container:

     $this->assertEquals(
         array_get(['a' => 1], 'a', 'default'),
         Arr::get(['a' => 1], 'a', 'default')
     );
     

3. Performance Overhead:

   • Global helpers add minimal overhead, but frequent calls in loops may impact performance.
   • Optimization: Cache helper results or replace with direct Arr/Str calls in hot paths.

Config Quirks

• No Configuration: The package is zero-config—installation is all that’s needed.
• Facade Overrides: If you use the Helper facade, ensure it’s not overridden by other packages:

  // Check for conflicts
  composer show --tree | grep helper
  

Extension Points

• Custom Helpers: Since the package is closed to new helpers, extend functionality by:
  • Creating a custom trait for project-specific helpers:

    trait CustomHelpers {
        public function customHelper($arg) { ... }
    }
    

  • Using Laravel’s macro system to extend Arr/Str:

    Arr::macro('customMethod', function ($array) { ... });
    

• Monkey Patching: Avoid modifying core Laravel files. Instead, use runtime overrides via app/Providers/AppServiceProvider:

  public function boot()
  {
      if (!function_exists('custom_helper')) {
          function custom_helper($arg) { ... }
      }
  }
  

Pro Tips

1. Leverage Arr/Str Features:

   • Modern Arr/Str classes offer more features than global helpers (e.g., Arr::dot(), Str::of()).
   • Example:

     // Global helper
     str_contains($str, 'search');
     
     // Modern alternative
     Str::contains($str, 'search'); // + more methods like `Str::of()->contains()`
     

2. Automated Refactoring:

   • Use PHPStorm’s "Replace" refactoring to batch-replace helpers:
     • Search for array_get( → Replace with Arr::get(.
     • Enable "Update references" to handle all occurrences.

3. Document Migration Progress:

   • Add a TODO comment in legacy files to track helper usage:

     // TODO: Replace `array_get()` with `Arr::get()` in this method
     $value = array_get($data, 'path');
     

4. Monitor Usage:

   • Run `git grep "