Reading relations in bulk
Pro
$book->field( 'writers' ) reads one Book's whole list of Writers, which is what a page about that Book needs. A page that lists twenty Books usually needs less from each: how many Writers it has, the first one, or whether one particular Writer is among them. \VxFramework\Relation answers those for all twenty in one query, without loading their lists.
php
$writers = \VxFramework\Relation::get( 'book_writers' );
$counts = $writers->count_children( $book_ids ); // [ 12 => 3, 15 => 0 ]
$leads = $writers->children( $book_ids, [ 'limit' => 1 ] ); // [ 12 => [ 40 ], 15 => [] ]Naming the relation
Relation::get() takes the field's Relation key: the key the two paired fields share, or the field's own key if you left that setting empty.
The side whose field is Has one or Has many holds the parents, and the Belongs to side holds the children. With a "Writers" field on Books that has many, Books are the parents and Writers the children:
| You have | You want | Call |
|---|---|---|
| Books | the Writers of each | children( $books ) |
| Books | how many Writers each has | count_children( $books ) |
| Writers | the Books of each | parents( $writers ) |
| Writers | how many Books each is on | count_parents( $writers ) |
Each takes a list of ids, WP_Post objects or facades. Each returns an array keyed by the ids you asked about, in the order you gave them, with an entry for every one: an empty list or 0 for an entry that has no links.
Lists come back in the order editors arranged them, as ids. To show the linked posts, load them together with \VxFramework\Post::prime().
Narrowing what comes back
A second argument narrows the read. The three options combine.
status keeps linked posts in that status, or in any of a list of them. A draft stays linked to its Book, so without status it is listed and counted like any other:
php
$counts = $writers->count_children( $book_ids, [ 'status' => 'publish' ] );limit keeps the first few of each entry's list. The database stops reading each list there, so the first Writer of a Book with five hundred costs the same as the first of a Book with two:
php
$leads = $writers->children( $book_ids, [ 'status' => 'publish', 'limit' => 1 ] );include keeps only the linked entries you name, which narrows the read on both sides. This asks which of these Books list this Writer:
php
$on = $writers->children( $book_ids, [ 'include' => [ $writer_id ] ] );
$is_on_first_book = $on[ $book_ids[0] ] !== [];An archive of cards
Twenty Books, each showing how many Writers it has and the name of the first. Each of the two relation reads is one query for all twenty:
php
$books = \VxFramework\Post::query( [ 'post_type' => 'book', 'posts_per_page' => 20 ] );
$writers = \VxFramework\Relation::get( 'book_writers' );
$counts = $writers->count_children( $books, [ 'status' => 'publish' ] );
$leads = $writers->children( $books, [ 'status' => 'publish', 'limit' => 1 ] );
// Load the lead Writers together, then read them from the cache.
\VxFramework\Post::prime( array_merge( ...array_values( $leads ) ) );
foreach ( $books as $book ) {
$id = $book->get_id();
$lead = isset( $leads[ $id ][0] ) ? \VxFramework\Post::get( $leads[ $id ][0] ) : null;
echo esc_html( $book->get_title() );
echo esc_html( $lead ? $lead->get_title() : '' );
echo esc_html( (string) $counts[ $id ] );
}Limits
- Nothing is remembered between calls. Each one queries the database, so call once for the whole list and keep the result.
statusonly applies when the linked entries are posts. For users, every linked user that still exists is returned.limitdoesn't apply to a count.- A link to a post or user that has since been deleted is never listed or counted.
Related
Technical details for LLMs
\VxFramework\Relation::get( string $relation_key, array $kinds = [] )always returns an object.->exists()is false when no field of an active fieldset uses the key; its links, if any are stored, still read.->key(),->parent_kind(),->child_kind().- Kinds come from the fields that use the key: a
has_*field's own entry is the parent, abelongs_to_*field's own entry is the child.$kindsoverrides:[ 'parent' => post | user | term | comment | option_page, 'child' => post | user | term | comment ]. Both default topost. - Reads:
children( array $parents, array $args = [] ),parents( array $children, array $args = [] )→[ id => int[] ];count_children(),count_parents()→[ id => int ]. Repeated ids are answered once; anything that isn't an id, an object withget_id(), or aWP_Post/WP_User/WP_Term/WP_Commentis skipped. $args:status(string or string[];anyis no filter),limit(int, 1 or more; lists only),include(ids on the returned side; an empty list matches nothing and runs no query).- Order:
position, then row id: the order->field()->ids()returns. With no arguments, an entry's list equals->ids()of its relation field. - Cost: one query for every 500 entries asked about; with
limit, one for every 50.