Array Dot Notation Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require sajadsdi/array-dot-notation
   

   No additional configuration is required—just autoload via Composer.

2. First Use Case: Convert a flat array to dot notation for nested access:

   use Sajadsdi\ArrayDotNotation\ArrayDotNotation;
   
   $array = ['user' => ['name' => 'John', 'age' => 30]];
   $dotArray = ArrayDotNotation::dot($array);
   
   // Access nested values with dot notation
   echo $dotArray['user.name']; // Output: "John"
   

3. Where to Look First:

   • Class Docs (if available) for method signatures.
   • Test the dot() and undot() methods on sample arrays to understand transformations.

Implementation Patterns

Core Workflows

1. Dot Notation Conversion:

   • Flattening: Convert nested arrays to dot notation for APIs/configs.

     $config = ['database' => ['host' => 'localhost']];
     $dotConfig = ArrayDotNotation::dot($config);
     // $dotConfig['database.host'] = 'localhost'
     

   • Unflattening: Rebuild nested arrays from dot notation (e.g., for storage).

     $dotData = ['user.address.city' => 'New York'];
     $nestedData = ArrayDotNotation::undot($dotData);
     // $nestedData['user']['address']['city'] = 'New York'
     

2. Dynamic Access:

   • Useful for configurable settings or user input validation:

     $settings = ArrayDotNotation::dot($_POST);
     if ($settings['user.settings.notifications.enabled']) {
         // Handle enabled notifications
     }
     

3. Integration with Laravel:

   • Request Handling: Convert Request->all() to dot notation for cleaner access:

     $input = ArrayDotNotation::dot(request()->all());
     $theme = $input['app.theme']; // Instead of $input['app']['theme']
     

   • Configuration: Override config values dynamically:

     $config = ArrayDotNotation::undot(config('custom.dot_notation'));
     

4. Validation:

   • Simplify nested validation rules in Laravel:

     $rules = [
         'user.name' => 'required|string',
         'user.address.city' => 'string|max:50',
     ];
     $dotInput = ArrayDotNotation::dot(request()->input());
     $validator = Validator::make($dotInput, $rules);
     

Gotchas and Tips

Pitfalls

1. Overwriting Keys:

   • Dot notation may overwrite existing keys if paths collide. Example:

     $array = ['a.b' => 1, 'a' => ['b' => 2]];
     ArrayDotNotation::dot($array); // 'a.b' becomes 2 (overwritten)
     

   • Fix: Use ArrayDotNotation::dot($array, false) to preserve original keys.

2. Non-String Keys:

   • The package assumes keys are strings. Non-string keys (e.g., integers) may cause issues:

     $array = [1 => ['name' => 'Test']];
     ArrayDotNotation::dot($array); // Throws error or behaves unexpectedly
     

   • Fix: Cast keys to strings manually or pre-process the array.

3. Performance:

   • undot() can be slow for large arrays due to recursive rebuilding. Test with production-sized data.

4. Laravel Caching:

   • Cached dot-converted arrays (e.g., in config()) may not update if the underlying array changes. Re-convert on demand if needed.

Debugging Tips

1. Verify Transformations:

   • Use print_r() or dd() to inspect transformed arrays:

     $dotArray = ArrayDotNotation::dot($array);
     dd($dotArray); // Check for unexpected keys/values
     

2. Edge Cases:

   • Test with:
     • Empty arrays.
     • Arrays with null values.
     • Deeply nested structures (5+ levels).

3. Custom Separators:

   • The default separator is .. Override it globally:

     ArrayDotNotation::setSeparator('__');
     $array = ['user__name' => 'John']; // Now uses `__` instead of `.`
     

Extension Points

1. Custom Dot Paths:

   • Extend functionality by adding helper methods:

     // Example: Get all keys under a path
     function getDotKeys(array $dotArray, string $path): array {
         $keys = [];
         foreach ($dotArray as $key => $value) {
             if (str_starts_with($key, $path . '.')) {
                 $keys[] = str_replace($path . '.', '', $key);
             }
         }
         return $keys;
     }
     

2. Integration with Laravel Collections:

   • Combine with Collections for fluent dot notation:

     $collection = collect($array)->mapWithKeys(function ($item, $key) {
         return ArrayDotNotation::dot($item, false);
     });
     

3. Middleware for Dot Notation:

   • Automatically convert request input in Laravel middleware:

     public function handle($request, Closure $next) {
         $request->merge(ArrayDotNotation::dot($request->all()));
         return $next($request);
     }
     

     Now access $request->input('user.name') directly.