baxtian / wp_taxonomy

0.2.21 2026-10-07 18:14 UTC

Requires

• php: >=7.0

Requires (Dev)

• timber/timber: ^2.0

GPL-3.0-or-later

Published on Packagist.org on 2026-10-07 18:15 UTC

README

Base classes for registering WordPress taxonomies and managing term metadata.

Use in a Merak plugin

Require this package through Composer in the Merak plugin and make sure the Composer autoloader is loaded by the plugin. The package is already a dependency in baxtian/merak-tax.

composer require baxtian/wp_taxonomy

Create a taxonomy class under the plugin's src/Taxonomies/ directory. Configure its properties in the constructor, register its init() method on WordPress init, and call the parent constructor after configuring the class:

In the examples below, replace MyPlugin and MY_PLUGIN_D with the plugin's namespace and text-domain constant.

<?php
namespace MyPlugin\Taxonomies;

use Baxtian\WP_Taxonomy as Taxonomy;

class Genre extends Taxonomy
{
	use \Baxtian\SingletonTrait;

	protected function __construct()
	{
		$this->slug      = 'genre';
		$this->post_type = ['post', 'movie'];

		add_action('init', [$this, 'init']);
		parent::__construct();
	}

	public function init()
	{
		$labels = [
			'name'           => __('Genres', MY_PLUGIN_D),
			'singular_name'  => __('Genre', MY_PLUGIN_D),
			'all_items'      => __('All genres', MY_PLUGIN_D),
			'settings_field' => __('Genre base', MY_PLUGIN_D),
		];

		$this->args = [
			'hierarchical' => true,
			'labels'       => $labels,
			'show_ui'      => true,
			'show_in_rest' => true,
			'base_setting' => true,
			'rewrite'      => [
				'slug' => get_option('genre_base') ?: 'genre',
			],
		];

		parent::init();
	}
}

When base_setting is enabled, provide labels['settings_field']. Use a non-empty fallback for the rewrite slug because the saved option may be empty.

Add term fields

Extend Baxtian\WP_TermMeta to declare fields for one or more registered taxonomies. Each field's name is its term-meta key. Fields marked with column are shown in the term list; sortable can enable sorting for a field column.

<?php
namespace MyPlugin\Taxonomies\Fields;

use Baxtian\WP_TermMeta as TermMeta;

class GenreFields extends TermMeta
{
	use \Baxtian\SingletonTrait;

	protected function __construct()
	{
		$this->handle     = 'genre-fields';
		$this->taxonomies = ['genre'];

		add_action('init', [$this, 'init']);
		parent::__construct();
	}

	public function init()
	{
		$this->variables = [
			[
				'name'        => 'color',
				'type'        => 'color',
				'label'       => __('Color', MY_PLUGIN_D),
				'description' => false,
				'column'      => true,
				'sortable'    => false,
			],
			[
				'name'        => 'featured',
				'type'        => 'checkbox',
				'label'       => __('Featured', MY_PLUGIN_D),
				'description' => false,
				'column'      => true,
				'sortable'    => false,
			],
			[
				'name'   => 'formats',
				'type'   => 'options',
				'label'  => __('Formats', MY_PLUGIN_D),
				'column' => true,
				'options' => [
					['value' => 'book', 'label' => __('Book', MY_PLUGIN_D)],
					['value' => 'film', 'label' => __('Film', MY_PLUGIN_D)],
				],
			],
		];

		parent::init();
	}
}

Supported field types: checkbox, color, dropdown, file, image, number, options, text, textarea, url, and wysiwyg. For dropdown and options, define choices as an array of value/label pairs. The fields render on the classic add/edit term screens; they are not displayed in the Gutenberg interface. WP_TermMeta also registers the configured fields in the REST API and adds the configured columns to the term list.

Initialize the classes

Register the singleton instances from the plugin's src/Instances.php so their constructors attach the WordPress hooks:

MyPlugin\Taxonomies\Genre::get_instance();
MyPlugin\Taxonomies\Fields\GenreFields::get_instance();

Follow the plugin's existing Instances.php conventions and ensure the taxonomy instance is registered along with its field component.

Mantainers

Juan Sebastián Echeverry [e-mail]

Changelog

See CHANGELOG.md.