wp-​Typography API

While wp-​Typography is set up to pro­vide the best pos­si­ble ex­pe­ri­ence “out of the box”, Word­Press is an open sys­tem and some­times, as a theme or plu­g­in de­vel­op­er, you need to fine-​tune the re­sults. To this end, wp-​Typography pro­vides sev­er­al func­tions and fil­ter hooks.

In­tro­duc­tion

Al­though wp-​Typography in­cludes a va­ri­ety of fil­ters to make your web­page look good, it may be nec­es­sary to add fil­ters to ar­eas not cov­ered by the de­faults. In or­der to do this, you cur­rent­ly have use code sim­i­lar to this:

add_filter('some_custom_hook', [ 'WP_Typography', 'process' ] ); 

If you don't want to apply the full list of typographic adjustments (most notably hyphenation), but want to get smart quotes and characters, you can use the filter_feed method instead.

add_filter('some_custom_hook', [ 'WP_Typography', 'process_feed' ] ); 

Sometimes, you may like to apply slightly different settings to a particular string. You can do that as well. In this example, only really long words should be hyphenated:

$s = WP_Typography::get_user_settings();
$s->set_min_length_hyphenation( 10 );

$hyphenated_title = WP_Typography::process_title( $title_with_big_words, $s );

Note

Prior to wp-Typography 5.3.0, WP_Typography::process et al. could only be called on the object returned by WP_Typography::get_instance() and for static calls their WP_Typography::filter aliases had to be used. These aliases have been deprecated as of 5.3.0 and will be removed entirely with the release of wp-Typography 6.0.0.

Available Functions

Content Filtering

WP_Typography::process

Process content text fragment. Available since version 4.0.0.

Returns the processed string.

Parameters:

  • string $text: Required. The HTML fragment to process.
  • bool $is_title: Optional. Whether the rules for titles should be applied. Default false.
  • bool $is_feed: Optional. Whether to force processing according to feed rules. Default false.
  • \PHP_Typography\Settings $settings: Optional. A settings object. Default null (which means the internal settings will be used).

WP_Typography::process_title

Process title text fragment. Available since version 4.0.0.

Returns the processed string.

Parameters:

  • string $text: Required.
  • \PHP_Typography\Settings $settings: Optional. A settings object. Default null (which means the internal settings will be used).

WP_Typography::process_title_parts

Process title parts and strip ­ and zero-width space. Available since version 4.0.0.

Returns the processed string.

Parameters:

  • string[] $title_parts: Required. An array of strings.
  • \PHP_Typography\Settings $settings: Optional. A settings object. Default null (which means the internal settings will be used).

WP_Typography::process_feed

Process content text fragment as RSS feed (limiting HTML features to most widely compatible ones). Available since version 4.0.0.

Returns the processed string.

Parameters:

  • string $text: Required.
  • bool $is_title: Optional. Whether the rules for titles should be applied. Default false.
  •  \PHP_Typography\Settings $settings: Optional. A settings object. Default null (which means the internal settings will be used).

WP_Typography::process_feed_title

Process title text fragment as RSS feed (limiting HTML features to most widely compatible ones). Available since version 4.0.0.

Returns the processed string.

Parameters:

  • string $text: Required.
  •  \PHP_Typography\Settings $settings: Optional. A settings object. Default null (which means the internal settings will be used).

Settings

WP_Typography::get_user_settings

Retrieves a copy of the preferences set by the user via the plugin settings screen. Available since version 4.0.0.

Returns an instance of \PHP_Typography\Settings.

Parameters: none.

WP_Typography::get_hyphenation_languages

Retrieves the list of valid hyphenation languages. Available since version 4.0.0. Since version 5.0.0, the language names are translated and the list is cached.

Returns an array in the form of ( $lang_code => $language).

Parameters: none.

WP_Typography::get_diacritic_languages

Retrieves the list of valid diacritic replacement languages. Available since version 4.0.0. Since version 5.0.0, the language names are translated and the list is cached.

Returns an array in the form of ( $lang_code => $language ).

Parameters: none.

Meta Functions

WP_Typography::get_instance

Retrieve the plugin singleton. Normally, it is not necessary to directly use this function. Available since version 3.2.0.

Returns an instance of WP_Typography.

Parameters: none.

Filter Hooks

Processing-related Filters

typo_settings

Filters the settings object used for processing the text fragment. (Be careful not to change the default settings object.) Available since version 5.0.0.

Parameters:

  • \PHP_Typography\Settings $settings: The settings instance.

typo_current_locale

Filters the current locale for wp-Typography. Return a non-empty string to short-circuit the automatic locale detection. Available since version 5.0.0.

Parameters:

  • string $locale Default ''.

typo_match_hyphenate_language

Filters the matched language. Available since version 5.0.0.

Parameters:

  • string $match: The matched PHP-Typography language code. Default ''.
  • array  $languages: An array in the form of ( $lang_code => $language ),
  • string $locale: The current locale, separated with a dash (e.g. 'en-US').
  • string $language: The current two-letter language code (e.g. 'en').

typo_match_diacritic_language

Filters the matched language. Available since version 5.0.0.

Parameters:

  • string $match: The matched PHP-Typography language code. Default ''.
  • array  $languages: An array in the form of ( $lang_code => $language ),
  • string $locale: The current locale, separated with a dash (e.g. 'en-US').
  • string $language: The current two-letter language code (e.g. 'en').

typo_enable_french_punctuation_spacing_for_locale

Filters the setting for French punctuation spacing for the current locale. Available since version 5.0.0.

Parameters:

  • bool $enable: Whether French punctuation spacing should be enabled.
  • string $locale: The current locale with '-' as the separating character (e.g. 'en-US').

typo_dash_style_for_locale

Filters the dash style for the current locale. The returned value has to be a valid style constant from \PHP_Typography\Settings\Dash_Style. Available since version 5.0.0.

Parameters:

  • string|Dash $dash_style: A style constant (Dash_Style::TRADITIONAL_US or Dash_Style::INTERNATIONAL) or object.
  • string $locale: The current locale with '-' as the separating character (e.g. 'en-US').

typo_primary_quote_style_for_locale

Filters the primary quote style for the current locale. The returned value has to be a valid style constant from \PHP_Typography\Settings\Quote_Style or a \PHP_Typography\Settings\Quotes instance. Available since version 5.0.0.

Parameters:

  • string|Quotes $primary: A quote style constant or object.
  • string $locale: The current locale with '-' as the separating character (e.g. 'en-US').

typo_secondary_quote_style_for_locale

Filters the secondary quote style for the current locale. The returned value has to be a valid style constant from \PHP_Typography\Settings\Quote_Style or a \PHP_Typography\Settings\Quotes instance. Available since version 5.0.0.

Parameters:

  • string|Quotes $primary: A quote style constant or object.
  • string $locale: The current locale with '-' as the separating character (e.g. 'en-US').

Meta Filters

typo_filter_priority

Filters the priority used for wp-Typography's text processing filters. When NextGen Gallery is detected, the priority is set to PHP_INT_MAX. Available since version 3.2.0.

Parameters:

  • int $priority: The filter priority. Default 9999.

typo_disable_filtering

Disable automatic filtering by wp-Typography. Available since version 3.6.0.

Parameters:

  • bool $disable: Whether to disable automatic filtering. Default false.
  • string $filter_group: Which filters to disable. Possible values 'content', 'heading', 'title', and 'acf'.

Error Handling

typo_ignore_parser_errors

Filter whether HTML parser errors should be silently ignored. The resulting HTML will be a "best guess" by the parser, like it was before version 3.5.2. Available since version 3.6.0.

Parameters:

  • bool $ignore: Default false.

typo_handle_parser_errors

Filters the HTML parser errors (if there are any). The resulting HTML will be a "best guess" by the parser, like it was before version 3.5.2. Available since version 4.0.0.

Parameters:

  • array $errors: An array of error messages.

Caching

typo_processed_text_caching_duration

Filters the caching duration for processed text fragments. Available since version 3.2.0.

Parameters:

  • int $duration: The duration in seconds. Defaults to 1 day.

typo_php_typography_caching_duration

Filters the caching duration for the PHP_Typography engine state. Available since version 3.2.0.

Parameters:

  • int $duration: The duration in seconds. Defaults to 0 (no expiration).

typo_language_list_caching_duration

Filters the caching duration for the language plugin lists. Available since version 3.2.0.

Parameters:

  • int $duration: The duration in seconds. Defaults to 1 week.
  • string $list: The name language plugin list. Either 'hyphenate_languages' or 'diacritic_languages'.
|

No Comments

Leave a Reply

By posting a comment you consent that we store the submitted information as well as your anonymized IP address on our servers, under the terms of our data protection policy. Your email is never shared with anyone else.

Required fields are marked *.