Correct displaying the _doing_it_wrong() message for add_theme_support( 'html5' )

[SergeyBiryukov]

Background: #24932, #51390.

As a result of [25193], [25235], and [25785] add_theme_support( 'html5' ) is supposed to return false and display a _doing_it_wrong() notice: "You need to pass an array of types".

As far as I can tell, this has never worked as expected, due to ! is_array( $args[0] ) check being in the elseif condition after empty( $args[0] ), which always succeeds in this case.

Currently, calling add_theme_support( 'html5' ) without passing an array of supported types just silently falls back to array( 'comment-list', 'comment-form', 'search-form' ) for backward compatibility, without any indication that it is not the recommended approach.

[audrasjb]

Themes: Correct displaying the _doing_it_wrong() message for add_theme_support( 'html5' )

[audrasjb]

_doing_it_wrong notice

[audrasjb]

Nice catch @SergeyBiryukov!

I think 51657.diff does the job :)

Just wonder if we want to change the version param. I think it's fine to keep the reference to the version it was added, but on another hand, it would be nice to upgrade the version to 5.7.0 as the notice will be displayed for the very first time. Any thought?

[audrasjb]

Adding needs-dev-note workflow keyword. It won't need a full dev note, but a quick mention in the Miscellaneous changes won't hurt :)

[peterwilsoncc]

Reviewing 51657.diff​ :

• The condition can be reduced to if ( empty( $args[0] ) || ! is_array( $args[0] ) ) -- empty() is a short cut for ! isset($var) || ! $var.
• I haven't run the full test suite but I am getting a few failures in Tests_Theme_Support
• Some additional tests to make sure the feature is throwing a doing it wrong as expected would be ideal too

> phpunit --filter Tests_Theme_Support

.....FFF....                                                      12 / 12 (100%)

There were 3 failures:

1) Tests_Theme_Support::test_supports_html5
Unexpected incorrect usage notice for add_theme_support( 'html5' )
Failed asserting that an array is empty.

/vagrant/wordpress-develop/tests/phpunit/includes/abstract-testcase.php:516
/vagrant/wordpress-develop/tests/phpunit/includes/abstract-testcase.php:528

2) Tests_Theme_Support::test_supports_html5_subset
Failed asserting that null is false.

/vagrant/wordpress-develop/tests/phpunit/tests/theme/support.php:101

3) Tests_Theme_Support::test_supports_html5_invalid
Failed asserting that null is false.

/vagrant/wordpress-develop/tests/phpunit/tests/theme/support.php:130

[JeffPaul]

Given that the needs-refresh keyword was added in before this got milestoned AND no further actions since then, I'm going to punt this to Future Release with the 5.8 Beta 1 release tomorrow.

[SergeyBiryukov]

In 52828:

Themes: Correct the logic for displaying a _doing_it_wrong() notice for add_theme_support( 'html5' ).

• Calling add_theme_support( 'html5' ) without passing an array of supported types should throw a _doing_it_wrong() notice: "You need to pass an array of types".
• If the second parameter is not specified, it should fall back to an array of comment-list, comment-form, and search-form for backward compatibility.
• If the second parameter is not an array, the function should return false.

The latter two points are covered by existing unit tests. The first one is now addressed by @expectedIncorrectUsage.

Follow-up to [25193], [25235], [25785].

Props audrasjb, peterwilsoncc, SergeyBiryukov.
Fixes #51657.

[bobbingwide]

Just wonder if we want to change the version param. I think it's fine to keep the reference to the version it was added, but on another hand, it would be nice to upgrade the version to 5.7.0 as the notice will be displayed for the very first time. Any thought?

I've just spent a while trying to understand why I've not seen this message before WordPress 6.0
I agree that the original doing_it_wrong was added in 3.6.1.

But up to 5.9.3 everything was OK since the code magically defaulted the args array.
It would have been nice to have seen something that indicated there'd been a further change in 6.0

[SergeyBiryukov]

In 53513:

Docs: Add @since notes for html5 theme feature changes in add_theme_support():

• As of WordPress 3.6.1, the html5 feature requires an array of types to be passed. Defaults to comment-list, comment-form, search-form for backward compatibility.
• As of WordPress 6.0, the previously added _doing_it_wrong() notice is actually displayed as expected.

Follow-up to [25193], [25235], [25785], [49344], [49354], [52828].

Props bobbingwide.
See #51657, #55646.

[SergeyBiryukov]

Replying to bobbingwide:

It would have been nice to have seen something that indicated there'd been a further change in 6.0

You're absolutely right, thanks for bringing this up! [53513] adds the corresponding @since notes.