Skip to main content

Read one guest by id from another add-on

Premium Beginner Guest Manager

For an add-on that keeps a guest’s id and needs the guest as they are now, such as Transcription’s speaker mapping or AI Search. Never read the benecaster_guest post or its meta directly.

benecaster_guest_manager_get_guest() returns [ 'id' => int, 'name' => string, 'title' => string, 'organization' => string, 'website' => string, 'photo_url' => string, 'profile_url' => string, 'bio' => string, 'edit_url' => string ]:

  • The keys of benecaster_guest_manager_get_episode_guests(), with the same meanings, plus photo_url: the guest’s photo at thumbnail size, or '' without one. The guest’s private email is never included.
  • bio: the guest’s bio as plain text: tags (and any script or style) stripped, HTML entities decoded, every run of spaces and line breaks made one space, '' without one. It is meant for search and embedding, such as AI Search; for the formatted bio, use the guest’s page or the [benecaster_guest] shortcode.
  • edit_url: the guest’s record on the Guests screen in Benecaster’s admin, opened on the first show where Guest Manager is on, because the Guests screen is drawn only for such a show. It is returned whoever is viewing: it is an admin address that WordPress refuses to anyone without access, so it tells a visitor nothing the id does not. Show the link only to someone who can open it (current_user_can( 'manage_options' )). It is '' only when Benecaster does not provide benecaster_get_admin_url(). Use it rather than building the address yourself, so the link keeps working if the admin’s routes change.
  • null when the id is not a published guest (an unknown id, a trashed guest, a draft, another post type), and when Guest Manager is off on every show.
  • Not gated by show. Guests are the site’s, not a show’s, so no show is asked about. When you draw the guest on an episode, check that episode’s show yourself with benecaster_addon_is_active() ( 'benecaster-addon-guest-manager', $show_id ), as get_episode_guests() does for you.
  • Values are raw text: escape on output (esc_html(), esc_url()).
  • It is defined on every request while Guest Manager is active, so function_exists() only has to cover Guest Manager not being installed. Keys may be added in later versions; none will be removed or change meaning.

benecaster_guest_manager_guest filters the guest, ( array $guest, int $guest_id ): ?array. It runs only for a guest the function would return. Return null to hide the guest from callers; any other return that is not an array is ignored.

Keeping a guest’s id. Store the id and the name at the time you store it. Show get_guest()‘s current name, and fall back to your stored name when it returns null or Guest Manager is off for the episode’s show. A rename then reaches everything you draw, and a deleted guest leaves the name you saved. To refresh a cache on a rename or deletion, hook benecaster_guest_manager_after_save_guest and benecaster_guest_manager_after_delete_guest.

Code

<?php
// A transcript speaker mapped to a guest: $mapped = [ 'guest_id' => 42, 'name' => 'Alice Smith' ].
function my_addon_speaker_name( array $mapped, int $episode_id ): string {
    $show_id = (int) get_post_field( 'post_parent', $episode_id );
    $guest   = function_exists( 'benecaster_guest_manager_get_guest' )
        && function_exists( 'benecaster_addon_is_active' )
        && benecaster_addon_is_active( 'benecaster-addon-guest-manager', $show_id )
        ? benecaster_guest_manager_get_guest( (int) $mapped['guest_id'] )
        : null;

    return null !== $guest ? $guest['name'] : (string) $mapped['name'];
}

// A search result linking to the guest's record, for administrators only.
$guest = benecaster_guest_manager_get_guest( 42 );
if ( null !== $guest && '' !== $guest['edit_url'] && current_user_can( 'manage_options' ) ) {
    printf( '<a href="%s">%s</a>', esc_url( $guest['edit_url'] ), esc_html( $guest['name'] ) );
}

// Offer the episode's own guests first in a mapping list, then search the roster
// with GET /wp-json/benecaster-guest-manager/v1/guests?search=… (recipe guest-manager-guests-rest, manage_options).
$suggested = function_exists( 'benecaster_guest_manager_get_episode_guests' )
    ? benecaster_guest_manager_get_episode_guests( $episode_id )
    : [];

View on GitHub →

Hooks Used

Need this built rather than just documented? See our services →