feat: add ensureContainerExists()

Checks via HEAD whether a container exists, catches
ClientExceptionInterface for 404 specifically and lets other errors
propagate. Recursively creates missing parent containers via PUT.

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

Author: soyuka

src/SolidClient.php

@@ -13,6 +13,7 @@
 
 use EasyRdf\Graph;
 use ML\JsonLD\JsonLD;
+use Symfony\Contracts\HttpClient\Exception\ClientExceptionInterface;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
 use Symfony\Contracts\HttpClient\ResponseInterface;
 
@@ -139,6 +140,50 @@ 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
+    {
+        if (!str_ends_with($url, '/')) {
+            $url .= '/';
+        }
+
+        try {
+            $this->head($url, $options)->getHeaders();
+
+            return;
+        } catch (ClientExceptionInterface $e) {
+            if (404 !== $e->getResponse()->getStatusCode()) {
+                throw $e;
+            }
+        }
+
+        // Ensure parent exists first
+        $parentUrl = self::getParentContainerUrl($url);
+        if (null !== $parentUrl && $parentUrl !== $url) {
+            $this->ensureContainerExists($parentUrl, $options);
+        }
+
+        $this->put($url, null, true, $options);
+    }
+
+    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,45 @@ 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);
+    }
+
 }