Make WordPress Core

Opened 10 years ago

Closed 9 years ago

#27764 closed enhancement (wontfix)

Allow the_terms() and get_the_terms() to accept an array of taxonomies

Reported by: ramiy's profile ramiy Owned by:
Milestone: Priority: normal
Severity: normal Version: 3.8.2
Component: Taxonomy Keywords: needs-patch needs-unit-tests
Focuses: Cc:


The the_terms() can accept array of taxonomies (several taxonomies) but the phpDocs say it can accept only a string (one taxonomy). This wrong documentation could save me a lot of time.

I fix the documentation in the code for other developers. See the attached file. After the ticket will be accepted, i will fix the Codex.

Attachments (1)

category-template.php.patch (1.8 KB) - added by ramiy 10 years ago.

Download all attachments as: .zip

Change History (12)

#1 @DrewAPicture
10 years ago

  • Keywords dev-feedback added

After taking a closer look at this, I think the only way the_terms() is able to accept an array is by the cache get failing in get_object_term_cache(), thereby passing the array of taxonomies to wp_get_object_terms() in get_the_terms() instead.

Seems like rather than continuing to allow an array to be passed in the_terms() we should explicitly check for a string in get_the_terms().

This ticket was mentioned in IRC in #wordpress-dev by DrewAPicture. View the logs.

10 years ago

#3 @SergeyBiryukov
10 years ago

  • Keywords close added

Passing an array of taxonomies to the_terms() leads to some issues:

  1. It causes array to string conversion for term_links-$taxonomy filter, making it 'term_links-Array'.
  2. It causes the same conversion in get_object_term_cache() and get_the_terms(), resulting in 'Array_relationships' cache key.
  3. It breaks anyone's code using the_terms or get_the_terms filters and only expecting a string in $taxonomy argument.

So, the documentation is correct, string is the only valid option currently here.

#4 follow-up: @ramiy
10 years ago

Hi guys, thanks for the clarification.

Do you think we need to change the ticket target, from documentation to bug fix?
To solve all the array issues in the_terms() and all other functions?

#5 in reply to: ↑ 4 @SergeyBiryukov
10 years ago

Replying to ramiy:

Do you think we need to change the ticket target, from documentation to bug fix?

It would be an enhancement (allow the_terms() and get_the_terms() to accept an array as $taxonomy argument), since it currently works as intended with a string argument.

Last edited 10 years ago by SergeyBiryukov (previous) (diff)

#6 @wonderboymusic
10 years ago

  • Keywords needs-patch needs-unit-tests added; dev-feedback close removed
  • Milestone changed from Awaiting Review to Future Release
  • Type changed from defect (bug) to enhancement

This can stay alive but will need someone to champion it with some .diff files

#7 @DrewAPicture
10 years ago

  • Focuses docs removed
  • Summary changed from the_terms() - update phpDocs and add "array" to $taxonomy parameter to Allow the_terms() and get_the_terms() to accept an array of taxonomies

#8 @wonderboymusic
10 years ago

Should be tackled along with: #26234

#9 @philbuchanan
10 years ago

Just a quick note, unlike the_terms(), the get_the_terms() documentation currently says that it accepts an array for the taxonomy parameter. Can that be updated until the function is patched to accept arrays?

#10 @sem101
10 years ago

Hi guys, is this a bug? I just found this ticket after posting to the forums...

Thanks for any update.

#11 @wonderboymusic
9 years ago

  • Milestone Future Release deleted
  • Resolution set to wontfix
  • Status changed from new to closed

The docs for the_terms() and - get_the_term_list(), get_the_terms(), and get_object_term_cache() (which are written in the context of only one taxonomy) - all take string as the value of $taxonomy.

This would result in some bizarre churn in those funcs, just so they can pass an array to wp_get_object_terms() down the chain - I vote no

Note: See TracTickets for help on using tickets.