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.

CSS requires intermediate containers to exist before creating nested
resources, making this a necessary operation before any write to a
new path.

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

Author: soyuka

src/SolidClient.php

@@ -138,13 +138,60 @@ 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
+    {
+        // Remove trailing slash for parsing
+        $trimmed = rtrim($url, '/');
+        $lastSlash = strrpos($trimmed, '/');
+        if (false === $lastSlash) {
+            return null;
+        }
+
+        $parent = substr($trimmed, 0, $lastSlash + 1);
+        // Don't go above the authority (e.g., "http://example.com/")
+        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,44 @@ 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/');
+
+        // Only one HEAD request should have been made
+        $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/');
+
+        // Should have HEAD child/ (404), HEAD parent/ (200), then PUT child/
+        $methods = array_column($requests, 0);
+        $this->assertContains('PUT', $methods);
+    }
 }