feat: overwriteContent option for resolved blocks

Author: johannschopplich

.gitignore

@@ -12,3 +12,4 @@
 /index.dev.mjs
 /tests/coverage
 /tests/*/tmp
+/tools/**/vendor

README.md

@@ -323,7 +323,7 @@ return [
 
 The `toResolvedBlocks()` method is a wrapper around the `toBlocks()` method. It is primarily intended for usage with KQL queries, because the `toBlocks()` method returns only UUIDs for the `files` and `pages` fields.
 
-This field method will resolve the UUIDs to the actual file or page objects, so you can access their properties directly in your frontend.
+This field method will resolve the UUIDs to the actual file or page objects, so you can access their properties directly in your frontend. All resolved fields are stored in the `resolved` key of the block.
 
 ```php
 # /site/config/config.php
@@ -402,6 +402,19 @@ return [
 ];
 ```
 
+#### Overwrite Blocks Content
+
+By default, resolved fields don't overwrite the original field content. Instead, they are stored in the `resolved` key of the block. If you want to overwrite the original field content with the resolved fields, you can set the `overwriteContent` option to `true`:
+
+```php
+# /site/config/config.php
+return [
+    'blocksResolver' => [
+        'overwriteContent' => true
+    ]
+];
+```
+
 ## Page Methods
 
 ### `i18nMeta()`

src/extensions/fieldMethods.php

@@ -48,11 +48,17 @@
         // Get already resolved images
         $resolved = $block->content()->get('resolved')->or([])->value();
 
-        $block->content()->update([
-            'resolved' => array_merge($resolved, [
-                strtolower($key) => $images->map($defaultResolver)->values()
-            ])
-        ]);
+        if ($kirby->option('blocksResolver.overwriteContent', false)) {
+            $block->content()->update([
+                $key => $images->map($defaultResolver)->values()
+            ]);
+        } else {
+            $block->content()->update([
+                'resolved' => array_merge($resolved, [
+                    strtolower($key) => $images->map($defaultResolver)->values()
+                ])
+            ]);
+        }
     }
 
     return $block;
@@ -93,11 +99,17 @@
         // Get already resolved images
         $resolved = $block->content()->get('resolved')->or([])->value();
 
-        $block->content()->update([
-            'resolved' => array_merge($resolved, [
-                strtolower($key) => $pages->map($defaultResolver)->values()
-            ])
-        ]);
+        if ($kirby->option('blocksResolver.overwriteContent', false)) {
+            $block->content()->update([
+                $key => $pages->map($defaultResolver)->values()
+            ]);
+        } else {
+            $block->content()->update([
+                'resolved' => array_merge($resolved, [
+                    strtolower($key) => $pages->map($defaultResolver)->values()
+                ])
+            ]);
+        }
     }
 
     return $block;
@@ -115,14 +127,20 @@
             continue;
         }
 
-        $resolved = $block->content()->get('resolved')->or([])->value();
         $field = $block->content()->get($key);
+        $resolved = $block->content()->get('resolved')->or([])->value();
 
-        $block->content()->update([
-            'resolved' => array_merge($resolved, [
-                strtolower($key) => $resolver($field, $block)
-            ])
-        ]);
+        if ($kirby->option('blocksResolver.overwriteContent', false)) {
+            $block->content()->update([
+                $key => $resolver($field, $block)
+            ]);
+        } else {
+            $block->content()->update([
+                'resolved' => array_merge($resolved, [
+                    strtolower($key) => $resolver($field, $block)
+                ])
+            ]);
+        }
     }
 
     return $block;