laravel/framework: Pull Request Analysis: Fix `incrementOrCreate()` ignoring `$extra` attributes on record creation

Category: Bug fix (9)

If you use incrementOrCreate() in a Laravel 13 application, pull request #61878 fixes a subtle but frustrating bug: the $extra attributes you pass were silently dropped whenever the method had to create the record instead of updating it. The fix lands in Illuminate\Database\Eloquent\Builder as well as the BelongsToMany and HasOneOrMany relation classes, so the very first call for a given record now behaves exactly like every call after it. If you are upgrading from v13.34.0, there is nothing to change in your code — the fix simply makes the method do what it always looked like it should do.

What changed

incrementOrCreate(array $attributes, string $column = 'count', $default = 1, $step = 1, array $extra = []) has always had two paths. When a matching record exists, it calls increment($column, $step, $extra), which bumps the counter and updates the extra columns. When no record exists, it calls firstOrCreate() — but until now it only passed [$column => $default] as the creation values. The $extra array was never forwarded, so those columns fell back to their database defaults (usually null) on the freshly created row.

The patch changes the creation call in three places — the Eloquent builder, BelongsToMany::incrementOrCreate(), and HasOneOrMany::incrementOrCreate():

// before
$this->firstOrCreate($attributes, [$column => $default]);

// after
$this->firstOrCreate($attributes, array_merge($extra, [$column => $default]));

The merge order matters: $extra is merged in first and the counter column with its $default is appended last, so the counter always starts at $default even if extra happened to contain a same-named key.

Why it matters

The bug produced rows that were wrong from birth. A classic example is tracking daily API usage per token:

$token->usages()->incrementOrCreate(
    ['date' => today()],
    'requests',
    extra: ['last_used_at' => now(), 'last_ip' => $request->ip()],
);
// first request of the day: last_used_at and last_ip are null
// every later request: both are set

Before the fix, the first request of each day created a row with requests = 1 but last_used_at and last_ip left null. Only from the second request onward did the extras get written. Any reporting, auditing, or analytics built on those columns silently missed the first hit of every period — arguably the one request you most want recorded. Workarounds like calling the method twice, following it with a manual update(), or falling back to firstOrCreate() plus increment() were the only options.

How the fix behaves in practice

The integration test added with this PR shows the full lifecycle on a belongsToMany relation:

$tag = $post->tags()->incrementOrCreate(
    ['name' => 'wavez'],
    extra: ['type' => 'featured'],
);

// First call: tag is created with count = 1 and type = 'featured'
$this->assertTrue($tag->wasRecentlyCreated);

$tag = $post->tags()->incrementOrCreate(
    ['name' => 'wavez'],
    extra: ['type' => 'pinned'],
);

// Second call: count is stepped to 2 and type is updated to 'pinned'

Both paths now share one contract: $attributes identify the record, the counter starts at $default (and is stepped by $step only on subsequent calls), and $extra is always reflected in the stored row.

Which surfaces are covered

The PR patches incrementOrCreate() in three classes:

• Illuminate\Database\Eloquent\Builder — standalone model queries.
• Illuminate\Database\Eloquent\Relations\BelongsToMany — pivot-style relations, which also covers morphToMany() and morphedByMany().
• Illuminate\Database\Eloquent\Relations\HasOneOrMany — the base for hasOne(), hasMany(), morphOne(), and morphMany().

Because the subclasses inherit the method, the fix reaches every relation type built on those base classes. A new unit test for the builder and a new integration test for BelongsToMany lock the behavior in.

Upgrade impact

This is a pure bug fix, and the impact for anyone on v13.34.0 is minimal:

• No signatures changed. $extra was already a parameter; it is simply honored on the create path now.
• Existing-record behavior is untouched. The increment($column, $step, $extra) branch is identical.
• The only observable difference is on creation, where extra columns are now populated. If some code path relied on the old behavior — deliberately passing extras you did not want persisted on first insert — audit it, though that pattern would be unusual.
• One reminder: the create path flows through firstOrCreate(), so the extra columns must be mass-assignable ($fillable / $guarded) just like $attributes. The increment path writes columns directly and does not go through mass assignment.

No database migration or configuration change is needed — update the framework and the next first call writes complete rows.

Takeaways

• incrementOrCreate() now passes $extra attributes to firstOrCreate(), so records created on the first call include them instead of leaving them null.
• The fix is applied in the Eloquent builder and in the BelongsToMany and HasOneOrMany relation classes, covering all relation types built on them.
• The existing-record path (increment() with extras) is unchanged.
• Merge order guarantees the counter column still starts at $default on creation.
• Upgrading from v13.34.0 is drop-in: no API, migration, or config changes — just consistent data on first writes.

Sources

• Pull request #61878
• Release v13.35.0