feat: add ResourceMetadata value object and getResourceMetadata()

Parses HEAD response headers into a structured ResourceMetadata object
with content type, length, last modified, LDP type, WAC-Allow permissions,
and ACL URL from Link headers.

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

Author: soyuka

src/ResourceMetadata.php

@@ -0,0 +1,80 @@
+<?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 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 function isContainer(): bool
+    {
+        return 'http://www.w3.org/ns/ldp#BasicContainer' === $this->ldpType
+            || 'http://www.w3.org/ns/ldp#Container' === $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;
+        foreach ($responseHeaders['link'] ?? [] as $linkHeader) {
+            foreach (explode(',', $linkHeader) as $link) {
+                $link = trim($link);
+                if (preg_match('/<([^>]+)>;\s*rel="type"/', $link, $matches)) {
+                    if (str_contains($matches[1], 'ldp#')) {
+                        $ldpType = $matches[1];
+                    }
+                }
+                if (preg_match('/<([^>]+)>;\s*rel="acl"/', $link, $matches)) {
+                    $aclUrl = $matches[1];
+                }
+            }
+        }
+
+        $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

@@ -96,6 +96,13 @@ public function patch(string $url, string $data, string $contentType = 'applicat
         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));
+    }
+
     public function request(string $method, string $url, array $options = []): ResponseInterface
     {
         if ($accessToken = $this->oidcClient?->getAccessToken()) {

tests/ResourceMetadataTest.php

@@ -0,0 +1,68 @@
+<?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\Tests;
+
+use Dunglas\PhpSolidClient\ResourceMetadata;
+use PHPUnit\Framework\TestCase;
+
+class ResourceMetadataTest extends TestCase
+{
+    public function testFromResponseHeaders(): void
+    {
+        $headers = [
+            'content-type' => ['text/turtle; charset=utf-8'],
+            'content-length' => ['4567'],
+            'last-modified' => ['Mon, 23 Feb 2026 12:00:00 GMT'],
+            'link' => [
+                '<http://www.w3.org/ns/ldp#BasicContainer>; rel="type"',
+                '<http://pod.example/resource.acl>; rel="acl"',
+            ],
+            'wac-allow' => ['user="read write append control",public="read"'],
+        ];
+
+        $metadata = ResourceMetadata::fromResponseHeaders($headers);
+
+        $this->assertSame('text/turtle', $metadata->contentType);
+        $this->assertSame(4567, $metadata->contentLength);
+        $this->assertInstanceOf(\DateTimeImmutable::class, $metadata->lastModified);
+        $this->assertSame('http://www.w3.org/ns/ldp#BasicContainer', $metadata->ldpType);
+        $this->assertTrue($metadata->isContainer());
+        $this->assertSame('http://pod.example/resource.acl', $metadata->aclUrl);
+        $this->assertSame(['read', 'write', 'append', 'control'], $metadata->wacAllow['user']);
+        $this->assertSame(['read'], $metadata->wacAllow['public']);
+    }
+
+    public function testResourceNotContainer(): void
+    {
+        $headers = [
+            'content-type' => ['application/ld+json'],
+            'link' => ['<http://www.w3.org/ns/ldp#Resource>; rel="type"'],
+        ];
+
+        $metadata = ResourceMetadata::fromResponseHeaders($headers);
+
+        $this->assertFalse($metadata->isContainer());
+        $this->assertSame('http://www.w3.org/ns/ldp#Resource', $metadata->ldpType);
+    }
+
+    public function testEmptyHeaders(): void
+    {
+        $metadata = ResourceMetadata::fromResponseHeaders([]);
+
+        $this->assertNull($metadata->contentType);
+        $this->assertNull($metadata->contentLength);
+        $this->assertNull($metadata->lastModified);
+        $this->assertNull($metadata->ldpType);
+        $this->assertNull($metadata->aclUrl);
+        $this->assertSame([], $metadata->wacAllow);
+    }
+}