Ia Arr Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require pragmarx/ia-arr
   

   Add the namespace to your project:

   use IlluminateAgnostic\Arr\Support\Arr;
   

2. First Use Case: Replace native PHP array operations with Arr helpers. For example:

   $data = ['user' => ['name' => 'John', 'email' => 'john@example.com']];
   $email = Arr::get($data, 'user.email'); // Returns 'john@example.com'
   

3. Key Documentation:

   • Refer to Laravel's official Arr helper docs for method signatures.
   • Check the package changelog for version-specific updates.

Implementation Patterns

Common Workflows

1. Data Extraction: Use Arr::get(), Arr::get() with defaults, or Arr::only()/Arr::except() to filter nested arrays:

   $user = Arr::only($data, ['user.name', 'user.email']);
   

2. Modification: Leverage Arr::set(), Arr::prepend(), or Arr::pull() for in-place updates:

   Arr::set($data, 'user.address.city', 'New York');
   

3. Validation & Checks: Combine with Arr::has() or Arr::exists() for conditional logic:

   if (Arr::has($data, 'user.settings')) {
       // Handle nested settings
   }
   

4. Collection Integration: Convert arrays to Illuminate\Support\Collection for fluent operations:

   $collection = collect($data)->map(function ($value, $key) {
       return Arr::get($value, 'name');
   });
   

Integration Tips

• Laravel Projects: Use the IlluminateAgnostic namespace to avoid conflicts with Laravel’s native Arr (e.g., in non-Laravel classes).
• Non-Laravel Projects: Pair with symfony/var-dumper (included as a dependency) for debugging:

  dump(Arr::get($data, 'user.*')); // Dump nested keys
  

• Testing: Mock Arr methods in unit tests:

  $this->partialMock(Arr::class, ['get'])->willReturn('mocked_value');
  

Gotchas and Tips

Pitfalls

1. Case Sensitivity:

   • Arr::get() is case-sensitive by default. Use Arr::get($array, 'user.Name') for exact matches or lowercase keys if needed.
   • Fix: Normalize keys before use:

     $normalized = array_change_key_case($array, CASE_LOWER);
     Arr::get($normalized, 'user.name');
     

2. Deep Dot Notation:

   • Fails silently if a path doesn’t exist (returns null). Always provide defaults:

     Arr::get($data, 'user.non_existent', []); // Returns empty array
     

3. PHP 7.0+ Only:

   • Avoid using on older PHP versions (e.g., 5.x). The package drops support for pre-7.0.

4. Collection vs. Array:

   • Methods like Arr::pluck() may behave differently on Collection vs. raw arrays. Prefer collect($array)->pluck() for consistency.

Debugging

• Var Dumping: Use dump(Arr::all($array)) to inspect nested structures.
• Method Chaining: Avoid chaining methods that modify the original array (e.g., Arr::pull()). Store results in variables:

  $value = Arr::pull($array, 'key');
  $modified = Arr::set($array, 'new.key', $value);
  

Extension Points

1. Custom Helpers: Extend the package by creating a wrapper class:

   class CustomArr extends Arr {
       public static function customMethod(array $array) {
           return self::get($array, 'custom.path', []);
       }
   }
   

2. Laravel Facade: In Laravel projects, create a facade to reuse the package’s methods:

   // app/Providers/AppServiceProvider.php
   use Illuminate\Support\Facades\Facade;
   Facade::alias('Arr', IlluminateAgnostic\Arr\Support\Arr::class);
   

3. Performance: For large arrays, cache results of expensive operations (e.g., Arr::pluck()) to avoid recomputation:

   $cached = Arr::pluck($data, 'user.*');
   cache()->put('user_data', $cached, now()->addHours(1));
   

Config Quirks

• No Configuration: The package is stateless. All behavior is determined by method arguments (e.g., Arr::set($array, $key, $value)).