Dto Handler Bundle Laravel Package

Getting Started

To leverage the new DtoUtility::updateEntityList() feature in v2.3.3, start by importing the DtoUtility class (likely from the package namespace, e.g., Vendor\Package\DtoUtility). The key change is the new optional parameter for property-based comparison when updating entity lists.

First use case:

use Vendor\Package\DtoUtility;

// Example: Update a collection of User entities, comparing only 'name' and 'email'
$updatedEntities = DtoUtility::updateEntityList(
    $originalEntities, // Collection of Eloquent models or arrays
    $dtoList,          // Data Transfer Objects (DTOs) with updated data
    ['name', 'email']  // NEW: Specify properties for comparison
);

Check the package’s README.md for:

• The exact namespace of DtoUtility.
• Whether $originalEntities must be a collection or can be an array.
• Default behavior if no properties are specified (likely falls back to full comparison).

Implementation Patterns

1. Workflow for Partial Updates

Use the new parameter to optimize performance when only specific fields need validation before updating. For example:

// Update only 'status' and 'last_updated_at' fields
$updatedUsers = DtoUtility::updateEntityList(
    $users,
    $userDtos,
    ['status', 'last_updated_at']
);

2. Integration with Eloquent

If working with Eloquent models, ensure the compared properties exist in the model’s $fillable or $guarded arrays to avoid mass assignment errors. Example:

// In User model:
protected $fillable = ['name', 'email', 'status'];

// Safe update:
$updated = DtoUtility::updateEntityList($users, $dtos, ['name', 'status']);

3. Combining with Validation

Pair with Laravel’s validation to enforce rules before updating:

use Illuminate\Support\Facades\Validator;

$validator = Validator::make($dtoList, [
    '*.name' => 'required|string|max:255',
    '*.email' => 'required|email',
]);

if ($validator->fails()) {
    return response()->json(['errors' => $validator->errors()], 422);
}

$updated = DtoUtility::updateEntityList($users, $dtoList, ['name', 'email']);

4. Dynamic Property Selection

Fetch properties dynamically (e.g., from a config or request):

$compareFields = config('app.entity_comparison_fields'); // ['id', 'slug']
$updated = DtoUtility::updateEntityList($entities, $dtos, $compareFields);

Gotchas and Tips

Pitfalls

1. Property Existence:

   • If a specified property doesn’t exist on the entity, the method may silently skip the comparison or throw an error. Test with edge cases like:

     DtoUtility::updateEntityList($users, $dtos, ['nonexistent_field']); // Behavior?
     

2. Case Sensitivity:

   • Property names in the array must match the entity’s exact property names (e.g., camelCase vs snake_case). Use array_map('strtolower', ...) if needed.

3. Performance:

   • Over-specifying properties (e.g., comparing all columns) negates the performance benefit. Stick to only the fields used for uniqueness or critical updates.

4. DTO Structure:

   • Ensure DTOs align with the compared properties. For example, if comparing ['name', 'email'], the DTO must have these fields populated.

Debugging Tips

• Log Comparisons: Temporarily log the comparison logic to verify behavior:

  \Log::debug('Comparison properties:', ['properties' => ['name', 'email']]);
  

• Test Edge Cases: Validate with:
  • Empty property arrays.
  • DTOs missing compared properties.
  • Entities with null values in compared fields.

Extension Points

1. Custom Comparison Logic:

   • Override the default comparison by extending DtoUtility or using a wrapper:

     class CustomDtoUtility extends DtoUtility {
         public static function updateEntityList($entities, $dtos, $properties = []) {
             // Add custom logic (e.g., ignore null values)
             return parent::updateEntityList($entities, $dtos, $properties);
         }
     }
     

2. Event Hooks:

   • Listen for eloquent.updating events to add pre-update logic:

     User::updating(function ($user) {
         // Modify $user->attributes before DtoUtility updates it
     });
     

3. Configuration:

   • Store default comparison fields in config/package.php:

     'default_comparison_fields' => ['id', 'slug'],
     

   • Then use:

     $fields = config('package.default_comparison_fields');
     $updated = DtoUtility::updateEntityList($entities, $dtos, $fields);