feat: refactored attribute handling, all attributes can be overridden

Author: timnarr

README.md

@@ -147,6 +147,10 @@ You can choose from many options to customize your images and pass them to the I
 
 For each HTML element of the picture element you can add attributes, CSS classes, inline-styles, data-attributes and so on. You only need to add your attributes to one of these three attribute categories, which I call "loading modes": `shared`, `eager` and `lazy`. The `shared` mode is for attributes that should exists always, no matter what loading mode the image is. If you have attributes that should only be used in `eager` or `lazy` loading mode you can add them to one of it. Imagex will merge the `shared` attributes with the attributes of the current loading mode automatically. The attributes of the non-applicable loading mode will have no effect then.
 
+**All attributes can be overridden:** User-defined attributes always take precedence over default attributes generated by Imagex. This means you can override any attribute, including `src`, `srcset`, `loading`, `width`, `height`, and others. If you don't specify an attribute, Imagex will use its default values as fallback. For `class` and `style` attributes, user values are merged with defaults rather than replaced.
+
+⚠️ **Note:** When overriding dimension-related attributes (`width`, `height`, `src`, `srcset`), be aware that Imagex calculates dimensions based on the `ratio` parameter. Overriding these attributes makes you responsible for maintaining consistency between dimensions and image sources. [See detailed explanation below](#overriding-default-attributes).
+
 | Option | Default | Type | Description |
 | ------ | ------- | ---- | ----------- |
 | `image` | – | File-Object | Required. Your initial image. Be sure to return a file object here: `$field->toFile()`. |
@@ -195,8 +199,8 @@ $options = [
     'lazy' => [
       // extend `shared` attributes in lazy loading mode
     ],
-    // Do not add `src`, `srcset` or `loading` or their equivalents for lazy loading (like `data-src`) here.
-    // These attributes are handled automatically by Imagex and adding them here will throw an exception.
+    // You can override any attribute generated by Imagex, including `src`, `srcset`, `loading`, etc.
+    // User-defined attributes always take precedence over Imagex defaults.
   ],
   'srcsetName' => 'my-srcset',
   'critical' => $isCritical ?? false,
@@ -213,6 +217,128 @@ $options = [
 <?php snippet('imagex-picture', $options) ?>
 ```
 
+### Overriding Default Attributes
+You can override any attribute that Imagex generates by default. User-defined attributes always take precedence.
+
+#### Why Override Attributes?
+
+While Imagex handles most scenarios automatically, there are practical reasons to override certain attributes:
+
+**1. Improved SEO and Social Media Sharing**
+Many crawlers (Google, Facebook, Twitter) don't fully understand `<picture>` elements or modern formats and only read the `src` attribute of the `<img>` tag. By default, Imagex uses the smallest image from your srcset as `src` (e.g., 400px width). Overriding `src` with a larger, high-quality image ensures better:
+- Google Image Search results
+- Social media previews (Open Graph, Twitter Cards)
+- SEO rankings with higher-quality images
+
+**2. Custom Lazy Loading Strategies**
+Override `src` with a low-quality image placeholder (LQIP) or blur-up effect for custom lazy loading implementations.
+
+**3. Special Loading Behavior**
+Override `loading` or other attributes for specific images that need different behavior than the global settings.
+
+#### Basic Example
+
+```php
+<?php
+$options = [
+  'image' => $image,
+  'imgAttributes' => [
+    'shared' => [
+      'width' => 500,  // Override default width
+      'height' => 300, // Override default height
+    ],
+    'lazy' => [
+      'src' => 'custom-placeholder.jpg', // Override default src
+      'loading' => 'custom-lazy', // Override lazy loading behavior
+    ],
+  ],
+  'srcsetName' => 'my-srcset',
+];
+
+snippet('imagex-picture', $options);
+```
+
+In the basic example above:
+- `width` and `height` will be set to your custom values instead of the calculated defaults
+- `src` will use your custom placeholder image
+- `loading` attribute will be set to `eager` even though Imagex would normally set it to `lazy`
+- Attributes not specified by you (like `decoding`, `fetchpriority`, etc.) will still use Imagex defaults
+
+#### SEO-Optimized Example
+
+```php
+<?php
+// Provide a larger image for crawlers while keeping optimized srcset for browsers
+$options = [
+  'image' => $image,
+  'imgAttributes' => [
+    'shared' => [
+      'src' => $image->thumb(['width' => 1200, 'quality' => 85])->url(), // Large image for crawlers
+      'alt' => $image->alt(),
+    ],
+  ],
+  'srcsetName' => 'my-srcset', // Srcset will still use optimized sizes (400w, 800w, etc.)
+];
+
+snippet('imagex-picture', $options);
+```
+
+In this SEO example:
+- Modern browsers use the optimized `srcset` with modern formats (avif, webp) and appropriate sizes
+- Crawlers and social media bots get a high-quality 1200px image from the `src` attribute (which serves as a fallback)
+- Best of both worlds: Fast loading for users, quality images for SEO
+
+**Note on src as fallback:** The `src` attribute primarily serves as a fallback for very old browsers and is what crawlers read. Modern browsers will always prefer images from `srcset` or `<source>` elements. This means you can safely override `src` with a different aspect ratio or larger size for SEO purposes without affecting the user experience, as browsers will load the correctly-sized images from your `srcset`.
+
+**Example - Different ratio for SEO:**
+```php
+<?php
+// Use 16:9 for browsers, but 1:1 for SEO/social media
+$options = [
+  'image' => $image,
+  'ratio' => '16/9', // Browser gets 16:9 images via srcset
+  'imgAttributes' => [
+    'shared' => [
+      // Crawlers get a square image
+      'src' => $image->thumb(['width' => 1200, 'height' => 1200, 'crop' => true])->url(),
+    ],
+  ],
+  'srcsetName' => 'my-srcset',
+];
+```
+Result: Browsers display 16:9 images (from srcset), crawlers and social media get 1:1 image (from src).
+
+**Important Note on Ratio Handling:**
+Imagex automatically calculates image dimensions based on the specified `ratio` parameter. When you override dimension-related attributes (`width`, `height`, `src`, or `srcset`), you become responsible for maintaining consistency:
+
+- **Overriding `width`/`height`**: The `srcset` will still use thumbnails generated with the original ratio, which may not match your custom dimensions.
+- **Overriding `src`/`srcset`**: The `width` and `height` attributes will still reflect the calculated ratio, which may not match your custom images.
+
+If you override these attributes, ensure that your custom values are consistent with each other and with the aspect ratio of your images to avoid layout shifts or distorted images.
+
+**Example - Correct way to override dimensions:**
+```php
+<?php
+// If you need custom dimensions, override all related attributes together
+$options = [
+  'image' => $image,
+  'imgAttributes' => [
+    'shared' => [
+      'width' => 600,
+      'height' => 400, // Make sure this matches your desired ratio (3:2 in this case)
+    ],
+    'lazy' => [
+      // If you also override srcset, make sure your images have the same 3:2 ratio
+      'srcset' => 'custom-300.jpg 300w, custom-600.jpg 600w, custom-900.jpg 900w',
+    ],
+  ],
+  'srcsetName' => 'my-srcset',
+  'ratio' => '3/2', // This ratio is now only used for generating the default thumbnails
+];
+```
+Note: In most cases, you should **not** need to override `width`, `height`, or `srcset`. Let Imagex handle these automatically based on your `ratio` parameter for best results.
+```
+
 ## Cache
 Imagex will do some simple calculations per image, like calculating the height by the given width and ratio. Basically Imagex get the srcset definition from the config file, calculate and set the height and output the final config. The result will be cached to reduce unnecessary calculations when you use the same combination of srcset-preset and ratio for other images.
 

docs/examples/basic-config.md

@@ -78,11 +78,11 @@ $options = [
       'sizes' => '(min-width: 800px) 400px, 100vw',
       'class' => [
         'my-image',
-        $conditionalClass ? 'my-image--variant' : null // let's ssume $conditionalClass is `true`
+        $conditionalClass ? 'my-image--variant' : null // let's assume $conditionalClass is `true`
       ],
       'style' => [
         'object-fit: cover;',
-        'object-position: ' . $image->toFile()->focus(); . ';'
+        'object-position: ' . $image->toFile()->focus() . ';'
       ]
     ]
   ]
@@ -138,7 +138,7 @@ $options = [
       'class' => ['my-image'],
       'style' => [
         'object-fit: cover;',
-        'object-position: ' . $image->toFile()->focus(); . ';'
+        'object-position: ' . $image->toFile()->focus() . ';'
       ]
     ],
   ],
@@ -168,7 +168,7 @@ $options = [
       https://example.com/image-400x225-crop-52-65-q75-sharpen10.webp 400w,
       https://example.com/image-800x450-crop-52-65-q75-sharpen10.webp 800w">
   <img
-    class="my-image my-image--variant" sizes="(min-width: 800px) 400px, 100vw"
+    class="my-image" sizes="(min-width: 800px) 400px, 100vw"
     style="object-fit: cover; object-position: 52% 65%;"
     width="400" height="225" decoding="async" loading="lazy"
     alt="A cat sits in the sun in front of yellow flowers."

helpers/attributes.php

@@ -38,49 +38,15 @@ function validateAttributeTypes(array $options): void
 	}
 }
 
-/**
- * Validates the attributes array against a set of disallowed attributes for each loading mode.
- *
- * @param array $options The attributes array to validate
- * @throws InvalidArgumentException If disallowed attributes are detected in any loading mode.
- */
-function validateAttributes(array $options): void
-{
-	$disallowedAttributes = [
-		'shared' => ['type', 'src', 'data-src', 'srcset', 'data-srcset', 'loading', 'width', 'height'],
-		'eager' => ['srcset', 'data-srcset', 'loading'],
-		'lazy' => ['data-srcset', 'loading'],
-	];
-
-	$violations = [];
-
-	foreach ($options as $loadingMode => $attributes) {
-		// Check if there are disallowed attributes defined for the current loading mode
-		if (!isset($disallowedAttributes[$loadingMode])) {
-			continue;
-		}
-
-		foreach ($attributes as $attribute => $value) {
-			// Check if the attribute is disallowed in the current loadingMode
-			if (in_array($attribute, $disallowedAttributes[$loadingMode])) {
-				$violations[] = "attribute \"$attribute\" in \"$loadingMode\"";
-			}
-		}
-	}
-
-	if (!empty($violations)) {
-		throw new InvalidArgumentException('[kirby-imagex] Disallowed attributes detected: ' . implode(', ', $violations) . '.');
-	}
-}
-
 /**
  * Merges HTML attributes for different loading modes with optional default values.
  *
+ * User attributes always override default attributes. Defaults are used as fallback.
  * Extend 'shared' by 'eager' or 'lazy' loading mode attributes.
  *
- * @param array $options Attributes structured by loading modes.
+ * @param array $attributes User-defined attributes structured by loading modes.
  * @param string $loadingMode The loading mode to merge attributes for.
- * @param array $defaultOptions Optional default attributes to apply before merging.
+ * @param array $defaultAttributes Optional default attributes to apply as fallback.
  * @return array Merged array of HTML attributes for specified loading mode.
  * @throws InvalidArgumentException If $loadingMode is invalid or missing.
  */
@@ -89,8 +55,6 @@ function mergeHTMLAttributes(array $attributes, string $loadingMode, array $defa
 	validateAttributeTypes($defaultAttributes);
 	validateAttributeTypes($attributes);
 
-	validateAttributes($attributes);
-
 	if (!in_array($loadingMode, ['shared', 'eager', 'lazy'])) {
 		throw new InvalidArgumentException("[kirby-imagex] Invalid loadingMode: \"$loadingMode\".");
 	}
@@ -100,7 +64,7 @@ function mergeHTMLAttributes(array $attributes, string $loadingMode, array $defa
 	}
 
 	$mergableAttributes = ['class', 'style'];
-	$mergedAttributes = $defaultAttributes['shared'] ?? [];
+	$mergedAttributes = [];
 
 	// Function to merge attributes, handling both array and string values
 	$mergeAttributeValues = function ($key, $currentValue, $newValue) use ($mergableAttributes) {
@@ -118,21 +82,28 @@ function mergeHTMLAttributes(array $attributes, string $loadingMode, array $defa
 		}
 	};
 
-	// Merge default loading mode-specific attributes
+	// Step 1: Start with default 'shared' attributes
+	if (isset($defaultAttributes['shared'])) {
+		foreach ($defaultAttributes['shared'] as $attr => $value) {
+			$mergedAttributes[$attr] = $value;
+		}
+	}
+
+	// Step 2: Merge default loading mode-specific attributes
 	if (isset($defaultAttributes[$loadingMode])) {
 		foreach ($defaultAttributes[$loadingMode] as $attr => $value) {
 			$mergedAttributes[$attr] = $mergeAttributeValues($attr, $mergedAttributes[$attr] ?? '', $value);
 		}
 	}
 
-	// Merge shared source attributes
+	// Step 3: Merge/override with user 'shared' attributes (user attributes have priority)
 	if (isset($attributes['shared'])) {
 		foreach ($attributes['shared'] as $attr => $value) {
 			$mergedAttributes[$attr] = $mergeAttributeValues($attr, $mergedAttributes[$attr] ?? '', $value);
 		}
 	}
 
-	// Merge loading mode-specific source attributes
+	// Step 4: Merge/override with user loading mode-specific attributes (highest priority)
 	if (isset($attributes[$loadingMode])) {
 		foreach ($attributes[$loadingMode] as $attr => $value) {
 			$mergedAttributes[$attr] = $mergeAttributeValues($attr, $mergedAttributes[$attr] ?? '', $value);

tests/attributesTest.php

@@ -22,16 +22,18 @@ public function testValidateAttributesValidInput()
 		validateAttributes($options);
 	}
 
-	public function testValidateAttributesInvalidInput()
+	public function testValidateAttributesAllowsAllAttributes()
 	{
-		$this->expectExceptionMessage('[kirby-imagex] Disallowed attributes detected: attribute "type" in "shared", attribute "srcset" in "eager", attribute "loading" in "lazy".');
-
+		// All attributes are now allowed and can be overridden by users
 		$options = [
 			'shared' => ['type' => 'image/jpeg', 'data-attribute' => 'my-attr-value', 'style' => ['background: red;']],
 			'eager' => ['data-src' => 'image-eager.jpg', 'srcset' => 'image-eager.jpg'],
 			'lazy' => ['loading' => 'lazy', 'src' => 'image-lazy.jpg'],
 		];
 
+		// Expect no exception
+		$this->expectNotToPerformAssertions();
+
 		validateAttributes($options);
 	}
 
@@ -128,4 +130,45 @@ public function testMergeHTMLAttributesLazy()
 
 		$this->assertEquals($expected, $result);
 	}
+
+	public function testMergeHTMLAttributesUserOverridesDefaults()
+	{
+		// Test that user attributes override default attributes
+		$userAttributes = [
+			'shared' => [
+				'width' => 500,
+				'height' => 300,
+			],
+			'lazy' => [
+				'src' => 'custom-image.jpg',
+				'loading' => 'eager',
+			],
+		];
+		$loadingMode = 'lazy';
+		$defaultAttributes = [
+			'shared' => [
+				'width' => 1000,
+				'height' => 600,
+				'decoding' => 'async',
+			],
+			'lazy' => [
+				'src' => 'default-image.jpg',
+				'loading' => 'lazy',
+				'data-src' => 'default-data-image.jpg',
+			],
+		];
+
+		$expected = [
+			'width' => 500, // User override
+			'height' => 300, // User override
+			'decoding' => 'async', // From defaults
+			'src' => 'custom-image.jpg', // User override
+			'loading' => 'eager', // User override
+			'data-src' => 'default-data-image.jpg', // From defaults (not overridden by user)
+		];
+
+		$result = mergeHTMLAttributes($userAttributes, $loadingMode, $defaultAttributes);
+
+		$this->assertEquals($expected, $result);
+	}
 }