feat: add recursive container traversal via walkContainer generator

Adds walkContainer() which recursively descends an LDP container tree
using getContainerContents(), yielding ContainerEntry objects. Supports
configurable depth limits: -1 for unlimited, 0 for current level only.

Uses PHP generators for memory-efficient traversal of deep hierarchies.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: soyuka

src/SolidClient.php

@@ -167,6 +167,30 @@ public function ensureContainerExists(string $url, array $options = []): void
         $this->put($url, null, true, $options);
     }
 
+    /**
+     * Recursively walks an LDP container tree, yielding ContainerEntry objects.
+     *
+     * @param int $maxDepth -1 for unlimited, 0 for current level only
+     *
+     * @return \Generator<int, ContainerEntry>
+     */
+    public function walkContainer(string $url, int $maxDepth = -1, array $options = []): \Generator
+    {
+        $entries = $this->getContainerContents($url, $options);
+
+        foreach ($entries as $entry) {
+            yield $entry;
+
+            if ($entry->isContainer && 0 !== $maxDepth) {
+                yield from $this->walkContainer(
+                    $entry->url,
+                    -1 === $maxDepth ? -1 : $maxDepth - 1,
+                    $options,
+                );
+            }
+        }
+    }
+
     public function getResourceMetadata(string $url, array $options = []): ResourceMetadata
     {
         $response = $this->head($url, $options);

tests/ContainerOperationsTest.php

@@ -138,4 +138,74 @@ public function testEnsureContainerExistsCreates(): void
         $methods = array_column($requests, 0);
         $this->assertContains('PUT', $methods);
     }
+
+    public function testWalkContainer(): void
+    {
+        $rootJson = json_encode([
+            '@id' => 'http://pod.example/root/',
+            '@type' => ['http://www.w3.org/ns/ldp#BasicContainer'],
+            'http://www.w3.org/ns/ldp#contains' => [
+                ['@id' => 'http://pod.example/root/file.txt'],
+                ['@id' => 'http://pod.example/root/sub/', '@type' => ['http://www.w3.org/ns/ldp#BasicContainer']],
+            ],
+        ]);
+
+        $subJson = json_encode([
+            '@id' => 'http://pod.example/root/sub/',
+            '@type' => ['http://www.w3.org/ns/ldp#BasicContainer'],
+            'http://www.w3.org/ns/ldp#contains' => [
+                ['@id' => 'http://pod.example/root/sub/nested.ttl'],
+            ],
+        ]);
+
+        $httpClient = new MockHttpClient(static function (string $method, string $url) use ($rootJson, $subJson): MockResponse {
+            if ('http://pod.example/root/' === $url) {
+                return new MockResponse($rootJson, [
+                    'http_code' => 200,
+                    'response_headers' => ['Content-Type' => 'application/ld+json'],
+                ]);
+            }
+            if ('http://pod.example/root/sub/' === $url) {
+                return new MockResponse($subJson, [
+                    'http_code' => 200,
+                    'response_headers' => ['Content-Type' => 'application/ld+json'],
+                ]);
+            }
+
+            return new MockResponse('', ['http_code' => 404]);
+        });
+        $client = new SolidClient($httpClient);
+
+        $entries = iterator_to_array($client->walkContainer('http://pod.example/root/'), false);
+
+        $this->assertCount(3, $entries);
+        $this->assertSame('http://pod.example/root/file.txt', $entries[0]->url);
+        $this->assertSame('http://pod.example/root/sub/', $entries[1]->url);
+        $this->assertSame('http://pod.example/root/sub/nested.ttl', $entries[2]->url);
+    }
+
+    public function testWalkContainerWithMaxDepth(): void
+    {
+        $rootJson = json_encode([
+            '@id' => 'http://pod.example/root/',
+            '@type' => ['http://www.w3.org/ns/ldp#BasicContainer'],
+            'http://www.w3.org/ns/ldp#contains' => [
+                ['@id' => 'http://pod.example/root/sub/', '@type' => ['http://www.w3.org/ns/ldp#BasicContainer']],
+            ],
+        ]);
+
+        $httpClient = new MockHttpClient(static function (string $method, string $url) use ($rootJson): MockResponse {
+            return new MockResponse($rootJson, [
+                'http_code' => 200,
+                'response_headers' => ['Content-Type' => 'application/ld+json'],
+            ]);
+        });
+        $client = new SolidClient($httpClient);
+
+        $entries = iterator_to_array($client->walkContainer('http://pod.example/root/', 0), false);
+
+        // maxDepth=0 should only return root level entries, no recursion
+        $this->assertCount(1, $entries);
+        $this->assertSame('http://pod.example/root/sub/', $entries[0]->url);
+    }
 }