Add whenNested() or nested flag to when() for grouped conditions

[musiermoore]

Add whenNested() or nested flag to when() for grouped conditions

Closures passed into when() are currently not grouped automatically.
Because of this, mixed where / orWhere conditions are applied directly to the main query unless an extra nested closure is added.

Problem Example

->when($condition, fn ($q) =>
    $q->where('author_id', 1)->orWhere('published', true)
);

This produces SQL like:

... AND author_id = 1 OR published = true

To ensure proper grouping today, you must write:

->when($condition, fn ($q) =>
    $q->where(fn ($q2) =>
        $q2->where('author_id', 1)->orWhere('published', true)
    )
);

This becomes verbose and reduces readability.

Proposal

Introduce one of the following (or both, if desired):

1. New whenNested() method

->whenNested($condition, fn ($q) => ...)

This would automatically apply the callback inside a grouped where, so it would produce clean, grouped SQL:

... AND (author_id = 1 OR published = true)

2. Add a nested parameter to when()

->when($condition, fn ($q) => ..., nested: false)

nested defaults to false, preserving all existing behavior.

When set to true, the callback is executed inside a grouped where, and would also produce:

... AND (author_id = 1 OR published = true)

Summary

Adding whenNested() or a nested parameter to when() would simplify grouped conditional queries, prevent subtle logic errors, and improve readability while remaining fully backward compatible.

If this sounds useful, I’m happy to create a PR to implement it.

[macropay-solutions]

This becomes verbose and reduces readability.

Verbose is better than hidden under the carpet.

[musiermoore]

@macropay-solutions using whenNested() makes it clear the closure will be grouped, so the behavior is explicit. Since it’s optional, it doesn’t affect existing code

[macropay-solutions]

You are right. The only downside to it is some overhead.