Array Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require minwork/array
   

   Import the facade in your code:

   use Minwork\Array\Arr;
   

2. First Use Case: Replace native PHP array operations with fluent, expressive methods. For example, set a nested value:

   $array = Arr::set([], 'user.profile.name', 'John Doe');
   

3. Where to Look First:

   • Documentation for method signatures and examples.
   • Arr facade for all methods (e.g., Arr::get(), Arr::map()).
   • Focus on get, set, has, and map for 80% of daily use cases.

Implementation Patterns

Core Workflows

1. Nested Data Manipulation: Use get, set, and has for deep array traversal without manual recursion:

   $value = Arr::get($array, 'user.address.city');
   Arr::set($array, 'user.address.zip', '12345');
   if (Arr::has($array, 'user.email')) { ... }
   

2. Object Arrays: Treat arrays of objects like arrays with mapObjects, groupObjects, and sortObjects:

   $sizes = Arr::mapObjects($products, 'getSize');
   $grouped = Arr::groupObjects($users, 'getRole');
   

3. Chaining: Chain methods for declarative transformations:

   $result = Arr::obj($data)
       ->set('meta.total', count($data))
       ->remove('meta.old')
       ->getArray();
   

4. Data Validation: Use check for assertions:

   Arr::check($array, 'user.id', 'integer');
   Arr::check($array, 'user.name', 'string|min:3');
   

5. Grouping and Sorting: Group by keys or object methods, then sort:

   $grouped = Arr::group($data, 'category');
   $sorted = Arr::sortByKeys($grouped, 'priority');
   

Integration Tips

• Replace array_map/array_filter: Use Arr::map() with modes for flexible callbacks:

  Arr::map($array, fn($key, $value) => strtoupper($value), Arr::MAP_ARRAY_KEY_VALUE);
  

• Laravel Synergy: Use with Laravel collections for hybrid operations:

  $collection = collect($array)->mapWithKeys(fn($item) => Arr::map($item, ...));
  

• Form Requests: Sanitize nested input arrays:

  $validated = Arr::set($request->all(), 'user.roles', explode(',', $request->roles));
  

Gotchas and Tips

Pitfalls

1. Deprecated Syntax: Avoid Arr::map($callback, $array)—use Arr::map($array, $callback) to prevent warnings.

2. Key Collisions in Flattening: Arr::flatten($array, null, true) may lose keys if duplicates exist. Use Arr::flattenSingle() for single-element arrays.

3. Object Comparison: diffObjects/intersectObjects compare object references, not values. Use Arr::mapObjects() to normalize first if needed.

4. Chaining Pitfalls: Methods like set/remove modify the array in-place. Use getArray() to extract the result:

   $result = Arr::obj($data)->set('x', 1)->getArray(); // Correct
   $result = Arr::obj($data)->set('x', 1); // Returns Arr object, not array
   

Debugging Tips

• Check for Nested Keys: Use Arr::has() to verify paths before get/set:

  if (!Arr::has($array, 'user.address')) {
      Arr::set($array, 'user.address', []);
  }
  

• Inspect Flattened Arrays: Use Arr::flatten($array, 1, true) to debug partial flattening.

• Callback Errors: Wrap map/filter callbacks in try-catch for silent failures:

  Arr::map($array, fn($key, $value) => try { ... } catch (...) { null });
  

Extension Points

1. Custom Modes: Extend Arr::map() by defining new modes in the package’s MapMode class.

2. Object Normalization: Create a helper to convert objects to arrays for comparison:

   function normalizeForComparison($obj) {
       return Arr::mapObjects([$obj], 'getId');
   }
   

3. Laravel Service Provider: Bind Arr as a singleton for global access:

   $this->app->singleton('arr', fn() => new Arr());
   

4. Testing: Use Arr::check() for input validation in tests:

   Arr::check($response->data, 'user.id', 'integer|exists:users');