term_exists() may return 0 which is not a text-documented return type

[dotancohen]

The PHPDoc for term_exists() reads as follows:

Returns null if the term does not exist. Returns the term ID if no taxonomy is specified and the term ID exists. Returns an array of the term ID and the term taxonomy ID the taxonomy is specified and the pairing exists.

Despite this, under some conditions ($term===0) the method return int 0. The attached patch rectifies this to return null, and additionally updates the @return tag datatype from mixed to string|array|null for better IDE support.

[dotancohen]

Patch to resolve issue.

[pento]

This patch needs to be reviewed for side effects of changing the return value.

[johnbillion]

I traced this condition back to [5739]. It hasn't been changed since its introduction.

[johnbillion]

I've been poking around and this change doesn't seem to break anything. I suspect this can be treated as legacy code and the condition no longer gets triggered during post creation (both with the classic editor and the block editor).

Tentative +1 on the change but some more eyes would be good.

[johnbillion]

Clarification: This condition was originally introduced to prevent a category with the name 0 being inserted when a post is saved with no categories selected (presumably due to the <input type="hidden" name="post_category[]" value="0"> in the Categories meta box.

[jipmoors]

Looking at this during a contributor day for the "Core Testing" tasks to be picked up.
Test instructions are very unclear, suggest to remove the "needs testing" tag from this issue.

Looks to me that having unit-tests for this change would be a much better way of ensuring functionality.

[johnbillion]

I'm honestly not sure what to do with this change. It seems like something could unexpectedly break so I'm hesitant to change that return value. Let's just correct the docs instead.

[sathyapulse]

Adds documentation of the undocumented return 0.

[sathyapulse]

Adds detailed documentation of the return 0.

[donmhico]

As @johnbillion mentioned, I also think that making the return 0 clear in the docs is good enough. There are quite a number of core's unit tests that asserts to 0 and there might be 3rd party plugins that are operating with the return 0.

[johnbillion]

In 47205:

Taxonomy: Clarify the docs for the return values of the term_exists() function.

Props dotancohen, sathyapulse

Fixes #43345