Working with Taxonomies in Wikit

Overview

Wikit provides a Taxonomy class for registering custom taxonomies with WordPress. Taxonomies can be associated with any post type and support hierarchical or tag-like structures.

Basic Implementation

Simple Taxonomy

use WDG\Core\Taxonomy;

// Register a taxonomy for products
new Taxonomy( 'product_category', ['product'], [
    'labels' => [
        'name'          => 'Product Categories',
        'singular_name' => 'Product Category',
    ],
    'hierarchical' => true,
    'show_in_rest' => true,
]);

Within a PostType Class

Most commonly, taxonomies are registered within the init() method of a PostType:

class Products extends PostType {
    
    protected $post_type = 'product';
    
    public function init() {
        parent::init();
        
        // Register primary taxonomy
        new Taxonomy( 'product_category', [ $this->post_type ], [
            'hierarchical' => true,
        ]);
        
        // Register additional taxonomy
        new Taxonomy( 'product_tag', [ $this->post_type ], [
            'hierarchical' => false,
        ]);
    }
}

PostTypeTerm - Cross-Referencing Posts

The PostTypeTerm class creates a special taxonomy that allows cross-referencing between post types:

use WDG\Core\PostTypeTerm;

// In your PostType's init() method
$this->post_type_term = new PostTypeTerm(
    'product',              // The post type being referenced
    'related_products',     // The taxonomy name
    ['post', 'page'],      // Post types that can reference products
    [
        'labels' => [
            'name'          => 'Related Products',
            'singular_name' => 'Related Product',
        ],
        'hierarchical' => false,
        'block_editor_control' => 'checkbox', // or 'radio', 'select'
    ]
);

This creates a taxonomy that:

• Shows up in the block editor for posts and pages
• Allows selecting products as related items
• Provides a clean UI for cross-referencing content

Real-World Examples

People Taxonomy (from wikit-app)

class People extends PostType {
    
    protected $post_type = 'people';
    protected $taxonomy = 'people_tax';
    
    public function init() {
        parent::init();
        
        // Allow other post types to reference people
        $this->post_type_term = new PostTypeTerm(
            $this->post_type,
            $this->taxonomy,
            ['post', 'resource', 'event', 'page'],
            [
                'labels' => [
                    'name'          => 'People',
                    'singular_name' => 'Person',
                ],
                'hierarchical' => false,
                'block_editor_control' => 'checkbox',
            ]
        );
        
        // Add a separate taxonomy for people types
        new Taxonomy( 'people_type', [ $this->post_type ] );
    }
}

Advanced Features

Custom Capabilities

new Taxonomy( 'product_brand', ['product'], [
    'capabilities' => [
        'manage_terms' => 'manage_product_brands',
        'edit_terms'   => 'edit_product_brands',
        'delete_terms' => 'delete_product_brands',
        'assign_terms' => 'assign_product_brands',
    ],
]);

Custom Rewrite Rules

new Taxonomy( 'product_category', ['product'], [
    'rewrite' => [
        'slug' => 'shop/category',
        'with_front' => false,
        'hierarchical' => true,
    ],
]);

REST API Configuration

new Taxonomy( 'product_tag', ['product'], [
    'show_in_rest' => true,
    'rest_base' => 'product-tags',
    'rest_controller_class' => 'WP_REST_Terms_Controller',
]);

Project-Specific Taxonomies

Projects can add their own taxonomies by:

1. Creating them in the project repository:

// In /projects/{project}/repositories/{repo}/src/Taxonomy/ClientCategory.php
namespace ClientProject\Taxonomy;

use WDG\Core\Taxonomy;

class ClientCategory {
    public function __construct() {
        new Taxonomy( 'client_category', ['post', 'page'], [
            'labels' => [
                'name' => 'Client Categories',
            ],
            'hierarchical' => true,
        ]);
    }
}

2. Or extending existing post types:

// In project's functions.php
add_action('init', function() {
    register_taxonomy('project_specific_tax', ['product'], [
        'label' => 'Project Specific',
        'show_in_rest' => true,
    ]);
});

Best Practices

1. Use PostTypeTerm for Relationships: When creating relationships between post types
2. Enable REST API: Add 'show_in_rest' => true for Gutenberg support
3. Set Hierarchical Appropriately: Use true for categories, false for tags
4. Label Consistently: Follow WordPress labeling patterns
5. Consider Rewrite Rules: Plan URL structure early

Common Patterns

Multi-Post Type Taxonomy

// Shared across multiple post types
new Taxonomy( 'content_type', ['post', 'page', 'product', 'resource'] );

Private Taxonomy

new Taxonomy( 'internal_category', ['post'], [
    'public' => false,
    'show_ui' => true,
    'show_in_menu' => true,
]);

Filter-Only Taxonomy

new Taxonomy( 'filter_option', ['product'], [
    'public' => true,
    'show_ui' => true,
    'show_in_nav_menus' => false,
    'show_tagcloud' => false,
    'show_admin_column' => true,
]);