Skip to Content
Menu

remote_get()

Get a remote resource and cache the hostname at the same time to prevent needing to manually set transients or duplicate lookups.

PHP March 29, 2021

Usage

PHP
nebula()->remote_get($url, $args)

Parameters

$url
(Required) (String) The URL of the requested resource
Default: None

$args
(Optional) (Array) Parameters for wp_remote_get() such as headers
Default: None

Parameter Notes

For documentation on the $args parameter, see the WordPress documentation for wp_remote_get().

Request or provide clarification »

Examples

Make a simple call to a remote endpoint. Remember to sanitize the return value!

PHP
$response = nebula()->remote_get('https://api.example.com/whatever.json');
if ( is_wp_error($response) ){
    //Do your thing here
}

Make an authenticated request using headers

PHP
$issues = nebula()->remote_get('https://api.github.com/repos/chrisblakley/Nebula/issues?sort=updated', array(
    'headers' => array(
        'Authorization' => 'token ' . nebula()->get_option('github_pat'),
    )
));
if ( is_wp_error($issues) ){
    //Do your thing here
}

Disable some or all remote requests

PHP
//Place this in a functions file to control which remote requests are allowed
add_filter('disable_nebula_remote_get', function($default, $url){
    if ( strpos($url, 'github.com') !== false ){
        return true; //Disable certain remote gets
    }

    return true; //Disable all remote gets
    return false; //Allow all remote gets
}, 10, 2);

Additional Notes

This is basically wp_remote_get() with a caching aspect. If a resource is unavailable, Nebula will not remotely request from that hostname for 10 minutes to maintain quick load times.

Never call this function without following it up with a check for is_wp_error() on the response! Refer to the examples on this page.

Was this page helpful? Yes No


    A feedback message is required to submit this form.


    Please check that you have entered a valid email address.

    Enter your email address if you would like a response.

    Thank you for your feedback!

    Source File

    Located in /libs/Utilities/Utilities.php on line 1135.

    2 Hooks

    Find these filters and actions in the source code below to hook into them. Use do_action() and add_filter() in your functions file or plugin.

    Filters
    "disable_nebula_remote_get"
    Need a new filter hook? Request one here.

    Actions
    "qm/info"
    Need a new action hook? Request one here.

    Note: This function contains 1 to-do comment.

    PHP
            public function remote_get($url, $args=null, $ignore_cache=false){
                if ( apply_filters('disable_nebula_remote_get', false, $url) ){ //Consider a Nebula Option here as well?
                    return new WP_Error('disabled', 'Nebula remote_get has been disabled (for this or all requests).');
                }
    
                //Must be a valid URL
                if ( empty($url) || strpos($url, 'http') !== 0 ){ //@todo "Nebula" 0: Update strpos() to str_contains() in PHP8
                    return new WP_Error('broke', 'Requested URL is either empty or missing acceptable protocol.');
                }
    
                $timer_name = $this->timer('Remote Get (' . $url . ')', 'start', 'Remote Get');
                $hostname = str_replace('.', '_', $this->url_components('hostname', $url));
    
                //Check if the resource was unavailable in the last 10 minutes
                if ( !$ignore_cache ){ //This is useful for debugging– it will always make the remote request regardless of availability of the endpoint
                    if ( !$this->is_available($url, true, false) ){ //We do not want to make 2 requests from this, so we tell is_available() to not make its own request (third parameter is "false")– note that this function also updates the "nebula_site_available..." transient if a problem arises– which will then be seen by is_available().
                        $this->timer($timer_name, 'end');
                        return new WP_Error('unavailable', 'This resource was unavailable within the last 15 minutes.');
                    }
                }
    
                //Get the remote resource
                $response = wp_safe_remote_get($url, $args);
                do_action('qm/info', 'Nebula Remote Get: ' . $url);
                if ( is_wp_error($response) ){
                    set_transient('nebula_site_available_' . $hostname, 'Unavailable', MINUTE_IN_SECONDS*10); //10 minute expiration
                }
    
                //Return the response. Do not set a transient here because failed requests still return here.
                $this->timer($timer_name, 'end');
                return $response;
            }
    

    Override

    This function can not be short-circuited with an override filter. Request one?