PHP 8.5: New locale_is_right_to_left function and Locale::isRightToLeft method

Version8.5
TypeNew Feature

The Intl extension in PHP 8.5 adds new functionality to determine if a given locale uses an RTL (Right-to-Left) script.

Arabic, Hebrew, Urdu, and a few other language scripts are written right-to-left. While the list of RTL scripts is relatively small, and new scripts are added only rarely, the new functionality utilizes ICU data, which is consistently updated across other software that rely on ICU data.

The new function locale_is_right_to_left and the static method Locale::isRightToleft both take a string locale name as their only parameter, and returns true or false indicating the script is RTL.

New locale_is_right_to_left function

/**
 * Returns whether the given $locale has an RTL script.
 *  @param string $locale
 *  @return bool Whether the script is RTL
 */
function locale_is_right_to_left(string $locale): bool {}
  • The locale_is_right_to_left function is declared in the global namespace.
  • Passing no parameters throws an ArgumentCountError.
  • Passing an empty string returns false.
  • Passing an invalid locale returns false.

The error handling behavior, for example, on empty an invalid locale, is consistent other other locale_ functions that return false-y return values on invalid inputs.

locale_is_right_to_left('en'); // false
locale_is_right_to_left(''); // false
locale_is_right_to_left('ar'); // true
locale_is_right_to_left('ar-US'); // true
locale_is_right_to_left('he_IL'); // true
locale_is_right_to_left('ar-XY'); // true

New Locale::isRightToLeft static method

The Locale class from the Intl extension in PHP 8.5 also gets a new static method named Locale::isRightToLeft that provides identical functionality and behaves identically to the locale_is_right_to_left function.

class Locale {
  // ...
  /**
   * Returns whether the given $locale has an RTL script.
   * @param string $locale
   * @return bool Whether the script is RTL
   * @alias locale_is_right_to_left
   */
  public static function isRightToLeft(string $locale): bool {}
}
  • Locale::isRightToLeft is a static method.
  • Follows identical error handling to the locale_is_right_to_left function.
Locale::isRightToLeft('en'); // false
Locale::isRightToLeft(''); // false
Locale::isRightToLeft('ar'); // true
Locale::isRightToLeft('ar-US'); // true
Locale::isRightToLeft('ar-XY'); // true

Userland PHP Polyfill

It is possible to mimic the locale_is_right_to_left functionality with a hardcoded list of locales. Because new RTL scripts are rarely introduced to ICU, this is a relatively safe polyfill to make.

The following polyfill checks if the given $locale parameter matches or prefix-matches with a known list of RTL scripts:

  • ar: Arabic
  • dv: Dhivehi
  • he: Hebrew
  • ku-Arab: Kurshish Sorani
  • ps: Pashto
  • fa: Persian (Farsi)
  • sd: Sindhi
  • ur: Urdu
  • yi: Yiddish
/**
 * Returns whether the given $locale has an RTL script.
 *  @param string $locale
 *  @return bool Whether the script is RTL
 */
function locale_is_right_to_left(string $locale): bool {
  return (bool) preg_match('/^(?:ar|he|fa|ur|ps|sd|ug|ckb|yi|dv|ku_arab|ku-arab)(?:[_-].*)?$/i', $locale);
}

Backward Compatibility Impact

  • locale_is_right_to_left is a new PHP function added to the global namespace. Unless a PHP application declares its own function with an identical name, this should not cause any BC impact.
  • Locale::isRightToleft is a new static method added to the Locale class. It is not declared final. Unless a PHP application extends the Locale class with a mismatching method name, this change does not cause any BC impact.

Further, it is possible to bring the locale_is_right_to_left functionality to older PHP versions with a trivial polyfill.


locale_is_right_to_left Locale::isRightToLeftImplementation