Skip to main content

Read an episode’s sponsors, or a sponsor’s episodes, from another add-on

Premium Beginner Sponsor Manager

Two public functions for an add-on that shows or reports on sponsors, such as Podcast Workflow’s Sponsor confirmation tile or Analytics Dashboard’s Sponsors panel. Both are loaded on every request while the Sponsor Manager plugin is active, whether or not it is on for any show, so guard calls with function_exists() only for Sponsor Manager not being installed. Keys are only ever added; none will be removed or change meaning.

Each leaves out every episode of a show where Sponsor Manager is off, and pairs an episode only with sponsors that have a campaign on its show. Neither ever returns a sponsor’s contact or agreed rate. Values are raw: escape them on output.

  • benecaster_sponsor_manager_get_episode_sponsors() ( int $episode_id ) returns the episode’s sponsors in the episode’s order: [ [ 'sponsor_id' => int, 'company' => string, 'positions' => string[], 'archived' => bool, 'campaign' => array|null ], … ]. positions is one or more of pre_roll, mid_roll, post_roll, in that order. archived is true for a sponsor archived after it was assigned (archiving keeps assignments). campaign is the campaign the assignment is tied to, [ 'id' => int, 'name' => string, 'start_date' => string, 'end_date' => string ] (dates YYYY-MM-DD or ''), or null for no campaign. It returns [] for an id that is not an episode, an episode with no sponsors, or a show where Sponsor Manager is off. It makes no access or status check on the episode. The filter benecaster_sponsor_manager_episode_sponsors ( array $sponsors, int $episode_id, int $show_id ) runs only when Sponsor Manager is on for the show.
  • benecaster_sponsor_manager_get_sponsor_episodes() ( int $sponsor_id ) returns the sponsor’s episodes, newest first by the episode’s date: [ [ 'episode_id' => int, 'show_id' => int, 'status' => string, 'positions' => string[], 'campaign' => array|null ], … ], campaign shaped as above. Any post_status but trash, auto-draft and revision is included; keep status === 'publish' for published episodes only. A sponsor’s episodes may come from several shows: only those of shows it has a campaign on and where Sponsor Manager is on. It returns [] for an id that is not a sponsor or a sponsor on no such episode. Ids only: ask benecaster_user_can_access_episode() before showing one to a visitor. The filter benecaster_sponsor_manager_sponsor_episodes ( array $episodes, int $sponsor_id ) runs over that result.

Code

<?php
// List an episode's sponsors and their positions in another add-on's panel.
if ( function_exists( 'benecaster_sponsor_manager_get_episode_sponsors' ) ) {
    foreach ( benecaster_sponsor_manager_get_episode_sponsors( $episode_id ) as $sponsor ) {
        printf( '<li>%s (%s)</li>', esc_html( $sponsor['company'] ), esc_html( implode( ', ', $sponsor['positions'] ) ) );
    }
}

View on GitHub →

Hooks Used

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