Address final review: missing replace* methods, stale docs, lazy expand filter

- Add replaceFilter/replaceOrderBy/replaceExpand for symmetry with replaceSelect
- Fix HasODataQuery PHPDoc references to old #[ODataVersion] name
- CLAUDE.md: Saloon v3 -> v4, drop phantom LogicalOperator from layout
- Defer ExpandBuilder::filter() rendering for consistency with parent builder
- Document the count: false skip-sentinel behaviour on DefaultODataQuery
- Add note about OData 4.01 short nextLink form on the paginator
- Fix trailing comma in composer.json config block
- Tests for replace* methods and attribute-default override scenarios

Author: mdpoulter

CLAUDE.md

@@ -7,7 +7,7 @@ A Saloon PHP plugin providing a fluent, version-aware OData query-string builder
 ## Stack
 
 - PHP `^8.4` (uses asymmetric visibility, `#[\Override]`, readonly value objects)
-- Saloon v3
+- Saloon v4
 - Pest 3 (with arch plugin)
 - Laravel Pint
 - PHPStan level 10
@@ -21,7 +21,7 @@ src/
   Filter/FilterBuilder.php       closure target for ->filter()
   Expand/ExpandBuilder.php       closure target for ->expand() (v4 only)
   Order/OrderByClause.php        readonly value object
-  Enums/                         ODataVersion, ComparisonOperator, LogicalOperator, SortDirection
+  Enums/                         ODataVersion, ComparisonOperator, SortDirection
   Attributes/                    UsesODataVersion, ODataEntity, DefaultODataQuery
   Support/                       Literal (version-aware encoder), DateOnly, Guid, PropertyName, SkipToken, AttributeReader
   Pagination/ODataPaginator.php  Saloon Paginator: walks @odata.nextLink / __next / d.__next

README.md

@@ -94,7 +94,7 @@ class GetSalesInvoices extends Request
 }
 ```
 
-Defaults are applied on first access to `odataQuery()`. Runtime calls layer over them; use `clearSelect()` / `replaceSelect(...)` (and the equivalents for `Filter`, `OrderBy`, `Expand`) when you need to override rather than append.
+Defaults are applied on first access to `odataQuery()`. Runtime calls layer over them; use `clearSelect()` / `replaceSelect()` / `clearFilter()` / `replaceFilter()` / `clearOrderBy()` / `replaceOrderBy()` / `clearExpand()` / `replaceExpand()` when you need to override rather than append.
 
 The version is resolved in this order:
 1. Explicit `ODataQueryBuilder::make($version)` call.

composer.json

@@ -54,7 +54,7 @@
         "allow-plugins": {
             "pestphp/pest-plugin": true,
             "phpstan/extension-installer": true
-        },
+        }
     },
     "minimum-stability": "stable",
     "prefer-stable": true

src/Attributes/DefaultODataQuery.php

@@ -13,6 +13,9 @@
      * @param  list<string>  $select
      * @param  list<string>  $expand
      * @param  array<string, 'asc'|'desc'>  $orderBy
+     * @param  bool  $count  Set to true to emit `$count=true` (v4) / `$inlinecount=allpages` (v3).
+     *                       false (the default) skips the parameter entirely; if you need to
+     *                       explicitly emit `$count=false`, call `->count(false)` on the builder.
      * @param  array<string, scalar>  $params
      */
     public function __construct(

src/Concerns/HasODataQuery.php

@@ -14,11 +14,11 @@
  * Add OData query-building to a Saloon Request.
  *
  * On first access, lazily creates an {@see ODataQueryBuilder} using the
- * version from `#[ODataVersion]` on the Request (or any parent), falling
+ * version from `#[UsesODataVersion]` on the Request (or any parent), falling
  * back to v4. Any `#[DefaultODataQuery]` on the Request is applied.
  *
  * At boot, if the Request didn't declare a version, the Connector's
- * `#[ODataVersion]` attribute is consulted and applied via `withVersion()`.
+ * `#[UsesODataVersion]` attribute is consulted and applied via `withVersion()`.
  * Filters and nested $expand are rendered lazily, so the late switch is
  * applied consistently to all chained calls. (Pre-encoded `filterRaw()`
  * fragments are version-baked by the caller.)

src/Expand/ExpandBuilder.php

@@ -36,7 +36,8 @@ final class ExpandBuilder
 
     private ?bool $count = null;
 
-    private ?string $filter = null;
+    /** @var Closure(FilterBuilder): mixed|null */
+    private ?Closure $filter = null;
 
     public function __construct(public readonly ODataVersion $version)
     {
@@ -71,10 +72,7 @@ public function expand(string $navigation): self
      */
     public function filter(Closure $build): self
     {
-        $filter = new FilterBuilder($this->version);
-        $build($filter);
-
-        $this->filter = $filter->render();
+        $this->filter = $build;
 
         return $this;
     }
@@ -132,8 +130,13 @@ public function render(): ?string
         if ($this->select !== []) {
             $parts[] = '$select='.implode(',', $this->select);
         }
-        if ($this->filter !== null && $this->filter !== '') {
-            $parts[] = '$filter='.$this->filter;
+        if ($this->filter !== null) {
+            $filterBuilder = new FilterBuilder($this->version);
+            ($this->filter)($filterBuilder);
+            $rendered = $filterBuilder->render();
+            if ($rendered !== '') {
+                $parts[] = '$filter='.$rendered;
+            }
         }
         if ($this->orderBy !== []) {
             $parts[] = '$orderby='.implode(',', $this->orderBy);

src/ODataQueryBuilder.php

@@ -146,6 +146,16 @@ public function clearFilter(): self
         return $this;
     }
 
+    /**
+     * Discard any existing filter fragments, then apply the given closure.
+     *
+     * @param  Closure(FilterBuilder): mixed  $build
+     */
+    public function replaceFilter(Closure $build): self
+    {
+        return $this->clearFilter()->filter($build);
+    }
+
     /**
      * Add a navigation property to $expand.
      *
@@ -170,6 +180,14 @@ public function clearExpand(): self
         return $this;
     }
 
+    /**
+     * Discard any existing $expand entries, then add the given navigation.
+     */
+    public function replaceExpand(string $navigation, ?Closure $build = null): self
+    {
+        return $this->clearExpand()->expand($navigation, $build);
+    }
+
     public function orderBy(string $property, SortDirection|string $direction = SortDirection::Asc): self
     {
         PropertyName::assert($property);
@@ -190,6 +208,14 @@ public function clearOrderBy(): self
         return $this;
     }
 
+    /**
+     * Discard any existing $orderby clauses, then add the given one.
+     */
+    public function replaceOrderBy(string $property, SortDirection|string $direction = SortDirection::Asc): self
+    {
+        return $this->clearOrderBy()->orderBy($property, $direction);
+    }
+
     public function top(int $top): self
     {
         if ($top < 0) {

src/Pagination/ODataPaginator.php

@@ -29,6 +29,12 @@
  * The paginator only parses spec-defined fields. Vendor extensions are out of
  * scope; a Request that needs to extract items differently can implement
  * Saloon's MapPaginatedResponseItems contract.
+ *
+ * Note: OData 4.01 also permits a short `nextLink` form (without the
+ * `@odata.` prefix) under minimal-metadata negotiation. This paginator looks
+ * only for the canonical `@odata.nextLink` form, which is what every
+ * mainstream OData v4 server (Microsoft Graph, Dynamics, SAP, Exact Online)
+ * emits in practice.
  */
 final class ODataPaginator extends Paginator
 {

tests/Feature/AttributeDefaultsOverrideTest.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+use Saloon\Http\Faking\MockClient;
+use Saloon\Http\Faking\MockResponse;
+use SimpleSquid\SaloonOData\Support\AttributeReader;
+use SimpleSquid\SaloonOData\Tests\Fixtures\AttributedRequest;
+use SimpleSquid\SaloonOData\Tests\Fixtures\TestConnector;
+
+beforeEach(fn () => AttributeReader::flush());
+
+it('replaceSelect overrides the attribute-supplied $select', function (): void {
+    $mock = new MockClient([MockResponse::make([])]);
+    $connector = new TestConnector;
+    $connector->withMockClient($mock);
+
+    $request = new AttributedRequest;
+    // Attribute selects ID, InvoiceDate, AmountDC. Replace with a single field.
+    $request->odataQuery()->replaceSelect('ID');
+
+    $connector->send($request);
+
+    expect($mock->getLastPendingRequest()?->query()->all())
+        ->toMatchArray(['$select' => 'ID']);
+});
+
+it('clearSelect drops the attribute-supplied $select entirely', function (): void {
+    $mock = new MockClient([MockResponse::make([])]);
+    $connector = new TestConnector;
+    $connector->withMockClient($mock);
+
+    $request = new AttributedRequest;
+    $request->odataQuery()->clearSelect();
+
+    $connector->send($request);
+
+    expect($mock->getLastPendingRequest()?->query()->all())
+        ->not->toHaveKey('$select');
+});

tests/Unit/BuilderClearReplaceTest.php

@@ -45,6 +45,35 @@
     expect($params['$expand'])->toBe('C');
 });
 
+it('replaceFilter discards prior fragments and replaces them', function (): void {
+    $params = ODataQueryBuilder::make()
+        ->filter(fn (FilterBuilder $f) => $f->whereEquals('A', 1))
+        ->replaceFilter(fn (FilterBuilder $f) => $f->whereEquals('B', 2))
+        ->toArray();
+
+    expect($params['$filter'])->toBe('B eq 2');
+});
+
+it('replaceOrderBy discards prior clauses and replaces with a single one', function (): void {
+    $params = ODataQueryBuilder::make()
+        ->orderBy('A')
+        ->orderByDesc('B')
+        ->replaceOrderBy('C')
+        ->toArray();
+
+    expect($params['$orderby'])->toBe('C asc');
+});
+
+it('replaceExpand discards prior expansions', function (): void {
+    $params = ODataQueryBuilder::make()
+        ->expand('A')
+        ->expand('B')
+        ->replaceExpand('C')
+        ->toArray();
+
+    expect($params['$expand'])->toBe('C');
+});
+
 it('clearFilter wipes filter fragments', function (): void {
     $params = ODataQueryBuilder::make()
         ->filter(fn (FilterBuilder $f) => $f->whereEquals('A', 1))