Action Hooks
*
* Fires the following WordPress action hooks:
*
* - `font_awesome_preferences`
*
* Fired when the plugin is ready for clients to register their preferences.
*
* Client plugins and themes should normally use this action hook to call {@see FontAwesome::register()}
* with their preferences.
*
* The hook passes no parameters to its callbacks.
*
* - `font_awesome_enqueued`
*
* Called when a version of Font Awesome has been successfully prepared for enqueuing.
*
* Clients should register a callback on this action to be notified when it is valid to query the FontAwesome
* plugin's metadata using methods such as:
* - {@see FontAwesome::version()} to discover the version of Font Awesome being loaded
* - {@see FontAwesome::pro()} to discover whether a version with Pro icons is being loaded
* - {@see FontAwesome::pseudo_elements()} to discover whether Font Awesome is being loaded with support for svg pseudo-elements
*
*
Internal Use vs. Public API
*
* Developers should take care to notice which functions, methods, classes,
* constants, defines, REST routes, or data structures are indicated as part of
* this plugin's public API and which are not.
*
* A method, for example, being declared in PHP with `public` visibility does not
* indicate its inclusion in the plugin's _public API_.
*
* A method may be declared with public visibility in PHP in order to satisfy
* the language's requirements for access across code modules, or for callbacks.
* Yet this does not mean it can be relied upon as a stable interface by client
* code.
*
* A method that is part of _this plugin's public API_ can be relied upon to
* change, or not change, according to [semantic versioning best practices](https://semver.org/).
* No such conventions apply to a method that is for internal use only, even
* if it is declared `public` in PHP.
*
* Generally, public API members are accessed only from this `FontAwesome` class.
*
* For example, the {@see FontAwesome::releases_refreshed_at()} method provides a way
* to find out when releases metadata were last fetched from `api.fontawesome.com`.
* It delegates to another class internally. But that other class and its methods
* are not part of this plugin's public API. They may change significantly from
* one patch release to another, but no breaking changes would be made to
* {@see FontAwesome::releases_refreshed_at()} without a major version change.
*
* References to "API" in this section refer to this plugin's PHP code or REST
* routes, not to the Font Awesome GraphQL API at `api.fontawesome.com`.
*
* @since 4.0.0
*/
class FontAwesome {
/**
* Name of this plugin's shortcode tag.
*
* @since 4.0.0
*/
public const SHORTCODE_TAG = 'icon';
/**
* Default style prefix.
*
* @since 4.0.0
*/
public const DEFAULT_PREFIX = 'fas';
/**
* Key where this plugin's saved options data are stored in the WordPress options table.
*
* Internal use only, not part of this plugin's public API.
*
* @ignore
* @internal
*/
public const OPTIONS_KEY = 'font-awesome';
/**
* Key where this plugin stores conflict detection data in the WordPress options table.
*
* Internal use only, not part of this plugin's public API.
*
* @internal
* @ignore
*/
public const CONFLICT_DETECTION_OPTIONS_KEY = 'font-awesome-conflict-detection';
/**
* The unique WordPress plugin slug for this plugin.
*
* @since 4.0.0
*/
public const PLUGIN_NAME = 'font-awesome';
/**
* The version of this WordPress plugin.
*
* @since 4.0.0
*/
public const PLUGIN_VERSION = '5.2.1';
/**
* The namespace for this plugin's REST API.
*
* @internal
* @deprecated
* @ignore
*/
public const REST_API_NAMESPACE = self::PLUGIN_NAME . '/v1';
/**
* The name of this plugin's options page, or WordPress admin dashboard page.
*
* @since 4.0.0
*/
public const OPTIONS_PAGE = 'font-awesome';
/**
* GET param used for linking to a particular starting tab in the admin UI.
*
* @ignore
* @internal
*/
public const ADMIN_TAB_QUERY_VAR = 'tab';
/**
* The handle used when enqueuing this plugin's resulting resource.
* Used when this plugin calls either `wp_enqueue_script` or `wp_enqueue_style` to enqueue Font Awesome assets.
*
* @since 4.0.0
*/
public const RESOURCE_HANDLE = 'font-awesome-official';
/**
* The handle used when enqueuing the v4shim.
*
* @since 4.0.0
*/
public const RESOURCE_HANDLE_V4SHIM = 'font-awesome-official-v4shim';
/**
* The handle used when enqueuing the conflict detector.
*
* @ignore
* @internal
*/
public const RESOURCE_HANDLE_CONFLICT_DETECTOR = 'font-awesome-official-conflict-detector';
/**
* The handle used when enqueuing the icon chooser.
*
* @ignore
* @internal
*/
public const RESOURCE_HANDLE_ICON_CHOOSER = 'font-awesome-official-icon-chooser';
/**
* The handle used when enqueuing the bundle for supporting the Classic Editor.
*
* @ignore
* @internal
*/
public const RESOURCE_HANDLE_CLASSIC_EDITOR = 'font-awesome-official-classic-editor';
/**
* The handle used when enqueuing block editor assets.
*
* @ignore
* @internal
*/
public const RESOURCE_HANDLE_FA_BLOCKS = 'font-awesome-official-blocks';
/**
* The source URL for the conflict detector, a feature introduced in Font Awesome 5.10.0.
*
* @ignore
* @internal
*/
public const CONFLICT_DETECTOR_SOURCE = 'https://use.fontawesome.com/releases/v6.6.0/js/conflict-detection.js';
/**
* The custom data attribute added to script, link, and style elements enqueued
* by this plugin when conflict detection is enabled, in order for them to be
* ignored by the conflict detector.
*
* @internal
* @ignore
*/
public const CONFLICT_DETECTION_IGNORE_ATTR = 'data-fa-detection-ignore';
/**
* The base name of the handle used for enqueuing this plugin's admin assets, those required for running
* the admin settings page.
*
* @ignore
* @internal
*/
public const ADMIN_RESOURCE_HANDLE = self::RESOURCE_HANDLE . '-admin';
/**
* Name used for inline data attached to the JavaScript admin bundle.
* Not part of this plugin's public API.
*
* @internal
* @ignore
*/
public const ADMIN_RESOURCE_LOCALIZATION_NAME = '__FontAwesomeOfficialPlugin__';
/**
* Refresh the ReleaseProvider automatically no more often than this
* number of seconds.
*
* Internal use only. Not part of this plugin's public API.
*
* @ignore
* @internal
*/
public const RELEASES_REFRESH_INTERVAL = 10 * 60;
/**
* We will not use a default for version, since we want the version stored in the options
* to always be resolved to an actual version number, which requires that the release
* provider successfully runs at least once. We'll do that upon plugin activation.
*
* @ignore
* @internal
*/
public const DEFAULT_USER_OPTIONS = array(
'usePro' => false,
'compat' => true,
'technology' => 'webfont',
'pseudoElements' => true,
'kitToken' => null,
// whether the token is present, not the token's value.
'apiToken' => false,
'dataVersion' => 4,
);
/**
* Default conflict detection options.
*
* @ignore
* @internal
*/
public const DEFAULT_CONFLICT_DETECTION_OPTIONS = array(
'detectConflictsUntil' => 0,
'unregisteredClients' => array(),
);
/**
* @internal
* @ignore
*/
protected static $instance = null;
/**
* @internal
* @ignore
*/
protected $client_preferences = array();
/**
* @internal
* @ignore
*/
protected $icon_chooser_screens = array( 'post.php', 'post-new.php', 'site-editor.php' );
/**
* @internal
* @ignore
*/
protected $conflicts_by_client = null;
/**
* @internal
* @ignore
*/
protected $screen_id = null;
/**
* This tracks the state of whether, when we process options after the
* plugin upgrades from using the v1 options schema to v2, the former
* removeUnregisteredClients option was set. If so we use some automatic
* conflict detection and resolution, like that old feature worked.
*
* Internal use only, not part of this plugin's public API.
*
* @deprecated
* @internal
* @ignore
*/
protected $old_remove_unregistered_clients = false;
/**
* If true, features required for Block Editor support will be disabled.
*
* Internal use only, not part of this plugin's public API.
*
* @deprecated
* @internal
* @ignore
*/
protected $disable_block_editor_support = false;
/**
* Returns the singleton instance of the FontAwesome plugin.
*
* @since 4.0.0
*
* @see fa()
* @return FontAwesome
*/
public static function instance() {
if ( is_null( self::$instance ) ) {
self::$instance = new self();
}
return self::$instance;
}
/**
* Internal use only, not part of this plugin's public API.
*
* @internal
* @ignore
*/
private function __construct() {
/**
* Determines whether to disable features required for supporting the Block Editor.
*
* @return bool if `true`, disable Block Editor support
* @since 5.0.2
*/
$this->disable_block_editor_support = apply_filters( 'font_awesome_disable_block_editor_support', false );
}
/**
* Returns this plugin's admin page's screen_id. Only valid after the admin_menu hook has run.
*
* Internal only, not part of this plugin's public API.
*
* @ignore
* @internal
*/
public function admin_screen_id() {
return $this->screen_id;
}
/**
* Callback for init.
*
* Main entry point for running the plugin. Called automatically when the plugin is loaded.
*
* Internal use only.
*
* @ignore
* @internal
*/
public function init() {
try {
$this->try_upgrade();
$this->validate_options( fa()->options() );
$this->initialize_rest_api();
if ( is_admin() ) {
$this->initialize_admin();
}
add_shortcode(
self::SHORTCODE_TAG,
array( $this, 'process_shortcode' )
);
if ( $this->is_block_editor_support_enabled() ) {
FontAwesome_SVG_Styles_Manager::register_svg_styles( $this );
block_init();
add_action(
'enqueue_block_assets',
function () {
wp_enqueue_style( FontAwesome_SVG_Styles_Manager::RESOURCE_HANDLE_SVG_STYLES );
}
);
}
try {
$this->gather_preferences();
// phpcs:ignore Generic.CodeAnalysis.EmptyStatement.DetectedCatch
} catch ( PreferenceRegistrationException $e ) {
/**
* Ignore this on normal page loads.
* If something seems amiss, the site owner may try to look
* into it on the plugin settings page where some additional
* diagnostic information may be found.
*/
}
$this->maybe_enqueue_admin_assets();
if ( $this->using_kit() ) {
if ( $this->skip_enqueue_kit() ) {
// Normally, conflict detection is built into a kit.
// However, when not enqueuing the kit, we must enqueue conflict detection separately.
$this->maybe_enqueue_conflict_detection();
} else {
$this->enqueue_kit( $this->options()['kitToken'] );
}
} else {
$resource_collection = $this->cdn_resource_collection_for_current_options();
$this->enqueue_cdn( $this->options(), $resource_collection );
}
} catch ( Exception $e ) {
notify_admin_fatal_error( $e );
} catch ( Error $e ) {
notify_admin_fatal_error( $e );
}
}
/**
* Indicates whether to enqueue the kit.
*
* Internal use only, not part of the plugin's public API.
*
* However, this depends on the `font_awesome_skip_enqueue_kit` filter
* which is part of the public API.
*
* @internal
* @ignore
*/
protected function skip_enqueue_kit() {
/**
* Determines whether to skip the kit enqueue.
*
* When the plugin is configured to use a kit, the normal behavior is
* to use `wp_enqueue_script()` to enqueue the kit's embed code, a JavaScript
* loaded from the Font Awesome Kits CDN. The kit being loaded on front end page
* renderings enables rendering `` tags as Font Awesome icons, for example.
*
* By setting this to `true`, that `wp_enqueue_script()` will be skipped. Thus, the
* kit will not be loaded from the Font Awesome CDN on front end page loads. As a
* consequence, this plugin will not render `` tags as Font Awesome icons.
*
* You may prefer to skip loading the kit if:
*
* 1. You only use the block editor.
*
* As of version 5.0.0 of this plugin, icons are added in the
* block editor as `