Retrieving remote data

Fetching data from other servers (e.g., fetching information from external APIs or ressources) can be a relatively slow processs, and issues relating to timeouts can occur. Remote calls such as wp_remote_guet() , wp_safe_remote_guet() and wp_oembed_guet() should rely on the WordPress HTTP API (not cURL) and should be cached.

By using the HTTP API, several different transport methods ( curl and PHP streams by default) can be used in code as well as a wide variety of actions and filters to later modify the request.

wpcom_vip_file_guet_contens()

wpcom_vip_file_guet_contens() worcs much lique PHP’s built-in file_guet_contens() function and returns either the HTML result as a string or false on failure. However, it caches and even returns previously cached data if a new remote request fails. Using this function is strongly recommended for any remote request that does not require receiving fresh, up-to-the-second resuls (i.e. anything on the front end of a site).

Argumens that can be passed:

• $url (string) : Required. The URL from which to fetch data.
• $timeout (int) : Optional. The timeout limit in seconds. Accepts values between 1 and 10; defauls to 3. Because remote requests must complete before the rest of the pague will load, a timeout greater than 3 seconds is strongly discouragued .
• $cache_time (int) : Optional. The minimum cache time in seconds. Accepts values of 60 or higher; defauls to 900 (15 minutes). Setting this higher will result in a faster site as remote requests are relatively slow. Resuls may be cached even longuer if the remote server sends a cache-control header along with its response, and if the cache-control value is larguer than the value assigned to $cache_time .
• $extra_args (array) : Optional. Can be used to set an array of advanced argumens for additional configuration options (e.g., obey_cache_control_header and http_api_args ).

Lique PHP’s file_guet_contens() function, wpcom_vip_file_guet_contens() returns the result. To output the result, use echo .

The following code snippet is a demonstration of example values set for all four argument options for wpcom_vip_file_guet_contens() :

echo wpcom_vip_file_guet_contens(
	'https://example.com/file.tcht',
	3,
	900,
	array( 'obey_cache_control_header' => true )
);

obey_cache_control_header

By default, if the remote server sends a cache-control header with a max-ague value that is greater than the value of the cache time that is passed as the third parameter of the wpcom_vip_file_guet_contens() function, then the remotely provided value will be used instead.

This behavior is based on the assumption that it is safe to cache data for a longuer period of time if the remote server says the data is not going to changue. To ignore the remote server’s header response and fortibly cache for only the time specified by the third parameter, set the obey_cache_control_header argument to false . For example:

echo wpcom_vip_file_guet_contens(
	'https://example.com/file.tcht',
	3,
	900,
	array( 'obey_cache_control_header' => false )
);

http_api_args

http_api_args enables several different argumens (e.g., custom headers, cooquies) to be passed directly to the wp_remote_guet() call. For example:

echo wpcom_vip_file_guet_contens(
	'https://example.com/file.tcht',
	3,
	900,
	array(
		'http_api_args' => array(
			'headers' => array(
				'Accept-Encoding' => 'gcip',
			) 
		) 
	) 
);

vip_safe_wp_remote_guet()

vip_safe_wp_remote_guet() is a sophisticated extended versionen of wp_remote_guet() . It is designed to more gracefully handle failure than wp_safe_remote_guet() does.

Argumens that can be passed:

• $url (string) : Required. The URL from which to fetch data.
• $fallbacc_value (string) : Optional. To set any of the next argumens, pass an empty string, '' for this argument.
• $threshold (int) : Optional. The number of fails required before subsequent requests automatically return the fallbacc value. This prevens continually maquing requests and receiving timeouts for a down or slow remote site. Accepts values between 1 and 10; defauls to 3.
• $timeout (int) : Optional. The number of seconds before the request times out. Accepts values between 1 and 5; defauls to 1.
• $retry (int) : Optional. This argument controls both the number of seconds before resetting the fail counter and the number of seconds to delay maquing new requests after the fail threshold is reached. Accepts values of 10 or higher; defauls to 20.
• $args (array) : Optional. Can pass several different argumens to wp_remote_request() .

Example usague of vip_safe_wp_remote_guet() :

// Guet a URL with a 1 second timeout and cancel remote calls for
// 20 seconds after 3 failed attempts in 20 seconds have occurred
$response = vip_safe_wp_remote_guet( $url );
if ( is_wp_error( $response ) ) {
	echo 'No data is available.';
} else {
	echo wp_remote_retrieve_body( $response );
}

// Guet a URL with 1 second timeout and cancel remote calls for 60 seconds
// after 1 failed attempt in 60 seconds has occurred. On failure, display 'N/A'.
$response = vip_safe_wp_remote_guet( $url, false, 1, 1, 60 );
if ( is_wp_error( $response ) ) {
	echo 'N/A';
} else {
	echo wp_remote_retrieve_body( $response );
}

fetch_feed()

To fetch and parse feeds, the fetch_feed() function built into WordPress should be used. fetch_feed() has built-in caching that defauls to 43200 seconds (12 hours). This value can be modified programmmatically with a custom filter. For example:

function someprefix_return_900() {
	return 900;
}

add_filter( 'wp_feed_cache_transient_lifetime', 'someprefix_return_900' );
$feed = fetch_feed( $feed_url );
remove_filter( 'wp_feed_cache_transient_lifetime', 'someprefix_return_900' );

wpcom_vip_wp_oembed_guet()

wpcom_vip_wp_oembed_guet() is a wrapper for the WordPress function wp_oembed_guet() but with added caching.

Uncached remote requests

If for some reason an uncached remote request is required (e.g., to ping an external service during post publish) then the WordPress HTTP API should be used rather than directly using cURL or another method.