Add helper functions for retrieving post relationships

[s3rgiosan]

Description of the Change

This PR introduces three new helper functions to improve Block Editor integration by providing a more modular way to access relationship data.

• get_post_to_post_relationships_by and get_post_to_user_relationships_by allow developers to retrieve post-to-post and post-to-user relationships based on a specific field, such as key, post type, or from/to post types in post-to-post relationships.
• get_post_relationship_data exposes the same data used in the Vue app without requiring the tenup_content_connect_post_relationship_data filters.

Closes #82

Changelog Entry

Added - Helper function get_post_to_post_relationships_by that retrieves post-to-post relationships based on a specified field.
Added - Helper function get_post_to_user_relationships_by that retrieves post-to-user relationships based on a specified field.
Added - Helper function get_post_relationship_data that retrieves relationships (post-to-post and post-to-user) for a given post (#82).
Added - Helper function get_post_to_post_relationships_data that retrieves post-to-post relationship data for a given post.
Added - Helper function get_post_to_user_relationships_data that retrieves post-to-user relationship data for a given post.

Credits

Props @s3rgiosan

Checklist:

• I agree to follow this project's Code of Conduct.
• I have updated the documentation accordingly.
• I have added Critical Flows, Test Cases, and/or End-to-End Tests to cover my change.
• All new and existing tests pass.

[s3rgiosan]

Hi @rickalee @jeffpaul, this is ready for review. This PR provides the foundational work for #95, #94, and #97 and should be merged first.

[s3rgiosan]

I've created a try/block-editor-ui all-in-one branch to make it easier to test the features in both the block and classic editors, as well as the Query Loop integration.

[benlk]

Could this be extended to provide a canonical REST API endpoint to get lists of relationships?

[benlk]

Chunk of sample code implementing that request, from a plugin that I'm working on:

<?php
/**
 * REST API listing for Content Connect Relationships
 */

namespace UIKit\ContentConnect;

use TenUp\ContentConnect\Plugin;

class RestRelationships {

	/**
	 * Set up
	 *
	 * @return void
	 */
	public static function setup() {
		add_action( 'rest_api_init', array( __CLASS__, 'register_endpoint' ) );
		add_filter( 'tenup_content_connect_localize_data', array( __CLASS__, 'localize_endpoints' ) );
	}

	/**
	 * Register REST API endpoint
	 *
	 * @return void
	 */
	public static function register_endpoint() {
		register_rest_route(
			'ui-kit-content-connect/v1',
			'/relationships',
			array(
				'methods'             => 'GET',
				'callback'            => array( __CLASS__, 'list_relationships' ),
				'permission_callback' => '__return_true',
			)
		);
	}

	public static function localize_endpoints( $data ) {
		$data['endpoints']['relationships'] = get_rest_url( get_current_blog_id(), 'ui-kit-content-connect/v1/relationships' );

		return $data;
	}

	/**
	 * List registered relationships.
	 *
	 * @param \WP_REST_Request $request {
	 *     @type string $object_type post or user?
	 *     @type string $post_type   The post type to search for. Required if $object_type is post.
	 *
	 *
	 * @return array Array of relationships.
	 */
	public static function list_relationships( $request ) {
		$results     = [];
		$object_type = $request->get_param( 'object_type' );

		if ( ! in_array( $object_type, array( 'post', 'user' ), true ) ) {
			return new \WP_Error(
				'rest_invalid_object_type',
				__( 'Invalid object_type parameter. Must be "post" or "user".', 'uikit' ),
				array( 'status' => 400 )
			);
		}

		$final_post_types = array();
		if ( 'post' === $object_type ) {
			$post_types = $request->get_param( 'post_type' );

			if ( empty( $post_types ) ) {
				return new \WP_Error(
					'rest_invalid_post_type',
					__( 'Invalid post_type parameter. Must specify a post type slug.', 'uikit' ),
					array( 'status' => 400 )
				);
			}

			foreach ( (array) $post_types as $post_type ) {
				if ( post_type_exists( $post_type ) ) {
					$final_post_types[] = $post_type;
				}
			}

			if ( empty( $final_post_types ) ) {
				return rest_ensure_response( [] );
			}
		}

		$registry = Plugin::instance()->get_registry();
		if ( 'post' === $object_type ) {
			$relationships = $registry->get_post_to_post_relationships();
		} else {
			$relationships = $registry->get_post_to_user_relationships();
		}

		return rest_ensure_response( $relationships );
	}
}

[s3rgiosan]

@benlk I added a new endpoint here #95 (comment).