Related:

• Feature: Timber::get_terms() merge option #2211
• Ability to get terms from PostQuery #3211

Issue

When working on the PostQuery::terms() feature suggested by @cbirdsong , I ran into code code duplication between Post and PostQuery for splitting term results by taxonomy. Then I remembered the very old Feature request in #2211 and decided to give that a shot.

Solution

Moved the taxonomy splitting logic into TermFactory and exposed it through the existing but unused $options parameter in Timber::get_terms().

Changes:

1. TermFactory Enhancement - Added from_with_options() method to handle the merge option and partition_tax_queries() helper. I am not really a fan of this. Maybe @gchtr or @nlemoine can lend some eyes on this?
2. Timber API Update - Updated get_terms() to pass options through to TermFactory
3. Post Simplification - Removed partition_tax_queries() and delegated to Timber::get_terms()

Impact

• Centralizes term taxonomy splitting logic in one place (TermFactory)
• Makes the feature discoverable through Timber::get_terms() public API
• Maintains full backwards compatibility - existing code continues to work unchanged

(Backwards) Compatibility:
All existing Post::terms() and maybe future PostQuery::terms() calls work identically

Usage Changes

Users can now use the merge option directly with Timber::get_terms():

// Get terms grouped by taxonomy
$terms_by_tax = Timber::get_terms([
    'taxonomy' => ['category', 'post_tag'],
    'object_ids' => [123, 456],
], ['merge' => false]);

// Returns:
// [
//     'category' => [Term, Term, ...],
//     'post_tag' => [Term, Term, ...],
// ]

This was previously only available through Post::terms() and PostQuery::terms() methods, which continue to work as before:

// Still works exactly the same
$terms_by_tax = $post->terms(['category', 'post_tag'], ['merge' => false]);
$terms_by_tax = $posts->terms(['category', 'post_tag'], ['merge' => false]);

Considerations

Future enhancements:
The merge: false option name is functional but somewhat unintuitive (you set it to false to get grouping). Consider adding a group_by_taxonomy: true alias in the future for better developer experience

Testing

Unit tests included

Added two new tests in TermTest.php:

• testGetTermsGroupedByTaxonomy() - Verifies merge: false correctly groups terms by taxonomy
• testGetTermsMergedByDefault() - Verifies default merge: true behavior returns flat array