[13.x] Clarify orWhere with array propagates boolean to inner conditions#11178
Open
scabarcas17 wants to merge 1 commit intolaravel:13.xfrom
Open
[13.x] Clarify orWhere with array propagates boolean to inner conditions#11178scabarcas17 wants to merge 1 commit intolaravel:13.xfrom
scabarcas17 wants to merge 1 commit intolaravel:13.xfrom
Conversation
There was a problem hiding this comment.
Pull request overview
Documentation-only update to the Query Builder docs clarifying the behavioral “footgun” where orWhere with array syntax applies the outer or boolean to every inner condition, and pointing readers toward closure-based grouping to get AND-joined inner clauses.
Changes:
- Added a
[!NOTE]explaining the SQL behavior oforWhere([...])with an example and a link to closure-based grouping. - Expanded the existing
[!WARNING]blocks (in both “Or Where Clauses” and “Logical Grouping”) to mention the array-syntax behavior in addition to the existing global-scope warning.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ``` | ||
|
|
||
| > [!NOTE] | ||
| > When this array syntax is used with `orWhere`, the inner conditions inherit the outer `or` boolean. For example, `->orWhere([['a', 1], ['b', 2]])` produces `or ("a" = 1 or "b" = 2)`, not `or ("a" = 1 and "b" = 2)`. To group `or` conditions with `and` between the inner clauses, pass a closure to `orWhere` instead — see [Or Where Clauses](#or-where-clauses) below. |
|
|
||
| > [!WARNING] | ||
| > You should always group `orWhere` calls in order to avoid unexpected behavior when global scopes are applied. | ||
| > You should always group `orWhere` calls using a closure — both to avoid unexpected behavior when global scopes are applied, and because passing an array directly to `orWhere` propagates the `or` boolean to every condition inside the group rather than joining them with `and`. |
|
|
||
| > [!WARNING] | ||
| > You should always group `orWhere` calls in order to avoid unexpected behavior when global scopes are applied. | ||
| > You should always group `orWhere` calls using a closure — both to avoid unexpected behavior when global scopes are applied, and because passing an array directly to `orWhere` propagates the `or` boolean to every condition inside the group rather than joining them with `and`. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Body del PR sugerido:
Closes laravel/framework#59516 (in spirit — that issue requests documentation, per @crynobone's comment).
This clarifies a footgun introduced in laravel/framework#53147 (Laravel 11.28) where
orWherewith array syntax propagates theorboolean toevery condition inside the group, rather than joining the inner conditions with
andas users naturally expect.Three small additions:
[!NOTE]right after the array-of-conditions example showing the actual SQL produced and pointing readers to the closure-based grouping.[!WARNING]in the Or Where Clauses section to explicitly mention the array-syntax behavior (not just global scopes).No code changes; documentation only.