WordPress Custom Post Type — CPT Registration PHP Boilerplate

register_post_type() is WordPress’s API for creating content types beyond posts and pages. It accepts two arguments: the post type slug (a lowercase string, max 20 characters, no spaces — "project") and an associative array of arguments. WordPress stores the configuration in the global $wp_post_types object and generates admin menu items, URL rewrite rules, and database capabilities based on these args. The function must be called on or after the init hook — calling it earlier means WordPress’s internal structures aren’t ready. The minimal viable args are public => true (makes it visible in admin and front-end), has_archive => true (generates an archive page), and labels => [ 'name' => '...', 'singular_name' => '...' ] (provides human-readable text). Everything else falls back to WordPress defaults.

The labels array uses __() for i18n — each string is a translation key. When WordPress renders the admin interface, it calls get_post_type_labels() which merges your labels with a default set. If you omit add_new_item, WordPress falls back to “Add New Post” — generic and unhelpful. The text domain ('textdomain') should match your theme or plugin slug so translation files are discoverable. A complete labels array covers five contexts: admin menu (name, menu_name), editor screen (add_new_item, edit_item, new_item, view_item), list table (all_items, search_items), empty states (not_found, not_found_in_trash), and front-end (archives). Each context has its own translation string because languages handle these phrases differently — German uses different cases for menu items vs. editor headings.

Rewrite rules translate pretty permalinks into query variables. When you set rewrite => [ 'slug' => 'projects' ], WordPress generates internal rules that map /projects/ to index.php?post_type=project and /projects/sample-project/ to the single post query. These rules are stored in the rewrite_rules option in the database — they are not dynamic. Changing a slug requires flushing the rules: go to Settings → Permalinks and click Save (this calls flush_rewrite_rules()). On production, call this once. Never call flush_rewrite_rules() on every page load — it rebuilds the entire rewrite array from scratch, which is an expensive database operation (reads all registered post types, all taxonomies, and all custom rewrite structures, then writes a large serialized array to the options table).

show_in_rest => true enables the WordPress REST API for this post type, which is required for the Gutenberg block editor. Behind the scenes, WordPress registers REST routes at /wp-json/wp/v2/project and /wp-json/wp/v2/project/{id} with standard CRUD endpoints. The block editor uses these routes to load and save post data. If you set show_in_rest => false, the classic editor loads instead. The template argument pre-fills the block editor with a default layout — pass an array of block definitions (each is [ 'namespace/block-name', [ 'attribute' => 'value' ] ]) and new posts start with that structure. Users can modify or delete the template blocks; this is a starting point, not a locked layout (for locked layouts, use template_lock).

Filter hooks are the child-theme safety net. Every apply_filters() call in the production boilerplate creates an extension point. A child theme’s functions.php can modify any of the four configurable arrays with a single add_filter() line. This matters for theme shops and agencies: the parent theme ships with sensible defaults, and each client’s child theme overrides only what’s different — the slug for one client, the icon for another. The parent theme can be updated (bug fixes, new features) without overwriting client customizations because the customizations live in filters, not in edited copies of the parent theme’s files. This is the same pattern WordPress core uses: register defaults, expose filters, let downstream code modify.

Place the file and require it. Copy the Step 5 code into inc/cpt-project.php. In your theme’s functions.php, add this line near the top — above any template-specific includes but after the theme setup function:

require_once get_template_directory() . '/inc/cpt-project.php';

If you’re using a child theme, require from the child theme’s functions.php — the filter hooks in the boilerplate let you customize without touching the parent file. For multiple post types, create one file per post type (cpt-testimonial.php, cpt-faq.php) and require each. This keeps the registration for each post type isolated and easier to debug.

Flush permalinks. After adding the require line, visit Settings → Permalinks in the WordPress admin and click “Save Changes”. You don’t need to change any settings — the save action triggers flush_rewrite_rules() internally, which rebuilds the URL routing table. Without this step, /projects/ returns a 404 because WordPress doesn’t know the rewrite rule for your new post type yet. If you deploy via version control, add a one-time flush to your deploy script — or use a plugin activation hook if you’re shipping this as part of a plugin.

Test the archive page. Navigate to yoursite.com/projects/ (or whatever slug you set). You should see an archive page — likely empty if you haven’t created any projects yet. WordPress uses archive.php or index.php as the fallback template. For a custom archive design, create archive-project.php in your theme root — WordPress’s template hierarchy will automatically load it for this post type. Test with at least one published project post to verify the loop displays content correctly.

Test the single page. Create a new project (Projects → Add New), publish it, and view it on the front-end at /projects/your-project-slug/. WordPress uses single.php or singular.php as the fallback. For a custom single template, create single-project.php. Verify that the title, content, featured image, and any custom fields render correctly. Check the admin list table (Projects → All Projects) — the columns should show the title and date, and the “Add New” button at the top should read “Add New Project” (the label from Step 2).

Add custom admin columns. The default list table shows title and date — not useful for a Project post type that has a client name or status field. Use the manage_{$post_type}_posts_columns filter to add columns and manage_{$post_type}_posts_custom_column to populate them:

add_filter( 'manage_project_posts_columns', function( $cols ) {n    $cols['client']  = __( 'Client', 'theme' );n    $cols['status']  = __( 'Status', 'theme' );n    return $cols;n} );nnadd_action( 'manage_project_posts_custom_column', function( $col, $id ) {n    if ( 'client' === $col ) echo esc_html( get_field( 'client_name', $id ) );n    if ( 'status' === $col ) echo esc_html( get_field( 'project_status', $id ) );n}, 10, 2 );

These hooks fire only for the project list table — you can add different columns for each post type. The $id parameter is the post ID, so you can pull any post meta, taxonomy terms, or computed values. For sortable columns, add a third hook (manage_edit-project_sortable_columns) that maps your column to an orderby value.

Add taxonomy support. A Project post type often needs categories (project type, industry) and tags (technology, client). Register a custom taxonomy and attach it to your post type:

function theme_register_project_taxonomies() {n    register_taxonomy( 'project_type', 'project', [n        'labels'            => [n            'name'          => __( 'Project Types', 'theme' ),n            'singular_name' => __( 'Project Type', 'theme' ),n        ],n        'hierarchical'      => true,  // Category-like (checkboxes).n        'show_in_rest'      => true,  // Enable in block editor sidebar.n        'rewrite'           => [ 'slug' => 'project-type' ],n    ] );n}nadd_action( 'init', 'theme_register_project_taxonomies' );

hierarchical => true makes it category-like with parent/child relationships. Set to false for flat, tag-like taxonomies. show_in_rest => true puts the taxonomy panel in the block editor sidebar under the “Post” tab. Register the taxonomy on init (same hook as the post type) — order doesn’t matter because both are registered before WordPress processes any request. For a post type that needs both categories and tags, you can also pass 'taxonomies' => [ 'category', 'post_tag' ] inside the register_post_type() args to reuse built-in taxonomies.

Register multiple post types from a single config array. If your theme registers Projects, Testimonials, and FAQs, convert the boilerplate into a loop-driven factory that reads from a configuration array:

function theme_register_all_cpts() {n    $types = apply_filters( 'theme_cpt_config', [n        [n            'slug'    => 'project',n            'rewrite' => 'projects',n            'icon'    => 'dashicons-portfolio',n            'singular' => 'Project', 'plural' => 'Projects',n        ],n        [n            'slug'    => 'testimonial',n            'rewrite' => 'testimonials',n            'icon'    => 'dashicons-format-quote',n            'singular' => 'Testimonial', 'plural' => 'Testimonials',n        ],n    ] );n    foreach ( $types as $cpt ) {n        $labels = [n            'name'          => $cpt['plural'],n            'singular_name' => $cpt['singular'],n            'add_new_item'  => sprintf( __( 'Add New %s', 'theme' ), $cpt['singular'] ),n            'edit_item'     => sprintf( __( 'Edit %s', 'theme' ), $cpt['singular'] ),n            'all_items'     => sprintf( __( 'All %s', 'theme' ), $cpt['plural'] ),n        ];n        register_post_type( $cpt['slug'], [n            'labels'      => $labels,n            'public'      => true,n            'has_archive' => true,n            'menu_icon'   => $cpt['icon'],n            'rewrite'     => [ 'slug' => $cpt['rewrite'] ],n            'supports'    => [ 'title', 'editor', 'thumbnail' ],n            'show_in_rest' => true,n        ] );n    }n}nadd_action( 'init', 'theme_register_all_cpts' );

The child theme adds or removes post types by filtering theme_cpt_config. A client that doesn’t need Testimonials removes that entry from the array. A client that adds a Portfolio post type appends a new entry. The registration loop copies the same structure from each entry — supports, rewrite slug, and icon — so all post types share consistent behavior.

Converting a static page section to a CPT. Many sites have a “Team” section built as a static page with hardcoded HTML. Converting it to a Team Members CPT makes it editable through the WordPress admin. The process: (1) Register the CPT using this boilerplate. (2) Build archive-team.php and single-team.php templates that replicate the static page’s HTML structure — replace hardcoded member data with the WordPress loop. (3) Copy each team member’s content into individual CPT posts. (4) Replace the static page’s content with a redirect or a custom page template that queries the CPT. (5) Delete or unpublish the static page once the CPT archive matches it. The pre_get_posts hook from Step 4 controls the display order (alphabetical by last name, by hire date, by custom sort order field).