[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /**
   4   * Joomla! Content Management System
   5   *
   6   * @copyright  (C) 2007 Open Source Matters, Inc. <https://www.joomla.org>
   7   * @license    GNU General Public License version 2 or later; see LICENSE.txt
   8   */
   9  
  10  namespace Joomla\CMS\Language;
  11  
  12  use Joomla\CMS\Factory;
  13  use Joomla\CMS\HTML\HTMLHelper;
  14  
  15  // phpcs:disable PSR1.Files.SideEffects
  16  \defined('JPATH_PLATFORM') or die;
  17  // phpcs:enable PSR1.Files.SideEffects
  18  
  19  /**
  20   * Text handling class.
  21   *
  22   * @since  1.7.0
  23   */
  24  class Text
  25  {
  26      /**
  27       * JavaScript strings
  28       *
  29       * @var    array
  30       * @since  1.7.0
  31       */
  32      protected static $strings = array();
  33  
  34      /**
  35       * Translates a string into the current language.
  36       *
  37       * Examples:
  38       * `<script>alert(Joomla.Text._('<?php echo Text::_("JDEFAULT", array("script"=>true)); ?>'));</script>`
  39       * will generate an alert message containing 'Default'
  40       * `<?php echo Text::_("JDEFAULT"); ?>` will generate a 'Default' string
  41       *
  42       * @param   string   $string                The string to translate.
  43       * @param   mixed    $jsSafe                Boolean: Make the result javascript safe.
  44       * @param   boolean  $interpretBackSlashes  To interpret backslashes (\\=\, \n=carriage return, \t=tabulation)
  45       * @param   boolean  $script                To indicate that the string will be push in the javascript language store
  46       *
  47       * @return  string  The translated string or the key if $script is true
  48       *
  49       * @since   1.7.0
  50       */
  51      public static function _($string, $jsSafe = false, $interpretBackSlashes = true, $script = false)
  52      {
  53          if (\is_array($jsSafe)) {
  54              if (\array_key_exists('interpretBackSlashes', $jsSafe)) {
  55                  $interpretBackSlashes = (bool) $jsSafe['interpretBackSlashes'];
  56              }
  57  
  58              if (\array_key_exists('script', $jsSafe)) {
  59                  $script = (bool) $jsSafe['script'];
  60              }
  61  
  62              $jsSafe = \array_key_exists('jsSafe', $jsSafe) ? (bool) $jsSafe['jsSafe'] : false;
  63          }
  64  
  65          if (self::passSprintf($string, $jsSafe, $interpretBackSlashes, $script)) {
  66              return $string;
  67          }
  68  
  69          $lang = Factory::getLanguage();
  70  
  71          if ($script) {
  72              static::$strings[$string] = $lang->_($string, $jsSafe, $interpretBackSlashes);
  73  
  74              return $string;
  75          }
  76  
  77          return $lang->_($string, $jsSafe, $interpretBackSlashes);
  78      }
  79  
  80      /**
  81       * Checks the string if it should be interpreted as sprintf and runs sprintf over it.
  82       *
  83       * @param   string   &$string               The string to translate.
  84       * @param   mixed    $jsSafe                Boolean: Make the result javascript safe.
  85       * @param   boolean  $interpretBackSlashes  To interpret backslashes (\\=\, \n=carriage return, \t=tabulation)
  86       * @param   boolean  $script                To indicate that the string will be push in the javascript language store
  87       *
  88       * @return  boolean  Whether the string be interpreted as sprintf
  89       *
  90       * @since   3.4.4
  91       */
  92      private static function passSprintf(&$string, $jsSafe = false, $interpretBackSlashes = true, $script = false)
  93      {
  94          // Check if string contains a comma
  95          if (empty($string) || strpos($string, ',') === false) {
  96              return false;
  97          }
  98  
  99          $lang = Factory::getLanguage();
 100          $string_parts = explode(',', $string);
 101  
 102          // Pass all parts through the Text translator
 103          foreach ($string_parts as $i => $str) {
 104              $string_parts[$i] = $lang->_($str, $jsSafe, $interpretBackSlashes);
 105          }
 106  
 107          $first_part = array_shift($string_parts);
 108  
 109          // Replace custom named placeholders with sprintf style placeholders
 110          $first_part = preg_replace('/\[\[%([0-9]+):[^\]]*\]\]/', '%\1$s', $first_part);
 111  
 112          // Check if string contains sprintf placeholders
 113          if (!preg_match('/%([0-9]+\$)?s/', $first_part)) {
 114              return false;
 115          }
 116  
 117          $final_string = vsprintf($first_part, $string_parts);
 118  
 119          // Return false if string hasn't changed
 120          if ($first_part === $final_string) {
 121              return false;
 122          }
 123  
 124          $string = $final_string;
 125  
 126          if ($script) {
 127              foreach ($string_parts as $i => $str) {
 128                  static::$strings[$str] = $string_parts[$i];
 129              }
 130          }
 131  
 132          return true;
 133      }
 134  
 135      /**
 136       * Translates a string into the current language.
 137       *
 138       * Examples:
 139       * `<?php echo Text::alt('JALL', 'language'); ?>` will generate a 'All' string in English but a "Toutes" string in French
 140       * `<?php echo Text::alt('JALL', 'module'); ?>` will generate a 'All' string in English but a "Tous" string in French
 141       *
 142       * @param   string   $string                The string to translate.
 143       * @param   string   $alt                   The alternate option for global string
 144       * @param   mixed    $jsSafe                Boolean: Make the result javascript safe.
 145       * @param   boolean  $interpretBackSlashes  To interpret backslashes (\\=\, \n=carriage return, \t=tabulation)
 146       * @param   boolean  $script                To indicate that the string will be pushed in the javascript language store
 147       *
 148       * @return  string  The translated string or the key if $script is true
 149       *
 150       * @since   1.7.0
 151       */
 152      public static function alt($string, $alt, $jsSafe = false, $interpretBackSlashes = true, $script = false)
 153      {
 154          if (Factory::getLanguage()->hasKey($string . '_' . $alt)) {
 155              $string .= '_' . $alt;
 156          }
 157  
 158          return static::_($string, $jsSafe, $interpretBackSlashes, $script);
 159      }
 160  
 161      /**
 162       * Like Text::sprintf but tries to pluralise the string.
 163       *
 164       * Note that this method can take a mixed number of arguments as for the sprintf function.
 165       *
 166       * The last argument can take an array of options:
 167       *
 168       * array('jsSafe'=>boolean, 'interpretBackSlashes'=>boolean, 'script'=>boolean)
 169       *
 170       * where:
 171       *
 172       * jsSafe is a boolean to generate a javascript safe strings.
 173       * interpretBackSlashes is a boolean to interpret backslashes \\->\, \n->new line, \t->tabulation.
 174       * script is a boolean to indicate that the string will be push in the javascript language store.
 175       *
 176       * Examples:
 177       * `<script>alert(Joomla.Text._('<?php echo Text::plural("COM_PLUGINS_N_ITEMS_UNPUBLISHED", 1, array("script"=>true)); ?>'));</script>`
 178       * will generate an alert message containing '1 plugin successfully disabled'
 179       * `<?php echo Text::plural('COM_PLUGINS_N_ITEMS_UNPUBLISHED', 1); ?>` will generate a '1 plugin successfully disabled' string
 180       *
 181       * @param   string   $string  The format string.
 182       * @param   integer  $n       The number of items
 183       *
 184       * @return  string  The translated strings or the key if 'script' is true in the array of options
 185       *
 186       * @since   1.7.0
 187       */
 188      public static function plural($string, $n)
 189      {
 190          $lang = Factory::getLanguage();
 191          $args = \func_get_args();
 192          $count = \count($args);
 193  
 194          // Try the key from the language plural potential suffixes
 195          $found = false;
 196          $suffixes = $lang->getPluralSuffixes((int) $n);
 197  
 198          // Add the count as possible suffix to allow for eg "a dozen" with suffix _12.
 199          // Only do that if it is a real plural (more than one) to avoid issues with languages. See https://github.com/joomla/joomla-cms/pull/29029
 200          if ($n != 1) {
 201              array_unshift($suffixes, (int) $n);
 202          }
 203  
 204          foreach ($suffixes as $suffix) {
 205              $key = $string . '_' . $suffix;
 206  
 207              if ($lang->hasKey($key)) {
 208                  $found = true;
 209                  break;
 210              }
 211          }
 212  
 213          if (!$found) {
 214              // Not found so revert to the original.
 215              $key = $string;
 216          }
 217  
 218          if (\is_array($args[$count - 1])) {
 219              $args[0] = $lang->_(
 220                  $key,
 221                  \array_key_exists('jsSafe', $args[$count - 1]) ? $args[$count - 1]['jsSafe'] : false,
 222                  \array_key_exists('interpretBackSlashes', $args[$count - 1]) ? $args[$count - 1]['interpretBackSlashes'] : true
 223              );
 224  
 225              if (\array_key_exists('script', $args[$count - 1]) && $args[$count - 1]['script']) {
 226                  static::$strings[$key] = \call_user_func_array('sprintf', $args);
 227  
 228                  return $key;
 229              }
 230          } else {
 231              $args[0] = $lang->_($key);
 232          }
 233  
 234          return \call_user_func_array('sprintf', $args);
 235      }
 236  
 237      /**
 238       * Passes a string thru a sprintf.
 239       *
 240       * Note that this method can take a mixed number of arguments as for the sprintf function.
 241       *
 242       * The last argument can take an array of options:
 243       *
 244       * array('jsSafe'=>boolean, 'interpretBackSlashes'=>boolean, 'script'=>boolean)
 245       *
 246       * where:
 247       *
 248       * jsSafe is a boolean to generate a javascript safe strings.
 249       * interpretBackSlashes is a boolean to interpret backslashes \\->\, \n->new line, \t->tabulation.
 250       * script is a boolean to indicate that the string will be push in the javascript language store.
 251       *
 252       * @param   string  $string  The format string.
 253       *
 254       * @return  string  The translated strings or the key if 'script' is true in the array of options.
 255       *
 256       * @since   1.7.0
 257       */
 258      public static function sprintf($string)
 259      {
 260          $lang = Factory::getLanguage();
 261          $args = \func_get_args();
 262          $count = \count($args);
 263  
 264          if (\is_array($args[$count - 1])) {
 265              $args[0] = $lang->_(
 266                  $string,
 267                  \array_key_exists('jsSafe', $args[$count - 1]) ? $args[$count - 1]['jsSafe'] : false,
 268                  \array_key_exists('interpretBackSlashes', $args[$count - 1]) ? $args[$count - 1]['interpretBackSlashes'] : true
 269              );
 270  
 271              if (\array_key_exists('script', $args[$count - 1]) && $args[$count - 1]['script']) {
 272                  static::$strings[$string] = \call_user_func_array('sprintf', $args);
 273  
 274                  return $string;
 275              }
 276          } else {
 277              $args[0] = $lang->_($string);
 278          }
 279  
 280          // Replace custom named placeholders with sprintf style placeholders
 281          $args[0] = preg_replace('/\[\[%([0-9]+):[^\]]*\]\]/', '%\1$s', $args[0]);
 282  
 283          return \call_user_func_array('sprintf', $args);
 284      }
 285  
 286      /**
 287       * Passes a string thru an printf.
 288       *
 289       * Note that this method can take a mixed number of arguments as for the sprintf function.
 290       *
 291       * @param   string  $string  The format string.
 292       *
 293       * @return  mixed
 294       *
 295       * @since   1.7.0
 296       */
 297      public static function printf($string)
 298      {
 299          $lang = Factory::getLanguage();
 300          $args = \func_get_args();
 301          $count = \count($args);
 302  
 303          if (\is_array($args[$count - 1])) {
 304              $args[0] = $lang->_(
 305                  $string,
 306                  \array_key_exists('jsSafe', $args[$count - 1]) ? $args[$count - 1]['jsSafe'] : false,
 307                  \array_key_exists('interpretBackSlashes', $args[$count - 1]) ? $args[$count - 1]['interpretBackSlashes'] : true
 308              );
 309          } else {
 310              $args[0] = $lang->_($string);
 311          }
 312  
 313          return \call_user_func_array('printf', $args);
 314      }
 315  
 316      /**
 317       * Translate a string into the current language and stores it in the JavaScript language store.
 318       *
 319       * @param   string   $string                The Text key.
 320       * @param   boolean  $jsSafe                Ensure the output is JavaScript safe.
 321       * @param   boolean  $interpretBackSlashes  Interpret \t and \n.
 322       *
 323       * @return  array
 324       *
 325       * @since   1.7.0
 326       */
 327      public static function script($string = null, $jsSafe = false, $interpretBackSlashes = true)
 328      {
 329          if ($string === null) {
 330              @trigger_error(
 331                  sprintf(
 332                      'As of 3.7.0, passing a null value for the first argument of %1$s() is deprecated and will not be supported in 4.0.'
 333                      . ' Use the %2$s::getScriptStrings() method to get the strings from the JavaScript language store instead.',
 334                      __METHOD__,
 335                      __CLASS__
 336                  ),
 337                  E_USER_DEPRECATED
 338              );
 339          }
 340  
 341          if (\is_array($jsSafe)) {
 342              if (\array_key_exists('interpretBackSlashes', $jsSafe)) {
 343                  $interpretBackSlashes = (bool) $jsSafe['interpretBackSlashes'];
 344              }
 345  
 346              if (\array_key_exists('jsSafe', $jsSafe)) {
 347                  $jsSafe = (bool) $jsSafe['jsSafe'];
 348              } else {
 349                  $jsSafe = false;
 350              }
 351          }
 352  
 353          // Add the string to the array if not null.
 354          if ($string !== null) {
 355              // Normalize the key and translate the string.
 356              static::$strings[strtoupper($string)] = Factory::getLanguage()->_($string, $jsSafe, $interpretBackSlashes);
 357  
 358              // Load core.js dependency
 359              HTMLHelper::_('behavior.core');
 360  
 361              // Update Joomla.Text script options
 362              Factory::getDocument()->addScriptOptions('joomla.jtext', static::$strings, false);
 363          }
 364  
 365          return static::getScriptStrings();
 366      }
 367  
 368      /**
 369       * Get the strings that have been loaded to the JavaScript language store.
 370       *
 371       * @return  array
 372       *
 373       * @since   3.7.0
 374       */
 375      public static function getScriptStrings()
 376      {
 377          return static::$strings;
 378      }
 379  }