category_description() does not work properly since 4.9

[torben.tschechne@…]

Hello,
since upgrading to 4.9 the category_description() function stopped working properly in my case. I use category_description() outside the loop and it returns an empty string.

I tracked down

get_term_field()

in wp-includes/taxonomy.php and

sanitize_term_field( $field, $term->$field, $term->term_id, $term->taxonomy, $context );

Does return only a string of the Category, but no description.

When I use 4.8.3 - I get the description.

[torben.tschechne@…]

A quick update.

This happens when I want to determine the category description of a product category and this call:

return term_description( $category, 'category' );

in category_description. If I change this to

return term_description( $category, 'product_cat' );

it works. However this is not happening in 4.8.3. So I assume that category_description() is not usable in 4.9 for product_cat anymore.

[nikolov.tmw]

Hi @torben.tschechne@…, does your second example work in 4.8.3? I think in this case you might have been using the function wrong. See - you're supplying the second parameter, but it's incorrect - if the $category term is in fact from the product_cat taxonomy, then why not just use product_cat?

The Codex says that the second parameter is optional. So perhaps try with(product_cat) and without the second parameter in 4.8.3 and if that works, then maybe it used to work incorrectly before.

[torben.tschechne@…]

Hey @nikolov.tmw - I have not used term_description before. I have used

category_description( $category_id );

In 4.8.3 and it returned the description of the product category. But in 4.9 this stopped working - when using category_description I have not the possibility to define a taxonomy. So maybe this was a bug in 4.8.3 and I had a benefit from this bug ...?

When I use:

term_description($product_cat_id, 'product_cat');

It does work in 4.9

[harsh175]

category_description() function only return the default WordPress post category description. For custom taxonomy category description you have to use term_description() function.

​https://codex.wordpress.org/Function_Reference/category_description

[markjaquith]

see #42771

[boonebgorges]

In 42368:

category_description() should be taxonomy-agnostic.

This change reinstates the previous de facto behavior of category_description().
See [40979], [42364]. Because term_description() no longer passes $taxonomy to
get_term_field(), the parameter is no longer needed and has been deprecated.

Fixes #42605. See #42771.

[boonebgorges]

In 42372:

category_description() should be taxonomy-agnostic.

This change reinstates the previous de facto behavior of category_description().
See [40979], [42364]. Because term_description() no longer passes $taxonomy to
get_term_field(), the parameter is no longer needed and has been deprecated.

Merges [42368] to the 4.9 branch.

Fixes #42605. See #42771.

[jorbin]

@boonebgorges Should we throw a deprecation notice here in case people are expecting a different behavior?

[boonebgorges]

Replying to jorbin:

@boonebgorges Should we throw a deprecation notice here in case people are expecting a different behavior?

It's hard to see what this would look like. Uses of category_description() and friends will work the same as how they worked prior to 4.9. If anything, I'd imagine that the appropriate change would be a _doing_it_wrong() when passing a $term_id to category_description() that matches a term that is not, in fact, a category. But this also seems as if it might be overkill for a fairly harmless bit of backward compat overhead.

[jorbin]

My thinking is that it will help people clean up and test code if they see a deprecated argument notice. I don't expect code to break now, but I do worry if there comes a time in the future where there is a desire to add a new parameter to term_description and the committers then accidentally adding it as the 2nd parameter rather than the 3rd and code-breaking then.

Something along the lines of:

<?php
 function term_description( $term = 0, $deprecated = null ) {
    if ( null !== $deprecated ) {
        _deprecated_argument( __FUNCTION__ , '4.9.2', 'since terms are now split, taxonomy does not need to be passed to term_description' ) {
    }

[boonebgorges]

@jorbin Ah yes, that makes perfect sense. Thanks for the clarification. I'll work on this.

[boonebgorges]

Thinking about this more, I think @jorbin is correct that we need to keep $deprecated in the function signature, but I don't think it's something we need to expose to developers via _deprecated_argument().

[boonebgorges]

In 42417:

Taxonomy: Restore deprecated argument to term_description() signature.

This ensures that the parameter can't be reused for something else
in the future.

Props jorbin.
Fixes #42605.

[boonebgorges]

In 42418:

Taxonomy: Restore deprecated argument to term_description() signature.

This ensures that the parameter can't be reused for something else
in the future.

Merges [42417] to the 4.9 branch.

Props jorbin.
Fixes #42605.

[jorbin]

@boonebgorges Any particular reason to keep it hidden? My main argument for having _deprecated_argument would be consistency and that's how core has traditionally deprecated arguments (to the best of my knowledge). My main argument against it would be my inability to think up a quality message to send with it.

[boonebgorges]

The semantics of "keep it hidden" make it sound like I'm pulling the wool over someone's eyes :) I just don't see the reason to fill up error logs with notices for something that is harmless. I grepped through the codebase before my commit above and found lots of instances of $deprecated arguments that don't throw notices. That said, if the general agreement is that we should always throw notices in such cases, let's add it.

[jorbin]

Makes complete sense. I support your decision. Thank you for explaining and sorry for my semantical misnomer.