Potential bug due to incorrect use of orWhereState with relationships

[Rurek5000]

Laravel Version

12.10.2

PHP Version

8.4.3

Database Driver & Version

No response

Description

We discovered a logic issue when using orWhereState directly on a relationship query. For example:

$posts = $user->posts()
    ->whereState('status', Published::class)
    ->orWhereState('status', Archived::class)
    ->get();

Although this seems correct at first glance, it results in incorrect SQL logic.

This means that some posts not belonging to the given user may be included, because the OR applies globally.

✅ Correct version

To ensure the condition applies only to the user's posts, the status logic must be wrapped in a closure:

$posts = $user->posts()
    ->where(function ($query) {
        $query->whereState('status', Published::class)
              ->orWhereState('status', Archived::class);
    })
    ->get();

When using orWhere* (including orWhereState) in combination with relationship constraints (e.g. $user->posts()), always wrap those conditions in a where(function ($q) { ... }) block. This avoids incorrect global application of OR clauses and ensures consistent results.

Steps To Reproduce

Create a simple model relationship:

// User.php
public function posts()
{
    return $this->hasMany(Post::class);
}

Use Laravel Model States (e.g. Spatie model states) and define two states for status:

Published

Archived

Seed the database with sample data:

$userA = User::factory()->create();
$userB = User::factory()->create();

Post::factory()->create([
    'user_id' => $userA->id,
    'status' => Published::class,
]);

Post::factory()->create([
    'user_id' => $userB->id,
    'status' => Archived::class,
]);

Run the problematic query:

$posts = $userA->posts()
    ->whereState('status', Published::class)
    ->orWhereState('status', Archived::class)
    ->get();

Expected result: Only posts belonging to $userA and having status of either Published or Archived.

Actual result: You will get the Archived post that belongs to $userB, which should not be included.

[rodrigopedra]

First, out of curiosity, aren't whereState, and orWhereState custom additions to your project? Maybe from a 3rd-party package?

I couldn't find any reference to it on the whole laravel GitHub organization:

https://github.com/search?q=org%3Alaravel%20whereState&type=code

other than this very issue, and some references on 2 PRs regarding code samples

As you reference them like a built-in feature, you got me curious about this.

Second:

To ensure the condition applies only to the user's posts, the status logic must be wrapped in a closure

Yes, that is the way to go.

If you use OR constraints, you must group them into parenthesis. The way it is done on the query builder is to wrap them into a closure.

It always worked this way.

Maybe we could handle those as we do with Model scopes (automatically wrap them into a closure), but in contrast with scopes where you already pass the whole Builder to a well delimited method, I believe it would be very hard as constraints added after a relationship are too open-ended.

[macropay-solutions]

@rodrigopedra This is not a bug but a know feature / bad usage that was previously discussed. It could be a feature request at most.