Custom Post Types and Taxonomies

A post type is a kind of content: it decides which editing screen is used, which fields the editor shows, who may edit it, which URLs it answers to and whether it appears in the REST API. A taxonomy is a way of grouping content with terms: categories and tags are the two built-in ones for posts. Terms live in wp_terms, wp_term_taxonomy and wp_term_relationships; Database Schema shows the tables.

WordPress 7.1.3 itself registers 16 post types (besides posts and pages: attachment, revision, nav_menu_item, wp_block, wp_template, wp_template_part, wp_global_styles, wp_navigation, wp_font_family, wp_font_face, custom_css, customize_changeset, oembed_cache, user_request) and 7 taxonomies (category, post_tag, nav_menu, post_format, wp_theme, wp_template_part_area, wp_pattern_category); plugin keys must not collide.

Post types and taxonomies are plugin territory. A theme that registers them takes the content away when the site changes theme: the books would still be in the database but would have no screens, no URLs and no REST endpoint. The theme only provides templates for them.

The catalogue consists of the post type lp_book (archive at /books/, books at /books/<slug>/), the public status lp_out_of_print for titles no longer sold, the hierarchical taxonomy lp_genre (Fiction > Crime fiction, at /books/genre/<path>/) and the flat taxonomy lp_series (at /books/series/<slug>/), with capabilities of their own (edit_lp_books, publish_lp_books, …​, manage_lp_terms) for the Catalogue Manager role. The meta fields lp_isbn, lp_pages and lp_published_on are registered on Metadata and Custom Fields. The code extends the skeleton of Plugin Fundamentals (Composer autoloading of Lumen\Catalog, hooks added in Plugin::boot(), activation in Installer): this page fills in src/PostTypes.php and adds src/Taxonomies.php.

With the default 'capability_type' => 'post', anyone who may edit posts may edit books. Lumen Press needs book permissions of their own for its Catalogue Manager role, so the type passes a singular and plural base, array( 'lp_book', 'lp_books' ), and WordPress generates the capability names:

Source: Code Reference: get_post_type_capabilities()

Two kinds of capability appear. Meta capabilities (edit_lp_book, read_lp_book, delete_lp_book) are about one book and are never granted to a role. current_user_can( 'edit_post', $book_id ) asks for one, and map_meta_cap() translates it into the primitive capabilities the situation requires (the author, the status, whether the book is published). Primitive capabilities (edit_lp_books, edit_others_lp_books, publish_lp_books, …​) are what roles hold.

'map_meta_cap' => true turns that translation on for the new names. Without it, a custom capability_type leaves edit_lp_book unmapped, so only a user given edit_lp_book itself (which then covers every book) can edit anything. For the published book 5, owned by maria.editor, map_meta_cap( 'edit_post', 3, 5 ) returns edit_others_lp_books and edit_published_lp_books for tom.author, while for the owner it returns only edit_published_lp_books.

No role has the new capabilities until something grants them, and that includes administrators: right after activation, the Catalogue menu would be missing for everyone. Capabilities are stored in the wp_user_roles option (lp_user_roles with this site’s table prefix), so they are granted once, on activation, not on every request. Installer::activate() gives Administrators and Editors the full set:

Source: Plugin Handbook: Roles and Capabilities

wp cap list editor | grep lp_ then lists ten primitive capabilities plus manage_lp_terms. The Catalogue Manager role and uninstall clean-up are on Roles and Capabilities API. WPCS 3.4.1 warns about custom names in current_user_can() until they are listed in its custom_capabilities property.

template is the list of blocks a new book starts with: each entry is a block name, its attributes and, optionally, inner blocks. The lp_book template opens the editor with a blurb paragraph, an "About the author" heading and a biography paragraph, both paragraphs showing their placeholders. template_lock decides what the author may change:

Lumen Press uses 'insert': catalogue entries stay uniform, and authors can still reorder the sections. Cover, ISBN and page count are not blocks of the template; they are the featured image and meta fields, which keeps them out of the content and available to the REST API and the theme’s blocks. The template only applies to items created after it was set; existing books keep their content. wp-admin/edit-form-blocks.php passes template and templateLock to the editor settings only when the type has a template.

A block’s own templateLock attribute changes the lock for its children (see Attributes, Supports and InnerBlocks).

Core statuses are publish, future, draft, pending, private, trash, auto-draft and inherit. register_post_status() adds one. Lumen Press marks books it no longer sells as Out of print: the page stays online, but the list screen can filter them. The arguments, as registered in PostTypes::register() above:

What a custom status does and does not do, checked on 7.1.3:

Pretty permalinks work by matching the requested path against an ordered list of regular expressions, the rewrite rules, stored in the rewrite_rules option. Registering a post type or taxonomy adds its rules to the in-memory list, but the stored list is rebuilt only when the rules are flushed: by flush_rewrite_rules(), by saving Settings > Permalinks, or by wp rewrite flush. Until then, new URLs return 404 and changed slugs keep the old ones. On the test site, changing the book slug to catalogue with the register_post_type_args filter left /catalogue/the-lantern-keeper/ at 404 and the old URL at 200; after wp rewrite flush the new URL answered 200 and the old one redirected to it with a 301.

Flushing is expensive (it regenerates every rule and writes an option, and a hard flush rewrites .htaccess), so it runs only on activation and deactivation, never on init or another per-request hook. On activation the plugin has not yet run its init callbacks, so Installer::activate() registers the types itself before flushing; on deactivation it unregisters them first, so their URLs stop answering:

Source: Plugin Handbook: Activation / Deactivation Hooks

flush_rewrite_rules( false ) is a soft flush: it updates the option without touching .htaccess, which the plugin does not need. After deactivation /books/ and /books/genre/fiction/ return 404; after reactivation both return 200 again. A plugin updated in place (not reactivated) that changes a slug calls flush_rewrite_rules() once from its versioned upgrade routine (see Plugin Fundamentals).

Registration order matters when slugs nest. Each post type adds an attachment rule, books/[^/]+/([^/]+)/?$, that matches any two segments after books/. Registered after the post type, the genre rules come too late and /books/genre/fiction/ is read as an attachment called "fiction":

Source: WP-CLI: wp rewrite list

In that order /books/genre/fiction/ and /books/series/harbour-lights/ return 404, while /books/genre/fiction/crime/ (three segments) still works, which makes the bug easy to miss. Registering the taxonomies first, as Plugin::boot() does, puts books/genre/(.+?)/?$ at the top. The Rewrite API and custom rules are covered on Rewrite API and Permalinks.

Registering lp_book adds slots to the template hierarchy that a theme can fill; nothing in the plugin has to render HTML. In a block theme the files are HTML templates in templates/; in a classic theme, PHP files:

The lumen theme ships archive-lp_book.html and single-lp_book.html (see Templates and Template Parts), and the plugin can provide a fallback for themes that do not with register_block_template() (6.7+), shown on the same page. The full lookup order is on Template Hierarchy.

A custom post type is queried like any other, with WP_Query and 'post_type' => 'lp_book'. A tax_query on lp_genre with the slug fiction also returns "Crime fiction" books, because include_children defaults to true. A custom type does not appear on the blog home page, which shows posts only; a pre_get_posts callback that checks is_main_query() and is_home() and sets 'post_type' => array( 'post', 'lp_book' ) adds books there (on the test site the home page then listed both books and "Hello world!"). Query patterns are on WP_Query and the Database API.

After activation, WP-CLI, the REST API and plain HTTP requests confirm each part. The taxonomies:

Source: WP-CLI: wp taxonomy list

The test content is a genre "Fiction" (term 3) with the child "Crime fiction" (term 4, slug crime), a series "Harbour Lights" (term 5), created with wp term create, and the published book "The Lantern Keeper" (post 5), tagged with wp post term set.

The REST API describes the type and serves the books and terms anonymously:

Source: REST API Handbook: Adding REST API Support For Custom Content Types

Each term array in a book holds term IDs; ?_embed or a second request resolves them. The permalinks:

Source: Plugin Handbook: Working with Custom Post Types

The genre pages render with the term as their title ("Fiction – Lumen Press", "Crime fiction – Lumen Press").