Global Content: GC_Helper

The GC_Helper class acts as the nerve centre of the Greyd Global Content plugin. It groups a wide range of static utilities that support distribution, synchronisation and retrieval of posts across a multisite network and remote connections. Unlike most classes in the system, GC_Helper maintains no state; you call its methods directly without creating an instance. The class is instantiated only to register a small number of filters, but every public method is static and available for you to use. This guide explains how the helper works, documents its public API and shows how you can integrate it into your own code.

Approach and Architecture

During a distribution run the plugin uses GC_Helper as a facade over low‑level operations. It fetches global posts by their global ID (GID), prepares posts for import, constructs and interprets global identifiers, manages connection maps between posts on different blogs, queries local and remote networks, exports and imports posts, and handles errors. The class exposes its functionality through discrete static methods so that other parts of the plugin and external developers can perform these tasks without duplicating logic. Internally the helper delegates to WordPress core functions, caches results in both object and transient caches, and calls into the Remote_Operations component when interacting with remote networks. Because of this design you can rely on the helper to resolve the correct context and maintain consistency across network boundaries.

Public static functions

GC_Helper defines dozens of static methods. The following sections describe what each one does and how you might use it.

Global ID and post retrieval

  • get_global_post( string $gid ) — Retrieves a global post by its global ID. It checks the object cache and transient cache, splits the GID into its components, then switches to the appropriate blog or calls remote APIs to fetch the post. If the post exists and has global metadata the method returns a GC_Post instance; otherwise it returns null. A filter allows you to customise the returned object before it is returned.
  • prepare_global_post_for_import( string $gid, array $args = [] ) — Retrieves all posts required to import a global post into the current site. It merges arguments stored in the post’s metadata with those supplied in $args, exports the root post and gathers all dependent posts. On remote networks it delegates to Remote_Operations::prepare_remote_global_post. It returns an array of prepared posts or null if none are available.
  • get_gid( WP_Post|string $post ) — Returns the global ID of a post. It reads the gc_post_id meta value and applies a filter so that you can modify the format. If no global ID is found the function returns false.
  • get_post_id_by_gid( string $gid ) — Locates a local post ID by its global ID. It performs a meta query for posts with gc_post_id equal to the supplied GID and returns the first matching ID or 0 if none is found.
  • explode_gid( string $gid ) — Splits a global ID into its component parts: blog ID, post ID and site URL. Each component passes through a dedicated filter and a final filter adjusts the entire array. The method returns an array [ blog_id, post_id, site_url ] with null entries when the input is invalid.
  • get_local_post_by_gid( string $gid, string $post_type = 'any' ) — Returns a local WP_Post object for a given global ID. It queries posts of the specified post type with a matching gc_post_id meta value. If a match is found it returns the post; otherwise it returns null.
  • get_local_post_links( int $blog_id, int $post_id ) — Builds an associative array of URLs for a local post, including edit links and frontend links. You typically do not call this directly; use get_post_links_by_gid instead.
  • get_post_links_by_gid( string $gid ) — Returns the same array of links as get_local_post_links but accepts a global ID. It resolves the local post ID and blog ID and then delegates to get_local_post_links. If the post is remote or cannot be resolved it returns an empty array.
  • get_global_permalink( string $permalink, WP_Post $post, bool $leavename = false, bool $sample = false ) — Hooked into WordPress’s post_link filter, this function rewrites permalinks for posts that belong to the global content system. It returns a global permalink when the post is remote and a normal permalink otherwise.

Aggregation and listing

  • get_all_global_posts( string|array|null $query = null, string|null $network_url = null ) — Returns an array of global posts across the current network and connected remote networks. You can supply a search term or WP_Query array in $query and restrict results to a particular network with $network_url. The method caches results and uses Remote_Operations to fetch remote posts. A filter lets you modify the returned array.
  • get_all_network_posts( string|array|null $query = null ) — Iterates through all blogs in the current multisite network and returns an array of global posts from each. Like get_all_global_posts it accepts a search query and caches results. A filter allows you to adjust the returned list.
  • get_blog_global_posts( int|string $blog_id = '', string $filter_status = '', string|array|null $query = null ) — Retrieves global posts for a specific blog. The $filter_status argument lets you filter posts by their gc_post_status meta value (e.g. 'root' or 'linked'). An optional query restricts the search further. The method returns an array of posts or null if none are found.
  • get_all_blogs() — Returns an associative array of all blogs in the network. Keys are blog IDs and values hold basic blog information. The helper uses this list internally; you can call it if you need to iterate over blogs yourself.
  • get_blog_global_posts_with_errors( int $blog_id = 0, bool $repair_posts = false, array|null $query_args = null ) — Fetches global posts that have errors on a specific blog. If $repair_posts is true the method attempts to repair each post before returning the list. It accepts optional query arguments for additional filtering.
  • get_all_local_post_connections( string $gid ) — Returns an associative array of all posts that are connected to the post identified by the supplied global ID on the current network. The keys in the returned array are network identifiers and the values are connection maps.
  • get_all_local_linked_posts( string $gid ) — Returns an array of posts linked to the supplied global ID on the current network. It is a wrapper around get_all_local_post_connections that collapses the connection map into a simple list of posts.
  • get_similar_global_posts( WP_Post $post ) — Finds and returns global posts similar to the supplied post. Similarity is determined by comparing the post title and post name across the network. The method is useful when suggesting possible parent posts during the linking process.
  • get_connections() — Returns an array of connection objects representing remote networks configured in the plugin. Each connection includes settings like the remote URL and authentication tokens. You rarely need to call this directly; higher-level methods use it internally.
  • get_content_connections() — Returns the same list of connections as get_connections but formatted for content operations. It ensures that each connection is ready for content distribution and filters out connections that have been disabled.
  • get_search_connections( string $search ) — Returns a subset of connections whose URLs or labels match the supplied search term. Use this when building administrative interfaces to search through configured remote networks.
  • get_languages_codes() — Returns an array of language codes supported by the plugin. Each entry maps a language code to a human-readable label. Use it when presenting language choices to users.
  • get_wp_template_theme() — Returns the name of the WordPress theme used for template rendering within the plugin. It is helpful when customising the look of global content templates.
  • get_translation_tool() — Returns the active translation tool configured in the plugin. This can be used to control language translation during exports and imports.
  • get_posts( array $args ) — A thin wrapper around WP_Query that returns posts based on the supplied arguments. It ensures that the helper respects plugin-specific defaults and filters. Use it instead of calling WP_Query directly when working within the global content context.

Metadata and settings

  • get_gc_meta( int|WP_Post $post_id, string $meta_key ) — Returns the value of a single global content meta key for a given post. It first checks the post’s meta property if the parameter is a GC_Post, then falls back to get_post_meta for a post ID. If no value is found it returns an empty string.
  • default_meta_values() — Returns an associative array of default metadata keys and their default values. The plugin uses these values when constructing GC_Post objects and when normalising metadata during import and export.
  • default_export_args() — Returns the default arguments used when exporting posts. The returned array includes keys like append_nested, whole_posttype and resolve_menus. You can merge this with custom arguments when calling export_post or export_posts.
  • delete_gc_meta( int $post_id, string $meta_key ) — Deletes a specific global content meta key for a given post. It wraps delete_post_meta and returns a boolean indicating success.
  • gc_meta( int $post_id, string $meta_key, mixed $default = null ) — Returns the value of a global content meta key or a default value if the key is not set. This helper allows you to specify a fallback in one call instead of checking for false yourself.
  • get_post_language_code( WP_Post|int $post ) — Determines the language code for a post based on plugin settings and metadata. It returns a string such as 'en' or null if the language cannot be determined.

Connection map and manipulation

  • get_post_connection_map( int $post_id ) — Returns a nested array describing how a post is connected to other posts across blogs and networks. The array keys are network URLs and blog IDs; the values include the local post ID and other metadata. Use it to understand the distribution of a post.
  • get_network_remote_connection_map_by_gid( string $gid ) — Retrieves the remote connection map for a global ID across all remote networks. It helps identify where a post has been distributed outside the current network.
  • add_or_remove_post_connection_from_connection_map( array $map, string $network_url, int $blog_id, int $post_id, bool $remove = false ) — Adds or removes a single post connection from a connection map. When $remove is false the function adds the connection; when true it removes it. It returns the updated map.
  • add_post_connection_to_connection_map( array $map, string $network_url, int $blog_id, int $post_id ) — Convenience wrapper around add_or_remove_post_connection_from_connection_map that always adds a connection.
  • remove_post_connection_from_connection_map( array $map, string $network_url, int $blog_id, int $post_id ) — Convenience wrapper around add_or_remove_post_connection_from_connection_map that always removes a connection.
  • convert_connection_map_to_destination_ids( array $map ) — Converts a connection map into an array of destination IDs. Destination IDs are values like blog_id-post_id that identify where posts have been distributed. Use this when building Destination objects for a distribution run.
  • convert_gc_post_into_post_connection( GC_Post $post, string $network_url = null ) — Converts a GC_Post object into a simple connection map entry. If you pass a network URL it uses that value; otherwise it reads from the post’s metadata.
  • convert_post_to_root( GC_Post $post ) — Converts a linked post to a root post by adjusting its metadata. This is used when promoting a linked post to be the new root of a global post set.
  • create_post_connection_map_array( int $blog_id, int $post_id ) — Returns a canonical array structure for a single connection. The structure includes keys for ID, blog_id, post_id, and connection metadata.
  • check_connection_map( array $map ) — Validates a connection map and removes entries that refer to blogs or posts that no longer exist. Use this before persisting a map or sending it to a remote network.
  • check_post_for_errors( GC_Post $post ) — Runs a series of checks on a GC_Post and returns a WP_Error object if any problems are found. Typical checks include verifying the post status, ensuring required meta keys are set and validating connection maps.
  • current_user_can_edit_global_posts() — Returns true if the current user has the capability to edit global posts. It wraps a WordPress capability check and plugin configuration.
  • get_network_url() — Returns the canonical URL of the current network. Remote connections use this value as a key in connection maps.
  • get_nice_url( string $url ) — Normalises a URL by removing protocol and trailing slashes. The helper uses it when building global IDs and connection keys.
  • setup_complete() — Returns true if the global content plugin is fully configured. If this returns false you should not attempt to distribute content.

Export and import

  • export_post( int $post_id, array $args = [] ) — Exports a single post to the prepared posts buffer. It merges $args with default export arguments and delegates to the configured post export function. After calling this you can retrieve the exported data via other helper functions.
  • export_posts( array $post_ids, array $args = [] ) — Exports multiple posts in one call. It iterates through the supplied IDs and calls export_post for each. The returned value depends on the configured export function.
  • import_posts( array $posts, array $args = [] ) — Imports an array of prepared posts into the current site. It merges $args with default import options and delegates to the configured import function. It returns an array of results or a WP_Error on failure.
  • prepare_global_post_for_import( string $gid, array $args = [] ) — Already covered above; it retrieves and prepares the posts required for import.
  • call_post_export_func( string $function, ...$args ) — Calls an export helper function defined by the plugin or a remote connection. Use this to invoke functions like export_post or get_all_posts in a consistent manner.
  • call_posttype_func( string $function, ...$args ) — Calls a post‑type specific helper function. It is primarily used internally to support different post types with custom export or import logic.
  • call_connections_func( array $connections, string $function, ...$args ) — Invokes a helper function across multiple connections. Each connection is asked to perform the function and the results are aggregated. Use this to send operations to all remote networks.
  • call_settings_func( string $function, ...$args ) — Calls a settings helper function on the current network or remote networks. It is used to fetch or update plugin settings across networks.
  • call_greyd_helper_func( string $function, ...$args ) — Calls a helper function on the GC_Helper class across remote networks. This meta‑helper is rarely needed outside the core plugin.
  • remove_filters_from_query_args( array $args ) — Cleans up WP_Query arguments by removing filters that would otherwise alter the results. Call this before querying posts when you need a clean query environment.
  • extend_post_object( object $post ) — Extends a basic post object with additional fields required for export. It adds fields such as the author’s display name and formatted dates. Use it when you need to output post data in templates.

Error and status handling

  • get_post_error( GC_Post|WP_Post $post ) — Returns a WP_Error describing any issues with the post. It checks metadata and connection maps and returns null if no errors are found.
  • get_error_message( WP_Error|string $error ) — Accepts a WP_Error or error code and returns a human‑readable message. Use this when displaying errors to users.
  • get_error_repaired_log( WP_Error $error ) — Returns a log message indicating that an error has been repaired. This is used internally after automatic repairs.
  • is_error_repaired( WP_Error|string $error ) — Returns true if the supplied error has been marked as repaired. Use it to avoid displaying the same error twice.
  • get_blog_global_posts_with_errors( int $blog_id = 0, bool $repair_posts = false, array|null $query_args = null ) — Already covered; see above.
  • get_network_global_posts_with_errors( string $network_url, bool $repair_posts = false ) — Similar to get_blog_global_posts_with_errors but operates on an entire remote network. It fetches posts via Remote_Operations and returns those with errors.
  • repair_post( GC_Post $post, bool $silent = false ) — Attempts to repair a post that has failed distribution. Repairs may include resetting metadata, re‑exporting and removing invalid connections. When $silent is true the method suppresses error messages.
  • render_status_box( GC_Post $post ) — Outputs a status box for the post in the WordPress admin. It shows the distribution status and any errors. This is primarily used by the plugin’s UI.
  • show_message( string $message, string $type = 'info' ) — Displays a message in the WordPress admin. It supports different types such as error, warning, success and info.

Utility

  • switch_to_blog( int $blog_id ) — Wraps switch_to_blog and ensures that plugin‑specific caches and settings are correctly updated. Always call this wrapper instead of WordPress’s native function when working with global content.
  • is_rest_request() — Returns true if the current request is a REST API call. The plugin avoids certain operations during REST requests for performance reasons.
  • get_edit_post_link( GC_Post|WP_Post $post ) — Returns the edit URL for a post. It respects multisite context and remote posts. Use it when building administrative lists.

Internal or low‑level helpers

Several functions such as add_post_connection_to_connection_map, remove_post_connection_from_connection_map, convert_gc_post_into_post_connection, convert_post_to_root, create_post_connection_map_array, check_connection_map, check_post_for_errors, and extend_post_object manipulate connection maps and internal data structures. These are primarily used by the plugin itself but remain public for advanced use cases. You should read their implementations before using them directly.

Usage examples

Here are a few examples that illustrate how to use GC_Helper in your own code. These snippets assume that the Global Content plugin is active and configured.

Retrieve a global post and inspect meta data

PHP
// Retrieve a global post by its GID.
$gcPost = \\Greyd\\Global_Contents\\GC_Helper::get_global_post( '1-1234' );
if ( $gcPost ) {
    // Access core properties.
    echo $gcPost->post_title;
    // Inspect global metadata.
    $meta = $gcPost->meta;
    // Use the connection map.
    $connections = \\Greyd\\Global_Contents\\GC_Helper::get_post_connection_map( $gcPost->ID );
}

Prepare and import a global post

PHP
// Prepare all posts required to import a global post.
$posts = \\Greyd\\Global_Contents\\GC_Helper::prepare_global_post_for_import( '1-1234', array( 'append_nested' => true ) );
if ( is_array( $posts ) ) {
    // Import the posts into the current site.
    $result = \\Greyd\\Global_Contents\\GC_Helper::import_posts( $posts );
    if ( is_wp_error( $result ) ) {
        error_log( 'Import failed: ' . $result->get_error_message() );
    }
}

Find all global posts on the network

PHP
// Retrieve all global posts on the current multisite network.
$globalPosts = \\Greyd\\Global_Contents\\GC_Helper::get_all_global_posts();
foreach ( $globalPosts as $post ) {
    // Do something with each GC_Post.
    echo $post->post_title . "\\n";
}

Derive and explode global IDs

PHP
// Obtain the global ID for a local post.
$gid = \\Greyd\\Global_Contents\\GC_Helper::get_gid( 42 );
if ( $gid ) {
    list( $blogId, $postId, $siteUrl ) = \\Greyd\\Global_Contents\\GC_Helper::explode_gid( $gid );
    echo "Blog ID: $blogId, Post ID: $postId, Site URL: $siteUrl";
}

Manage connection maps

PHP
// Add a connection to a connection map.
$map = [];
$map = \\Greyd\\Global_Contents\\GC_Helper::add_post_connection_to_connection_map( $map, 'example.com', 2, 99 );
// Remove the same connection later.
$map = \\Greyd\\Global_Contents\\GC_Helper::remove_post_connection_from_connection_map( $map, 'example.com', 2, 99 );

Last updated: