Introduce functions to check whether there are multiple taxonomy terms

[flixos90]

We've had a function is_multi_author() since version 3.2.0, which is regularly used by themes to check if a site has multiple authors with published posts.

A similar function is often needed by themes for taxonomies (mostly categories), for example the latest default themes have contained a function *_categorized_blog(). I think this functionality is essential for several themes, and we can make their lifes easier by providing these functions to them (especially since several theme authors don't really wanna mess with hooks for invalidating transients).

Of course, for backward compatibility a theme should check whether that function exists, and if not, it still needs to take care of things by itself. However, I think this will still be a good solution long-term to include this functionality in WordPress Core.

[flixos90]

37825.diff​ introduces a function is_multi_taxonomy() that checks whether there exist more than one term with assigned posts for a given taxonomy. It uses transients to store the results, and these transients are automatically invalidated when necessary.

The patch also includes is_multi_category() and is_multi_tag() which are wrappers for is_multi_taxonomy().

[boonebgorges]

Idea seems OK to me, if it is in fact true that theme authors would find it useful. I don't fully grasp the utility of it, but I also don't fully grasp the utility of is_multi_author() :) Do you have examples of themes that are implementing this logic on their own?

A couple notes on the patch:

• is_multi_taxonomy() does not feel like the right name for this proposed function. is_multi_author() is checking to see whether the site has multiple authors. By extension, is_multi_taxonomy() would check to see whether the site has multiple taxonomies. But this is not right. wp_taxonomy_has_multiple_terms( $taxonomy ) seems more semantically correct.
• I don't think we need to have the underscore prefix for _clear_multi_taxonomy_cache(). We're moving away from this kind of naming convention.

[flixos90]

Replying to boonebgorges:

Idea seems OK to me, if it is in fact true that theme authors would find it useful. I don't fully grasp the utility of it, but I also don't fully grasp the utility of is_multi_author() :) Do you have examples of themes that are implementing this logic on their own?

Actually, most recent default themes did. See ​https://github.com/WordPress/twentysixteen/blob/master/inc/template-tags.php#L201 for example. They only do that for categories, but the above implementation would of course also cover that, and in addition also help theme developers that create custom themes for support of custom taxonomies.

Regarding the naming conventions, good point with the is_multi_taxonomy() name, your approach is certainly more clear. About the underscore prefix, when was this decided? It feels to me that if we don't do that anymore, the function won't be "marked" as private anymore (although of course it's technically not private anyway). I have always felt like the underscore-prefixed functions would indeed be treated as private so that we could theoretically remove them if they weren't used anymore (as that underscore should discourage plugin/theme developers to use it).

[boonebgorges]

Actually, most recent default themes did.

Point taken :)

About the underscore prefix, when was this decided?

I don't know of a specific time or where it's written down. It's been personally conveyed to me a number of times. @DrewAPicture can you chime in on this? Even if we were sticking with the underscore convention, it's not obvious to me why the cache-clearing function would qualify as something "private" or "to-be-deprecated" - we'll always need to clear the cache.

[DrewAPicture]

Replying to boonebgorges:

Actually, most recent default themes did.

Point taken :)

About the underscore prefix, when was this decided?

I don't know of a specific time or where it's written down. It's been personally conveyed to me a number of times. @DrewAPicture can you chime in on this? Even if we were sticking with the underscore convention, it's not obvious to me why the cache-clearing function would qualify as something "private" or "to-be-deprecated" - we'll always need to clear the cache.

I don't know that we're specifically "moving away from" the convention – maybe more-so in areas where the underscore is kind of moot, e.g. private methods or properties.

I'd be in favor of underscore-prefixing this new helper mostly for consistency. For instance, we've introduced new cache priming helpers with the underscore prefix as recently as 4.4 (_prime_comment_caches()) and 4.6 (_prime_network_caches()).

Does that answer your question(s)?

[sladjanquantox]

We were discussing on contributor day about method name and decided that wp_has_multiple_terms is more appropriate name

[flixos90]

Thanks for the update @sladjanquantox!

@boonebgorges I think it makes sense to omit the taxonomy in the name, terms is already clear enough in my opinion. What do you think?

[boonebgorges]

The naming in 37825.2.diff​ looks good to me. term is much clearer in this context.

The filter name (and variable names) in is_multi_taxonomy() should probably be updated to match the new naming. is_multi_taxonomy is misleading anyway - it suggests that an object has terms in more than one different taxonomy, which is not what's being tested here. "is_multi_term" is not particularly mellifluous but is more accurate.