in get_the_category_list(), filter categories before constructing list

[KevinB]

The template function get_the_category_list returns a concatenated string of category links for an individual post. The only filtering available is on the full concatenated sting, via 'the_category' hook.

Since filtering the category array directly is greatly preferable for most uses, please consider adding the attached patch, or something like it.

Whatever hook is added should somehow indicate the data context - in this case for display. In filtering post categories, there is the potential for non-display situations in which the actual post categories must be maintained even though the display filtering hides some from the current user. What we should not do is apply a single filter inside get_the_category or wp_get_object_terms, since themes and plugins may already call those functions for multiple data contexts.

I had considered calling the new hook 'get_the_category_for_list'. Instead I'm suggesting a more generic 'get_the_category' hook, passing context as the second argument. That would leave the API consistent for possible future use in filtering other contexts.

[KevinB]

direct filtering of the post categories array in get_the_category list

[filosofo]

Replying to KevinB:

I had considered calling the new hook 'get_the_category_for_list'. Instead I'm suggesting a more generic 'get_the_category' hook, passing context as the second argument. That would leave the API consistent for possible future use in filtering other contexts.

So wouldn't it make more sense to add the filter to get_the_category()'s return?

[KevinB]

Replying to filosofo:

Replying to KevinB:

I had considered calling the new hook 'get_the_category_for_list'. Instead I'm suggesting a more generic 'get_the_category' hook, passing context as the second argument. That would leave the API consistent for possible future use in filtering other contexts.

So wouldn't it make more sense to add the filter to get_the_category()'s return?

The problem I see is that get_the_category() does not know the context it's called in, whereas get_the_category_list() would always be a display context. Since get_the_category() returns an array, some themes or plugins would not be unreasonable in using it in a raw/db context - for a maintenance operation which pertains to all stored post categories regardless of the currently logged user. Is this a valid concern, or would you just assume that get_the_category() is always for display purposes and all backend operations use wp_get_object_terms()?

I want to filter post categories in a display context for the current user (who may be restricted by my plugin), so I need a hook which will prevent me from fibbing to someone about the actual post categories.

[Denis-de-Bernardy]

+1. would naming the hook get_the_category_list instead make more sense?

[Denis-de-Bernardy]

see also #8704 and #9719

[Denis-de-Bernardy]

#8704 got fixed, we can probably close this one as fixed too.

[kevinb]

The wp_get_object_terms filter added in #8704 is not, as the seasoned professionals say, a "robust" solution to the issue I raised here.

The wp_get_object_terms filter alone (and the term_cache which it loads) does not allow for any distinction between terms which an object has and terms which the current user can view.

[Denis-de-Bernardy]

punting per IRC discussion

[Denis-de-Bernardy]

patch still applies clean

[ericlewis]

In attachment:9227.2.diff​ I suggest using a new filter named the_category_list.

[wonderboymusic]

Please review the inline docs.

[DrewAPicture]

9227.2.diff​ looks OK except that the mixed type on the @param lines should be bool, not false. The description should be used to describe where false would be passed for each.

Edit: No "returns" here.

[ericlewis]

attachment:9227.3.diff​ fixes the types of the @params and gives a more verbose description to the $categories parameter.

[DrewAPicture]

@ericlewis Can fix aligning the 2nd+ lines with the beginning of the parameter description instead of the variable?

@param type $var This is a very long description that has the possibility
            of spanning multiple lines.

vs.

@param type $var This is a very long description that has the possibility
                 of spanning multiple lines.

Also, the $post_id param line needs a description.

[ericlewis]

attachment:9227.4.diff​ fixes alignment and gives $post_id a description.

[DrewAPicture]

9227.4.diff​ works for me.

[SergeyBiryukov]

1. In 9227.4.diff​, $categories should be an array rather than array|bool, because get_the_category()​ always returns an array. The docs need to be adjusted as well.
2. get_the_categories​ filter was added in [16332]. Is there a use case that cannot be achieved using that filter? You can conditionally apply it on front-end as needed. We don't pass the post ID there, perhaps we should do that instead of introducing a new filter.

[boonebgorges]

Replying to SergeyBiryukov:

1. In 9227.4.diff​, $categories should be an array rather than array|bool, because get_the_category()​ always returns an array. The docs need to be adjusted as well.
2. get_the_categories​ filter was added in [16332]. Is there a use case that cannot be achieved using that filter? You can conditionally apply it on front-end as needed. We don't pass the post ID there, perhaps we should do that instead of introducing a new filter.

get_the_category() is also used in get_permalink(). This is a very different context from using get_the_category() to get categories for display. So I'd say that it's worth having a separate filter, though passing the post ID to 'get_the_categories' is also a dynamite idea.

[boonebgorges]

In 34624:

Pass the post ID to the get_the_categories filter.

Props SergeyBiryukov.
See #9227.

[boonebgorges]

In 34625:

Introduce 'the_category_list' filter.

Used to filter categories as structured data, before building markup in
get_the_category_list().

We use this filter in addition to upstream filters (such as
'get_the_categories'`) because those upstream filters are used in numerous
contexts, while 'the_category_list' is always used for generating markup
for display.

Props KevinB, ericlewis, SergeyBiryukov, DrewAPicture.
Fixes #9227.