baxtian / wp_taxonomy

0.2.23 2026-11-13 17:06 UTC

Requires

• php: >=7.0

Requires (Dev)

• timber/timber: ^2.0

GPL-3.0-or-later

Published on Packagist.org on 2026-11-13 17:06 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. The REST value is the stored one (a checkbox reads '1' or ''); writing converts it to what the form stores, and a value that does not fit the field type answers 400.

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.