feat: introducing resource views

.gitignore

@@ -8,3 +8,4 @@ composer.lock
 !var/log/.gitkeep
 /tools
 .phpactor.json
+notes.md

config/services.yaml

@@ -31,4 +31,21 @@ services:
     class: Atoolo\Resource\Loader\SiteKitResourceHierarchyLoader
     arguments:
       - '@atoolo_resource.cached_resource_loader'
-      - 'category'
+      - 'category'
+
+  # resource view system
+
+  atoolo_resource.resource_view_factory:
+    class: Atoolo\Resource\ResourceViewFactory
+    arguments:
+      - !tagged_iterator resource_view.contributor
+
+  atoolo_resource.resource_view_manager:
+    class: Atoolo\Resource\ResourceViewManager
+    arguments:
+      - '@atoolo_resource.resource_view_factory'
+
+  atoolo_resource.resource_view_contributor:
+    class: Atoolo\Resource\ResourceViewContributor
+    tags: ['resource_view.contributor']
+

src/Exception/MissingFeatureException.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Atoolo\Resource\Exception;
+
+use Atoolo\Resource\ResourceLocation;
+use Atoolo\Resource\ResourceView;
+
+/**
+ * This exception is used when a resource feature is requested that
+ * does not exist in a given resource view.
+ */
+class MissingFeatureException extends \LogicException
+{
+    public function __construct(
+        public readonly string $feature,
+        public readonly ResourceView $resourceView,
+        int $code = 0,
+        ?\Throwable $previous = null,
+    ) {
+        parent::__construct(
+            "Feature $feature not available.",
+            $code,
+            $previous,
+        );
+    }
+}

src/Loader/SiteKitLoader.php

@@ -14,6 +14,7 @@
 use Atoolo\Resource\ResourceLanguage;
 use Atoolo\Resource\ResourceLoader;
 use Atoolo\Resource\ResourceLocation;
+use Atoolo\Resource\SiteKit\SiteKitResource;
 use Error;
 use Locale;
 use ParseError;
@@ -46,15 +47,15 @@ public function __construct(
      * @throws InvalidResourceException
      * @throws ResourceNotFoundException
      */
-    public function load(ResourceLocation $location): Resource
+    public function load(ResourceLocation $location): SiteKitResource
     {
         $data = $this->loadRaw($location);
 
         $data = $this->validateData($location, $data);
 
         $resourceLang = ResourceLanguage::of($data['locale']);
 
-        return new Resource(
+        return new SiteKitResource(
             $location->location,
             (string) $data['id'],
             $data['name'],

src/Model/Copyright.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Atoolo\Resource\Model;
+
+final class Copyright
+{
+    public function __construct() {}
+}

src/Model/GeoJson.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Atoolo\Resource\Model;
+
+final class GeoJson
+{
+    public function __construct(
+        // TODO GeoJSON
+    ) {}
+}

src/Model/Image/Image.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Atoolo\Resource\Model\Image;
+
+use Atoolo\Resource\Model\Copyright;
+use Atoolo\Resource\Model\Image\Asset;
+
+/**
+ * Represents a complete image, including multiple sources for responsive
+ * design (<picture>, srcset) and essential metadata.
+ */
+final class Image
+{
+    /**
+     * @param string $url The primary, fallback URL for the <img> src attribute.
+     * @param ImageSource[] $sources An array of alternative sources for different formats and resolutions.
+     * @param ?string $alt The essential alternative text for accessibility.
+     * @param ?int $width The intrinsic width of the fallback image to prevent layout shift.
+     * @param ?int $height The intrinsic height of the fallback image to prevent layout shift.
+     * @param ?Copyright $copyright Copyright information for the image.
+     * @param ?string $characteristic
+     * @param array<string,mixed> $variants
+     */
+    public function __construct(
+        public readonly string $url,
+        public readonly array $sources = [],
+        public readonly ?string $alt = null,
+        public readonly ?int $width = null,
+        public readonly ?int $height = null,
+        public readonly ?Copyright $copyright = null,
+        public readonly ?string $characteristic = null,
+        public readonly array $variants = [], // TODO
+    ) {}
+}

src/Model/Image/ImageSource.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Atoolo\Resource\Model\Image;
+
+/**
+ * Represents a single source for a responsive image, corresponding to a
+ * <source> tag or an entry in a srcset attribute.
+ */
+final class ImageSource
+{
+    /**
+     * @param string $url The URL of this image version.
+     * @param ?string $mediaQuery The media query for art direction (e.g., '(min-width: 900px)').
+     * @param ?string $mimeType The MIME type for different formats (e.g., 'image/webp').
+     * @param ?int $width The width of this version in pixels.
+     * @param ?int $height The height of this version in pixels.
+     */
+    public function __construct(
+        public readonly string $url,
+        public readonly ?string $mediaQuery = null,
+        public readonly ?string $mimeType = null,
+        public readonly ?int $width = null,
+        public readonly ?int $height = null,
+    ) {}
+}

src/Model/Link.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Atoolo\Resource\Model;
+
+final class Link
+{
+    public function __construct(
+        public readonly string $url,
+        public readonly ?string $label = null,
+        public readonly ?string $accessibilityLabel = null,
+        public readonly ?string $description = null,
+        public readonly ?string $rel = null,
+        public readonly ?string $target = null,
+        public readonly bool $isExternal = false,
+    ) {}
+}

src/Model/OpenGraph/OpenGraphAudio.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace Atoolo\Resource\Model\OpenGraph;
+
+final class OpenGraphAudio
+{
+    public function __construct(
+        public readonly string $url,
+        public readonly ?string $secure_url = null,
+        public readonly ?string $type = null,
+    ) {}
+}

src/Model/OpenGraph/OpenGraphData.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Atoolo\Resource\Model\OpenGraph;
+
+final class OpenGraphData
+{
+    /**
+     * @param array<string,mixed> $additionalAttributes e.g. namespace specific attributes
+     */
+    public function __construct(
+        public readonly string $title,
+        public readonly string $type,
+        public readonly OpenGraphImage $image,
+        public readonly string $url,
+        public readonly ?OpenGraphAudio $audio = null,
+        public readonly ?string $description = null,
+        public readonly ?string $determiner = null,
+        public readonly ?string $locale = null,
+        public readonly ?string $locale_alternate = null,
+        public readonly ?string $site_name = null,
+        public readonly ?OpenGraphVideo $video = null,
+        public readonly array $additionalAttributes = [],
+    ) {}
+}

src/Model/OpenGraph/OpenGraphImage.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Atoolo\Resource\Model\OpenGraph;
+
+final class OpenGraphImage
+{
+    public function __construct(
+        public readonly string $url,
+        public readonly ?string $secure_url = null,
+        public readonly ?string $type = null,
+        public readonly ?int $width = null,
+        public readonly ?int $height = null,
+        public readonly ?string $alt = null,
+    ) {}
+}

src/Model/OpenGraph/OpenGraphVideo.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Atoolo\Resource\Model\OpenGraph;
+
+final class OpenGraphVideo
+{
+    public function __construct(
+        public readonly string $url,
+        public readonly ?string $secure_url = null,
+        public readonly ?string $type = null,
+        public readonly ?int $width = null,
+        public readonly ?int $height = null,
+        public readonly ?string $alt = null,
+    ) {}
+}

src/Model/TaxonomyTerm.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace Atoolo\Resource\Model;
+
+final class TaxonomyTerm
+{
+    public function __construct(
+        public readonly string $id,
+        public readonly string $name,
+        public readonly ?string $url = null,
+    ) {}
+}

src/Resource.php

@@ -5,20 +5,50 @@
 namespace Atoolo\Resource;
 
 /**
- * In the Atoolo context, resources are aggregated data from
- * IES (Sitepark's content management system).
+ * !!! This class will be made abstract in version 2.0.0.
+
+ * Represents a resource with basic metadata (location, ID, language).
  */
 class Resource
 {
+    /**
+     * @deprecated This property will be removed in version 2.0.0.
+     * Use `\SP\Resource\SiteKitResource` if you want to keep using this property.
+     * @see \SP\Resource\SiteKitResource
+     */
+    public readonly string $name;
+
+    /**
+     * @deprecated This property will be removed in version 2.0.0.
+     * Use `\SP\Resource\SiteKitResource` if you want to keep using this property.
+     * @see \SP\Resource\SiteKitResource
+     */
+    public readonly string $objectType;
+
+    /**
+     * @deprecated This property will be removed in version 2.0.0.
+     * Use `\SP\Resource\SiteKitResource` if you want to keep using this property.
+     * @see \SP\Resource\SiteKitResource
+     */
+    public readonly DataBag $data;
+
     public function __construct(
         public readonly string $location,
         public readonly string $id,
-        public readonly string $name,
-        public readonly string $objectType,
+        string $name,
+        string $objectType,
         public readonly ResourceLanguage $lang,
-        public readonly DataBag $data,
-    ) {}
+        DataBag $data,
+    ) {
+        $this->name = $name;
+        $this->objectType = $objectType;
+        $this->data = $data;
+    }
 
+    /**
+     * @deprecated This method will be made abstract in version 2.0.0.
+     * Use the class \SP\Resource\SiteKitResource if you want to keep using this method.
+     */
     public function toLocation(): ResourceLocation
     {
         return ResourceLocation::of($this->location, $this->lang);

src/ResourceFeature/ContentFeature.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace Atoolo\Resource\ResourceFeature;
+
+/**
+ * Provides the content data of a resource
+ */
+final class ContentFeature implements ResourceFeature
+{
+    public function __construct(
+        public readonly ?string $headline = null,
+        public readonly ?string $subheadline = null,
+        public readonly ?string $kicker = null,
+        public readonly ?string $intro = null,
+        public readonly ?\DateTimeImmutable $date = null,
+        // ...content? TODO
+    ) {}
+}

src/ResourceFeature/GeoFeature.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Atoolo\Resource\ResourceFeature;
+
+use Atoolo\Resource\Model\GeoJson;
+
+/**
+ * Provides the geospatial data of a resource
+ */
+final class GeoFeature implements ResourceFeature
+{
+    public function __construct(
+        public readonly GeoJson $geoData,
+    ) {}
+}

src/ResourceFeature/IdentityFeature.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace Atoolo\Resource\ResourceFeature;
+
+/**
+ * Provides the most basic identitiy data of a resource
+ */
+final class IdentityFeature implements ResourceFeature
+{
+    /**
+     * @param string $id Stable unique identifier for this resource. Must not change even if URL changes.
+     * @param string $url Absolute URL to access this resource
+     */
+    public function __construct(
+        public readonly string $id,
+        public readonly string $url,
+    ) {}
+}

src/ResourceFeature/LinkFeature.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Atoolo\Resource\ResourceFeature;
+
+use Atoolo\Resource\Model\Link;
+
+/**
+ * Provides a html-renderable link that references the underlying resource
+ */
+final class LinkFeature implements ResourceFeature
+{
+    public function __construct(
+        public Link $link,
+    ) {}
+}