feat(endpoint): add withCache modifier

Author: andrepimpao

UPGRADE-3.0.md

@@ -121,7 +121,7 @@ use ProgrammatorDev\Api\Builder\CacheBuilder;
 
 return $this
     ->endpoint()
-    ->cache(fn (CacheBuilder $cache) => $cache->defaultTtl(60))
+    ->withCache(fn (CacheBuilder $cache) => $cache->defaultTtl(60))
     ->get('/live')
     ->collection(Event::class, key: 'data');
 ```

docs/05-resources.md

@@ -238,13 +238,15 @@ SDK authors can configure endpoint-specific cache defaults on the endpoint build
 ```php
 return $this
     ->endpoint()
-    ->cache(fn (CacheBuilder $cache) => $cache->defaultTtl(60))
+    ->withCache(fn (CacheBuilder $cache) => $cache->defaultTtl(60))
     ->get('/users')
     ->collection(User::class, key: 'data');
 ```
 
 Endpoint cache defaults are immutable and apply only to that request. They require API-level cache configuration because the global cache setup provides the PSR-6 pool.
 
+`Endpoint::cache()` is deprecated since version 3.2.0. Use `Endpoint::withCache()` instead.
+
 ## Resource Cache Overrides
 
 `withCache()` lets SDK users override cache behavior for one resource chain while keeping query, headers, body, and verbs inside `Endpoint`.

docs/09-cache.md

@@ -70,7 +70,7 @@ public function live(): FixtureCollection
 {
     return $this
         ->endpoint()
-        ->cache(fn (CacheBuilder $cache) => $cache->defaultTtl(60))
+        ->withCache(fn (CacheBuilder $cache) => $cache->defaultTtl(60))
         ->get('/fixtures/live')
         ->envelope(FixtureCollection::class);
 }
@@ -80,6 +80,8 @@ This is useful when the SDK author knows that one endpoint should behave differe
 
 Endpoint defaults do not mutate the API cache builder and do not affect later requests.
 
+`Endpoint::cache()` is deprecated since version 3.2.0. Use `Endpoint::withCache()` instead.
+
 ## Resource Overrides
 
 SDK users can override cache behavior for one resource chain with `withCache()`. The override wins over endpoint defaults, does not mutate the API cache builder, and does not affect later resource instances.

src/Endpoint.php

@@ -23,13 +23,23 @@ public function __construct(
     /**
      * @param callable(\ProgrammatorDev\Api\Builder\CacheBuilder): mixed $configure
      */
-    public function cache(callable $configure): static
+    public function withCache(callable $configure): static
     {
         return $this->withPipelineOptions(
             $this->pipelineOptions->withDefault(PipelineOption::CACHE, $configure)
         );
     }
 
+    /**
+     * @deprecated since 3.2.0. Use withCache().
+     *
+     * @param callable(\ProgrammatorDev\Api\Builder\CacheBuilder): mixed $configure
+     */
+    public function cache(callable $configure): static
+    {
+        return $this->withCache($configure);
+    }
+
     /**
      * @throws \JsonException
      */

tests/Fixture/UserResource.php

@@ -57,17 +57,26 @@ public function createWithEndpointCache(array $data): Response
     {
         return $this
             ->endpoint()
-            ->cache(fn($cache) => $cache->methods(['POST']))
+            ->withCache(fn($cache) => $cache->methods(['POST']))
             ->json($data)
             ->post('/users');
     }
 
     public function createWithChainedEndpointCache(array $data): Response
+    {
+        return $this
+            ->endpoint()
+            ->withCache(fn($cache) => $cache->methods(['POST']))
+            ->withCache(fn($cache) => $cache->methods(['GET']))
+            ->json($data)
+            ->post('/users');
+    }
+
+    public function createWithDeprecatedEndpointCache(array $data): Response
     {
         return $this
             ->endpoint()
             ->cache(fn($cache) => $cache->methods(['POST']))
-            ->cache(fn($cache) => $cache->methods(['GET']))
             ->json($data)
             ->post('/users');
     }

tests/Integration/CacheTest.php

@@ -44,6 +44,20 @@ public function testEndpointCanOverrideCacheConfiguration(): void
         $this->assertCount(1, $client->getRequests());
     }
 
+    public function testDeprecatedEndpointCacheAliasStillConfiguresCache(): void
+    {
+        $client = $this->mockClient(new Response(body: '{"id":1,"name":"John"}'));
+        $api = new FakeApi($client);
+        $api->setup()->cache(new ArrayAdapter())->methods(['GET']);
+
+        $first = $api->users()->createWithDeprecatedEndpointCache(['name' => 'John']);
+        $second = $api->users()->createWithDeprecatedEndpointCache(['name' => 'John']);
+
+        $this->assertSame(['id' => 1, 'name' => 'John'], $first->data());
+        $this->assertSame(['id' => 1, 'name' => 'John'], $second->data());
+        $this->assertCount(1, $client->getRequests());
+    }
+
     public function testResourceCacheOverrideWinsOverEndpointCacheDefault(): void
     {
         $client = $this->mockClient(