<?php
/**
* This module is not considered part of the public API, only internal.
* Any data or functionality that it produces should be exported by the
* main FontAwesome class and the API documented and semantically versioned there.
*/
namespace FortAwesome;
use \WP_Error, \Error, \Exception;
/**
* Provides metadata about Font Awesome releases.
*
* @noinspection PhpIncludeInspection
*/
// phpcs:ignore Generic.Commenting.DocComment.MissingShort
/**
* @ignore
*/
require_once trailingslashit( FONTAWESOME_DIR_PATH ) . 'includes/class-fontawesome-resource.php';
require_once trailingslashit( FONTAWESOME_DIR_PATH ) . 'includes/class-fontawesome-resourcecollection.php';
require_once trailingslashit( FONTAWESOME_DIR_PATH ) . 'includes/class-fontawesome-metadata-provider.php';
require_once trailingslashit( FONTAWESOME_DIR_PATH ) . 'includes/class-fontawesome-exception.php';
/**
* Provides metadata about Font Awesome releases by querying fontawesome.com.
*
* Theme and plugin developers normally should _not_ access this Release Provider API directly. It's here to support the
* functionality of {@see FontAwesome}.
*/
class FontAwesome_Release_Provider {
/**
* Name of the option that stores the Font Awesome release metadata so we won't query
* the fontawesome.com releases API except when the admin settings page is re-loaded.
*
* @since 4.0.0-rc22
* @ignore
*/
const OPTIONS_KEY = 'font-awesome-releases';
/**
* Name of the transient that stores the cache of the last used Font Awesome
* release so we won't load all of the releases metadata on each page load.
*
* @since 4.0.0-rc4
* @ignore
* @internal
*/
const LAST_USED_RELEASE_TRANSIENT = 'font-awesome-last-used-release';
/**
* Expiry time for the releases transient.
*
* @ignore
* @internal
*/
const LAST_USED_RELEASE_TRANSIENT_EXPIRY = YEAR_IN_SECONDS;
// phpcs:ignore Generic.Commenting.DocComment.MissingShort
/**
* @ignore
*/
protected $releases = null;
// phpcs:ignore Generic.Commenting.DocComment.MissingShort
/**
* @ignore
*/
protected $refreshed_at = null;
// phpcs:ignore Generic.Commenting.DocComment.MissingShort
/**
* @ignore
*/
protected $latest_version = null;
// phpcs:ignore Generic.Commenting.DocComment.MissingShort
/**
* @ignore
*/
protected $latest_version_5 = null;
// phpcs:ignore Generic.Commenting.DocComment.MissingShort
/**
* @ignore
*/
protected $latest_version_6 = null;
// phpcs:ignore Generic.Commenting.DocComment.MissingShort
/**
* @ignore
*/
protected $api_client = null;
// phpcs:ignore Generic.Commenting.DocComment.MissingShort
/**
* @ignore
*/
protected static $instance = null;
/**
* Returns the FontAwesome_Release_Provider singleton instance.
*
* @return FontAwesome_Release_Provider
*/
public static function instance() {
if ( is_null( self::$instance ) ) {
self::$instance = new self();
}
return self::$instance;
}
/**
* Resets the singleton instance referenced by this class and returns that new instance.
* All previous releases metadata held in the previous instance will be abandoned.
*
* @return FontAwesome_Release_Provider
*/
public static function reset() {
self::$instance = null;
return self::instance();
}
/**
* Private constructor.
*
* Requires that releases metadata have already been loaded into the db option.
*
* @ignore
* @internal
* @throws ReleaseMetadataMissingException
*/
private function __construct() {
$option_value = self::get_option();
if ( $option_value ) {
$this->releases = $option_value['data']['releases'];
$this->refreshed_at = $option_value['refreshed_at'];
/**
* Gracefully handle the upgrade scenario from plugin version 4.1.1 where
* there was a "latest", referring to the latest 5.x, but not yet
* keys for "latest_version_5" and "latest_version_6".
*/
$latest_version_5 = isset( $option_value['data']['latest_version_5'] )
? $option_value['data']['latest_version_5']
: ( isset( $option_value['data']['latest'] )
? $option_value['data']['latest']
: null
);
$this->latest_version_5 = $latest_version_5;
$this->latest_version_6 = isset( $option_value['data']['latest_version_6'] )
? $option_value['data']['latest_version_6']
: null;
} else {
throw new ReleaseMetadataMissingException();
}
}
/**
* Loads release metadata and saves to the options table.
*
* Internal use only. Not part of this plugin's public API.
*
* @internal
* @ignore
* @throws ApiRequestException
* @throws ApiResponseException
* @throws ReleaseProviderStorageException
* @return void
*/
public static function load_releases() {
$query = <<< EOD
query {
latest_version_5: release(version: "5.x") {
version
}
latest_version_6: release(version: "6.x") {
version
}
releases {
version
srisByLicense {
free {
path
value
}
pro {
path
value
}
}
}
}
EOD;
$body = json_decode( self::query( $query ), true );
$releases = array();
foreach ( $body['data']['releases'] as $release ) {
$sris = array();
foreach ( $release['srisByLicense'] as $license => $sri_set ) {
$sris[ $license ] = array();
foreach ( $sri_set as $sri ) {
$sris[ $license ][ $sri['path'] ] = $sri['value'];
}
}
$releases[ $release['version'] ] = array(
'sri' => $sris,
);
}
$refreshed_at = time();
$latest_version_5 = isset( $body['data']['latest_version_5']['version'] ) ? $body['data']['latest_version_5']['version'] : null;
$latest_version_6 = isset( $body['data']['latest_version_6']['version'] ) ? $body['data']['latest_version_6']['version'] : null;
if ( is_null( $latest_version_5 ) ) {
throw ApiResponseException::with_wp_error( new WP_Error( 'missing_latest_version_5' ) );
}
if ( is_null( $latest_version_6 ) ) {
throw ApiResponseException::with_wp_error( new WP_Error( 'missing_latest_version_6' ) );
}
$option_value = array(
'refreshed_at' => $refreshed_at,
'data' => array(
'latest_version_5' => $latest_version_5,
'latest_version_6' => $latest_version_6,
'releases' => $releases,
),
);
self::update_option( $option_value );
}
/**
* Internal use only, not part of this plugin's public API.
*
* @internal
* @ignore
* @return FontAwesome_Resource
*/
private function build_resource( $version, $file_basename, $flags = array(
'use_svg' => false,
'use_pro' => false,
) ) {
$full_url = 'https://';
$full_url .= boolval( $flags['use_pro'] ) ? 'pro.' : 'use.';
$full_url .= 'fontawesome.com/releases/v' . $version . '/';
// use the style to build the relative url lookup the relative url.
$relative_url = $flags['use_svg'] ? 'js/' : 'css/';
$relative_url .= $file_basename . '.';
$relative_url .= $flags['use_svg'] ? 'js' : 'css';
$full_url .= $relative_url;
$license = $flags['use_pro'] ? 'pro' : 'free';
// if we can't resolve an integrity_key in this deeply nested lookup, it will remain null.
$integrity_key = null;
if ( isset( $this->releases()[ $version ]['sri'][ $license ][ $relative_url ] ) ) {
$integrity_key = $this->releases()[ $version ]['sri'][ $license ][ $relative_url ];
}
return( new FontAwesome_Resource( $full_url, $integrity_key ) );
}
/**
* Internal use only. Not part of this plugin's public API.
*
* @ignore
* @internal
* @throws ApiTokenMissingException
* @throws ApiTokenEndpointRequestException
* @throws ApiTokenEndpointResponseException
* @throws ApiTokenInvalidException
* @throws AccessTokenStorageException
* @throws ApiRequestException
* @throws ApiResponseException
* @return array
*/
protected static function query( $query ) {
return fa_metadata_provider()->metadata_query( $query, true );
}
/**
* Retrieves Font Awesome releases metadata from the singleton instance.
*
* Makes no network or database requests.
*
* @return array
*/
protected function releases() {
return $this->releases;
}
/**
* Returns the time, in unix epoch seconds when the releases metadata were
* last refreshed, or null for never.
*
* Internal use only. Clients should use the public API method on the
* FontAwesome object.
*
* @ignore
* @internal
* @return null|int
*/
public function refreshed_at() {
return $this->refreshed_at;
}
/**
* Returns a simple array of available Font Awesome versions as strings, sorted in descending version order.
*
* @return array
*/
public function versions() {
$versions = array_keys( $this->releases() );
usort(
$versions,
function( $first, $second ) {
return version_compare( $second, $first );
}
);
return $versions;
}
/**
* Returns an array containing version, shim, source URLs and integrity keys for given params.
* They should be loaded in the order they appear in this collection.
*
* First tries to resolve this by using the LAST_USED_RELEASE_TRANSIENT, without
* instantiating a Release Provider and thus incurring the cost of a trip to
* the database to load the release metadata. If it does need to instantiate
* the Release Provider, it will also populate that transient so that subsequent
* invocations of the function will probably not incur the cost of a database
* query.
*
* @param string $version
* @param array $flags boolean flags, defaults: array('use_pro' => false, 'use_svg' => false, 'use_compatibility' => true)
* @throws ReleaseMetadataMissingException
* @throws ApiRequestException
* @throws ApiResponseException
* @throws ReleaseProviderStorageException
* @throws ConfigCorruptionException when called with an invalid configuration
* @return array
*/
public static function get_resource_collection( $version, $flags = array(
'use_pro' => false,
'use_svg' => false,
'use_compatibility' => true,
) ) {
$resources = array();
if ( ! is_string( $version ) || 0 === strlen( $version ) ) {
throw new ConfigCorruptionException();
}
if ( $flags['use_compatibility'] && ! $flags['use_svg'] && version_compare( '5.1.0', $version, '>' ) ) {
throw ConfigSchemaException::webfont_v4compat_introduced_later();
}
// If this is the same query as last time, then our LAST_USED_RELEASE_TRANSIENT should be current.
$last_used_transient = self::get_last_used_release();
if ( $last_used_transient ) {
// For simplicity, we're require that it's exactly what we're looking for, else we'll re-build and overwrite it.
if (
$version === $last_used_transient['version']
&& $flags['use_pro'] === $last_used_transient['use_pro']
&& $flags['use_svg'] === $last_used_transient['use_svg']
&& $flags['use_compatibility'] === $last_used_transient['use_compatibility']
&& is_array( $last_used_transient['resources'] )
/**
* Checking for all because we only want to use a newer transient whose
* resources is key/value array. So if it's the older version that is
* just a list, we'll fall through and rebuild it below.
*/
&& isset( $last_used_transient['resources']['all'] )
) {
return new FontAwesome_ResourceCollection( $version, $last_used_transient['resources'] );
}
}
$provider = self::instance();
if ( ! array_key_exists( $version, $provider->releases() ) ) {
throw new ReleaseMetadataMissingException();
}
$resources['all'] = $provider->build_resource( $version, 'all', $flags );
if ( $flags['use_compatibility'] ) {
$resources['v4-shims'] = $provider->build_resource( $version, 'v4-shims', $flags );
}
$transient_value = array(
'version' => $version,
'use_pro' => $flags['use_pro'],
'use_svg' => $flags['use_svg'],
'use_compatibility' => $flags['use_compatibility'],
'resources' => $resources,
);
self::update_last_used_release( $transient_value );
return new FontAwesome_ResourceCollection( $version, $resources );
}
/**
* Returns a version number corresponding to the most recent minor release
* in the 5.x line.
*
* Internal use only. Clients should use the FontAwesome::latest_version_5()
* or FontAwesome::latest_version_6() public API methods instead.
*
* @internal
* @ignore
* @deprecated
* @return string|null most recent major.minor.patch 5.x version or null if there's
* not yet been a successful query to the API server for releases metadata.
*/
public function latest_version() {
return $this->latest_version_5;
}
/**
* Returns a version number corresponding to the most recent minor release
* in the 5.x line.
*
* Internal use only. Clients should use the FontAwesome::latest_version_5()
* public API methods instead.
*
* @internal
* @ignore
* @deprecated
* @return string|null most recent major.minor.patch 5.x version or null if there's
* not yet been a successful query to the API server for releases metadata.
*/
public function latest_version_5() {
return $this->latest_version_5;
}
/**
* Returns a version number corresponding to the most recent minor release
* in the 6.x line.
*
* Internal use only. Clients should use the FontAwesome::latest_version_6()
* public API methods instead.
*
* @internal
* @ignore
* @deprecated
* @return string|null most recent major.minor.patch 6.x version or null if there's
* not yet been a successful query to the API server for releases metadata.
*/
public function latest_version_6() {
return $this->latest_version_6;
}
/**
* In multisite mode, we will store the releases metadata just once for the
* whole network in a network option.
*
* Internal use only, not part of this plugin's public API.
*
* @internal
* @ignore
*/
public static function update_option( $option_value ) {
if ( is_multisite() ) {
$network_id = get_current_network_id();
return update_network_option( $network_id, self::OPTIONS_KEY, $option_value );
} else {
return update_option( self::OPTIONS_KEY, $option_value, false );
}
}
/**
* In multisite mode, we will store the releases metadata just once for the
* whole network in a network option.
*
* Internal use only, not part of this plugin's public API.
*
* @internal
* @ignore
*/
public static function get_option() {
if ( is_multisite() ) {
$network_id = get_current_network_id();
return get_network_option( $network_id, self::OPTIONS_KEY );
} else {
return get_option( self::OPTIONS_KEY );
}
}
/**
* Internal use only, not part of this plugin's public API.
*
* @internal
* @ignore
*/
public static function delete_option() {
if ( is_multisite() ) {
$network_id = get_current_network_id();
return delete_network_option( $network_id, self::OPTIONS_KEY );
} else {
return delete_option( self::OPTIONS_KEY );
}
}
/**
* Internal use only, not part of this plugin's public API.
*
* @internal
* @ignore
*/
public static function get_last_used_release() {
return get_transient( self::LAST_USED_RELEASE_TRANSIENT );
}
/**
* Internal use only, not part of this plugin's public API.
*
* @internal
* @ignore
*/
public static function update_last_used_release( $transient_value ) {
return set_transient( self::LAST_USED_RELEASE_TRANSIENT, $transient_value, self::LAST_USED_RELEASE_TRANSIENT_EXPIRY );
}
/**
* Internal use only, not part of this plugin's public API.
*
* @internal
* @ignore
*/
public static function delete_last_used_release() {
return delete_transient( self::LAST_USED_RELEASE_TRANSIENT );
}
}
/**
* Convenience global function to get a singleton instance of the Release Provider.
* Normally, plugins and themes should not need to access this directly.
*
* @see FontAwesome_Release_Provider::instance()
* @return FontAwesome_Release_Provider
*/
function fa_release_provider() {
return FontAwesome_Release_Provider::instance();
}