[5.x]: GraphQL type name conflict when overriding Matrix field handle

What happened?

Description

If two entry types use two different matrix fields, which support different entry-types, but use the same handle for these matrix fields, GraphQL throws an error indicating the nested entry types are not available for the matrix field.

It seems like the Matrix field uses the overridden handle to generate it's GraphQL content type name, and that creates a conflict meaning that the schema is missing some types.

Steps to reproduce

I have quickly setup a small Craft-CMS project repository which you can clone, with a simple project config that reproduces the error (steps 1 to 8 below). To recreate the issue in another Craft-CMS project, setup the following project config:

1. Create an entry type named "Text Block" (textBlock)
2. Create an entry type named "Image Block" (imageBlock)
3. Create an entry type named "Gallery Block" (galleryBlock)
4. Create a Matrix field named "Simple Body Blocks" (simpleBodyBlocks) with support for the following nested entry-types:
   • "Text Block" (textBlock)
   • "Image Block" (imageBlock)
5. Create an entry type named "Simple Page" and add the "Simple Body Blocks" Matrix field to its field layout with the overridden field handle bodyBlocks.
6. Create a Matrix field named "Complex Body Blocks" (complexBodyBlocks) with support for the following nested entry-types:
   • "Text Block" (textBlock)
   • "Image Block"(imageBlock)
   • "Gallery Block"(galleryBlock)
7. Create an entry type named "Complex Page" and add the "Complex Body Blocks" Matrix field to its field layout, with the overridden field handle bodyBlocks.
8. Create a section named "Pages" and add the "Simple Page" and "Complex Page" entry-types to it (this is only so we can easily create the data needed to reproduce the bug, and does not seem relevant for causing the bug itself).

Once you have the project config setup:

9. Create 1x "Simple Page" entry and add 1x "Text Block" and 1x "Image Block" to its bodyBlocks field.
10. Create 1x "Complex Page" entry and add 1x "Text Block", 1x "Image Block" and 1x "Gallery Block" to its bodyBlocks field.
11. Open GraphiQL and run the following query:

query {
  pagesEntries {
    ... on simplePage_Entry {  
      bodyBlocks {
        __typename
        ... on textBlock_Entry {
          id
          typeHandle
          title
        }
        ... on imageBlock_Entry {
          id
          typeHandle
          title
        }
      }
    }
    ... on complexPage_Entry {
      bodyBlocks {
        __typename
        ... on textBlock_Entry {
          id
          typeHandle
          title
        }
        ... on imageBlock_Entry {
          id
          typeHandle
          title
        }
        ... on galleryBlock_Entry {
          id
          typeHandle
          title
        }
      }
    }
  }
}

Expected behavior

The GraphQL API should return the data for the two entries and the nested entries created in their matrix field (steps 9-11):

{
  "data": {
    "pagesEntries": [
      {
        "bodyBlocks": [
          {
            "__typename": "textBlock_Entry",
            "id": "21",
            "typeHandle": "textBlock",
            "title": "Test Text (Simple)"
          },
          {
            "__typename": "imageBlock_Entry",
            "id": "22",
            "typeHandle": "imageBlock",
            "title": "Test Image (Simple)"
          }
        ]
      },
      {
        "bodyBlocks": [
          {
            "__typename": "imageBlock_Entry",
            "id": "27",
            "typeHandle": "imageBlock",
            "title": "Test Image (Complex)"
          },
          {
            "__typename": "textBlock_Entry",
            "id": "28",
            "typeHandle": "textBlock",
            "title": "Test Text (Complex)"
          },
          {
            "__typename": "galleryBlock_Entry",
            "id": "29",
            "typeHandle": "galleryBlock",
            "title": "Test Gallery (Complex)"
          }
        ]
      }
    ]
  }
}

Actual behavior

The GraphQL API returns the following error data:

Fragment cannot be spread here as objects of type \"bodyBlocks_MatrixField\" can never be of type \"galleryBlock_Entry\".

If we remove the ... on galleryBlock_Entry {} fragment from the GraphQL query, another error is returned and the galleryBlock entry is missing from the data:

Runtime Object type \"galleryBlock_Entry\" is not a possible type for \"bodyBlocks_MatrixField\"."

Suggested Solution

We suspect the problem is that the Matrix field generates a type name based on its handle in the current field layout (i.e. bodyBlocks in the example setup above). This creates a conflict, and as a result only one of the two Matrix types exist in the GraphQL schema. This could be solved by using the original handle (the handle defined in the CP > Settings > Fields section) in the field's getContentGqlType() method to avoid such conflicts.

We could not try out this solution because –at the time when the getContentGqlType() method is called– the Matrix Field's handle property is set to the overridden handle, and there is no originalHandle property. We quickly tested including the field's id in the type name, and –although we suspect that would introduce new problems– it did solve the issue.

Craft CMS version

5.4.9

PHP version

8.2.22

Operating system and version

Linux 6.10.12-orbstack-00282-gd1783374c25e

Database type and version

MySQL 8.0.36

Image driver and version

Imagick 3.7.0 (ImageMagick 6.9.11-60)

Installed plugins and versions

(None)

Clone the linked reproduction repository, follow steps 1–11, and run the GraphiQL query. Compare the generated bodyBlocks_MatrixField schema with the runtime error shown from webonyx/graphql-php's ReferenceExecutor.php; done means both matrix fields expose their permitted nested entry types and the query returns galleryBlock_Entry data.