WordPress Custom Post Types and Taxonomies: Developer Guide

When to Use Custom Post Types

Custom Post Types (CPTs) are content types beyond the default Posts and Pages. Use them when you have structured, repeatable content: a Portfolio site needs Portfolio CPT, a law firm needs Case Studies CPT, a restaurant needs a Menu CPT. CPTs give content a dedicated admin menu, their own permalink structure, and allow category-like taxonomies specific to that content type.

Registering a Custom Post Type

Register CPTs with register_post_type() inside an init action hook in your theme's functions.php or a plugin. Set the key arguments: labels (what admins see), public (true to show in admin), has_archive (true for a listing page), supports (title, editor, thumbnail, custom-fields), rewrite (the URL slug), and show_in_rest (true to enable Gutenberg editor and REST API support).

Registering Custom Taxonomies

Custom taxonomies work like categories and tags but are attached to your CPT. Use register_taxonomy() with the taxonomy name, associated post type, and labels. Set hierarchical: true for a category-like taxonomy (parent-child structure) or hierarchical: false for a tag-like taxonomy (flat list). Register taxonomies before post types and include them in the CPT's taxonomies argument.

Template Hierarchy for CPTs

WordPress uses a template hierarchy for CPT templates. For a single post of your CPT: single-{post-type}.php, then single.php. For the archive listing: archive-{post-type}.php, then archive.php. Create these template files in your child theme to customize the layout for your CPT specifically. Use get_template_part() to share common components like post headers across templates.

Querying CPTs with WP_Query

Query custom post types with WP_Query: new WP_Query(['post_type' => 'portfolio', 'tax_query' => [['taxonomy' => 'portfolio-category', 'field' => 'slug', 'terms' => 'web-design']]]). Use posts_per_page to control pagination, orderby and order for sorting, and meta_query to filter by ACF custom field values. Always reset post data after a custom query with wp_reset_postdata().

CPTs Without Plugins: Why Use PHP?

Plugins like Custom Post Type UI generate CPT registration code, which is convenient for non-developers. However, CPT registration belongs in your theme or a site-specific plugin — not a standalone plugin that could be deactivated accidentally, breaking your content type registration and making all CPT content inaccessible. Write the PHP code directly or use CPT UI to generate the code and paste it into your functions.php.