Skip to main content

benecaster_outlinks_site_link()

Utilities Premium outlinks
benecaster_outlinks_site_link( string $url, array $args = [] ): array|WP_Error

Creates or finds the site-wide Outlinks link for a URL. A site-wide link is a tracked /go/ link that belongs to no show, for a link that is the site’s rather than a show’s: a guest’s book, a sponsor page. Guest Manager’s Track with Outlinks uses it. The link answers at /go/{slug} like any tracked link, with the same affiliate URL, country rules and expiry, and its clicks are reported on Settings → Site-wide Links, never on a show’s Outlinks tab.

It finds first: when a site-wide link already points at exactly the cleaned URL, that link is returned. A show’s tracked link to the same URL is never returned. Otherwise it creates one. See Track a link that belongs to no show and get its /go/ address.

Parameters

Name Type Default Required Description
url string — Yes The destination. Cleaned with esc_url_raw(); it must be an http or https address.
args array [] No Optional slug, the name after /go/ for a new link. Cleaned with sanitize_title() (at most 100 characters). Ignored when an existing link is returned. Without it, Outlinks picks a name from the URL's last path segment (or its host) and makes it free with -2, -3.

Return Value

Type: array|WP_Error

[ 'id' => int, 'slug' => string, 'go_url' => string, 'destination_url' => string, 'affiliate_url' => ?string, 'created' => bool ]. go_url is the address to publish. affiliate_url is null until one is set on Settings → Site-wide Links. created is true when a new link was made and false when a site-wide link to exactly that URL already existed (the oldest, when there are several). A WP_Error for a URL that is not http or https (benecaster_outlinks_url_invalid), an unusable name (benecaster_outlinks_slug_invalid) or a name already taken (benecaster_outlinks_slug_taken, with [ 'suggestion' => string ], a free name, as its data).

Example

// From a handler that has already checked manage_options.
if ( function_exists( 'benecaster_outlinks_site_link' ) ) {
    $link = benecaster_outlinks_site_link( $publication['url'], [ 'slug' => sanitize_title( $publication['title'] ) ] );
    if ( is_wp_error( $link ) && 'benecaster_outlinks_slug_taken' === $link->get_error_code() ) {
        $link = benecaster_outlinks_site_link( $publication['url'], [ 'slug' => $link->get_error_data()['suggestion'] ] );
    }
    if ( ! is_wp_error( $link ) ) {
        $publication['outlinks_id'] = $link['id'];
    }
}

Hooks Fired

Notes

No capability check. It trusts its caller. Call it only from code that has already checked current_user_can( 'manage_options' ), or use the POST /benecaster-outlinks/v1/site-links REST route, which checks for you (see Create, find, list or edit site-wide Outlinks links over REST).

Defined only while Outlinks is switched on for at least one show. It loads with the add-on, so function_exists() answers "installed and running". When it is missing, draw the link's own URL.

Store the plain URL and the id, never the /go/ address in place of the URL. Read the link back with benecaster_outlinks_get_site_link() when you draw it.

Outlinks never deletes a site-wide link. When your stored URL changes, call this function with the new one: you get a new link, and the old one keeps redirecting wherever it was published.

Clicks on a site-wide link fire benecaster_outlinks_click_logged and benecaster_outlinks_before_redirect with $episode_id null. When Outlinks is off for every show or the license has lapsed, the link still redirects to its destination but records nothing.

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