[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  namespace dokuwiki\Utf8;
   4  
   5  use dokuwiki\Logger;
   6  
   7  /**
   8   * DokuWiki sort functions
   9   *
  10   * When "intl" extension is available, all sorts are done using a collator.
  11   * Otherwise, primitive PHP functions are called.
  12   *
  13   * The collator is created using the locale given in $conf['lang'].
  14   * It always uses case insensitive "natural" ordering in its collation.
  15   * The fallback solution uses the primitive PHP functions that return almost the same results
  16   * when the input is text with only [A-Za-z0-9] characters.
  17   *
  18   * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
  19   * @author     Moisés Braga Ribeiro <moisesbr@gmail.com>
  20   * @author     Andreas Gohr <andi@splitbrain.org>
  21   */
  22  class Sort
  23  {
  24      /** @var \Collator[] language specific collators, usually only one */
  25      protected static $collators = [];
  26  
  27      /** @var bool should the intl extension be used if available? For testing only */
  28      protected static $useIntl = true;
  29  
  30      /**
  31       * Initialization of a collator using $conf['lang'] as the locale.
  32       * The initialization is done only once.
  33       * The collation takes "natural ordering" into account, that is, "page 2" is before "page 10".
  34       *
  35       * @return \Collator Returns a configured collator or null if the collator cannot be created.
  36       *
  37       * @author Moisés Braga Ribeiro <moisesbr@gmail.com>
  38       */
  39      protected static function getCollator()
  40      {
  41          global $conf;
  42          $lc = $conf['lang'];
  43  
  44          // check if intl extension is available
  45          if (!self::$useIntl || !class_exists('\Collator')) {
  46              return null;
  47          }
  48  
  49          // load collator if not available yet
  50          if (!isset(self::$collators[$lc])) {
  51              $collator = \Collator::create($lc);
  52              if (!isset($collator)) return null; // check needed as stated in the docs
  53              $collator->setAttribute(\Collator::NUMERIC_COLLATION, \Collator::ON);
  54              Logger::getInstance(Logger::LOG_DEBUG)->log(
  55                  'Collator created with locale "' . $lc . '": numeric collation on, ' .
  56                  'valid locale "' . $collator->getLocale(\Locale::VALID_LOCALE) . '", ' .
  57                  'actual locale "' . $collator->getLocale(\Locale::ACTUAL_LOCALE) . '"',
  58                  null,
  59                  __FILE__,
  60                  __LINE__
  61              );
  62              self::$collators[$lc] = $collator;
  63          }
  64  
  65          return self::$collators[$lc];
  66      }
  67  
  68      /**
  69       * Enable or disable the use of the "intl" extension collator.
  70       * This is used for testing and should not be used in normal code.
  71       *
  72       * @param bool $use
  73       *
  74       * @author Andreas Gohr <andi@splitbrain.org>
  75       */
  76      public static function useIntl($use = true)
  77      {
  78          self::$useIntl = $use;
  79      }
  80  
  81      /**
  82       * Drop-in replacement for strcmp(), strcasecmp(), strnatcmp() and strnatcasecmp().
  83       * It uses a collator-based comparison, or strnatcasecmp() as a fallback.
  84       *
  85       * @param string $str1 The first string.
  86       * @param string $str2 The second string.
  87       * @return int Returns < 0 if $str1 is less than $str2; > 0 if $str1 is greater than $str2, and 0 if they are equal.
  88       *
  89       * @author Moisés Braga Ribeiro <moisesbr@gmail.com>
  90       */
  91      public static function strcmp($str1, $str2)
  92      {
  93          $collator = self::getCollator();
  94          if (isset($collator)) {
  95              return $collator->compare($str1, $str2);
  96          } else {
  97              return strnatcasecmp($str1, $str2);
  98          }
  99      }
 100  
 101      /**
 102       * Drop-in replacement for sort().
 103       * It uses a collator-based sort, or sort() with flags SORT_NATURAL and SORT_FLAG_CASE as a fallback.
 104       *
 105       * @param array $array The input array.
 106       * @return bool Returns true on success or false on failure.
 107       *
 108       * @author Moisés Braga Ribeiro <moisesbr@gmail.com>
 109       */
 110      public static function sort(&$array)
 111      {
 112          $collator = self::getCollator();
 113          if (isset($collator)) {
 114              return $collator->sort($array);
 115          } else {
 116              return sort($array, SORT_NATURAL | SORT_FLAG_CASE);
 117          }
 118      }
 119  
 120      /**
 121       * Drop-in replacement for ksort().
 122       * It uses a collator-based sort, or ksort() with flags SORT_NATURAL and SORT_FLAG_CASE as a fallback.
 123       *
 124       * @param array $array The input array.
 125       * @return bool Returns true on success or false on failure.
 126       *
 127       * @author Moisés Braga Ribeiro <moisesbr@gmail.com>
 128       */
 129      public static function ksort(&$array)
 130      {
 131          $collator = self::getCollator();
 132          if (isset($collator)) {
 133              return uksort($array, [$collator, 'compare']);
 134          } else {
 135              return ksort($array, SORT_NATURAL | SORT_FLAG_CASE);
 136          }
 137      }
 138  
 139      /**
 140       * Drop-in replacement for asort(), natsort() and natcasesort().
 141       * It uses a collator-based sort, or asort() with flags SORT_NATURAL and SORT_FLAG_CASE as a fallback.
 142       *
 143       * @param array $array The input array.
 144       * @return bool Returns true on success or false on failure.
 145       *
 146       * @author Moisés Braga Ribeiro <moisesbr@gmail.com>
 147       */
 148      public static function asort(&$array)
 149      {
 150          $collator = self::getCollator();
 151          if (isset($collator)) {
 152              return $collator->asort($array);
 153          } else {
 154              return asort($array, SORT_NATURAL | SORT_FLAG_CASE);
 155          }
 156      }
 157  
 158      /**
 159       * Drop-in replacement for asort(), natsort() and natcasesort() when the parameter is an array of filenames.
 160       * Filenames may not be equal to page names, depending on the setting in $conf['fnencode'],
 161       * so the correct behavior is to sort page names and reflect this sorting in the filename array.
 162       *
 163       * @param array $array The input array.
 164       * @return bool Returns true on success or false on failure.
 165       *
 166       * @author Moisés Braga Ribeiro <moisesbr@gmail.com>
 167       * @author Andreas Gohr <andi@splitbrain.org>
 168       */
 169      public static function asortFN(&$array)
 170      {
 171          $collator = self::getCollator();
 172          return uasort($array, function ($fn1, $fn2) use ($collator) {
 173              if (isset($collator)) {
 174                  return $collator->compare(utf8_decodeFN($fn1), utf8_decodeFN($fn2));
 175              } else {
 176                  return strnatcasecmp(utf8_decodeFN($fn1), utf8_decodeFN($fn2));
 177              }
 178          });
 179      }
 180  }