This is taken from the src/api.php file. Use doxygen to create the apidoc directory.

Using the API

Retrieve the API object by asking Broadcast for it.

$api = ThreeWP_Broadcast()->api();

Or call an API method directly.

ThreeWP_Broadcast()->api()->broadcast_children( 123, [ 10, 11, 12 ] );

Broadcasting

The methods below refer to the post ID on the current blog.

To broadcast a post to one or more blogs, see broadcast_children( $post_id, [ blog1, blog2, blog7 ] ). The posts will be linked as children.

To rebroadcast (update) the post, see update_children( $post_id ). You can also, optionally, specified an array of new blog IDs which to add the post. Linking is parent <-> child.

Broadcasting is done like so:

• A broadcasting_data (bcd) object is created with the specified post_id as the source.
• The bcd will examine the post and prepare itself, setting its internal properties.
• The bcd constructor will create and prepare the meta_box_data object, which allows plugins to do things like force broadcast to blogs or similar.
• Optionally, the prepare_broadcasting_data action is executed in order to parse the meta box, to see which options and blogs are selected. This is only done when input from the user needs to be parsed. This is not run when using the API.
• The threewp_broadcast_broadcast_post action is executed, which will broadcast the post. The queue plugin overrides this hook and stores the bcd for later.
• The bcd object is returned.

If you wish to not use the default broadcasting_data values (perhaps you don’t want taxonomies broadcasted), then you should create the bcd object yourself, modify it, and then run action.

Priority

If you want posts you broadcast to end up in the queue, lower the priority of the api.

ThreeWP_Broadcast()->api()->low_priority()->broadcast_children( 123, [ 10, 11, 12 ] );

Post actions

The following are actions that can be run on already broadcasted (and linked) posts. The $post_id is the ID of the post on the current blog.

delete_children( $post_id, $blog_array )

Deletes the children of this post from the specified array of blog IDs. Deletes all children if the $blog_array is empty.

find_unlinked_children( $post_id, $blog_array )

Runs a find unlinked children bulk action on the post, optionally only on the specified array of blog IDs. If the $blog_array is empty, the action will be run on all blogs that the user has access to. Actions used: get_user_writable_blogs and find_unlinked_posts_blogs.

restore_children( $post_id, $blog_array )

restores (untrashes) the children of this post from the specified array of blog IDs. Restores all children if the $blog_array is empty.

trash_children( $post_id, $blog_array )

trashes the children of this post from the specified array of blog IDs. Trashes all children if the $blog_array is empty.

unlink( $post_id, $blog_array)

unlinks the post from either its parent post, or its child posts. If a parent post, the $blog_array specifies which children to unlink.

Linking

Linking is done via the API, using a linking controller. The controller works on a blog / post combination. Linking is done from a parent post to a child post.

Retrieve a linking controller for post 43 on blog 5.

$linking = ThreeWP_Broadcast()->api()->linking( 5, 43 );

Link the post to post 9 on blog 1.

$linking->link( 1, 9 );

And now unlink it.

$linking->unlink();

There are also link queries available once you get the controller.

$linking->is_linked();

$linking->is_parent();

$linking->is_child();

And retrieve an array of children for a parent post:

$linking->children();

And retrieve an array pointing to the [ parent_blog_id, parent_post_id ] of a child post:

$linking->parent();

Useful functions

The below isn’t really part of the API, but could be useful when coding together custom solutions.

The action each_linked_post executes a callback on each linked post.

The function ThreeWP_Broadcast()->switch_broadcast_data( $blog_or_post_id, $post_id = null ) can switch the broadcast data of two posts, making the parent the child and vice versa.