lib/textlib.class.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   4 // Moodle is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // Moodle is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU General Public License
  15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 /**
  18  * Defines string apis
  19  *
  20  * @package    core
  21  * @copyright  (C) 2001-3001 Eloy Lafuente (stronk7) {@link http://contiento.com}
  22  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23  */
  24
  25 defined('MOODLE_INTERNAL') || die();
  26
  27 /**
  28  * defines string api's for manipulating strings
  29  *
  30  * This class is used to manipulate strings under Moodle 1.6 an later. As
  31  * utf-8 text become mandatory a pool of safe functions under this encoding
  32  * become necessary. The name of the methods is exactly the
  33  * same than their PHP originals.
  34  *
  35  * A big part of this class acts as a wrapper over the Typo3 charset library,
  36  * really a cool group of utilities to handle texts and encoding conversion.
  37  *
  38  * Take a look to its own copyright and license details.
  39  *
  40  * IMPORTANT Note: Typo3 libraries always expect lowercase charsets to use 100%
  41  * its capabilities so, don't forget to make the conversion
  42  * from every wrapper function!
  43  *
  44  * @package   core
  45  * @category  string
  46  * @copyright 1999 onwards Martin Dougiamas  {@link http://moodle.com}
  47  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  48  */
  49 class textlib {
  50
  51     /**
  52      * Return t3lib helper class, which is used for conversion between charsets
  53      *
  54      * @param bool $reset
  55      * @return t3lib_cs
  56      */
  57     protected static function typo3($reset = false) {
  58         static $typo3cs = null;
  59
  60         if ($reset) {
  61             $typo3cs = null;
  62             return null;
  63         }
  64
  65         if (isset($typo3cs)) {
  66             return $typo3cs;
  67         }
  68
  69         global $CFG;
  70
  71         // Required files
  72         require_once($CFG->libdir.'/typo3/class.t3lib_cs.php');
  73         require_once($CFG->libdir.'/typo3/class.t3lib_div.php');
  74         require_once($CFG->libdir.'/typo3/interface.t3lib_singleton.php');
  75         require_once($CFG->libdir.'/typo3/class.t3lib_l10n_locales.php');
  76
  77         // do not use mbstring or recode because it may return invalid results in some corner cases
  78         $GLOBALS['TYPO3_CONF_VARS']['SYS']['t3lib_cs_convMethod'] = 'iconv';
  79         $GLOBALS['TYPO3_CONF_VARS']['SYS']['t3lib_cs_utils'] = 'iconv';
  80
  81         // Tell Typo3 we are curl enabled always (mandatory since 2.0)
  82         $GLOBALS['TYPO3_CONF_VARS']['SYS']['curlUse'] = '1';
  83
  84         // And this directory must exist to allow Typo to cache conversion
  85         // tables when using internal functions
  86         make_temp_directory('typo3temp/cs');
  87
  88         // Make sure typo is using our dir permissions
  89         $GLOBALS['TYPO3_CONF_VARS']['BE']['folderCreateMask'] = decoct($CFG->directorypermissions);
  90
  91         // Default mask for Typo
  92         $GLOBALS['TYPO3_CONF_VARS']['BE']['fileCreateMask'] = $CFG->directorypermissions;
  93
  94         // This full path constants must be defined too, transforming backslashes
  95         // to forward slashed because Typo3 requires it.
  96         if (!defined('PATH_t3lib')) {
  97             define('PATH_t3lib', str_replace('\\','/',$CFG->libdir.'/typo3/'));
  98             define('PATH_typo3', str_replace('\\','/',$CFG->libdir.'/typo3/'));
  99             define('PATH_site', str_replace('\\','/',$CFG->tempdir.'/'));
 100             define('TYPO3_OS', stristr(PHP_OS,'win')&&!stristr(PHP_OS,'darwin')?'WIN':'');
 101         }
 102
 103         $typo3cs = new t3lib_cs();
 104
 105         return $typo3cs;
 106     }
 107
 108     /**
 109      * Reset internal textlib caches.
 110      * @static
 111      */
 112     public static function reset_caches() {
 113         self::typo3(true);
 114     }
 115
 116     /**
 117      * Standardise charset name
 118      *
 119      * Please note it does not mean the returned charset is actually supported.
 120      *
 121      * @static
 122      * @param string $charset raw charset name
 123      * @return string normalised lowercase charset name
 124      */
 125     public static function parse_charset($charset) {
 126         $charset = strtolower($charset);
 127
 128         // shortcuts so that we do not have to load typo3 on every page
 129
 130         if ($charset === 'utf8' or $charset === 'utf-8') {
 131             return 'utf-8';
 132         }
 133
 134         if (preg_match('/^(cp|win|windows)-?(12[0-9]{2})$/', $charset, $matches)) {
 135             return 'windows-'.$matches[2];
 136         }
 137
 138         if (preg_match('/^iso-8859-[0-9]+$/', $charset, $matches)) {
 139             return $charset;
 140         }
 141
 142         if ($charset === 'euc-jp') {
 143             return 'euc-jp';
 144         }
 145         if ($charset === 'iso-2022-jp') {
 146             return 'iso-2022-jp';
 147         }
 148         if ($charset === 'shift-jis' or $charset === 'shift_jis') {
 149             return 'shift_jis';
 150         }
 151         if ($charset === 'gb2312') {
 152             return 'gb2312';
 153         }
 154         if ($charset === 'gb18030') {
 155             return 'gb18030';
 156         }
 157
 158         // fallback to typo3
 159         return self::typo3()->parse_charset($charset);
 160     }
 161
 162     /**
 163      * Converts the text between different encodings. It uses iconv extension with //TRANSLIT parameter,
 164      * falls back to typo3. If both source and target are utf-8 it tries to fix invalid characters only.
 165      *
 166      * @param string $text
 167      * @param string $fromCS source encoding
 168      * @param string $toCS result encoding
 169      * @return string|bool converted string or false on error
 170      */
 171     public static function convert($text, $fromCS, $toCS='utf-8') {
 172         $fromCS = self::parse_charset($fromCS);
 173         $toCS   = self::parse_charset($toCS);
 174
 175         $text = (string)$text; // we can work only with strings
 176
 177         if ($text === '') {
 178             return '';
 179         }
 180
 181         if ($toCS === 'utf-8' and $fromCS === 'utf-8') {
 182             return fix_utf8($text);
 183         }
 184
 185         $result = iconv($fromCS, $toCS.'//TRANSLIT', $text);
 186
 187         if ($result === false or $result === '') {
 188             // note: iconv is prone to return empty string when invalid char encountered, or false if encoding unsupported
 189             $oldlevel = error_reporting(E_PARSE);
 190             $result = self::typo3()->conv((string)$text, $fromCS, $toCS);
 191             error_reporting($oldlevel);
 192         }
 193
 194         return $result;
 195     }
 196
 197     /**
 198      * Multibyte safe substr() function, uses mbstring or iconv for UTF-8, falls back to typo3.
 199      *
 200      * @param string $text string to truncate
 201      * @param int $start negative value means from end
 202      * @param int $len maximum length of characters beginning from start
 203      * @param string $charset encoding of the text
 204      * @return string portion of string specified by the $start and $len
 205      */
 206     public static function substr($text, $start, $len=null, $charset='utf-8') {
 207         $charset = self::parse_charset($charset);
 208
 209         if ($charset === 'utf-8') {
 210             if (function_exists('mb_substr')) {
 211                 // this is much faster than iconv - see MDL-31142
 212                 if ($len === null) {
 213                     $oldcharset = mb_internal_encoding();
 214                     mb_internal_encoding('UTF-8');
 215                     $result = mb_substr($text, $start);
 216                     mb_internal_encoding($oldcharset);
 217                     return $result;
 218                 } else {
 219                     return mb_substr($text, $start, $len, 'UTF-8');
 220                 }
 221
 222             } else {
 223                 if ($len === null) {
 224                     $len = iconv_strlen($text, 'UTF-8');
 225                 }
 226                 return iconv_substr($text, $start, $len, 'UTF-8');
 227             }
 228         }
 229
 230         $oldlevel = error_reporting(E_PARSE);
 231         if ($len === null) {
 232             $result = self::typo3()->substr($charset, (string)$text, $start);
 233         } else {
 234             $result = self::typo3()->substr($charset, (string)$text, $start, $len);
 235         }
 236         error_reporting($oldlevel);
 237
 238         return $result;
 239     }
 240
 241     /**
 242      * Multibyte safe strlen() function, uses mbstring or iconv for UTF-8, falls back to typo3.
 243      *
 244      * @param string $text input string
 245      * @param string $charset encoding of the text
 246      * @return int number of characters
 247      */
 248     public static function strlen($text, $charset='utf-8') {
 249         $charset = self::parse_charset($charset);
 250
 251         if ($charset === 'utf-8') {
 252             if (function_exists('mb_strlen')) {
 253                 return mb_strlen($text, 'UTF-8');
 254             } else {
 255                 return iconv_strlen($text, 'UTF-8');
 256             }
 257         }
 258
 259         $oldlevel = error_reporting(E_PARSE);
 260         $result = self::typo3()->strlen($charset, (string)$text);
 261         error_reporting($oldlevel);
 262
 263         return $result;
 264     }
 265
 266     /**
 267      * Multibyte safe strtolower() function, uses mbstring, falls back to typo3.
 268      *
 269      * @param string $text input string
 270      * @param string $charset encoding of the text (may not work for all encodings)
 271      * @return string lower case text
 272      */
 273     public static function strtolower($text, $charset='utf-8') {
 274         $charset = self::parse_charset($charset);
 275
 276         if ($charset === 'utf-8' and function_exists('mb_strtolower')) {
 277             return mb_strtolower($text, 'UTF-8');
 278         }
 279
 280         $oldlevel = error_reporting(E_PARSE);
 281         $result = self::typo3()->conv_case($charset, (string)$text, 'toLower');
 282         error_reporting($oldlevel);
 283
 284         return $result;
 285     }
 286
 287     /**
 288      * Multibyte safe strtoupper() function, uses mbstring, falls back to typo3.
 289      *
 290      * @param string $text input string
 291      * @param string $charset encoding of the text (may not work for all encodings)
 292      * @return string upper case text
 293      */
 294     public static function strtoupper($text, $charset='utf-8') {
 295         $charset = self::parse_charset($charset);
 296
 297         if ($charset === 'utf-8' and function_exists('mb_strtoupper')) {
 298             return mb_strtoupper($text, 'UTF-8');
 299         }
 300
 301         $oldlevel = error_reporting(E_PARSE);
 302         $result = self::typo3()->conv_case($charset, (string)$text, 'toUpper');
 303         error_reporting($oldlevel);
 304
 305         return $result;
 306     }
 307
 308     /**
 309      * Find the position of the first occurrence of a substring in a string.
 310      * UTF-8 ONLY safe strpos(), uses mbstring, falls back to iconv.
 311      *
 312      * @param string $haystack the string to search in
 313      * @param string $needle one or more charachters to search for
 314      * @param int $offset offset from begining of string
 315      * @return int the numeric position of the first occurrence of needle in haystack.
 316      */
 317     public static function strpos($haystack, $needle, $offset=0) {
 318         if (function_exists('mb_strpos')) {
 319             return mb_strpos($haystack, $needle, $offset, 'UTF-8');
 320         } else {
 321             return iconv_strpos($haystack, $needle, $offset, 'UTF-8');
 322         }
 323     }
 324
 325     /**
 326      * Find the position of the last occurrence of a substring in a string
 327      * UTF-8 ONLY safe strrpos(), uses mbstring, falls back to iconv.
 328      *
 329      * @param string $haystack the string to search in
 330      * @param string $needle one or more charachters to search for
 331      * @return int the numeric position of the last occurrence of needle in haystack
 332      */
 333     public static function strrpos($haystack, $needle) {
 334         if (function_exists('mb_strpos')) {
 335             return mb_strrpos($haystack, $needle, null, 'UTF-8');
 336         } else {
 337             return iconv_strrpos($haystack, $needle, 'UTF-8');
 338         }
 339     }
 340
 341     /**
 342      * Try to convert upper unicode characters to plain ascii,
 343      * the returned string may contain unconverted unicode characters.
 344      *
 345      * @param string $text input string
 346      * @param string $charset encoding of the text
 347      * @return string converted ascii string
 348      */
 349     public static function specialtoascii($text, $charset='utf-8') {
 350         $charset = self::parse_charset($charset);
 351         $oldlevel = error_reporting(E_PARSE);
 352         $result = self::typo3()->specCharsToASCII($charset, (string)$text);
 353         error_reporting($oldlevel);
 354         return $result;
 355     }
 356
 357     /**
 358      * Generate a correct base64 encoded header to be used in MIME mail messages.
 359      * This function seems to be 100% compliant with RFC1342. Credits go to:
 360      * paravoid (http://www.php.net/manual/en/function.mb-encode-mimeheader.php#60283).
 361      *
 362      * @param string $text input string
 363      * @param string $charset encoding of the text
 364      * @return string base64 encoded header
 365      */
 366     public static function encode_mimeheader($text, $charset='utf-8') {
 367         if (empty($text)) {
 368             return (string)$text;
 369         }
 370         // Normalize charset
 371         $charset = self::parse_charset($charset);
 372         // If the text is pure ASCII, we don't need to encode it
 373         if (self::convert($text, $charset, 'ascii') == $text) {
 374             return $text;
 375         }
 376         // Although RFC says that line feed should be \r\n, it seems that
 377         // some mailers double convert \r, so we are going to use \n alone
 378         $linefeed="\n";
 379         // Define start and end of every chunk
 380         $start = "=?$charset?B?";
 381         $end = "?=";
 382         // Accumulate results
 383         $encoded = '';
 384         // Max line length is 75 (including start and end)
 385         $length = 75 - strlen($start) - strlen($end);
 386         // Multi-byte ratio
 387         $multilength = self::strlen($text, $charset);
 388         // Detect if strlen and friends supported
 389         if ($multilength === false) {
 390             if ($charset == 'GB18030' or $charset == 'gb18030') {
 391                 while (strlen($text)) {
 392                     // try to encode first 22 chars - we expect most chars are two bytes long
 393                     if (preg_match('/^(([\x00-\x7f])|([\x81-\xfe][\x40-\x7e])|([\x81-\xfe][\x80-\xfe])|([\x81-\xfe][\x30-\x39]..)){1,22}/m', $text, $matches)) {
 394                         $chunk = $matches[0];
 395                         $encchunk = base64_encode($chunk);
 396                         if (strlen($encchunk) > $length) {
 397                             // find first 11 chars - each char in 4 bytes - worst case scenario
 398                             preg_match('/^(([\x00-\x7f])|([\x81-\xfe][\x40-\x7e])|([\x81-\xfe][\x80-\xfe])|([\x81-\xfe][\x30-\x39]..)){1,11}/m', $text, $matches);
 399                             $chunk = $matches[0];
 400                             $encchunk = base64_encode($chunk);
 401                         }
 402                         $text = substr($text, strlen($chunk));
 403                         $encoded .= ' '.$start.$encchunk.$end.$linefeed;
 404                     } else {
 405                         break;
 406                     }
 407                 }
 408                 $encoded = trim($encoded);
 409                 return $encoded;
 410             } else {
 411                 return false;
 412             }
 413         }
 414         $ratio = $multilength / strlen($text);
 415         // Base64 ratio
 416         $magic = $avglength = floor(3 * $length * $ratio / 4);
 417         // basic infinite loop protection
 418         $maxiterations = strlen($text)*2;
 419         $iteration = 0;
 420         // Iterate over the string in magic chunks
 421         for ($i=0; $i <= $multilength; $i+=$magic) {
 422             if ($iteration++ > $maxiterations) {
 423                 return false; // probably infinite loop
 424             }
 425             $magic = $avglength;
 426             $offset = 0;
 427             // Ensure the chunk fits in length, reducing magic if necessary
 428             do {
 429                 $magic -= $offset;
 430                 $chunk = self::substr($text, $i, $magic, $charset);
 431                 $chunk = base64_encode($chunk);
 432                 $offset++;
 433             } while (strlen($chunk) > $length);
 434             // This chunk doesn't break any multi-byte char. Use it.
 435             if ($chunk)
 436                 $encoded .= ' '.$start.$chunk.$end.$linefeed;
 437         }
 438         // Strip the first space and the last linefeed
 439         $encoded = substr($encoded, 1, -strlen($linefeed));
 440
 441         return $encoded;
 442     }
 443
 444     /**
 445      * Returns HTML entity transliteration table.
 446      * @return array with (html entity => utf-8) elements
 447      */
 448     protected static function get_entities_table() {
 449         static $trans_tbl = null;
 450
 451         // Generate/create $trans_tbl
 452         if (!isset($trans_tbl)) {
 453             if (version_compare(phpversion(), '5.3.4') < 0) {
 454                 $trans_tbl = array();
 455                 foreach (get_html_translation_table(HTML_ENTITIES) as $val=>$key) {
 456                     $trans_tbl[$key] = textlib::convert($val, 'ISO-8859-1', 'utf-8');
 457                 }
 458
 459             } else if (version_compare(phpversion(), '5.4.0') < 0) {
 460                 $trans_tbl = get_html_translation_table(HTML_ENTITIES, ENT_COMPAT, 'UTF-8');
 461                 $trans_tbl = array_flip($trans_tbl);
 462
 463             } else {
 464                 $trans_tbl = get_html_translation_table(HTML_ENTITIES, ENT_COMPAT | ENT_HTML401, 'UTF-8');
 465                 $trans_tbl = array_flip($trans_tbl);
 466             }
 467         }
 468
 469         return $trans_tbl;
 470     }
 471
 472     /**
 473      * Converts all the numeric entities &#nnnn; or &#xnnn; to UTF-8
 474      * Original from laurynas dot butkus at gmail at:
 475      * http://php.net/manual/en/function.html-entity-decode.php#75153
 476      * with some custom mods to provide more functionality
 477      *
 478      * @param string $str input string
 479      * @param boolean $htmlent convert also html entities (defaults to true)
 480      * @return string encoded UTF-8 string
 481      */
 482     public static function entities_to_utf8($str, $htmlent=true) {
 483         static $callback1 = null ;
 484         static $callback2 = null ;
 485
 486         if (!$callback1 or !$callback2) {
 487             $callback1 = create_function('$matches', 'return textlib::code2utf8(hexdec($matches[1]));');
 488             $callback2 = create_function('$matches', 'return textlib::code2utf8($matches[1]);');
 489         }
 490
 491         $result = (string)$str;
 492         $result = preg_replace_callback('/&#x([0-9a-f]+);/i', $callback1, $result);
 493         $result = preg_replace_callback('/&#([0-9]+);/', $callback2, $result);
 494
 495         // Replace literal entities (if desired)
 496         if ($htmlent) {
 497             $trans_tbl = self::get_entities_table();
 498             // It should be safe to search for ascii strings and replace them with utf-8 here.
 499             $result = strtr($result, $trans_tbl);
 500         }
 501         // Return utf8-ised string
 502         return $result;
 503     }
 504
 505     /**
 506      * Converts all Unicode chars > 127 to numeric entities &#nnnn; or &#xnnn;.
 507      *
 508      * @param string $str input string
 509      * @param boolean $dec output decadic only number entities
 510      * @param boolean $nonnum remove all non-numeric entities
 511      * @return string converted string
 512      */
 513     public static function utf8_to_entities($str, $dec=false, $nonnum=false) {
 514         static $callback = null ;
 515
 516         if ($nonnum) {
 517             $str = self::entities_to_utf8($str, true);
 518         }
 519
 520         // Avoid some notices from Typo3 code
 521         $oldlevel = error_reporting(E_PARSE);
 522         $result = self::typo3()->utf8_to_entities((string)$str);
 523         error_reporting($oldlevel);
 524
 525         if ($dec) {
 526             if (!$callback) {
 527                 $callback = create_function('$matches', 'return \'&#\'.(hexdec($matches[1])).\';\';');
 528             }
 529             $result = preg_replace_callback('/&#x([0-9a-f]+);/i', $callback, $result);
 530         }
 531
 532         return $result;
 533     }
 534
 535     /**
 536      * Removes the BOM from unicode string {@link http://unicode.org/faq/utf_bom.html}
 537      *
 538      * @param string $str input string
 539      * @return string
 540      */
 541     public static function trim_utf8_bom($str) {
 542         $bom = "\xef\xbb\xbf";
 543         if (strpos($str, $bom) === 0) {
 544             return substr($str, strlen($bom));
 545         }
 546         return $str;
 547     }
 548
 549     /**
 550      * Returns encoding options for select boxes, utf-8 and platform encoding first
 551      *
 552      * @return array encodings
 553      */
 554     public static function get_encodings() {
 555         $encodings = array();
 556         $encodings['UTF-8'] = 'UTF-8';
 557         $winenc = strtoupper(get_string('localewincharset', 'langconfig'));
 558         if ($winenc != '') {
 559             $encodings[$winenc] = $winenc;
 560         }
 561         $nixenc = strtoupper(get_string('oldcharset', 'langconfig'));
 562         $encodings[$nixenc] = $nixenc;
 563
 564         foreach (self::typo3()->synonyms as $enc) {
 565             $enc = strtoupper($enc);
 566             $encodings[$enc] = $enc;
 567         }
 568         return $encodings;
 569     }
 570
 571     /**
 572      * Returns the utf8 string corresponding to the unicode value
 573      * (from php.net, courtesy - romans@void.lv)
 574      *
 575      * @param  int    $num one unicode value
 576      * @return string the UTF-8 char corresponding to the unicode value
 577      */
 578     public static function code2utf8($num) {
 579         if ($num < 128) {
 580             return chr($num);
 581         }
 582         if ($num < 2048) {
 583             return chr(($num >> 6) + 192) . chr(($num & 63) + 128);
 584         }
 585         if ($num < 65536) {
 586             return chr(($num >> 12) + 224) . chr((($num >> 6) & 63) + 128) . chr(($num & 63) + 128);
 587         }
 588         if ($num < 2097152) {
 589             return chr(($num >> 18) + 240) . chr((($num >> 12) & 63) + 128) . chr((($num >> 6) & 63) + 128) . chr(($num & 63) + 128);
 590         }
 591         return '';
 592     }
 593
 594     /**
 595      * Makes first letter of each word capital - words must be separated by spaces.
 596      * Use with care, this function does not work properly in many locales!!!
 597      *
 598      * @param string $text input string
 599      * @return string
 600      */
 601     public static function strtotitle($text) {
 602         if (empty($text)) {
 603             return $text;
 604         }
 605
 606         if (function_exists('mb_convert_case')) {
 607             return mb_convert_case($text, MB_CASE_TITLE, 'UTF-8');
 608         }
 609
 610         $text = self::strtolower($text);
 611         $words = explode(' ', $text);
 612         foreach ($words as $i=>$word) {
 613             $length = self::strlen($word);
 614             if (!$length) {
 615                 continue;
 616
 617             } else if ($length == 1) {
 618                 $words[$i] = self::strtoupper($word);
 619
 620             } else {
 621                 $letter = self::substr($word, 0, 1);
 622                 $letter = self::strtoupper($letter);
 623                 $rest   = self::substr($word, 1);
 624                 $words[$i] = $letter.$rest;
 625             }
 626         }
 627         return implode(' ', $words);
 628     }
 629
 630     /**
 631      * Locale aware sorting, the key associations are kept, values are sorted alphabetically.
 632      *
 633      * @param array $arr array to be sorted (reference)
 634      * @param int $sortflag One of Collator::SORT_REGULAR, Collator::SORT_NUMERIC, Collator::SORT_STRING
 635      * @return void modifies parameter
 636      */
 637     public static function asort(array &$arr, $sortflag = null) {
 638         debugging('textlib::asort has been superseeded by collatorlib::asort please upgrade your code to use that', DEBUG_DEVELOPER);
 639         collatorlib::asort($arr, $sortflag);
 640     }
 641 }
 642
 643
 644 /**
 645  * A collator class with static methods that can be used for sorting.
 646  *
 647  * @package   core
 648  * @copyright 2011 Sam Hemelryk
 649  *            2012 Petr Skoda
 650  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 651  */
 652 class collatorlib {
 653     /** @const compare items using general PHP comparison, equivalent to Collator::SORT_REGULAR, this may bot be locale aware! */
 654     const SORT_REGULAR = 0;
 655
 656     /** @const compare items as strings, equivalent to Collator::SORT_STRING */
 657     const SORT_STRING = 1;
 658
 659     /** @const compare items as numbers, equivalent to Collator::SORT_NUMERIC */
 660     const SORT_NUMERIC = 2;
 661
 662     /** @const compare items like natsort(), equivalent to SORT_NATURAL */
 663     const SORT_NATURAL = 6;
 664
 665     /** @const do not ignore case when sorting, use bitwise "|" with SORT_NATURAL or SORT_STRING, equivalent to Collator::UPPER_FIRST */
 666     const CASE_SENSITIVE = 64;
 667
 668     /** @var Collator|false|null **/
 669     protected static $collator = null;
 670
 671     /** @var string|null The locale that was used in instantiating the current collator **/
 672     protected static $locale = null;
 673
 674     /**
 675      * Prevent class instances, all methods are static.
 676      */
 677     private function __construct() {
 678     }
 679
 680     /**
 681      * Ensures that a collator is available and created
 682      *
 683      * @return bool Returns true if collation is available and ready
 684      */
 685     protected static function ensure_collator_available() {
 686         $locale = get_string('locale', 'langconfig');
 687         if (is_null(self::$collator) || $locale != self::$locale) {
 688             self::$collator = false;
 689             self::$locale = $locale;
 690             if (class_exists('Collator', false)) {
 691                 $collator = new Collator($locale);
 692                 if (!empty($collator) && $collator instanceof Collator) {
 693                     // Check for non fatal error messages. This has to be done immediately
 694                     // after instantiation as any further calls to collation will cause
 695                     // it to reset to 0 again (or another error code if one occurred)
 696                     $errorcode = $collator->getErrorCode();
 697                     $errormessage = $collator->getErrorMessage();
 698                     // Check for an error code, 0 means no error occurred
 699                     if ($errorcode !== 0) {
 700                         // Get the actual locale being used, e.g. en, he, zh
 701                         $localeinuse = $collator->getLocale(Locale::ACTUAL_LOCALE);
 702                         // Check for the common fallback warning error codes. If this occurred
 703                         // there is normally little to worry about:
 704                         // - U_USING_DEFAULT_WARNING (127)  - default fallback locale used (pt => UCA)
 705                         // - U_USING_FALLBACK_WARNING (128) - fallback locale used (de_CH => de)
 706                         // (UCA: Unicode Collation Algorithm http://unicode.org/reports/tr10/)
 707                         if ($errorcode === -127 || $errorcode === -128) {
 708                             // Check if the locale in use is UCA default one ('root') or
 709                             // if it is anything like the locale we asked for
 710                             if ($localeinuse !== 'root' && strpos($locale, $localeinuse) !== 0) {
 711                                 // The locale we asked for is completely different to the locale
 712                                 // we have received, let the user know via debugging
 713                                 debugging('Invalid locale: "' . $locale . '", with warning (not fatal) "' . $errormessage .
 714                                     '", falling back to "' . $collator->getLocale(Locale::VALID_LOCALE) . '"');
 715                             } else {
 716                                 // Nothing to do here, this is expected!
 717                                 // The Moodle locale setting isn't what the collator expected but
 718                                 // it is smart enough to match the first characters of our locale
 719                                 // to find the correct locale or to use UCA collation
 720                             }
 721                         } else {
 722                             // We've received some other sort of non fatal warning - let the
 723                             // user know about it via debugging.
 724                             debugging('Problem with locale: "' . $locale . '", with message "' . $errormessage .
 725                                 '", falling back to "' . $collator->getLocale(Locale::VALID_LOCALE) . '"');
 726                         }
 727                     }
 728                     // Store the collator object now that we can be sure it is in a workable condition
 729                     self::$collator = $collator;
 730                 } else {
 731                     // Fatal error while trying to instantiate the collator... something went wrong
 732                     debugging('Error instantiating collator for locale: "' . $locale . '", with error [' .
 733                         intl_get_error_code() . '] ' . intl_get_error_message($collator));
 734                 }
 735             }
 736         }
 737         return (self::$collator instanceof Collator);
 738     }
 739
 740     /**
 741      * Restore array contents keeping new keys.
 742      * @static
 743      * @param array $arr
 744      * @param array $original
 745      * @return void modifies $arr
 746      */
 747     protected static function restore_array(array &$arr, array &$original) {
 748         foreach ($arr as $key => $ignored) {
 749             $arr[$key] = $original[$key];
 750         }
 751     }
 752
 753     /**
 754      * Normalise numbers in strings for natural sorting comparisons.
 755      * @static
 756      * @param string $string
 757      * @return string string with normalised numbers
 758      */
 759     protected static function naturalise($string) {
 760         return preg_replace_callback('/[0-9]+/', array('collatorlib', 'callback_naturalise'), $string);
 761     }
 762
 763     /**
 764      * @internal
 765      * @static
 766      * @param array $matches
 767      * @return string
 768      */
 769     public static function callback_naturalise($matches) {
 770         return str_pad($matches[0], 20, '0', STR_PAD_LEFT);
 771     }
 772
 773     /**
 774      * Locale aware sorting, the key associations are kept, values are sorted alphabetically.
 775      *
 776      * @param array $arr array to be sorted (reference)
 777      * @param int $sortflag One of collatorlib::SORT_NUMERIC, collatorlib::SORT_STRING, collatorlib::SORT_NATURAL, collatorlib::SORT_REGULAR
 778      *      optionally "|" collatorlib::CASE_SENSITIVE
 779      * @return bool True on success
 780      */
 781     public static function asort(array &$arr, $sortflag = collatorlib::SORT_STRING) {
 782         if (empty($arr)) {
 783             // nothing to do
 784             return true;
 785         }
 786
 787         $original = null;
 788
 789         $casesensitive = (bool)($sortflag & collatorlib::CASE_SENSITIVE);
 790         $sortflag = ($sortflag & ~collatorlib::CASE_SENSITIVE);
 791         if ($sortflag != collatorlib::SORT_NATURAL and $sortflag != collatorlib::SORT_STRING) {
 792             $casesensitive = false;
 793         }
 794
 795         if (self::ensure_collator_available()) {
 796             if ($sortflag == collatorlib::SORT_NUMERIC) {
 797                 $flag = Collator::SORT_NUMERIC;
 798
 799             } else if ($sortflag == collatorlib::SORT_REGULAR) {
 800                 $flag = Collator::SORT_REGULAR;
 801
 802             } else {
 803                 $flag = Collator::SORT_STRING;
 804             }
 805
 806             if ($sortflag == collatorlib::SORT_NATURAL) {
 807                 $original = $arr;
 808                 if ($sortflag == collatorlib::SORT_NATURAL) {
 809                     foreach ($arr as $key => $value) {
 810                         $arr[$key] = self::naturalise((string)$value);
 811                     }
 812                 }
 813             }
 814             if ($casesensitive) {
 815                 self::$collator->setAttribute(Collator::CASE_FIRST, Collator::UPPER_FIRST);
 816             } else {
 817                 self::$collator->setAttribute(Collator::CASE_FIRST, Collator::OFF);
 818             }
 819             $result = self::$collator->asort($arr, $flag);
 820             if ($original) {
 821                 self::restore_array($arr, $original);
 822             }
 823             return $result;
 824         }
 825
 826         // try some fallback that works at least for English
 827
 828         if ($sortflag == collatorlib::SORT_NUMERIC) {
 829             return asort($arr, SORT_NUMERIC);
 830
 831         } else if ($sortflag == collatorlib::SORT_REGULAR) {
 832             return asort($arr, SORT_REGULAR);
 833         }
 834
 835         if (!$casesensitive) {
 836             $original = $arr;
 837             foreach ($arr as $key => $value) {
 838                 $arr[$key] = textlib::strtolower($value);
 839             }
 840         }
 841
 842         if ($sortflag == collatorlib::SORT_NATURAL) {
 843             $result = natsort($arr);
 844
 845         } else {
 846             $result = asort($arr, SORT_LOCALE_STRING);
 847         }
 848
 849         if ($original) {
 850             self::restore_array($arr, $original);
 851         }
 852
 853         return $result;
 854     }
 855
 856     /**
 857      * Locale aware sort of objects by a property in common to all objects
 858      *
 859      * @param array $objects An array of objects to sort (handled by reference)
 860      * @param string $property The property to use for comparison
 861      * @param int $sortflag One of collatorlib::SORT_NUMERIC, collatorlib::SORT_STRING, collatorlib::SORT_NATURAL, collatorlib::SORT_REGULAR
 862      *      optionally "|" collatorlib::CASE_SENSITIVE
 863      * @return bool True on success
 864      */
 865     public static function asort_objects_by_property(array &$objects, $property, $sortflag = collatorlib::SORT_STRING) {
 866         $original = $objects;
 867         foreach ($objects as $key => $object) {
 868             $objects[$key] = $object->$property;
 869         }
 870         $result = self::asort($objects, $sortflag);
 871         self::restore_array($objects, $original);
 872         return $result;
 873     }
 874
 875     /**
 876      * Locale aware sort of objects by a method in common to all objects
 877      *
 878      * @param array $objects An array of objects to sort (handled by reference)
 879      * @param string $method The method to call to generate a value for comparison
 880      * @param int $sortflag One of collatorlib::SORT_NUMERIC, collatorlib::SORT_STRING, collatorlib::SORT_NATURAL, collatorlib::SORT_REGULAR
 881      *      optionally "|" collatorlib::CASE_SENSITIVE
 882      * @return bool True on success
 883      */
 884     public static function asort_objects_by_method(array &$objects, $method, $sortflag = collatorlib::SORT_STRING) {
 885         $original = $objects;
 886         foreach ($objects as $key => $object) {
 887             $objects[$key] = $object->{$method}();
 888         }
 889         $result = self::asort($objects, $sortflag);
 890         self::restore_array($objects, $original);
 891         return $result;
 892     }
 893
 894     /**
 895      * Locale aware sorting, the key associations are kept, keys are sorted alphabetically.
 896      *
 897      * @param array $arr array to be sorted (reference)
 898      * @param int $sortflag One of collatorlib::SORT_NUMERIC, collatorlib::SORT_STRING, collatorlib::SORT_NATURAL, collatorlib::SORT_REGULAR
 899      *      optionally "|" collatorlib::CASE_SENSITIVE
 900      * @return bool True on success
 901      */
 902     public static function ksort(array &$arr, $sortflag = collatorlib::SORT_STRING) {
 903         $keys = array_keys($arr);
 904         if (!self::asort($keys, $sortflag)) {
 905             return false;
 906         }
 907         // This is a bit slow, but we need to keep the references
 908         $original = $arr;
 909         $arr = array(); // Surprisingly this does not break references outside
 910         foreach ($keys as $key) {
 911             $arr[$key] = $original[$key];
 912         }
 913
 914         return true;
 915     }
 916 }
 917