Post Relationships API

toolset_association_created

Description

This action is executed just after creating a new association between two posts. Action will be executed when creating a new related content or connecting to an existing one.

Arguments

$relationship_slug. string: Relationship slug.
$parent_id. int: Post ID of the parent element of the relationship.
$child_id. int: Post ID of the child element of the relationship.
$intermediary_id. int: Post ID of the intermediary element of the relationship.
$association_id. int: ID of the new association created.

Output

More Usage examples

Example

// Refreshing WP Super Cache cache for both parent and child posts, in case you have views displaying related content.
add_action( 'toolset_association_created', 'refresh_cache_after_association_created', 10, 5 );
function refresh_cache_after_association_created( $association_slug, $parent_id, $child_id, $intermediary_id, $association_id ) {
    wpsc_delete_post_cache( $parent_id );
    wpsc_delete_post_cache( $child_id );
}

toolset_before_association_delete

Description

This action is executed just before deleting a new association between two posts.

Arguments

$relationship_slug. string: Relationship slug.
$parent_id. int: Post ID of the parent element of the relationship.
$child_id. int: Post ID of the child element of the relationship.
$intermediary_id. int: Post ID of the intermediary element of the relationship.
$association_id. int: ID of the new association created.

Output

More Usage examples

Example

// When an association between two posts gets deleted, add a log record using a custom function myplugin_add_log_entry()
add_action( 'toolset_before_association_delete', 'myplugin_log_association_deleted', 10, 5 ); function myplugin_log_association_deleted( $relationship_slug, $parent_id, $child_id, $intermediary_id, $association_uid ) { myplugin_add_log_entry( "Deleted an association #{$association_uid} in a relationship '{$relationship_slug}' between posts #{$parent_id} and #{$child_id} (with intermediary #{$intermediary_id}" ). }

toolset_connect_posts

Description

Connects posts within a given post relationship.

Arguments

string|string[] $relationship The slug of the relationship or an array with the parent and the child post type of a legacy relationship.
int|WP_Post $parent The parent post to connect.
int|WP_Post $child The child post to connect.
int|WP_Post|null $intermediary Optional. The intermediary post to use for a many-to-many post relationship. If it is not provided and it is needed, a new post will be created.

Output

Returns an array with some of the following elements:

bool 'success': This element is always present. true or false.
string 'message': A message describing the result. May not be always present.
int 'intermediary_post': This element is present only if the operation has succeeded and contains the ID of the newly created intermediary post or zero if there is none.

More Usage examples

Example

// Connect a custom Author post with the ID of "5" to a custom Book post with the ID of "7" in a post relationship between Books and Authors
toolset_connect_posts( 'book-author', 5, 7 );

toolset_disconnect_posts

Description

Disconnects posts within a given post relationship.

Arguments

$relationship - string or array of strings Slug of the relationship or an array with the parent and the child post type of a legacy relationship.
$parent - integer Post ID of the parent post to connect.
$child - integer Post ID of the child post to connect.

Output

Returns true or false.

More Usage examples

Example

// Disconnect a custom Author post with the ID of "5" from a custom Book post with the ID of "7" in a post relationship between Books and Authors
toolset_disconnect_posts( 'book-author', 5, 7 );

toolset_get_parent_post_by_type

Description

Retrieves an ID of the parent post, using a legacy post relationship. Or, if new post relationships are already enabled, relationships migrated from the legacy implementation. For this to work, there needs to be a relationship between $target_type and the provided post’s type. Note: For more complex cases, use toolset_get_related_post() or toolset_get_related_posts() functions.

Arguments

$post - WP_Post|int Post whose parent should be returned.
$target_type - string Parent post type.

Output

int – Post ID or zero if no related post was found.

More Usage examples

Example

$book = get_post( $book_id ); $writer = toolset_get_parent_post_by_type( $book, 'writer' );

toolset_get_related_post

Description

Retrieve an ID of a single related post.

Note: For more complex cases, use toolset_get_related_posts

Arguments

$post - WP_Post|int Post whose related post should be returned.
$relationship - string|string[] Slug of the relationship to query by or an array with the parent and the child post type. The array variant can be used only for legacy relationships (or those migrated from the legacy implementation, after new post relationships are enabled). The relationship slug variant will obviously work only if new post relationships are already enabled.
$role_name_to_return - string Which posts from the relationship should be returned. Accepted values are ‘parent’ and ‘child’. The relationship needs to have only one possible result in this role, otherwise an exception will be thrown. Defaults to ‘parent’.
args array - Additional query arguments. Accepted arguments:
- meta_key, meta_value and meta_compare: Works exactly like in WP_Query. Only limited values are supported for meta_compare ('=' | 'LIKE').
- s: Text search in the posts.
- post_status: Array of post status values, or a string with one or more statuses separated by commas.
  The passed statuses need to be among the values returned by get_post_statuses() or added by the toolset_accepted_post_statuses_for_api filter.
  
  If this argument is not empty, only post with matching status will be returned.

Output

int – Post ID or zero if no related post was found.

More Usage examples

Example

$writer = toolset_get_related_post( $book_id, array( 'writer', 'book' ) );

toolset_get_related_post_types

Description

Get post types related to the provided one.

Arguments

string $return_role - Role that the results have in a relationship.
string $for_post_type - Post type slug in the opposite role.

Output

string[][] - An associative array where each post type has one key, and its value is an array of relationship slugs (in m2m) / post type pairs (in legacy implementation) that have matched the query.

More Usage examples

Example

// If there is a relationship appointment between "Doctor" and "Patient" post types we use the following
toolset_get_related_post_types( 'parent', 'patient' )

// This will return array( 'doctor' => array( 'appointment' ) )

toolset_get_related_posts

Description

Query related posts by a set of conditions.

Note about legacy implementation: By default, this function accepts an argument array as its third parameter ($args), but for backward compatibility reasons, the third argument can be also a query limit, and a number of other arguments is supported. But for the legacy implementation of post relationships (Types 2.3 and below, or before the relationship migration is performed), only the legacy notation of this function is supported. If you need documentation for those, please check the page about the legacy implementation of this function. For our purposes, $args is the argument array and following function parameters are completely ignored.

Arguments

int | \WP_Post | int[] | \WP_Post[] | int[][] | \WP_Post[][] $query_by_elements

One or more posts to query by. Mandatory.

There are several formats accepted:
1. Single post (ID or a post object): The function will return only posts that are connected to this one in the role provided by the 'query_by_role' argument.
2. Array of posts indexed by role names: The function will return only posts that are connected to any of these posts in given roles.
3. Arrays of arrays of posts indexed by role names: The function will return only posts that are connected to any of the provided posts for each role.
  Example:
  array( 'parent' => array( $parent1, $parent2 ), 'intermediary' => $intermediary1 )
  This returns posts connected to $parent1 or $parent2 in the parent role, and to the $intermediary1 in the intermediary role.
string | string[] $relationship

Slug of the relationship to query by or an array with the parent and the child post type. Mandatory.

Note: The array variant can be used only to identify relationships that have been migrated from the legacy implementation.
int | array $args

Array of arguments. All these arguments are optional unless explicitly stated otherwise.
1. string query_by_role: Name of the element role to query by. This argument is required if a single post is provided in $query_by_elements, and in other cases, it must not be present at all. Accepted values: 'parent' | 'child' | 'intermediary'.
2. int limit: Maximum number of returned results ("posts per page"). Default value is 100.
3. int offset: Result offset (number of post to displace or pass over). Default value is 0.
4. array args: Additional query arguments to narrow down the search. Accepted arguments:
  - meta_key, meta_value and meta_compare: Works exactly like in WP_Query. Only limited values are supported for meta_compare ('=' | 'LIKE').
  - s: Text search in the posts.
  - post_status: Array of post status values, or a string with one or more statuses separated by commas.
    Note: The passed statuses need to be among the values returned by get_post_statuses() or added by the toolset_accepted_post_statuses_for_api filter. If this argument is not empty, only post with matching status will be returned.
5. string return: Determines return type. 'post_id' for array of post IDs, 'post_object' for an array of \WP_Post objects. By default, post IDs are returned.
6. string | array role_to_return: Which posts from the relationship should be returned. Accepted values are 'parent' | 'child' | 'intermediary' | 'all' or an array of them.
  Note: If the query_by_role argument is 'parent' or 'child', it is also possible to pass 'other' here.
7. null | string orderby: Determine how the results will be ordered. Accepted values: null | 'title' | 'meta_value' | 'meta_value_num' | 'rfg_order'.
  Note: If you use the 'meta_value' and 'meta_value_num' there also needs to be a 'meta_key' argument in the search arguments (args).
  
  'rfg_order' is applicable only for repeatable field groups and it means the order which has been set manually by the user. Using it overrides the 'meta_key' value in 'args'.
  
  'null' is default and means no ordering.
8. string order: Accepted values: 'ASC' | 'DESC', ascending order is default.
9. string orderby_role: Name of the role by which ordering should happen. If no value is provided, the first value from the 'role_to_return' argument will be used.
10. bool need_found_rows: Signal if the query should also determine the total number of results (disregarding pagination). Default is false

Output

int[] | \WP_Post[] | array

If need_founds_rows is true, the array returned will be an array [ 'results' => $actual_results, 'found_rows' => $n ].

Otherwise, only $actual_results will be returned directly (array of post IDs or posts according to the return argument).

More Usage examples

Example


// Get books which are children of the selected $writer in the
// legacy/migrated relationship between "writer" and "book" post types
// and that contain the string "Harry".
// This returns WP_Post objects, and the results are paginated.

/** @var WP_Post[] $books */
$books = toolset_get_related_posts(
// get posts related to this one
$writer,

// Relationship between the posts
array( 'writer', 'book' ),

// Additional arguments
[
// Get posts where $writer is the parent in given relationship.
// This is mandatory because we're passing just a single $writer post as the first parameter.
'query_by_role' => 'parent',

// pagination
'limit' => $posts_per_page,
'offset' => ( $current_page - 1 ) * $post_per_page,

// How was his surname, again…? Search posts by the string "Harry".
'args' => [ 's' => 'Harry' ],

'role_to_return' => 'other'
'return' => 'post_object'
]
);

// --------------------------------------------------

// Get sets of connected posts in a "Doctor-patient appointments"
// many-to-many relationship (with intermediary posts) where
// a connection between a specific patient
// and one of two specific doctors exists.

$connected_posts = toolset_get_related_posts(
// $doctor1, $doctor2 and $patient can be either WP_Post objects or post IDs.
[
'parent' => [ $doctor1, $doctor2 ],
'child' => $patient
],

// Relationship slug.
'doctor_patient_appointments',

// Additional arguments.
[
'role_to_return' => 'all'
]
);

// The results might look like:
$connected_posts = [
// Each array here represents one connection between posts.
[
'parent' => 41, // ID of the Doctor post
'child' => 55, // ID of the Patient post
'intermediary' => 156, // ID of the intermediary post which represents the Appointment
],
[
'parent' => 43,
'child' => 57,
'intermediary' => 135,
],
// ...
];

// --------------------------------------------------

// Get first five books related to a particular writer that have
// a specific custom post status.
// Also include the total number of such books.

define( 'MY_CUSTOM_POST_STATUS', 'my_custom_post_status' );

// Allow querying by the custom post status.
add_filter( 'toolset_accepted_post_statuses_for_api', function( $accepted_statuses ) {
$accepted_statuses[] = MY_CUSTOM_POST_STATUS;
return $accepted_statuses;
});

$book_results = toolset_get_related_posts(
// Post representing a writer (or post ID), to which the results should be related.
$writer,

// Relationship slug.
'book_authorship',

// Additional arguments.
[
// Search arguments for the book posts.
'args' => [ 'post_status' => MY_CUSTOM_POST_STATUS ],

'need_found_rows' => true,
'limit' => 5,
]
);

// Parse results.
$total_custom_status_book_count = $book_results['found_rows'];
$books = $book_results['results'];

// --------------------------------------------------

// Retrieve books from a particular writer that are written in a selected language
// (here, the language is stored in a Types field "book-language").
// Order results by titles.

$books = toolset_get_related_posts(
// Post representing a writer (or post ID),
// to which the results should be related.
$writer,

// Relationship slug.
'book_authorship',

// Additional arguments.
[
// Specify the role to query by and to return.
// Notice that we can use "other" in this situation.
'query_by_role' => 'parent',
'role_to_return' => 'other',

// Search by a value of postmeta.
'args' => [
// Use a meta_key of a Types field,
// which by default uses the "wpcf-" prefix.
'meta_key' => 'wpcf-book-language',
'meta_value' => 'Czech',
'meta_compare' => 'LIKE',
],

// Ordering
'orderby' => 'title',
'order' => 'ASC'
]
);

toolset_get_related_posts (legacy)

Description

This is documentation for legacy implementation of toolset_get_related_posts()

Query related posts by a set of conditions.

Arguments

$query_by_element – int|\WP_Post Post to query by. All results will be posts connected to this one.
$relationship – string|string[] Slug of the relationship to query by or an array with the parent and the child post type. The array variant can be used only for legacy relationships (or those migrated from the legacy implementation, after new post relationships are enabled). The relationship slug variant will obviously work only if the new post relationships are already enabled.
$query_by_role_name – string Name of the element role to query by. Accepted values: ‘parent’|’child’|’intermediary’.
$limit – int Maximum number of returned results (“posts per page”).
$args – array Additional query arguments. Accepted arguments:
- meta_key, meta_value and meta_compare: Works exactly like in WP_Query. Only limited values are supported for meta_compare at the moment (‘=’|’LIKE’).
- s: Text search in the posts.
$return – string Determines return type. ‘post_id’ for array of post IDs, ‘post_object’ for an array of WP_Post objects.
$role_name_to_return – string Determines which posts from the relationship should be returned. Accepted values are ‘parent’|’child’|’intermediary’, but the value must be different from $query_by_role_name. If $query_by_role_name is ‘parent’ or ‘child’, it is also possible to pass ‘other’ here.
$orderby – null|string Determine how the results will be ordered. Accepted values: null, ‘title’, ‘meta_value’, ‘meta_value_num’. If the latter two are used, there also needs to be a ‘meta_key’ argument in $args. Passing null means no ordering.
$order – string Accepted values: ‘ASC’ or ‘DESC’.
$need_found_rows – bool Signal if the query should also determine the total number of results (disregarding pagination).
$found_rows – null|&int If $need_found_rows is set to true, the total number of results will be set into the variable passed to this parameter.

Output

int[]|\WP_Post[] – An array of post objects or post IDs that match the parameters.

More Usage examples

Example

// Get books which are children of the selected $writer in the
// legacy/migrated relationship between "writer" and "book" post types
// and that contain the string "Harry".
// This returns WP_Post objects, and the results are paginated.

/** @var WP_Post[] $books */
$books = toolset_get_related_posts(
$writer, // get posts related to this one
array( 'writer', 'book' ), // relationship between the posts
'parent', // get posts where $writer is the parent in given relationship
$posts_per_page, $current_page, // pagination
array( 's' => 'Harry' ), // How was his surname, again…?
'post_object'
);

toolset_get_relationship

Description

Get extended information about a single relationship definition.

Arguments

$identification - Relationship slug or a pair of post type slugs identifying a legacy relationship.

Output

array|null - Relationship information or null if it doesn't exist.

The relationship array contains following elements:

Elements of the relationhship array

array(
    'slug' (only if m2m is enabled) => Unique slug identifying the relationship.
    'labels' (only if m2m is enabled) => array(
        'plural' => Plural display name of the relationship.
        'singular' => Singular display name of the relationship.
    ),
    'roles' => array(
        'parent' => array(
            'domain' => Domain of parent elements. Currently, only 'posts' is supported.
            'types' => Array of (post) types involved in a single relationship. Currently,
 there's always only a single post type, but that may change in the future.
        ),
        'child' => Analogic to the parent role information.
        'intermediary' (present only if m2m is enabled and if the relationship 
		is of the many-to-many type) 
		=> Analogic to the parent role information. The domain is always 'posts' and
there is always a single post type.
    ),
    'cardinality' => array(
        'type' => 'many-to-many'|'one-to-many'|'one-to-one',
        'limits' => array(
            'parent' => array(
                'min' => The minimal amount of connected parent ("left side") posts for
each child ("right side") post. Currently, this is always 0, 
but it may change in the future.
                'max' => The maximal amount of connected parent posts for each child
post. If there is no limit, it's represented by the value -1.
            ),
            'child' => Analogic to the parent role information.
        )
    ),
    'origin' => 'post_reference_field'|'repeatable_group'|'standard' 
How was the relationship created. "standard" is the standard one.
)

More Usage examples

Example

$relationship = toolset_get_relationship('tracks-of-an-album');

Reference

toolset_association_created

toolset_before_association_delete

toolset_connect_posts

toolset_disconnect_posts

toolset_get_parent_post_by_type

toolset_get_related_post

toolset_get_related_post_types

toolset_get_related_posts

toolset_get_related_posts (legacy)

toolset_get_relationship