feat: add recursive container traversal via walkContainer

composer.json

@@ -18,9 +18,10 @@
         }
     ],
     "require": {
-        "php": ">=8.1",
+        "php": ">=8.2",
         "jumbojett/openid-connect-php": "^0.9.10",
-        "symfony/http-client": "^6.0",
+        "symfony/http-client": "^7.4",
+        "symfony/web-link": "^7.4",
         "easyrdf/easyrdf": "^1.1",
         "ml/json-ld": "^1.2",
         "web-token/jwt-core": "^3.0",
@@ -32,22 +33,22 @@
         "web-token/jwt-signature-algorithm-rsa": "^3.0"
     },
     "require-dev": {
-        "symfony/form": "^6.0",
-        "symfony/framework-bundle": "^6.0",
-        "symfony/http-foundation": "^6.0",
-        "symfony/validator": "^6.0",
-        "symfony/dependency-injection": "^6.0",
-        "symfony/routing": "^6.0",
-        "symfony/security-bundle": "^6.0",
-        "symfony/twig-bundle": "^6.0",
-        "symfony/debug-bundle": "^6.0",
-        "symfony/web-profiler-bundle": "^6.0",
-        "symfony/console": "^6.0",
-        "symfony/stopwatch": "^6.0",
-        "symfony/phpunit-bridge": "^6.0",
-        "symfony/browser-kit": "^6.0",
-        "symfony/css-selector": "^6.0",
-        "symfony/security-core": "^6.0",
-        "vimeo/psalm": "^5.12"
+        "symfony/form": "^7.4",
+        "symfony/framework-bundle": "^7.4",
+        "symfony/http-foundation": "^7.4",
+        "symfony/validator": "^7.4",
+        "symfony/dependency-injection": "^7.4",
+        "symfony/routing": "^7.4",
+        "symfony/security-bundle": "^7.4",
+        "symfony/twig-bundle": "^7.4",
+        "symfony/debug-bundle": "^7.4",
+        "symfony/web-profiler-bundle": "^7.4",
+        "symfony/console": "^7.4",
+        "symfony/stopwatch": "^7.4",
+        "symfony/phpunit-bridge": "^7.4",
+        "symfony/browser-kit": "^7.4",
+        "symfony/css-selector": "^7.4",
+        "symfony/security-core": "^7.4",
+        "vimeo/psalm": "^5.12 || ^6.0"
     }
 }

src/Bundle/Form/SolidLoginType.php

@@ -55,7 +55,7 @@ public function buildForm(FormBuilderInterface $builder, array $options): void
     public function configureOptions(OptionsResolver $resolver): void
     {
         $resolver->setDefaults([
-            'constraints' => [new Callback(function (array $data, ExecutionContextInterface $context): void {
+            'constraints' => [new Callback(static function (array $data, ExecutionContextInterface $context): void {
                 $webId = $data['webid'] ?? '';
                 $op = $data['op'] ?? '';
 

src/ContainerEntry.php

@@ -0,0 +1,25 @@
+<?php
+
+/*
+ * This file is part of the Solid Client PHP project.
+ * (c) Kévin Dunglas <kevin@dunglas.fr>
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Dunglas\PhpSolidClient;
+
+final class ContainerEntry
+{
+    /**
+     * @param list<string> $types RDF types of this entry
+     */
+    public function __construct(
+        public readonly string $url,
+        public readonly bool $isContainer,
+        public readonly array $types = [],
+    ) {
+    }
+}

src/ResourceMetadata.php

@@ -0,0 +1,84 @@
+<?php
+
+/*
+ * This file is part of the Solid Client PHP project.
+ * (c) Kévin Dunglas <kevin@dunglas.fr>
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Dunglas\PhpSolidClient;
+
+use Symfony\Component\WebLink\HttpHeaderParser;
+
+final class ResourceMetadata
+{
+    /**
+     * @param array<string, list<string>> $wacAllow parsed WAC-Allow header (e.g. ['user' => ['read', 'write'], 'public' => ['read']])
+     */
+    public function __construct(
+        public readonly ?string $contentType = null,
+        public readonly ?int $contentLength = null,
+        public readonly ?\DateTimeImmutable $lastModified = null,
+        public readonly ?string $ldpType = null,
+        public readonly array $wacAllow = [],
+        public readonly ?string $aclUrl = null,
+    ) {
+    }
+
+    public static function isContainerType(string $type): bool
+    {
+        return 'http://www.w3.org/ns/ldp#BasicContainer' === $type
+            || 'http://www.w3.org/ns/ldp#Container' === $type;
+    }
+
+    public function isContainer(): bool
+    {
+        return null !== $this->ldpType && self::isContainerType($this->ldpType);
+    }
+
+    /**
+     * @param array<string, list<string>> $responseHeaders normalized response headers
+     */
+    public static function fromResponseHeaders(array $responseHeaders): self
+    {
+        $contentType = isset($responseHeaders['content-type'][0])
+            ? explode(';', $responseHeaders['content-type'][0], 2)[0]
+            : null;
+
+        $contentLength = isset($responseHeaders['content-length'][0])
+            ? (int) $responseHeaders['content-length'][0]
+            : null;
+
+        $lastModified = isset($responseHeaders['last-modified'][0])
+            ? \DateTimeImmutable::createFromFormat(\DateTimeInterface::RFC7231, $responseHeaders['last-modified'][0]) ?: null
+            : null;
+
+        $ldpType = null;
+        $aclUrl = null;
+        $linkProvider = (new HttpHeaderParser())->parse($responseHeaders['link'] ?? []);
+        foreach ($linkProvider->getLinks() as $link) {
+            $rels = $link->getRels();
+            if (\in_array('type', $rels, true) && str_contains($link->getHref(), 'ldp#')) {
+                $ldpType = $link->getHref();
+            }
+            if (\in_array('acl', $rels, true)) {
+                $aclUrl = $link->getHref();
+            }
+        }
+
+        $wacAllow = [];
+        if (isset($responseHeaders['wac-allow'][0])) {
+            // Format: user="read write append control",public="read"
+            if (preg_match_all('/(\w+)="([^"]*)"/', $responseHeaders['wac-allow'][0], $matches, \PREG_SET_ORDER)) {
+                foreach ($matches as $match) {
+                    $wacAllow[$match[1]] = array_filter(explode(' ', $match[2]));
+                }
+            }
+        }
+
+        return new self($contentType, $contentLength, $lastModified, $ldpType, $wacAllow, $aclUrl);
+    }
+}

src/SolidClient.php

@@ -12,6 +12,8 @@
 namespace Dunglas\PhpSolidClient;
 
 use EasyRdf\Graph;
+use ML\JsonLD\JsonLD;
+use Symfony\Contracts\HttpClient\Exception\ClientExceptionInterface;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
 use Symfony\Contracts\HttpClient\ResponseInterface;
 
@@ -31,7 +33,7 @@ public function __construct(
     ) {
     }
 
-    public function createContainer(string $parentUrl, string $name, string $data = null): ResponseInterface
+    public function createContainer(string $parentUrl, string $name, ?string $data = null): ResponseInterface
     {
         return $this->post($parentUrl, $data, $name, true);
     }
@@ -41,7 +43,7 @@ public function createContainer(string $parentUrl, string $name, string $data =
      *
      * @see https://github.com/solid/solid-web-client/blob/main/src/client.js#L231=
      */
-    public function post(string $url, string $data = null, string $slug = null, bool $isContainer = false, array $options = []): ResponseInterface
+    public function post(string $url, ?string $data = null, ?string $slug = null, bool $isContainer = false, array $options = []): ResponseInterface
     {
         if ($isContainer || !isset($options['headers']['Content-Type'])) {
             $options['headers']['Content-Type'] = self::DEFAULT_MIME_TYPE;
@@ -53,16 +55,159 @@ public function post(string $url, string $data = null, string $slug = null, bool
             $options['headers']['Slug'] = $slug;
         }
 
-        $options['headers']['Link'] = sprintf('<%s>; rel="type"', $isContainer ? self::LDP_BASIC_CONTAINER : self::LDP_RESOURCE);
+        $options['headers']['Link'] = \sprintf('<%s>; rel="type"', $isContainer ? self::LDP_BASIC_CONTAINER : self::LDP_RESOURCE);
 
         return $this->request('POST', $url, $options);
     }
 
+    public function put(string $url, ?string $data = null, bool $isContainer = false, array $options = []): ResponseInterface
+    {
+        if (!isset($options['headers']['Content-Type'])) {
+            $options['headers']['Content-Type'] = self::DEFAULT_MIME_TYPE;
+        }
+        if (null !== $data) {
+            $options['body'] = $data;
+        }
+        if ($isContainer) {
+            $options['headers']['Link'] = \sprintf('<%s>; rel="type"', self::LDP_BASIC_CONTAINER);
+        }
+
+        return $this->request('PUT', $url, $options);
+    }
+
     public function get(string $url, array $options = []): ResponseInterface
     {
         return $this->request('GET', $url, $options);
     }
 
+    public function head(string $url, array $options = []): ResponseInterface
+    {
+        return $this->request('HEAD', $url, $options);
+    }
+
+    public function delete(string $url, array $options = []): ResponseInterface
+    {
+        return $this->request('DELETE', $url, $options);
+    }
+
+    public function patch(string $url, string $data, string $contentType = 'application/sparql-update', array $options = []): ResponseInterface
+    {
+        $options['headers']['Content-Type'] = $contentType;
+        $options['body'] = $data;
+
+        return $this->request('PATCH', $url, $options);
+    }
+
+    public function getResourceMetadata(string $url, array $options = []): ResourceMetadata
+    {
+        $response = $this->head($url, $options);
+
+        return ResourceMetadata::fromResponseHeaders($response->getHeaders(false));
+    }
+
+    /**
+     * Lists the contents of an LDP container by parsing ldp:contains from JSON-LD.
+     *
+     * @return list<ContainerEntry>
+     */
+    public function getContainerContents(string $url, array $options = []): array
+    {
+        $options['headers']['Accept'] = 'application/ld+json';
+        $response = $this->get($url, $options);
+        $decoded = json_decode($response->getContent());
+        $expanded = JsonLD::expand($decoded, ['base' => $url]);
+
+        $entries = [];
+        foreach ($expanded as $node) {
+            $contains = $node->{'http://www.w3.org/ns/ldp#contains'} ?? [];
+            if ([] === $contains || !$contains) {
+                continue;
+            }
+
+            foreach ($contains as $entry) {
+                $entryUrl = $entry->{'@id'} ?? null;
+                if (null === $entryUrl) {
+                    continue;
+                }
+                $types = $entry->{'@type'} ?? [];
+                $isContainer = [] !== array_filter($types, ResourceMetadata::isContainerType(...))
+                    || str_ends_with($entryUrl, '/');
+
+                $entries[] = new ContainerEntry($entryUrl, $isContainer, $types);
+            }
+        }
+
+        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);
+    }
+
+    /**
+     * 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,
+                );
+            }
+        }
+    }
+
+    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()) {
@@ -88,7 +233,7 @@ public function getOidcIssuer(string $webId, array $options = []): string
     {
         $graph = $this->getProfile($webId, $options);
 
-        $issuer = $graph->get($webId, sprintf('<%s>', self::OIDC_ISSUER))?->getUri();
+        $issuer = $graph->get($webId, \sprintf('<%s>', self::OIDC_ISSUER))?->getUri();
         if (!\is_string($issuer)) {
             throw new Exception('Unable to find the OIDC issuer associated with this WebID', 1);
         }

src/SolidClientFactory.php

@@ -22,7 +22,7 @@ public function __construct(private readonly HttpClientInterface $httpClient)
     {
     }
 
-    public function create(OidcClient $oidcClient = null): SolidClient
+    public function create(?OidcClient $oidcClient = null): SolidClient
     {
         return new SolidClient($this->httpClient, $oidcClient);
     }