Can't register Block Templates for CPTs with an underscore "_" character in the key

[alexandrebuffet]

After several days of using the new Block Templates API, I’ve noticed that we can’t register a template for a CPT that has underscore "_" in its key, it displays the error "Template names must contain a namespace prefix. Example: my-pluginmy-custom-template".

For example, I have a plugin that declares a CPT "school_course" and if I declare its associated templates "my-pluginarchive-school_course" and/or "my-pluginsingle-school_course" I get the error.

This error seems to be displayed because the test on the template name via the RegEx "/^{[a-z0-9-]+\/\/[a-z0-9-]+$/" returns false in register method from WP_Block_Templates_Registry class.}

Related issue in Gutenberg: ​https://github.com/WordPress/gutenberg/issues/67066

[karthickmurugan]

Allow underscore in register_block_template function patch.

[karthickmurugan]

Hello all.,

The above patch fixes the underscore issue in register_block_type function. Please have a look at this video for clear explanation and testing before and after the fix.

​https://share.cleanshot.com/qknmwCwGjX5tBWbCdFX5

[alexandrebuffet]

Thanks @karthickmurugan, I tested your patch and it corrects the problem.

[ankitkumarshah]

Test Report

Description

This report validates whether the indicated patch works as expected.

Patch tested: https://core.trac.wordpress.org/attachment/ticket/62523/62523.patch

Environment

• WordPress: 6.7.1
• PHP: 8.1.29
• Server: nginx/1.16.0
• Database: mysqli (Server: 8.0.16 / Client: mysqlnd 8.1.29)
• Browser: Chrome 131.0.0.0
• OS: macOS
• Theme: Twenty Twenty-Five 1.0
• MU Plugins: None activated
• Plugins:
  • Test Reports 1.2.0

Actual Results

1. ✅ Issue resolved with patch.

Supplemental Artifacts

Before Patch

​https://utfs.io/f/TnWMEUzoUd85e63Opo59in4IP8W2ScxrkUYbqyg7DsGdaTzp

After Patch

​https://utfs.io/f/TnWMEUzoUd85ETTGOEgxzLduKa2yRBnh7lb60Gwq5Sgc9H8V

[oglekler]

@noisysocks can you please look at this one?

This ticket was discussed during the Test team triage session.

According to WPCS
"Files should be named descriptively using lowercase letters. Hyphens should separate words."
​https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/

From this, it looks like all underscores in post type names should be filtered to hyphens, but if we don't have it yet, it can make braking change, so, it looks like the best option is to allow underscores in the template names.

[karthickmurugan]

@poena - Can you please take a look at this patch and move forward. Thanks in advance.

[gaambo]

register_post_type uses sanitize_key to sanitize the post type key, which in turn uses the following regex pattern: /[^a-z0-9_\-]/ I would recommend, to use the same regex and also comment/document that this must be the same as in register_post_type/sanitize_key so that it works for all post types.
I don't think there should be any problems with file names, since the same works for existing .php templates in classic themes as well.

[karthickmurugan]

Thanks @gaambo for the feedback. Updated the patch file with the consistent regex pattern. Tested it and working prefectly.

[karthickmurugan]

@poena - Can you have a look at this ticket?

[poena]

I am not able to apply the patch 62523-final.patch. Did you create if from the root directory? ​https://make.wordpress.org/core/handbook/tutorials/trac/submitting-a-patch/

patching file wp-includes/class-wp-block-templates-registry.php
Assertion failed: hunk, file ../patch-2.5.9-src/patch.c, line 354

If I manually add the code change, the template registration works.

I am not the best person to review a regex. :)

I also don't know if there was a reason for not allowing the underscore, there may be other issues that have not been brought up here. @aljullu

[karthickmurugan]

Created a new patch file.

[karthickmurugan]

@poena - Created a new patch file ( 62523.diff ) and tested it and it is working fine.

You're absolutely right that the underscore restriction might have been intentional. Unfortunately, I couldn't find specific documentation or discussions explaining the reasoning behind it. If anyone recalls or has insights into why this restriction exists, it would be great to hear more.

[poena]

I am still getting Assertion failed: hunk, file ../patch-2.5.9-src/patch.c, line 354

[karthickmurugan]

Patch file regenerated

[karthickmurugan]

@poena - I checked out the core svn again in local and regenerated the patch file. Please try with this ( 62523-final.diff )

[poena]

@karthickmurugan Please read my previous comment and ensure that you are creating and applying the patch or diff from the root directory. Not from inside the src directory.

A commiter can manually download the file and change the path, but ideally should not have to.

--- wp-includes/class-wp-block-templates-registry.php	(revision 58988)
+++ wp-includes/class-wp-block-templates-registry.php	(working copy)

When applying this patch on the SVN copy, using the terminal, the file cannot be found because the src is missing.

[karthickmurugan]

Final Patch file for CPT issue

[karthickmurugan]

@poena - Updated the patch file as per your advice. This (62523.2.patch) is the final version of it. Hope this will work as needed.

[poena]

I am now able to apply 62523.2.patch on macOS but not on Windows 11. So it is probably something with my environment.

[karthickmurugan]

Thank you, @poena, for confirming. It’s great to hear that the patch is now working on macOS. Hopefully, this will allow the core ticket to move forward smoothly and be committed soon. Please let me know if any further adjustments or clarifications are needed.

[jorbin]

Moving to 6.7.2 for review.

I think an automated test would be helpful here to ensure that the template name always allows exactly what is desired and does not include what is not desired.

Also, cc/ @flixos90 since he's worked on metadata registration related things.

[flixos90]

+1 for adding a test to cover support for template names that contain _. @karthickmurugan Would you be able to add a PHPUnit test for this?

Other than that, the latest patch looks good to me, and it makes sense - it needs to be allowed to register block templates for custom post types with underscores.

Trac ticket: https://core.trac.wordpress.org/ticket/62523

[karthickmurugan]

Thanks @sukhendu2002 for adding the PHPUnit test for this.

cc @flixos90

Hey @felixarntz, Thanks for the review! I have moved the test to the existing test file. Take a look when you get a chance. Thanks!

[flixos90]

Testing that the fix works as expected was done as part of 3. The production code implementation hasn't really changed since then, only test coverage was added. So this is good to go.

[flixos90]

In 59742:

Editor: Fix block template registration failing for custom post types containing underscore characters.

Custom post types may contain underscores, however block template registration has been using a regular expression that disallows underscores. Since the block template name for certain templates is directly associated with which post type it applies to, this regular expression was causing unexpected failures. This changeset adjusts the regular expression to allow block template names with underscore characters, effectively allowing block templates to be registered for any custom post type.

Props alexandrebuffet, ankitkumarshah, gaambo, jorbin, karthickmurugan, oglekler, poena, sukhendu2002.
Fixes #62523.

[flixos90]

Reopening for backport to the 6.7 branch.

[jorbin]

[59742] looks good for backporting to the 6.7 branch.

[flixos90]

In 59743:

Editor: Fix block template registration failing for custom post types containing underscore characters.

Custom post types may contain underscores, however block template registration has been using a regular expression that disallows underscores. Since the block template name for certain templates is directly associated with which post type it applies to, this regular expression was causing unexpected failures. This changeset adjusts the regular expression to allow block template names with underscore characters, effectively allowing block templates to be registered for any custom post type.

Reviewed by jorbin.
Merges [59742] to the 6.7 branch.

Props alexandrebuffet, ankitkumarshah, gaambo, jorbin, karthickmurugan, oglekler, poena, sukhendu2002.
Fixes #62523.