From 8b0e4009425aed18071d70a080e8f9b6f4c00d02 Mon Sep 17 00:00:00 2001
From: Alex Kazhukhouski <alex.kazhukhouski@wpengine.com>
Date: Tue, 4 Feb 2025 18:58:07 +0100
Subject: [PATCH] Improves comment and provides relevant README.md info.

---
 README.md                 | 144 ++++++++++++++++++++++++++++++++++++++
 includes/Blocks/Block.php |   3 +-
 2 files changed, 146 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 55235280..c5e734d9 100644
--- a/README.md
+++ b/README.md
@@ -146,6 +146,150 @@ So in order to put everything back in the Headless site, you want to use the `fl
 
 > Currently the `clientId` field is only unique per request and is not persisted anywhere. If you perform another request each block will be assigned a new `clientId` each time.
 
+---
+
+## Querying Object-Type Block Attributes in WPGraphQL
+
+### Overview
+With this update, you can now query object-type block attributes with each property individually, provided that the **typed structure** is defined in the class `typed_object_attributes` property or through a **WordPress filter**.
+
+### How It Works
+The `typed_object_attributes` is a **filterable** array that defines the expected **typed structure** for object-type block attributes.
+
+- The **keys** in `typed_object_attributes` correspond to **object attribute names** in the block.
+- Each value is an **associative array**, where:
+    - The key represents the **property name** inside the object.
+    - The value defines the **WPGraphQL type** (e.g., `string`, `integer`, `object`, etc.).
+- If a block attribute has a specified **typed structure**, only the properties listed within it will be processed.
+
+### Defining Typed Object Attributes
+Typed object attributes can be **defined in two ways**:
+
+#### 1. In a Child Class (`typed_object_attributes` property)
+Developers can extend the `Block` class and specify **typed properties** directly:
+
+```php
+class CustomMovieBlock extends Block {
+	/**
+	 * {@inheritDoc}
+	 *
+	 * @var array<string, array<string, "array"|"boolean"|"number"|"integer"|"object"|"rich-text"|"string">>
+	 */
+	protected array $typed_object_attributes = [
+		'film' => [
+			'id'         => 'integer',
+			'title'      => 'string',
+			'director'   => 'string',
+			'soundtrack' => 'object',
+		],
+		'soundtrack' => [
+			'title'  => 'string',
+			'artist' => 'string'
+		],
+	];
+}
+```
+
+#### 2. Via WordPress Filter
+You can also define **typed structures dynamically** using a WordPress filter.
+
+```php
+add_filter(
+    'wpgraphql_content_blocks_object_typing_my-custom-plugin_movie-block',
+    function () {
+        return [
+            'film'       => [
+                'id'         => 'integer',
+                'title'      => 'string',
+                'director'   => 'string',
+                'soundtrack' => 'object',
+            ],
+            'soundtrack' => [
+                'title'  => 'string',
+                'artist' => 'string'
+            ],
+        ];
+    }
+);
+```
+
+### Filter Naming Convention
+To apply custom typing via a filter, use the following format:
+
+```
+wpgraphql_content_blocks_object_typing_{block-name}
+```
+- Replace `/` in the block name with `-`.
+- Example:
+    - **Block name**: `my-custom-plugin/movie-block`
+    - **Filter name**: `wpgraphql_content_blocks_object_typing_my-custom-plugin_movie-block`
+
+### Example:
+
+
+#### Example `block.json` Definition
+If the block has attributes defined as **objects**, like this:
+
+```json
+"attributes": {
+    "film": {
+      "type": "object",
+      "default": {
+        "id": 1,
+        "title": "The Matrix",
+        "director": "Director Name"
+      }
+    },
+    "soundtrack": {
+      "type": "object",
+      "default": {
+        "title": "The Matrix Revolutions...",
+        "artist": "Artist Name"
+      }
+    }
+}
+```
+This means:
+- The `film` attribute contains `id`, `title`, `director`.
+- The `soundtrack` attribute contains `title` and `artist`.
+
+### WPGraphQL Query Example
+Once the typed object attributes are **defined**, you can query them **individually** in WPGraphQL.
+
+```graphql
+fragment Movie on MyCustomPluginMovieBlock {
+    attributes {
+        film {
+            id
+            title
+            director
+            soundtrack {
+                title
+            }
+        }
+        soundtrack {
+            title
+            artist
+        }
+    }
+}
+
+query GetAllPostsWhichSupportBlockEditor {
+    posts {
+        edges {
+            node {
+                editorBlocks {
+                    __typename
+                    name
+                    ...Movie
+                }
+            }
+        }
+    }
+}
+```
+---
+
 ### Contributor License Agreement
 
 All external contributors to WP Engine products must have a signed Contributor License Agreement (CLA) in place before the contribution may be accepted into any WP Engine codebase.
diff --git a/includes/Blocks/Block.php b/includes/Blocks/Block.php
index fcd90ec3..fb95ef92 100644
--- a/includes/Blocks/Block.php
+++ b/includes/Blocks/Block.php
@@ -54,7 +54,8 @@ class Block {
 	protected ?array $additional_block_attributes;
 
 	/**
-	 * A filtered array of block object attributes that are typed.
+	 * A filterable array of block object attributes that are typed.
+	 * The keys could be the object attribute names of the block and the value is an associative array where the key is the property name and the value is the type.
 	 *
 	 * @var array<string, array<string, "array"|"boolean"|"number"|"integer"|"object"|"rich-text"|"string">>
 	 */