arraypress/wp-term-utils

A lean WordPress library for working with taxonomies and terms

dev-main 2025-07-03 19:09 UTC

Requires

• php: >=7.4

GPL-2.0-or-later

• David Sherlock

• search
• wordpress
• taxonomy
• options
• terms
• hierarchical
• wp
• term-meta
• arraypress

README

A lightweight WordPress library for working with taxonomies and terms. Provides clean APIs for term operations, search functionality, and value/label formatting perfect for forms and admin interfaces.

Features

• 🎯 Clean API: WordPress-style snake_case methods with consistent interfaces
• 🔍 Built-in Search: Term and taxonomy search with value/label formatting
• 📋 Form-Ready Options: Perfect value/label arrays for selects and forms
• 🌳 Hierarchical Support: Indented options for hierarchical taxonomies
• 🔗 Object Relations: Easy term assignment and management for posts/objects
• 📊 Meta Operations: Simple term meta handling with type safety
• 🎨 Flexible Identifiers: Use IDs, slugs, names, or objects interchangeably

Requirements

• PHP 7.4 or later
• WordPress 5.0 or later

Installation

composer require arraypress/wp-term-utils

Basic Usage

Working with Single Terms

use ArrayPress\TermUtils\Term;

// Get term by ID
$term = Term::get( 123, 'category' );

// Get term by identifier (ID, slug, or name)
$term = Term::get_by_identifier( 'tech-news', 'category' );

// Check if term exists
if ( Term::exists( 123, 'category' ) ) {
	// Term exists
}

// Get term meta
$featured = Term::get_meta( 123, 'featured' );

// Get term children
$children = Term::get_children( 123, 'category' );

// Check if term has posts
if ( Term::has_posts( 'tech-news', 'category' ) ) {
	// Term has posts
}

// Get hierarchical path
$path = Term::get_path( 123, 'category' ); // "Parent > Child > Term"

Working with Multiple Terms

use ArrayPress\TermUtils\Terms;

// Get multiple terms
$terms = Terms::get( [ 1, 2, 3 ], 'category' );

// Get terms by identifiers
$term_ids = Terms::get_by_identifiers( [ 'tech', 'news', 'sports' ], 'category' );

// Get term names
$names = Terms::get_names( [ 1, 2, 3 ], 'category' );

// Get terms for a post
$post_terms = Terms::get_for_object( 123, 'category' );

// Set terms for a post
Terms::set_for_object( 123, 'category', [ 'tech', 'news' ] );

// Add single term to post
Terms::add_term( 123, 'category', 'breaking-news' );

// Search terms and get options
$options = Terms::search_options( 'tech', 'category' );
// Returns: [['value' => 1, 'label' => 'Technology'], ...]

// Get all terms as options
$all_options = Terms::get_options( 'category' );
// Returns: [1 => 'Technology', 2 => 'News', ...]

// Get hierarchical options (with indentation)
$hierarchical = Terms::get_options( 'category', [], true );
// Returns: [1 => 'Parent', 2 => '— Child', 3 => '—— Grandchild']

Working with Taxonomies

use ArrayPress\TermUtils\Taxonomy;

// Check if taxonomy exists
if ( Taxonomy::exists( 'product_category' ) ) {
	// Taxonomy exists
}

// Get taxonomy post types
$post_types = Taxonomy::get_post_types( 'category' );

// Get all public taxonomies
$public = Taxonomy::get_public();

// Get taxonomies for post type
$taxonomies = Taxonomy::get_for_post_type( 'product' );

// Get taxonomies as options
$tax_options = Taxonomy::get_options();
// Returns: ['category' => 'Categories', 'post_tag' => 'Tags']

// Search taxonomies
$search_results = Taxonomy::search_options( 'product' );
// Returns: [['value' => 'product_cat', 'label' => 'Product Categories']]

Utility Methods

// Get unused terms
$unused = Terms::get_unused( 'category' );

// Get most used terms
$popular = Terms::get_most_used( 'category', 5 );

// Sanitize term identifiers
$clean_ids = Terms::sanitize( [ '1', 'invalid', '3' ], 'category' );

Key Features

• Value/Label Format: Perfect for forms and selects
• Hierarchical Support: Indented options for hierarchical taxonomies
• Search Functionality: Built-in term and taxonomy search
• Object Relations: Easy term assignment to posts/objects
• Meta Operations: Simple term meta handling
• Flexible Identifiers: Use IDs, slugs, names, or objects interchangeably

Requirements

• PHP 7.4+
• WordPress 5.0+

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the GPL-2.0-or-later License.

Support

• Documentation
• Issue Tracker