WordPress/wp-includes/fonts/class-wp-font-face-resolver.php
hellofromTonya 8c4c35311b Introduce font-face styles generator and printer.
Introducing Font Face, a server-side `@font-face` styles generator and printer. 

tl;dr:
* Introduces Font Face.
* Deprecates `_wp_theme_json_webfonts_handler()`.

**Introduce Font Face**

From an array of fonts (i.e. each font-family and its font variations to be processed), it:

1. Validates each `font-face` declaration, i.e. the CSS property and value pairing. If validation fails, processing stops with no font-face styles printed.
3. Generates the `@font-face` CSS for each font-family.
4. Prints the CSS within a `<style id="wp-fonts-local">` element.

The entry point into Font Face is through a new global function called `wp_print_font_faces()`, which is automatically called:

* when the `'wp_head'` hook runs (for the front-end).
* when the `'admin_print_styles'` hook runs (for the back-end).
* when `_wp_get_iframed_editor_assets()` runs to inject the `@font-face` styles into the iframed editor.

Once called, it gets the fonts from Theme_JSON merged data layer, which includes theme defined fonts and user activated fonts (once the Font Library #59166 is introduced into Core).

For classic sites, themes and plugins can directly call `wp_print_font_faces()` and pass their fonts array to it for processing.

**Deprecates `_wp_theme_json_webfonts_handler()`.**

As Font Face is a direct replacement, the stopgap code in `_wp_theme_json_webfonts_handler()` (introduced in 6.0.0 via [53282]) is deprecated and unused in Core.

**Props note:**
There's a long multiple year history baked into Font Face, which dates back to the early versions of a web font API (see #46370 and [https://github.com/WordPress/gutenberg/issues/41479 roadmap]. The props list includes those who contributed from those early versions up to this commit.

**References:**
* #46370 original (Web)Fonts API proposal for registering and enqueuing web fonts.
* [https://github.com/WordPress/gutenberg/issues/41479 Gutenberg tracking issue] which includes the evolution from Webfonts API to Fonts API to Font Face.
* [53282] / #55567 Added the stopgap code `_wp_theme_json_webfonts_handler()` in 6.0.
* [https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face @font-face on mdn web docs]
* #59166 Font Library: Font manager for WordPress

Follow-up to [53282].

Props aristath, jonoaldersonwp, hellofromTonya, andraganescu, annezazu, antonvlasenko, arena, askdesign, azaozz, bph, bradley2083, colorful-tones, costdev, davidbaumwald, desrosj, dingo_d, djcowan, domainsupport, dryanpress, elmastudio, flixos90, francina, garrett-eclipse, gigitux, grantmkin, grapplerulrich, gziolo, ironprogrammer, jb510, jeffpaul, jeremyyip, jffng, joostdevalk, jorgefilipecosta, juanmaguitar, mamaduka, matveb, mburridge, mitogh, ndiego, ntsekouras, oandregal, ocean90, oglekler, paaljoachim, pagelab, peterwilsoncc, poena, priethor, scruffian, SergeyBiryukov, shiloey, simison, skorasaurus, soean, westonruter, wildworks, zaguiini.
Fixes #59165.
Built from https://develop.svn.wordpress.org/trunk@56500


git-svn-id: http://core.svn.wordpress.org/trunk@56012 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2023-08-31 21:49:20 +00:00

155 lines
4.2 KiB
PHP

<?php
/**
* WP_Font_Face_Resolver class.
*
* @package WordPress
* @subpackage Fonts
* @since 6.4.0
*/
/**
* The Font Face Resolver abstracts the processing of different data sources
* (such as theme.json) for processing within the Font Face.
*
* This class is for internal core usage and is not supposed to be used by
* extenders (plugins and/or themes).
*
* @access private
*/
class WP_Font_Face_Resolver {
/**
* Gets fonts defined in theme.json.
*
* @since 6.4.0
*
* @return array Returns the font-families, each with their font-face variations.
*/
public static function get_fonts_from_theme_json() {
$settings = wp_get_global_settings();
// Bail out early if there are no font settings.
if ( empty( $settings['typography']['fontFamilies'] ) ) {
return array();
}
return static::parse_settings( $settings );
}
/**
* Parse theme.json settings to extract font definitions with variations grouped by font-family.
*
* @since 6.4.0
*
* @param array $settings Font settings to parse.
* @return array Returns an array of fonts, grouped by font-family.
*/
private static function parse_settings( array $settings ) {
$fonts = array();
foreach ( $settings['typography']['fontFamilies'] as $font_families ) {
foreach ( $font_families as $definition ) {
// Skip if font-family "name" is not defined.
if ( empty( $definition['name'] ) ) {
continue;
}
// Skip if "fontFace" is not defined, meaning there are no variations.
if ( empty( $definition['fontFace'] ) ) {
continue;
}
$font_family = $definition['name'];
// Prepare the fonts array structure for this font-family.
if ( ! array_key_exists( $font_family, $fonts ) ) {
$fonts[ $font_family ] = array();
}
$fonts[ $font_family ] = static::convert_font_face_properties( $definition['fontFace'], $font_family );
}
}
return $fonts;
}
/**
* Converts font-face properties from theme.json format.
*
* @since 6.4.0
*
* @param array $font_face_definition The font-face definitions to convert.
* @param string $font_family_property The value to store in the font-face font-family property.
* @return array Converted font-face properties.
*/
private static function convert_font_face_properties( array $font_face_definition, $font_family_property ) {
$converted_font_faces = array();
foreach ( $font_face_definition as $font_face ) {
// Add the font-family property to the font-face.
$font_face['font-family'] = $font_family_property;
// Converts the "file:./" src placeholder into a theme font file URI.
if ( ! empty( $font_face['src'] ) ) {
$font_face['src'] = static::to_theme_file_uri( (array) $font_face['src'] );
}
// Convert camelCase properties into kebab-case.
$font_face = static::to_kebab_case( $font_face );
$converted_font_faces[] = $font_face;
}
return $converted_font_faces;
}
/**
* Converts each 'file:./' placeholder into a URI to the font file in the theme.
*
* The 'file:./' is specified in the theme's `theme.json` as a placeholder to be
* replaced with the URI to the font file's location in the theme. When a "src"
* beings with this placeholder, it is replaced, converting the src into a URI.
*
* @since 6.4.0
*
* @param array $src An array of font file sources to process.
* @return array An array of font file src URI(s).
*/
private static function to_theme_file_uri( array $src ) {
$placeholder = 'file:./';
foreach ( $src as $src_key => $src_url ) {
// Skip if the src doesn't start with the placeholder, as there's nothing to replace.
if ( ! str_starts_with( $src_url, $placeholder ) ) {
continue;
}
$src_file = str_replace( $placeholder, '', $src_url );
$src[ $src_key ] = get_theme_file_uri( $src_file );
}
return $src;
}
/**
* Converts all first dimension keys into kebab-case.
*
* @since 6.4.0
*
* @param array $data The array to process.
* @return array Data with first dimension keys converted into kebab-case.
*/
private static function to_kebab_case( array $data ) {
foreach ( $data as $key => $value ) {
$kebab_case = _wp_to_kebab_case( $key );
$data[ $kebab_case ] = $value;
if ( $kebab_case !== $key ) {
unset( $data[ $key ] );
}
}
return $data;
}
}