PHPDoc of get_category() is misleading

[apermo]

Recently I stumbled upon the case that get_term() will return an instance of WP_Term while get_category() suggests it will just return an object. And when I wanted to add strict comparison I was hesitant.

// Results via wp shell from a german project: Allgemein => uncategorized
> get_category(1)
= WP_Term {#10541
    +term_id: 1,
    +name: "Allgemein",
    +slug: "allgemein",
    +term_group: 0,
    +term_taxonomy_id: 1,
    +taxonomy: "category",
    +description: "",
    +parent: 0,
    +count: 50,
    +filter: "raw",
    +"cat_ID": 1,
    +"category_count": 50,
    +"category_description": "",
    +"cat_name": "Allgemein",
    +"category_nicename": "allgemein",
    +"category_parent": 0,
  }

> get_term(1,'category')
= WP_Term {#10553
    +term_id: 1,
    +name: "Allgemein",
    +slug: "allgemein",
    +term_group: 0,
    +term_taxonomy_id: 1,
    +taxonomy: "category",
    +description: "",
    +parent: 0,
    +count: 50,
    +filter: "raw",
  }

First of all, I think we should fix the PHPDoc, and I will open a PR for that.

Additionally I want to spark the discussion to either add WPCS rules to discourage the use of the aliases or maybe just mark get_category() as deprecated in favor of get_term( $term, 'category' ).

Added more details that WP_Term will have additional backwards compatible aliases for the era before WP 4.4 and 2.3

Trac ticket: https://core.trac.wordpress.org/ticket/62842#ticket

[audrasjb]

Hello, thanks for the proposal.
The suggested changes look good to me at a glance. Moving to milestone 6.8.

Maybe I'd rephrase a bit the explanation (see PR comments).

[apermo]

I already applied your suggestion, and I threw the link into the coding standards channel.

[apermo]

Additional question:

​https://php.watch/versions/8.2/dynamic-properties-deprecated

Regarding the deprecation of dynamic properties, won't this backwards compatibility function throw a deprecation warning with 8.2?

[audrasjb]

In 59704:

Docs: Improve @return docblock section for get_category().

This changeset adds more details on the WP_Term returned by get_category() as it contains additional backwards compatible aliases for the era before WP 4.4 and 2.3.

Props apermo, audrasjb.
Fixes #62842.
See #62281.

committed in https://core.trac.wordpress.org/changeset/59704

[audrasjb]

Replying to apermo:

Additional question:

​https://php.watch/versions/8.2/dynamic-properties-deprecated

Regarding the deprecation of dynamic properties, won't this backwards compatibility function throw a deprecation warning with 8.2?

Good point! Let's open a new specific ticket for this.

[apermo]

@audrasjb I've opened https://core.trac.wordpress.org/ticket/62863, though I found that WP_Term already allows dynamic properties, though I do think that we can still improve on that. More in the other ticket.