How to build custom Genesis child themes extensions utilizing modern REST API Controllers schemas
Leveraging WordPress REST API Controllers for Genesis Child Theme Extensions
Enterprise-grade WordPress deployments often necessitate highly customized functionalities that extend beyond the standard theme and plugin capabilities. When building on robust frameworks like Genesis, integrating custom data structures and business logic requires a scalable and maintainable approach. This document outlines how to architect and implement custom extensions for Genesis child themes by leveraging the WordPress REST API’s controller architecture and schema definition, enabling seamless data interaction and integration with external systems.
Defining Custom Post Types and Taxonomies
Before diving into API controllers, a solid foundation of custom data structures is paramount. For this example, let’s assume we need to manage ‘Projects’ with associated ‘Technologies’ used. This involves registering custom post types and taxonomies.
Registering the ‘Project’ Post Type
This code snippet, typically placed in your child theme’s functions.php or a dedicated plugin file, registers the ‘Project’ post type.
<?php
/**
* Register the 'Project' custom post type.
*/
function my_genesis_child_register_project_cpt() {
$labels = array(
'name' => _x( 'Projects', 'post type general name', 'my-genesis-child' ),
'singular_name' => _x( 'Project', 'post type singular name', 'my-genesis-child' ),
'menu_name' => _x( 'Projects', 'admin menu', 'my-genesis-child' ),
'name_admin_bar' => _x( 'Project', 'add new button in admin bar', 'my-genesis-child' ),
'add_new' => _x( 'Add New', 'project', 'my-genesis-child' ),
'add_new_item' => __( 'Add New Project', 'my-genesis-child' ),
'edit_item' => __( 'Edit Project', 'my-genesis-child' ),
'new_item' => __( 'New Project', 'my-genesis-child' ),
'view_item' => __( 'View Project', 'my-genesis-child' ),
'all_items' => __( 'All Projects', 'my-genesis-child' ),
'search_items' => __( 'Search Projects', 'my-genesis-child' ),
'parent_item_colon' => __( 'Parent Projects:', 'my-genesis-child' ),
'not_found' => __( 'No projects found.', 'my-genesis-child' ),
'not_found_in_trash' => __( 'No projects found in Trash.', 'my-genesis-child' ),
);
$args = array(
'labels' => $labels,
'public' => true,
'publicly_queryable' => true,
'show_ui' => true,
'show_in_menu' => true,
'query_var' => true,
'rewrite' => array( 'slug' => 'projects' ),
'capability_type' => 'post',
'has_archive' => true,
'hierarchical' => false,
'menu_position' => 20,
'menu_icon' => 'dashicons-portfolio',
'supports' => array( 'title', 'editor', 'thumbnail', 'excerpt', 'custom-fields' ),
'show_in_rest' => true, // Crucial for REST API integration
'rest_base' => 'projects', // Custom REST API base slug
'rest_controller_class' => 'WP_REST_Posts_Controller', // Default controller
);
register_post_type( 'project', $args );
}
add_action( 'init', 'my_genesis_child_register_project_cpt' );
?>
Registering the ‘Technology’ Taxonomy
This taxonomy will be used to categorize projects by the technologies they employ.
<?php
/**
* Register the 'Technology' custom taxonomy.
*/
function my_genesis_child_register_technology_taxonomy() {
$labels = array(
'name' => _x( 'Technologies', 'taxonomy general name', 'my-genesis-child' ),
'singular_name' => _x( 'Technology', 'taxonomy singular name', 'my-genesis-child' ),
'search_items' => __( 'Search Technologies', 'my-genesis-child' ),
'all_items' => __( 'All Technologies', 'my-genesis-child' ),
'parent_item' => __( 'Parent Technology', 'my-genesis-child' ),
'parent_item_colon' => __( 'Parent Technology:', 'my-genesis-child' ),
'edit_item' => __( 'Edit Technology', 'my-genesis-child' ),
'update_item' => __( 'Update Technology', 'my-genesis-child' ),
'add_new_item' => __( 'Add New Technology', 'my-genesis-child' ),
'new_item_name' => __( 'New Technology Name', 'my-genesis-child' ),
'menu_name' => __( 'Technologies', 'my-genesis-child' ),
);
$args = array(
'hierarchical' => true, // Set to false for non-hierarchical (tags)
'labels' => $labels,
'show_ui' => true,
'show_admin_column' => true,
'query_var' => true,
'rewrite' => array( 'slug' => 'technology' ),
'show_in_rest' => true, // Crucial for REST API integration
'rest_base' => 'technologies', // Custom REST API base slug
);
register_taxonomy( 'technology', array( 'project' ), $args );
}
add_action( 'init', 'my_genesis_child_register_technology_taxonomy', 0 );
?>
Custom REST API Controller for Enhanced Data Handling
While the default WP_REST_Posts_Controller handles basic CRUD operations for post types, complex business logic or specific data transformations often require a custom controller. This allows for fine-grained control over request handling, response formatting, and data validation.
Creating a Custom Controller Class
We’ll extend WP_REST_Controller to create our own controller for ‘Projects’. This class will define endpoints for retrieving, creating, updating, and deleting project data, potentially with custom fields or logic.
<?php
/**
* Custom REST API Controller for Projects.
*/
class My_Genesis_Child_REST_Projects_Controller extends WP_REST_Controller {
/**
* Namespace for the controller.
*
* @var string
*/
protected $namespace = 'my-genesis-child/v1';
/**
* The base for the controller.
*
* @var string
*/
protected $rest_base = 'projects';
/**
* Register the routes.
*/
public function register_routes() {
register_rest_route( $this->namespace, '/' . $this->rest_base, array(
array(
'methods' => WP_REST_Server::READABLE,
'callback' => array( $this, 'get_items' ),
'permission_callback' => array( $this, 'get_items_permissions_check' ),
'args' => $this->get_collection_params(),
),
array(
'methods' => WP_REST_Server::CREATABLE,
'callback' => array( $this, 'create_item' ),
'permission_callback' => array( $this, 'create_item_permissions_check' ),
'args' => $this->get_endpoint_args_for_item_schema( WP_REST_Server::CREATABLE ),
),
'schema' => array( $this, 'get_schema' ),
) );
register_rest_route( $this->namespace, '/' . $this->rest_base . '/(?P<id>[\d]+)', array(
array(
'methods' => WP_REST_Server::READABLE,
'callback' => array( $this, 'get_item' ),
'permission_callback' => array( $this, 'get_item_permissions_check' ),
'args' => array(
'id' => array(
'description' => __( 'Unique identifier for the resource.', 'my-genesis-child' ),
'type' => 'integer',
'validate_callback' => 'rest_validate_request_arg',
),
),
),
array(
'methods' => WP_REST_Server::EDITABLE,
'callback' => array( $this, 'update_item' ),
'permission_callback' => array( $this, 'update_item_permissions_check' ),
'args' => $this->get_endpoint_args_for_item_schema( WP_REST_Server::EDITABLE ),
),
array(
'methods' => WP_REST_Server::DELETABLE,
'callback' => array( $this, 'delete_item' ),
'permission_callback' => array( $this, 'delete_item_permissions_check' ),
'args' => array(
'force' => array(
'type' => 'boolean',
'default' => false,
'description' => __( 'Whether to bypass trash and force deletion.', 'my-genesis-child' ),
),
),
),
) );
}
/**
* Check if a given request has access to get items.
*
* @param WP_REST_Request $request Full data.
* @return WP_Error|bool
*/
public function get_items_permissions_check( $request ) {
// Example: Only allow authenticated users to view projects.
if ( ! current_user_can( 'read' ) ) {
return new WP_Error( 'rest_forbidden', esc_html__( 'Sorry, you cannot view projects.', 'my-genesis-child' ), array( 'status' => rest_authorization_required_code() ) );
}
return true;
}
/**
* Get a collection of items.
*
* @param WP_REST_Request $request Full data.
* @return WP_Error|WP_REST_Response
*/
public function get_items( $request ) {
$args = array(
'post_type' => 'project',
'posts_per_page' => $request['per_page'],
'paged' => $request['page'],
'orderby' => $request['orderby'],
'order' => $request['order'],
);
// Add query parameters for filtering by taxonomy, e.g., technology.
$tax_query = array();
if ( ! empty( $request['technology'] ) ) {
$tax_query[] = array(
'taxonomy' => 'technology',
'field' => 'slug',
'terms' => $request['technology'],
);
}
if ( ! empty( $tax_query ) ) {
$args['tax_query'] = $tax_query;
}
$projects = new WP_Query( $args );
$data = array();
if ( $projects->have_posts() ) {
foreach ( $projects->posts as $post ) {
$data[] = $this->prepare_item_for_response( $post, $request );
}
}
$response = new WP_REST_Response( $data );
$response->add_links( $this->link_header( $request ) );
// Add pagination headers.
$total_posts = $projects->found_posts;
$response->set_headers( array(
'X-WP-Total' => $total_posts,
'X-WP-TotalPages' => ceil( $total_posts / (int) $request['per_page'] ),
) );
return $response;
}
/**
* Check if a given request has access to create items.
*
* @param WP_REST_Request $request Full data.
* @return WP_Error|bool
*/
public function create_item_permissions_check( $request ) {
// Example: Only allow users with 'edit_posts' capability for 'project' post type.
if ( ! current_user_can( 'edit_posts' ) ) { // This capability might need to be more specific if using custom roles.
return new WP_Error( 'rest_forbidden', esc_html__( 'Sorry, you cannot create projects.', 'my-genesis-child' ), array( 'status' => rest_authorization_required_code() ) );
}
return true;
}
/**
* Create one item.
*
* @param WP_REST_Request $request Full data.
* @return WP_Error|WP_REST_Response
*/
public function create_item( $request ) {
// Basic validation for required fields.
if ( empty( $request['title'] ) ) {
return new WP_Error( 'rest_invalid_param', __( 'Title is required.' ), array( 'status' => 400 ) );
}
$post_data = array(
'post_title' => sanitize_text_field( $request['title'] ),
'post_content' => wp_kses_post( $request['content'] ),
'post_status' => 'publish', // Or handle status from request.
'post_type' => 'project',
);
// Handle custom fields.
if ( isset( $request['project_url'] ) ) {
$post_data['meta']['project_url'] = esc_url_raw( $request['project_url'] );
}
// Handle taxonomies.
if ( isset( $request['technologies'] ) && is_array( $request['technologies'] ) ) {
// Ensure terms exist or create them if allowed.
// For simplicity, we'll assume terms are pre-existing slugs.
$term_ids = wp_set_post_terms( 0, $request['technologies'], 'technology', false ); // 0 is placeholder for new post ID
if ( is_wp_error( $term_ids ) ) {
return $term_ids; // Return the error if term assignment fails.
}
// Note: wp_set_post_terms needs to be called *after* post insertion for existing posts.
// For new posts, we'll handle this after insertion.
}
$post_id = wp_insert_post( $post_data, true );
if ( is_wp_error( $post_id ) ) {
return $post_id;
}
// Now set terms for the newly created post.
if ( isset( $request['technologies'] ) && is_array( $request['technologies'] ) ) {
wp_set_post_terms( $post_id, $request['technologies'], 'technology', false );
}
// Update custom fields after post creation.
if ( isset( $request['project_url'] ) ) {
update_post_meta( $post_id, 'project_url', esc_url_raw( $request['project_url'] ) );
}
$post = get_post( $post_id );
$response = $this->prepare_item_for_response( $post, $request );
$response->set_status( 201 );
return $response;
}
/**
* Check if a given request has access to get a specific item.
*
* @param WP_REST_Request $request Full data.
* @return WP_Error|bool
*/
public function get_item_permissions_check( $request ) {
// Similar to get_items_permissions_check, or more specific if needed.
if ( ! current_user_can( 'read' ) ) {
return new WP_Error( 'rest_forbidden', esc_html__( 'Sorry, you cannot view this project.', 'my-genesis-child' ), array( 'status' => rest_authorization_required_code() ) );
}
return true;
}
/**
* Get one item.
*
* @param WP_REST_Request $request Full data.
* @return WP_Error|WP_REST_Response
*/
public function get_item( $request ) {
$post_id = (int) $request['id'];
$post = get_post( $post_id );
if ( ! $post || 'project' !== $post->post_type ) {
return new WP_Error( 'rest_not_found', __( 'Project not found.' ), array( 'status' => 404 ) );
}
$data = $this->prepare_item_for_response( $post, $request );
$response = new WP_REST_Response( $data );
return $response;
}
/**
* Check if a given request has access to update an item.
*
* @param WP_REST_Request $request Full data.
* @return WP_Error|bool
*/
public function update_item_permissions_check( $request ) {
// Example: Only allow users who can edit the specific post.
$post_id = (int) $request['id'];
if ( ! current_user_can( 'edit_post', $post_id ) ) {
return new WP_Error( 'rest_forbidden', esc_html__( 'Sorry, you cannot edit this project.', 'my-genesis-child' ), array( 'status' => rest_authorization_required_code() ) );
}
return true;
}
/**
* Update one item.
*
* @param WP_REST_Request $request Full data.
* @return WP_Error|WP_REST_Response
*/
public function update_item( $request ) {
$post_id = (int) $request['id'];
$post = get_post( $post_id );
if ( ! $post || 'project' !== $post->post_type ) {
return new WP_Error( 'rest_not_found', __( 'Project not found.' ), array( 'status' => 404 ) );
}
$update_data = array( 'ID' => $post_id );
if ( isset( $request['title'] ) ) {
$update_data['post_title'] = sanitize_text_field( $request['title'] );
}
if ( isset( $request['content'] ) ) {
$update_data['post_content'] = wp_kses_post( $request['content'] );
}
if ( isset( $request['status'] ) ) {
$update_data['post_status'] = sanitize_key( $request['status'] );
}
// Handle custom fields.
if ( isset( $request['project_url'] ) ) {
update_post_meta( $post_id, 'project_url', esc_url_raw( $request['project_url'] ) );
} elseif ( $request->has_param( 'project_url' ) && null === $request['project_url'] ) {
// Allow clearing the field.
delete_post_meta( $post_id, 'project_url' );
}
// Handle taxonomies.
if ( isset( $request['technologies'] ) && is_array( $request['technologies'] ) ) {
wp_set_post_terms( $post_id, $request['technologies'], 'technology', false );
} elseif ( $request->has_param( 'technologies' ) && null === $request['technologies'] ) {
// Allow clearing the terms.
wp_set_post_terms( $post_id, array(), 'technology', false );
}
$updated_post_id = wp_update_post( $update_data, true );
if ( is_wp_error( $updated_post_id ) ) {
return $updated_post_id;
}
$post = get_post( $post_id ); // Re-fetch the post after update.
$response = $this->prepare_item_for_response( $post, $request );
return $response;
}
/**
* Check if a given request has access to delete an item.
*
* @param WP_REST_Request $request Full data.
* @return WP_Error|bool
*/
public function delete_item_permissions_check( $request ) {
$post_id = (int) $request['id'];
if ( ! current_user_can( 'delete_post', $post_id ) ) {
return new WP_Error( 'rest_forbidden', esc_html__( 'Sorry, you cannot delete this project.', 'my-genesis-child' ), array( 'status' => rest_authorization_required_code() ) );
}
return true;
}
/**
* Delete one item.
*
* @param WP_REST_Request $request Full data.
* @return WP_REST_Response
*/
public function delete_item( $request ) {
$post_id = (int) $request['id'];
$force = isset( $request['force' ] ) && true === $request['force'];
$post = get_post( $post_id );
if ( ! $post || 'project' !== $post->post_type ) {
return new WP_Error( 'rest_not_found', __( 'Project not found.' ), array( 'status' => 404 ) );
}
// Check if the post is already in trash if not forcing deletion.
if ( ! $force && 'trash' === $post->post_status ) {
return new WP_Error( 'rest_already_in_trash', __( 'Project already in trash.' ), array( 'status' => 410 ) );
}
$deleted = wp_delete_post( $post_id, $force );
if ( ! $deleted ) {
return new WP_Error( 'rest_cannot_delete', __( 'The project could not be deleted.' ), array( 'status' => 500 ) );
}
$response = new WP_REST_Response();
$response->add_data( array(
'deleted' => true,
'previous' => $this->prepare_item_for_response( $post, $request ),
) );
return $response;
}
/**
* Prepare a single project for the REST response.
*
* @param WP_Post $post Post object.
* @param WP_REST_Request $request Request object.
* @return WP_REST_Response
*/
public function prepare_item_for_response( $post, $request ) {
$data = array(
'id' => $post->ID,
'date' => $this->prepare_date_response( $post->post_date, $request ),
'date_gmt' => $this->prepare_date_response( $post->post_date_gmt, $request ),
'guid' => array(
'rendered' => $post->guid,
'raw' => $post->guid,
),
'modified' => $this->prepare_date_response( $post->post_modified, $request ),
'modified_gmt' => $this->prepare_date_response( $post->post_modified_gmt, $request ),
'slug' => $post->post_name,
'status' => $post->post_status,
'type' => $post->post_type,
'link' => get_permalink( $post ),
'title' => array(
'rendered' => get_the_title( $post ),
'raw' => get_the_title( $post ),
),
'content' => array(
'rendered' => apply_filters( 'the_content', $post->post_content ),
'raw' => $post->post_content,
),
'excerpt' => array(
'rendered' => get_the_excerpt( $post ),
'raw' => $post->post_excerpt,
),
'featured_media' => get_post_thumbnail_id( $post ),
'project_url' => get_post_meta( $post->ID, 'project_url', true ),
'technologies' => wp_get_post_terms( $post->ID, 'technology', array( 'fields' => 'names' ) ), // Get term names
);
// Add featured image data if available.
if ( $data['featured_media'] ) {
$attachment_id = $data['featured_media'];
$data['featured_media_data'] = array(
'id' => $attachment_id,
'source_url' => wp_get_attachment_url( $attachment_id ),
'full' => wp_get_attachment_image_src( $attachment_id, 'full' ),
'medium' => wp_get_attachment_image_src( $attachment_id, 'medium' ),
'thumbnail' => wp_get_attachment_image_src( $attachment_id, 'thumbnail' ),
);
}
// Add term data for technologies.
$term_objects = wp_get_post_terms( $post->ID, 'technology', array( 'fields' => 'all' ) );
$data['technologies_data'] = array();
if ( ! is_wp_error( $term_objects ) && ! empty( $term_objects ) ) {
foreach ( $term_objects as $term ) {
$data['technologies_data'][] = array(
'id' => $term->term_id,
'name' => $term->name,
'slug' => $term->slug,
'link' => get_term_link( $term ),
);
}
}
// Filter to only include fields that are set.
$data = array_filter( $data );
$response = new WP_REST_Response( $data );
$response->add_link( 'self', rest_url( sprintf( '%s/%s/%d', $this->namespace, $this->rest_base, $post->ID ) ) );
return $response;
}
/**
* Prepare links for the items.
*
* @param WP_REST_Request $request Request object.
* @return array Links for the items.
*/
protected function link_header( $request ) {
$links = array();
$base = rest_url( sprintf( '%s/%s', $this->namespace, $this->rest_base ) );
// First page.
$links['self'] = $base;
// Previous page.
if ( $request['page'] > 1 ) {
$prev_page = $request['page'] - 1;
$links['prev'] = add_query_arg( 'page', $prev_page, $base );
}
// Next page.
$total_pages = ceil( (int) $request['total_posts'] / (int) $request['per_page'] ); // Assuming total_posts is set in the response headers
if ( $request['page'] < $total_pages ) {
$next_page = $request['page'] + 1;
$links['next'] = add_query_arg( 'page', $next_page, $base );
}
return $links;
}
/**
* Get the query params for collections.
*
* @return array
*/
public function get_collection_params() {
return array(
'page' => array(
'description' => __( 'Current page of the collection.', 'my-genesis-child' ),
'type' => 'integer',
'default' => 1,
'min' => 1,
'validate_callback' => 'rest_validate_request_arg',
'sanitize_callback' => 'absint',
),
'per_page' => array(
'description' => __( 'Maximum number of items to be returned in the collection.', 'my-genesis-child' ),
'type' => 'integer',
'default' => 10,
'min' => 1,
'max' => 100, // Limit per page for performance.
'validate_callback' => 'rest_validate_request_arg',
'sanitize_callback' => 'absint',
),
'orderby' => array(
'description' => __( 'Sort collection by object attribute.', 'my-genesis-child' ),
'type' => 'string',
'default' => 'date',
'enum' => array( 'date', 'id', 'include', 'title', 'slug' ),
'validate_callback' => 'rest_validate_request_arg',
'sanitize_callback' => 'sanitize_key',
),
'order' => array(
'description' => __( 'Order sort attribute ascending or descending.', 'my-genesis-child' ),
'type' => 'string',
'default' => 'desc',
'enum' => array( 'asc', 'desc' ),
'validate_callback' => 'rest_validate_request_arg',
'sanitize_callback' => 'strtolower',
),
'technology' => array(
'description' => __( 'Limit results to projects associated with a specific technology slug.', 'my-genesis-child' ),
'type' => 'string',
'validate_callback' => 'rest_validate_request_arg',
'sanitize_callback' => 'sanitize_key',
),
);
}
/**
* Get the schema for the item.
*
* @return array Schema array.
*/
public function get_schema() {
$schema = array(
'$schema' => 'http://json-schema.org/draft-04/schema#',
'title' => 'project',
'type' => 'object',
'properties' => array(
'id' => array(
'description' => __( 'Unique identifier for the resource.', 'my-genesis-child' ),
'type' => 'integer',
'context' => array( 'view', 'edit', 'embed' ),
'readonly' => true,
),
'date' => array(
'description