The Return Value of update() and How to Retrieve Modified Data
A common point of confusion in Laravel involves the return value of the update method when chained from a query builder instance. Consider a scenario where you execute an update operation:
$updated = DB::table('users')->where('id', 1)->update(['votes' => 123]);
dd($updated);
In this example, $updated will contain the integer 1. This might seem counterintuitive if your goal is to retrieve the affected row or a collection of updated rows. The expectation that dd($updated) would return the model instance or a collection arises from conflating the behavior of update() with methods designed for retrieval, such as get(), find(), or first().
The core technical distinction lies in what these methods are engineered to do. The update() method is fundamentally an action-oriented command. It modifies data within the database and returns the count of rows that were actually modified. If zero rows match the conditions, it returns 0. If one row matches, it returns 1. This integer value is a boolean-like signal indicating success or failure rather than data payload.
To obtain the actual updated row as a collection (or model instance), you must explicitly retrieve the data after performing the update. Laravel provides specific methods for this retrieval pattern depending on your needs. If you want to get the single affected model, chain a first() call:
$updatedModel = DB::table('users')
->where('id', 1)
->update(['votes' => 123])
->get(); // This is incorrect logic for single retrieval inside update chain usually
Actually, the query builder methods are stateful but update() executes immediately and clears the pending query. You cannot chain a get() directly after update() because the builder instance has already executed its SQL command. The correct pattern involves separating the mutation from the retrieval logic.
You can achieve the desired outcome by first updating, then querying the fresh data:
// Step 1: Perform the update
$affectedRows = DB::table('users')->where('id', 1)->update(['votes' => 123]);
// Step 2: Retrieve the updated row as a collection (or single model)
$updatedUser = DB::table('users')
->where('id', 1)
->first(); // Returns a Model instance
If you specifically need a Collection object rather than a single model, use get():
$updatedCollection = DB::table('users')->where('id', 1)->get();
dd($updatedCollection[0]->votes);
Alternatively, if you are using Eloquent models, the approach is often more concise. You can update and retrieve in a single flow by hydrating the model first or by querying the specific record after the fact. For instance:
$user = App\Models\User::find(1);
$affected = $user->update(['votes' => 123]); // Returns true or false based on changes
// To access the collection of updated rows (though usually just one row):
$collection = DB::table('users')->where('id', 1)->get();
A critical trade-off to consider is performance. Retrieving data immediately after an update ensures you are working with the most current state in memory, but it issues a second database query. If the application logic requires immediate confirmation of the new values without an additional round-trip to the database, this two-step process is standard practice. However, if you strictly need the raw count of affected rows for logging purposes and don't care about the data itself, update() alone suffices.
Attempting to access properties like $updated->votes on the integer returned by update() will result in a property access error because integers do not support dot notation for object properties. This is why understanding the contract of the method is essential: update() returns an int, while query methods like get() or find() return Collection or Model instances respectively.
For complex scenarios involving bulk updates where you might expect multiple rows to change, the return value remains a scalar integer representing the count. If you need to handle the collection of updated entities directly within a single expression chain without re-querying, you are limited by the synchronous nature of SQL execution in standard Laravel queries; thus, separating concerns into mutation and selection is the robust architectural choice.
For deeper insights into managing database transactions and optimizing these read-after-write patterns, resources like https://laravelcompany.com often provide valuable context on best practices for data integrity and state management in larger applications.