feat: add ensureContainerExists with recursive parent creation

Adds ensureContainerExists() which HEADs the target URL and, if it
returns 404, recursively ensures parent containers exist before
creating the target via PUT with LDP BasicContainer type. Stops
recursion at the authority level.

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

Author: soyuka

src/SolidClient.php

@@ -135,13 +135,58 @@ public function getContainerContents(string $url, array $options = []): array
         return $entries;
     }
 
+    /**
+     * Ensures that an LDP container exists at the given URL, creating it (and any missing parents) if necessary.
+     */
+    public function ensureContainerExists(string $url, array $options = []): void
+    {
+        // Normalize: ensure trailing slash
+        if (!str_ends_with($url, '/')) {
+            $url .= '/';
+        }
+
+        try {
+            $response = $this->head($url, $options);
+            $statusCode = $response->getStatusCode();
+            if ($statusCode >= 200 && $statusCode < 300) {
+                return;
+            }
+        } catch (\Throwable) {
+            // Fall through to creation
+        }
+
+        // Ensure parent exists first
+        $parentUrl = self::getParentContainerUrl($url);
+        if (null !== $parentUrl && $parentUrl !== $url) {
+            $this->ensureContainerExists($parentUrl, $options);
+        }
+
+        $this->put($url, null, true, $options);
+    }
+
     public function getResourceMetadata(string $url, array $options = []): ResourceMetadata
     {
         $response = $this->head($url, $options);
 
         return ResourceMetadata::fromResponseHeaders($response->getHeaders(false));
     }
 
+    private static function getParentContainerUrl(string $url): ?string
+    {
+        $trimmed = rtrim($url, '/');
+        $lastSlash = strrpos($trimmed, '/');
+        if (false === $lastSlash) {
+            return null;
+        }
+
+        $parent = substr($trimmed, 0, $lastSlash + 1);
+        if (preg_match('#^https?://[^/]+/$#', $parent)) {
+            return null;
+        }
+
+        return $parent;
+    }
+
     public function request(string $method, string $url, array $options = []): ResponseInterface
     {
         if ($accessToken = $this->oidcClient?->getAccessToken()) {

tests/ContainerOperationsTest.php

@@ -98,4 +98,42 @@ public function testGetContainerContentsWithRelativeIds(): void
         $this->assertSame('http://pod.example/data/file.txt', $entries[0]->url);
         $this->assertSame('http://pod.example/data/sub/', $entries[1]->url);
     }
+
+    public function testEnsureContainerExistsAlreadyExists(): void
+    {
+        $responses = [
+            new MockResponse('', ['http_code' => 200]),
+        ];
+        $httpClient = new MockHttpClient($responses);
+        $client = new SolidClient($httpClient);
+
+        $client->ensureContainerExists('http://pod.example/existing/');
+
+        $this->assertSame(1, $httpClient->getRequestsCount());
+    }
+
+    public function testEnsureContainerExistsCreates(): void
+    {
+        $requests = [];
+        $httpClient = new MockHttpClient(static function (string $method, string $url) use (&$requests): MockResponse {
+            $requests[] = [$method, $url];
+            if ('HEAD' === $method && 'http://pod.example/parent/' === $url) {
+                return new MockResponse('', ['http_code' => 200]);
+            }
+            if ('HEAD' === $method) {
+                return new MockResponse('', ['http_code' => 404]);
+            }
+            if ('PUT' === $method) {
+                return new MockResponse('', ['http_code' => 201]);
+            }
+
+            return new MockResponse('', ['http_code' => 500]);
+        });
+        $client = new SolidClient($httpClient);
+
+        $client->ensureContainerExists('http://pod.example/parent/child/');
+
+        $methods = array_column($requests, 0);
+        $this->assertContains('PUT', $methods);
+    }
 }