iksaku / laravel-mass-update
Update multiple Laravel Model records, each with different values, using a single query!
Installs: 573 339
Dependents: 1
Suggesters: 0
Security: 0
Stars: 126
Watchers: 5
Forks: 11
Open Issues: 3
Requires
- php: ^8.0
- illuminate/database: ^8.71|^9.0|^10.0|^11.0
- illuminate/support: ^8.71|^9.0|^10.0|^11.0
Requires (Dev)
- orchestra/testbench: ^8.0|^9.0
- pestphp/pest: ^1.19|^2.0
- vimeo/psalm: ^4.18|^5.6
README
Update multiple Laravel Model records, each with its own set of values, sending a single query to your database!
Installation
You can install the package via composer:
composer require iksaku/laravel-mass-update
Usage
In your model class, add the Iksaku\Laravel\MassUpdate\MassUpdatable
trait:
use Illuminate\Database\Eloquent\Model; use Iksaku\Laravel\MassUpdate\MassUpdatable; class User extends Model { use MassUpdatable; // ... }
And that's all! Your model is now ready to update multiple records with varying values in a single query!
Let's take a look at some possible use cases for this new query:
Simple use case: Update the values of multiple records
Imagine that you have the following users
table:
But, we want to update both records since those users have told us that their legal last name was misspelled:
González
is written with an accent on the lettera
, and only usesz
, never ans
.Martínez
is written with an accent on the letteri
, and last letter should be az
, not ans
Well, we can mass update those specific records:
User::massUpdate( values: [ ['id' => 1, 'name' => 'Jorge González'], ['id' => 2, 'name' => 'Gladys Martínez'], ] );
Now, both records will be updated with their corresponding values in a single query, resulting in:
By default, the massUpdate
query will grab your model's primary key name and apply it as part of
the query to not affect other records.
If you want to use another column as an index to separate value types, you could pass it as a second argument to the function call:
User::massUpdate( values: [ ['username' => 'iksaku', 'name' => 'Jorge González'], ['username' => 'gm_mtz', 'name' => 'Gladys Martínez'], ], uniqueBy: 'username' );
Simple use case #2: Updating multiple Eloquent Models
If you need to update the values in some Model classes and want to automatically mass update those changes, then this is for you!
The existing masUpdate
query is capable of identifying the dirty attributes of Eloquent
model classes
and compile them properly. You don't need to manually convert the models into an array, you just pass the
list of models you want to update, and it takes care of the rest.
Tip: If you pass a full list of
Eloquent
models, only those with dirty values will be updated, so you don't actually need to filter the unchanged ones manually.
Let's recreate the previous example, but using Eloquent
models...
// Say we already pulled our user models previously... Something like this: $jorge = User::where('name', 'Jorge Gonzales')->first(); $gladys = User::where('name', 'Gladys Martines')->first(); // And let's say we already made changes to those models... Like this: $jorge->name = 'Jorge González'; $gladys->name = 'Gladys Martínez'; // And now, let's update both models in a single query: User::massUpdate( values: [$jorge, $gladys] );
Pretty cool, right?
Note: It is only possible to mass update instances of the same
Eloquent
model, it is not possible to mix the Query Builder with differentEloquent
model classes.
Complicated use case: Using multiple indexes to differentiate records
Let's say that we just created expenses
table to track how much we spend across time, and
we manually filled the following values:
Above information is not real, I don't track my expenses quarterly.
Oops... We made a little mistake... Expenses from Q1 of 2020 and 2021 are switched, and in order to fix it
we could only pass the quarter
column as an index, but if we only pass down the quarter
column as an index,
we'll modify ALL Q1
records. So, for this, we should also pass down the year
column as an index:
Expense::massUpdate( values: [ ['year' => 2020, 'quarter' => 'Q1', 'total_expenses' => 431.35], ['year' => 2021, 'quarter' => 'Q1', 'total_expenses' => 416.70], ], uniqueBy: ['year', 'quarter'] );
Tip: If you ever need to specify more than one or two indexes, just include all of them in the
values
anduniqueBy
parameters.
The result in the table will be properly updated:
NOTE: It is important that you always include the
uniqueBy
columns in yourvalues
array, exceptions will be thrown otherwise.
NOTE #2: It is not possible to update the values of the
uniqueBy
columns. Every column specified in this parameter will be filtered from the ones that are going to be updated.This prevents unexpected side effects from happening while updating
values
inarray
shape and passed asEloquent
models.
Advanced use case: Chaining with other query statements
Let's try to keep things simple and imagine a system that tracks To-Do items for multiple users:
Like every To-Do system, we let our users order
their To-Do items to see the most important ones at
the top of the list, and to do this, we may be using a simple sorting package
that allows the user to drag items up and down the list.
Once the user moves one item in the list, in the backend we may receive an array with a specific key-value shape:
['position' => 'id']
. With this, we're going to update the records' position
based on the given id
.
We can simply call our massUpdate
query function and everything will be done... Well, sort of...
In this specific scenario, we're dealing with multiple lists for multiple users, that means that we may not
be always able to control which id
columns are sent to the server, maybe some malicious actor wants to hijack
our To-Do list and lower the priority for buying ThinkPads. This is a pretty serious security concern.
There are many ways to solve this kind of issues, and a simple one is to chain query statements to our
massUpdate
function.
In this case, we're going to add a where()
statement to only update those items that belong to the currently
logged in user. And it's as simple as in any other Laravel query builder:
TodoItem::query() ->where('user_id', auth()->id()) ->massUpdate( values: collect($request->input('item_order')) ->mapWithKeys( fn ($id, int $position) => ['id' => $id, 'order' => $position] ) );
Tip: Did you know you can pass Collections, LazyCollections, Eloquent Collections and basically any
Arrayable
instance asvalues
to themassUpdate
query function?
This can be used as an extra layer to ensure data integrity when dealing with User-provided input that affects multiple records in the database.
Testing
composer test
Changelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security Vulnerabilities
If you discover any security related issues, please email yo@jorgeglz.io instead of using the issue tracker.
Credits
License
The MIT License (MIT). Please see License File for more information.