Php Dot Notation Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require adbario/php-dot-notation
   

   No additional configuration is required—just autoload via Composer.

2. First Use Case: Access nested array values with dot notation:

   use Adbar\Dot;
   
   $array = ['user' => ['name' => 'John', 'details' => ['age' => 30]]];
   echo Dot::get($array, 'user.name'); // Output: "John"
   echo Dot::get($array, 'user.details.age'); // Output: 30
   

3. Where to Look First:

   • Class Documentation (if available).
   • Dot::get(), Dot::set(), and Dot::delete() methods for core functionality.
   • Dot::setDefault() for default value handling.

Implementation Patterns

Common Workflows

1. Accessing Nested Data:

   $data = ['config' => ['theme' => 'dark', 'notifications' => ['enabled' => true]]];
   $theme = Dot::get($data, 'config.theme'); // "dark"
   

2. Setting Nested Values:

   Dot::set($data, 'config.theme', 'light');
   // $data now: ['config' => ['theme' => 'light', ...]]
   

3. Deleting Nested Keys:

   Dot::delete($data, 'config.notifications');
   // Removes the 'notifications' sub-array.
   

4. Default Values:

   $value = Dot::get($data, 'user.address.city', 'Unknown');
   // Returns 'Unknown' if 'user.address.city' doesn't exist.
   

5. Array-to-Object Conversion:

   $obj = Dot::object($data);
   $obj->config->theme; // Access like an object.
   

Integration Tips

• Laravel Eloquent: Useful for flattening nested attributes in models or queries.

  $user = User::find(1);
  $theme = Dot::get($user->toArray(), 'preferences.theme');
  

• API Requests: Parse deeply nested JSON payloads.

  $requestData = json_decode($request->getContent(), true);
  $email = Dot::get($requestData, 'user.contact.email');
  

• Configuration: Dynamically access nested config values (e.g., config('services.stripe.key') alternative).

  $stripeKey = Dot::get(config('services'), 'stripe.key');
  

Gotchas and Tips

Pitfalls

1. Overwriting Existing Keys: Dot::set() will overwrite the entire array if the path doesn’t exist. Use Dot::setDefault() to avoid this:

   Dot::setDefault($data, 'new.key', 'value'); // Only sets if 'new.key' is missing.
   

2. Case Sensitivity: Dot notation is case-sensitive. 'User.Name' ≠ 'user.name'.

3. Non-Array Inputs: Passing non-array data to Dot::get() will throw an exception. Validate inputs:

   if (is_array($data)) {
       Dot::get($data, 'path');
   }
   

4. Performance: Deeply nested operations on large arrays may impact performance. Cache results if reused:

   $cached = [];
   $cached['theme'] = Dot::get($data, 'config.theme');
   

Debugging

• Check Path Validity: Use Dot::has() to verify a path exists before accessing:

  if (Dot::has($data, 'user.profile')) {
      Dot::get($data, 'user.profile');
  }
  

• Default Values: Explicitly set defaults to avoid null surprises:

  Dot::get($data, 'path.to.value', []); // Default to empty array.
  

Extension Points

1. Custom Separators: Override the default . separator by extending the class:

   class CustomDot extends Dot {
       protected static $separator = '::';
   }
   

   Usage:

   CustomDot::get($data, 'user::profile');
   

2. Validation: Combine with Laravel’s Validator for nested data:

   $validator = Validator::make($data, [
       'user.profile.email' => 'required|email',
   ]);
   

3. Array Manipulation: Useful for serializing/deserializing complex data structures (e.g., Redis, caching).