Ticket: #1802

Issue

It’s not yet possible to change the query parameters that are used for getting a post’s terms when using $post->terms().

Solution

This pull request adds support for more advanced arguments for $post->terms():

$terms = $post->terms( array(
    'query' => array(
        'taxonomy' => 'custom_tax',
        'orderby'  => 'count',
    ),
    'merge'      => false,
    'term_class' => 'My_Term_Class'
) );

The new style only accepts one argument: An array of arguments. An arguments array allows you to only pass the parameters that you want to change. You don’t have to provide a value for all the parameters.

The old $merge and $TermClass parameters are being deprecated and only left there for backwards compatibility.

It got a little more complicated than I thought. If we allow query parameters for getting the terms, then the merge parameter makes it trickier. Consider the query parameter for order. If that is set, we can’t get the terms for each taxonomy separately (as it’s done now), because when they are merged after that loop, the order wouldn’t be right.

I had to rewrite the function so that in the end wp_get_post_terms() is only called once instead of being called once for all the taxonomies that are requested. This has an additional benefit that only one query has to be performed. Yay, better performance! 🙌

For brevity in Twig, I think we should keep the possibility to chose a taxonomy by name only. I mean that it would be easier to write this

{{ post.terms('category')|join(', ') }}

instead of writing this:

{{ post.terms({
    query: {
        taxonomy: 'category',
    }
})|join(', ') }}

Anything that requires more parameters should probably be written in PHP and then passed to Twig.

Impact

Using query parameters becomes available. There’s no impact for backwards compatibility.

Considerations

The old parameters can be removed in version 2.x. I’ll add a separate pull request for this, once this is merged in.

Currently, it’s possible to

• use tag or tags instead of post_tag
• use categories instead of category

I would remove these checks. I think they are too forgiving. They might help, but they might also confuse: When you read {% for post.terms('tag') %}, you might first think that there’s a custom taxonomy named tag instead of post_tag. Also, what happens if there really is a custom taxonomy named tag?

I added some @todo tags for removing these in 2.x.

Testing

I added a couple of tests:

• Duplicated existing tests for testing the new arguments array
• Added tests for merge argument
• Added tests for query arguments