Add wrapWhere option to QueryScope

`QueryScope` adds its conditions at the top level of the query, where a
user-supplied `orWhere` can bypass the scope due to AND-over-OR precedence
(e.g. a `status = active` scope leaks on `where(id,1)->orWhere(id,2)`).

Add a `wrapWhere` constructor flag that calls `QueryBuilder::wrapWhere()`
before applying the scope conditions, enclosing already-registered user
conditions in a parenthesized AND-group. For scopes on joined loaders the
call is forwarded to the JOIN ON tokens via `wrapOnWhere`. The flag defaults
to false to preserve backwards-compatible behavior.

- QueryScope: new `wrapWhere` parameter with a thorough docblock
- Unit tests for QueryScope apply/wrap behavior, including the empty-where
  edge case
- HasMany integration tests switched from the throwaway WrappedQueryScope
  fixture to `QueryScope(wrapWhere: true)`, exercising the real class; the
  fixture is removed

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: roxblnfk

src/Select/QueryScope.php

@@ -5,17 +5,62 @@
 namespace Cycle\ORM\Select;
 
 /**
- * Provides the ability to scope query and load necessary relations into the loader.
+ * A ready-made {@see ScopeInterface} implementation that applies a set of WHERE
+ * conditions and an ORDER BY rule to the query.
+ *
+ *     // Only active records, newest first
+ *     new QueryScope(['status' => 'active'], ['created_at' => 'DESC']);
+ *
+ * ## Protecting the scope from `orWhere` bypass
+ *
+ * By default the conditions are added at the top level of the query. Because SQL
+ * binds AND tighter than OR, a user-supplied `orWhere` can bypass the scope:
+ *
+ *     // scope: WHERE status = 'active'
+ *     $select->scope(new QueryScope(['status' => 'active']))
+ *         ->where('id', 1)
+ *         ->orWhere('id', 2);
+ *     // WHERE id = 1 OR id = 2 AND status = 'active'
+ *     //   ≡ WHERE id = 1 OR (id = 2 AND status = 'active')  ← scope leaks on first arm
+ *
+ * Pass `wrapWhere: true` to enclose the already-registered conditions in a
+ * parenthesized group before adding the scope's own, keeping it effective
+ * regardless of how user code mixes AND/OR:
+ *
+ *     $select->scope(new QueryScope(['status' => 'active'], wrapWhere: true))
+ *         ->where('id', 1)
+ *         ->orWhere('id', 2);
+ *     // WHERE (id = 1 OR id = 2) AND status = 'active'
+ *
+ * The wrap is applied via {@see QueryBuilder::wrapWhere()}, which is a no-op when
+ * no conditions have been registered yet. For scopes attached to joined relation
+ * loaders the call is automatically forwarded to the JOIN's ON tokens. Passing an
+ * empty `$where` together with `wrapWhere: true` is still meaningful — it protects
+ * user conditions without adding any of its own.
+ *
+ * See {@see ScopeInterface} for the full discussion of scope bypass.
  */
 final class QueryScope implements ScopeInterface
 {
+    /**
+     * @param array $where Conditions to apply, in {@see QueryBuilder::where()} array syntax.
+     * @param array $orderBy ORDER BY rules, in {@see QueryBuilder::orderBy()} array syntax.
+     * @param bool $wrapWhere When true, wrap already-registered conditions in a nested
+     *        AND-group before adding this scope's conditions (protects against `orWhere`
+     *        bypass). Defaults to false to preserve backwards-compatible behavior.
+     */
     public function __construct(
-        private array $where,
-        private array $orderBy = [],
+        private readonly array $where,
+        private readonly array $orderBy = [],
+        private readonly bool $wrapWhere = false,
     ) {}
 
     public function apply(QueryBuilder $query): void
     {
+        if ($this->wrapWhere) {
+            $query->wrapWhere();
+        }
+
         $query->where($this->where)->orderBy($this->orderBy);
     }
 }

tests/ORM/Fixtures/WrappedQueryScope.php

@@ -15,7 +15,6 @@
 use Cycle\ORM\Tests\Fixtures\Comment;
 use Cycle\ORM\Tests\Fixtures\SortByIDScope;
 use Cycle\ORM\Tests\Fixtures\User;
-use Cycle\ORM\Tests\Fixtures\WrappedQueryScope;
 use Cycle\ORM\Tests\Traits\TableTrait;
 use Cycle\Database\Exception\StatementException;
 
@@ -485,14 +484,14 @@ public function testInloadJoinedScopeWithoutWrapWhereIsBypassedByAdversarialOrLo
     }
 
     /**
-     * Companion to the test above: with {@see WrappedQueryScope} (calls wrapWhere() first),
+     * Companion to the test above: with `QueryScope(..., wrapWhere: true)`,
      * QueryBuilder::targetFunc() forwards the wrap to `wrapOnWhere` on the JOIN's ON tokens,
      * enclosing the user's OR group. The scope's `level >= 2` condition stays effective.
      */
     public function testInloadJoinedScopeWithWrapWhereProtectsAgainstAdversarialOrLoad(): void
     {
         $this->orm = $this->withCommentsSchema([
-            Schema::SCOPE => new WrappedQueryScope(['@.level' => ['>=' => 2]]),
+            Schema::SCOPE => new Select\QueryScope(['@.level' => ['>=' => 2]], wrapWhere: true),
         ]);
 
         $res = (new Select($this->orm, User::class))
@@ -525,7 +524,7 @@ public function testInloadJoinedScopeWithWrapWhereProtectsAgainstAdversarialOrLo
     public function testInloadJoinedScopeWithWrapWhereWithoutAdversarialLoad(): void
     {
         $this->orm = $this->withCommentsSchema([
-            Schema::SCOPE => new WrappedQueryScope(['@.level' => ['>=' => 3]]),
+            Schema::SCOPE => new Select\QueryScope(['@.level' => ['>=' => 3]], wrapWhere: true),
         ]);
 
         $res = (new Select($this->orm, User::class))

tests/ORM/Functional/Driver/Common/Relation/HasMany/HasManyScopeTest.php

@@ -0,0 +1,90 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cycle\ORM\Tests\Unit\Select;
+
+use Cycle\Database\Query\SelectQuery;
+use Cycle\ORM\Select\AbstractLoader;
+use Cycle\ORM\Select\QueryBuilder;
+use Cycle\ORM\Select\QueryScope;
+use PHPUnit\Framework\TestCase;
+
+final class QueryScopeTest extends TestCase
+{
+    public function testAppliesWhereAndOrderBy(): void
+    {
+        $query = new SelectQuery(['users']);
+        $scope = new QueryScope(['status' => 'active'], ['created_at' => 'DESC']);
+
+        $scope->apply($this->makeBuilder($query));
+
+        $tokens = $query->getTokens();
+        $this->assertCount(1, $tokens['where']);
+        $this->assertSame('users.status', $tokens['where'][0][1][0]);
+        $this->assertSame([['users.created_at', 'DESC']], $tokens['orderBy']);
+    }
+
+    public function testDoesNotWrapByDefault(): void
+    {
+        $query = (new SelectQuery(['users']))
+            ->where('id', 1)
+            ->orWhere('id', 2);
+
+        (new QueryScope(['status' => 'active']))->apply($this->makeBuilder($query));
+
+        // Flat token list: no opening-paren group inserted before the user tokens.
+        $where = $query->getTokens()['where'];
+        $this->assertNotSame(['AND', '('], $where[0]);
+        // Scope condition appended at the top level.
+        $this->assertSame('users.status', $where[\count($where) - 1][1][0]);
+    }
+
+    public function testWrapWhereEnclosesExistingConditions(): void
+    {
+        $query = (new SelectQuery(['users']))
+            ->where('id', 1)
+            ->orWhere('id', 2);
+
+        (new QueryScope(['status' => 'active'], wrapWhere: true))->apply($this->makeBuilder($query));
+
+        $where = $query->getTokens()['where'];
+
+        // User conditions are now enclosed in a leading AND-group...
+        $this->assertSame(['AND', '('], $where[0]);
+        $this->assertSame(['', ')'], $where[3]);
+        // ...with the scope condition appended after the group.
+        $this->assertSame('users.status', $where[4][1][0]);
+    }
+
+    public function testWrapWhereWithEmptyConditionsStillProtectsUserWhere(): void
+    {
+        $query = (new SelectQuery(['users']))
+            ->where('id', 1)
+            ->orWhere('id', 2);
+
+        // Empty $where but wrapWhere: true — should wrap user conditions, add nothing.
+        (new QueryScope([], wrapWhere: true))->apply($this->makeBuilder($query));
+
+        $this->assertEquals(
+            [
+                ['AND', '('],
+                ['AND', ['id', '=', $query->getTokens()['where'][1][1][2]]],
+                ['OR', ['id', '=', $query->getTokens()['where'][2][1][2]]],
+                ['', ')'],
+            ],
+            $query->getTokens()['where'],
+        );
+    }
+
+    private function makeBuilder(SelectQuery $query): QueryBuilder
+    {
+        $loader = $this->createMock(AbstractLoader::class);
+        $loader->method('fieldAlias')->willReturn(null);
+        $loader->method('getAlias')->willReturn('users');
+        $loader->method('getTarget')->willReturn('user');
+        $loader->method('getParentLoader')->willReturn(null);
+
+        return new QueryBuilder($query, $loader);
+    }
+}