Search for hyphenated post templates for post types with underscores

[desrosj]

Custom post type names adhere to the rules within sanitize_key() (lowercase alphanumeric characters, dashes, and underscores).

This means registering a post type some_post_type is perfectly fine. The archive and single templates would be be archive-some_post_type.php and single-some_post_type.php.

These file names do not adhere to the core standard for file names.

Files should be named descriptively using lowercase letters. Hyphens should separate words.

Searching for archive-some-post-type.php in addition to archive_some_post_type.php would allow this standard to be followed better.

[jmichaelward]

@desrosj Here's a first-look patch that attempts to address this issue, by way of prepending a hyphenated archive template name within the logic of get_archive_template in template.php. When applied, this patch will allow a file to be named archive-custom_post_type.php or archive-custom-post-type.php, where the latter will take higher precedence in the template hierarchy.

To fully address the issue, I suspect that other templates - such as single - would need to be updated, as well. The larger question is whether this would be considered "code churn", but I do think that making updates to allow devs to name their templates in adherence to the WordPress Coding Standards is advisable and should be encouraged.

[desrosj]

Thanks for the initial patch @jmichaelward! In 41564.2.diff​, I added code for single templates and taxonomy archives. I think that if taxonomy-tax-name.php or single-post-type.php is searched for, then single-post-type-slug.php and taxonomy-tax-name-slug.php should probably should be searched for as well.

I had a few suggestions for changes in your patch that I made in the new patch and wanted to share them.

if ( strpos() ) could result in undesired behaviors, as 0 (first position in a string) would be considered falsy (_my_post_type, for example) false !== strpos() is a better check.

Also, instead of having to use array_unshift(), adding the value new before the current one is better.

[jmichaelward]

@desrosj Thanks for the updated patch. I think your changes and recommendations look good. Thanks!

Refreshing 41564.2.diff for review & testing

[SirLouen]

Test Report

Description

❌ This report can't fully validate that the indicated patch works as expected.

Patch tested: ​https://github.com/WordPress/wordpress-develop/pull/9973

Environment

• WordPress: 6.9-alpha-60093-src
• PHP: 8.2.29
• Server: nginx/1.29.1
• Database: mysqli (Server: 8.4.6 / Client: mysqlnd 8.2.29)
• Browser: Chrome 139.0.0.0
• OS: Windows 10/11
• Theme: Twenty Twenty-Five 1.3
• MU Plugins: None activated
• Plugins:
  • BBB Testing Dolly
  • Test Reports 1.2.0

Testing Instructions

There are 3 separate tests here (I've done only 2 to illustrate the problems)

Test Taxonomy Template

1. Add the code provided in Supp Artifacts
2. Create a term in Foo Bar for example "Sample Term"
3. Visit that Term, check the debug log.

🐞 Without the patch

[0] => taxonomy-foo_bar-sample-term.php
[1] => taxonomy-foo_bar.php
[2] => taxonomy.php

⚠️ With the patch:

[0] => taxonomy-foo_bar-sample-term.php
[1] => taxonomy-foo-bar.php
[2] => taxonomy-foo_bar.php
[3] => taxonomy.php

Test Post Type

1. Edit the code provided in Supp Artifacts to adapt to post types (need to register a post_type in this case)
2. Create a post in Foo Bar post type for example "Sample Post Type"
3. Visit that post in this new Post Type

🐞 Without the patch

[0] => single-foo_bar-sample-post-type.php
[2] => single-foo_bar.php
[3] => single.php

⚠️ With the patch:

[0] => single-foo_bar-sample-post-type.php
[1] => single-foo-bar.php
[2] => single-foo_bar.php
[3] => single.php

Actual Results

1. ❌ Issue is not resolved with patch.

Additional Notes

• Without the patch, there is no priority for the file without hyphens
• ⚠️ But the patch doesn't cover the template in case of targeting a specific term. In this case, the correct form should be full hyphened, for example taxonomy-foo-bar-sample-term.php following the same scenario provided in OP
• Given that the patch was done like 8+ years ago, I'm going to demote it to needs-patch as a whole new version is needed, but if you are willing to do a new patch take my ​PR 9973 as a reference.
• One unit tests for each of the 3 forms will be good also.

Supplemental Artifacts

Taxonomy Testing

<?php
add_action( 'init', 'register_test_taxonomy' );
function register_test_taxonomy() {
        register_taxonomy(
                'foo_bar',
                'post',
                array(
                        'label'        => 'Foo Bar',
                        'public'       => true,
                        'show_ui'      => true,
                        'show_in_rest' => true,
                )
        );
}
add_filter( 'taxonomy_template_hierarchy', 'log_taxonomy_hierarchy' );
function log_taxonomy_hierarchy( $templates ) {
        if ( is_tax( 'foo_bar' ) ) {
                error_log( 'taxonomy_template_hierarchy => ' . print_r( $templates, true ) );
        }
        return $templates;
}