PHPackages                             arraypress/wp-register-taxonomy - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. arraypress/wp-register-taxonomy

ActiveLibrary[Utility & Helpers](/categories/utility)

arraypress/wp-register-taxonomy
===============================

Lightweight library for registering taxonomies in WordPress with smart defaults, automatic label generation, and support for custom objects beyond post types.

10PHP

Since Nov 30Pushed 5mo agoCompare

[ Source](https://github.com/arraypress/wp-register-taxonomy)[ Packagist](https://packagist.org/packages/arraypress/wp-register-taxonomy)[ RSS](/packages/arraypress-wp-register-taxonomy/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

WordPress Register Taxonomy
===========================

[](#wordpress-register-taxonomy)

A powerful, elegant library for registering taxonomies in WordPress with smart defaults, automatic label generation, and support for custom objects beyond post types.

Features
--------

[](#features)

- 🎯 **Simple API** - Register taxonomies with minimal configuration
- 🏷️ **Auto Labels** - Generates all labels from singular/plural forms
- 📊 **Hierarchical & Flat** - Smart label generation for both types
- 🔗 **Permalink Management** - Easy slug configuration with auto-flush
- 📦 **Custom Objects** - Attach taxonomies to custom database tables (not just post types!)
- 🎨 **Meta Box Options** - Radio buttons, checkboxes, or custom
- 💼 **Admin Column** - Easy admin column integration
- ✨ **Clean Code** - Modern PHP 7.4+, fully typed, well-documented

Installation
------------

[](#installation)

Install via Composer:

```
composer require arraypress/wp-register-taxonomy
```

Quick Start
-----------

[](#quick-start)

### Minimal Example

[](#minimal-example)

```
register_tax( 'product_brand', [
    'post_types' => [ 'product' ],
    'labels' => [
        'singular' => 'Brand',
        'plural'   => 'Brands'
    ]
] );
```

That's it! This creates a fully functional taxonomy with:

- ✅ All labels auto-generated
- ✅ Public and queryable
- ✅ REST API enabled
- ✅ Show in UI

### Full Example

[](#full-example)

```
register_tax( 'product_brand', [
    'post_types' => [ 'product', 'review' ],
    'labels' => [
        'singular' => 'Brand',
        'plural'   => 'Brands'
    ],
    'hierarchical'      => true,         // Like categories
    'show_admin_column' => true,         // Show column in admin
    'meta_box'          => 'radio',      // Radio button selection
    'permalink' => [
        'slug'       => 'brand',
        'with_front' => false
    ]
] );
```

Configuration Options
---------------------

[](#configuration-options)

### Labels

[](#labels)

The library automatically generates all taxonomy labels from just two inputs:

```
'labels' => [
    'singular' => 'Brand',
    'plural'   => 'Brands'  // Optional - auto-pluralized if not provided
]
```

**For hierarchical taxonomies (like categories):**

- Generates parent/child related labels

**For flat taxonomies (like tags):**

- Generates popular items, comma separation labels

You can override any generated label:

```
'labels' => [
    'singular'  => 'Brand',
    'plural'    => 'Brands',
    'all_items' => 'All My Brands'  // Override specific label
]
```

### Hierarchical vs Flat

[](#hierarchical-vs-flat)

**Hierarchical (like categories):**

```
'hierarchical' => true
```

- Parent/child relationships
- Checkbox meta box by default
- Tree-style admin interface

**Flat (like tags):**

```
'hierarchical' => false
```

- No parent/child relationships
- Tag-style input by default
- Flat admin interface

### Post Types

[](#post-types)

Attach to one or more post types:

```
// Single post type
'post_types' => [ 'product' ]

// Multiple post types
'post_types' => [ 'product', 'review', 'portfolio' ]
```

### Custom Objects (Killer Feature!)

[](#custom-objects-killer-feature)

Attach taxonomies to custom database tables or objects:

```
register_tax( 'project_status', [
    'objects' => [ 'my_custom_projects_table' ],  // Not a post type!
    'labels' => [
        'singular' => 'Status',
        'plural'   => 'Statuses'
    ],
    'show_ui' => true,
    'show_in_menu' => 'tools.php'  // Show under Tools menu
] );
```

This is perfect for:

- Custom database tables
- External data sources
- Non-post WordPress objects
- Third-party integrations

### Meta Box Types

[](#meta-box-types)

Control how the taxonomy appears in the post editor:

```
// Radio buttons (select one)
'meta_box' => 'radio'

// Simple (WordPress default based on hierarchical setting)
'meta_box' => 'simple'

// Custom callback
'meta_box' => 'my_custom_meta_box_function'

// Disable meta box
'meta_box' => false
```

**Radio button example:**

```
register_tax( 'product_status', [
    'post_types'   => [ 'product' ],
    'labels'       => [
        'singular' => 'Status',
        'plural'   => 'Statuses'
    ],
    'hierarchical' => false,
    'meta_box'     => 'radio'  // Radio buttons instead of checkboxes
] );
```

### Permalink Structure

[](#permalink-structure)

Configure custom URL structure:

```
'permalink' => [
    'slug'         => 'brand',          // Custom slug
    'with_front'   => false,            // Don't prepend site's base
    'hierarchical' => true              // /parent/child/ structure
]
```

**Examples:**

```
// Simple slug
'permalink' => [
    'slug' => 'brands'
]
// Result: yoursite.com/brands/nike/

// Nested structure
'permalink' => [
    'slug' => 'shop/brands'
]
// Result: yoursite.com/shop/brands/nike/

// Hierarchical with parent/child
'permalink' => [
    'slug'         => 'category',
    'hierarchical' => true
]
// Result: yoursite.com/category/parent/child/

// Disable rewrites entirely
'permalink' => [
    'disabled' => true
]
```

### Admin Column

[](#admin-column)

Show taxonomy in admin list table:

```
'show_admin_column' => true
```

### Common Options

[](#common-options)

All standard `register_taxonomy()` options are supported:

OptionTypeDefaultDescription`public``bool``true`Public facing taxonomy`hierarchical``bool``false`Parent/child relationships`show_ui``bool``true`Show in admin UI`show_in_rest``bool``true`Enable Gutenberg & REST API`show_admin_column``bool``false`Show column in list table`show_in_nav_menus``bool``true`Show in nav menu selector`show_tagcloud``bool``true`Show in tag cloud widgetReal-World Examples
-------------------

[](#real-world-examples)

### E-Commerce Product Taxonomies

[](#e-commerce-product-taxonomies)

```
// Hierarchical brand taxonomy
register_tax( 'product_brand', [
    'post_types' => [ 'product' ],
    'labels' => [
        'singular' => 'Brand',
        'plural'   => 'Brands'
    ],
    'hierarchical'      => true,
    'show_admin_column' => true,
    'permalink' => [
        'slug' => 'brand'
    ]
] );

// Product tags
register_tax( 'product_tag', [
    'post_types' => [ 'product' ],
    'labels' => [
        'singular' => 'Product Tag',
        'plural'   => 'Product Tags'
    ],
    'hierarchical' => false,
    'show_admin_column' => true
] );

// Product status with radio buttons
register_tax( 'product_status', [
    'post_types' => [ 'product' ],
    'labels' => [
        'singular' => 'Status',
        'plural'   => 'Statuses'
    ],
    'hierarchical' => false,
    'meta_box' => 'radio',
    'show_admin_column' => true
] );
```

### Portfolio Taxonomies

[](#portfolio-taxonomies)

```
// Portfolio categories
register_tax( 'portfolio_category', [
    'post_types' => [ 'portfolio' ],
    'labels' => [
        'singular' => 'Portfolio Category',
        'plural'   => 'Portfolio Categories'
    ],
    'hierarchical' => true,
    'show_admin_column' => true,
    'permalink' => [
        'slug'         => 'portfolio/category',
        'hierarchical' => true
    ]
] );

// Skills (shared across multiple post types)
register_tax( 'skill', [
    'post_types' => [ 'portfolio', 'team' ],
    'labels' => [
        'singular' => 'Skill',
        'plural'   => 'Skills'
    ],
    'hierarchical' => false,
    'show_admin_column' => true
] );
```

### Custom Object Taxonomy

[](#custom-object-taxonomy)

```
// Taxonomy for custom database table
register_tax( 'project_status', [
    'objects' => [ 'my_custom_projects' ],  // Custom object!
    'labels' => [
        'singular' => 'Project Status',
        'plural'   => 'Project Statuses'
    ],
    'hierarchical' => false,
    'show_ui' => true,
    'show_in_menu' => 'tools.php'
] );

// Then attach terms to your custom objects
wp_set_object_terms( $project_id, [ 'active', 'high-priority' ], 'project_status' );
```

### Simple Taxonomy with Auto-Plural

[](#simple-taxonomy-with-auto-plural)

```
register_tax( 'difficulty', [
    'post_types' => [ 'course' ],
    'labels' => [
        'singular' => 'Difficulty'
        // Plural will be auto-generated as 'Difficulties'
    ],
    'hierarchical' => true,
    'show_admin_column' => true
] );
```

### Internal Taxonomy (No Public URLs)

[](#internal-taxonomy-no-public-urls)

```
register_tax( 'internal_category', [
    'post_types' => [ 'product' ],
    'labels' => [
        'singular' => 'Internal Category',
        'plural'   => 'Internal Categories'
    ],
    'hierarchical' => true,
    'public'       => false,
    'show_ui'      => true,
    'permalink'    => [
        'disabled' => true
    ]
] );
```

Using with register\_cpt()
--------------------------

[](#using-with-register_cpt)

If you're using `wp-register-post-type`, you can register taxonomies and attach them:

```
// Register post type
register_cpt( 'product', [
    'labels' => [ 'singular' => 'Product' ],
    'icon'   => 'cart',
    'taxonomies' => [ 'product_brand', 'product_tag' ]  // Attach taxonomies
] );

// Register taxonomies
register_tax( 'product_brand', [
    'post_types' => [ 'product' ],
    'labels'     => [ 'singular' => 'Brand', 'plural' => 'Brands' ],
    'hierarchical' => true
] );

register_tax( 'product_tag', [
    'post_types' => [ 'product' ],
    'labels'     => [ 'singular' => 'Tag', 'plural' => 'Tags' ],
    'hierarchical' => false
] );
```

How It Works
------------

[](#how-it-works)

### Automatic Label Generation

[](#automatic-label-generation)

The library uses intelligent pluralization and generates different labels based on whether the taxonomy is hierarchical:

**Hierarchical (categories):**

- Includes parent/child labels
- "Parent Category:", etc.

**Flat (tags):**

- Includes popular items labels
- "Separate tags with commas", etc.

### Permalink Management

[](#permalink-management)

- Rewrites are automatically configured based on your `permalink` settings
- Rewrite rules are flushed on plugin activation (no manual flush needed)
- Supports hierarchical URL structures

### Custom Objects

[](#custom-objects)

The library extends WordPress's taxonomy system to work with any object type, not just post types. This is done by:

1. Accepting `objects` parameter instead of just `post_types`
2. Passing objects to `register_taxonomy()`
3. Allowing you to use `wp_set_object_terms()` with your custom objects

Function Reference
------------------

[](#function-reference)

### `register_tax( string $taxonomy, array $config )`

[](#register_tax-string-taxonomy-array-config-)

Register a custom taxonomy.

**Parameters:**

- `$taxonomy` (string) - Taxonomy slug (max 32 characters, lowercase)
- `$config` (array) - Configuration array

**Returns:** `Taxonomy` instance

Requirements
------------

[](#requirements)

- PHP 7.4 or higher
- WordPress 5.0 or higher

Best Practices
--------------

[](#best-practices)

1. **Keep slugs short** - Max 32 characters for taxonomy slug
2. **Use singular form for slug** - `product_brand` not `product_brands`
3. **Provide both singular and plural** - For best label generation
4. **Choose hierarchical carefully** - Can't change easily after data exists
5. **Test permalink structure** - Always test your URLs after registration

Troubleshooting
---------------

[](#troubleshooting)

### Permalinks not working?

[](#permalinks-not-working)

Try visiting **Settings → Permalinks** to manually flush rewrite rules.

### Taxonomy not showing in REST API?

[](#taxonomy-not-showing-in-rest-api)

Make sure `show_in_rest` is `true` (it is by default).

### Meta box not showing?

[](#meta-box-not-showing)

Check that `show_ui` is `true` and the taxonomy is registered for the correct post type.

Contributing
------------

[](#contributing)

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

License
-------

[](#license)

GPL-2.0-or-later

Credits
-------

[](#credits)

Developed by [ArrayPress](https://arraypress.com/)

Support
-------

[](#support)

- [Documentation](https://github.com/arraypress/wp-register-taxonomy)
- [Issue Tracker](https://github.com/arraypress/wp-register-taxonomy/issues)

###  Health Score

17

—

LowBetter than 6% of packages

Maintenance48

Moderate activity, may be stable

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity13

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/cd6eb8aff0903d87eb674d1ba3c5f3653899c0d7661504eb0deb7798ed86b643?d=identicon)[arraypress](/maintainers/arraypress)

---

Top Contributors

[![arraypress](https://avatars.githubusercontent.com/u/22668877?v=4)](https://github.com/arraypress "arraypress (2 commits)")

### Embed Badge

![Health badge](/badges/arraypress-wp-register-taxonomy/health.svg)

```
[![Health](https://phpackages.com/badges/arraypress-wp-register-taxonomy/health.svg)](https://phpackages.com/packages/arraypress-wp-register-taxonomy)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)