MDL-36212 rework html entity conversions
[moodle.git] / 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/>.
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  */
25 defined('MOODLE_INTERNAL') || die();
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 {
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;
60         if ($reset) {
61             $typo3cs = null;
62             return null;
63         }
65         if (isset($typo3cs)) {
66             return $typo3cs;
67         }
69         global $CFG;
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');
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';
81         // Tell Typo3 we are curl enabled always (mandatory since 2.0)
82         $GLOBALS['TYPO3_CONF_VARS']['SYS']['curlUse'] = '1';
84         // And this directory must exist to allow Typo to cache conversion
85         // tables when using internal functions
86         make_temp_directory('typo3temp/cs');
88         // Make sure typo is using our dir permissions
89         $GLOBALS['TYPO3_CONF_VARS']['BE']['folderCreateMask'] = decoct($CFG->directorypermissions);
91         // Default mask for Typo
92         $GLOBALS['TYPO3_CONF_VARS']['BE']['fileCreateMask'] = $CFG->directorypermissions;
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         }
103         $typo3cs = new t3lib_cs();
105         return $typo3cs;
106     }
108     /**
109      * Reset internal textlib caches.
110      * @static
111      */
112     public static function reset_caches() {
113         self::typo3(true);
114     }
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);
128         // shortcuts so that we do not have to load typo3 on every page
130         if ($charset === 'utf8' or $charset === 'utf-8') {
131             return 'utf-8';
132         }
134         if (preg_match('/^(cp|win|windows)-?(12[0-9]{2})$/', $charset, $matches)) {
135             return 'windows-'.$matches[2];
136         }
138         if (preg_match('/^iso-8859-[0-9]+$/', $charset, $matches)) {
139             return $charset;
140         }
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         }
158         // fallback to typo3
159         return self::typo3()->parse_charset($charset);
160     }
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);
175         $text = (string)$text; // we can work only with strings
177         if ($text === '') {
178             return '';
179         }
181         if ($toCS === 'utf-8' and $fromCS === 'utf-8') {
182             return fix_utf8($text);
183         }
185         $result = iconv($fromCS, $toCS.'//TRANSLIT', $text);
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         }
194         return $result;
195     }
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);
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                 }
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         }
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);
238         return $result;
239     }
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);
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         }
259         $oldlevel = error_reporting(E_PARSE);
260         $result = self::typo3()->strlen($charset, (string)$text);
261         error_reporting($oldlevel);
263         return $result;
264     }
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);
276         if ($charset === 'utf-8' and function_exists('mb_strtolower')) {
277             return mb_strtolower($text, 'UTF-8');
278         }
280         $oldlevel = error_reporting(E_PARSE);
281         $result = self::typo3()->conv_case($charset, (string)$text, 'toLower');
282         error_reporting($oldlevel);
284         return $result;
285     }
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);
297         if ($charset === 'utf-8' and function_exists('mb_strtoupper')) {
298             return mb_strtoupper($text, 'UTF-8');
299         }
301         $oldlevel = error_reporting(E_PARSE);
302         $result = self::typo3()->conv_case($charset, (string)$text, 'toUpper');
303         error_reporting($oldlevel);
305         return $result;
306     }
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     }
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     }
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     }
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));
441         return $encoded;
442     }
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;
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                 }
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);
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         }
469         return $trans_tbl;
470     }
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 ;
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         }
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);
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     }
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 ;
516         if ($nonnum) {
517             $str = self::entities_to_utf8($str, true);
518         }
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);
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         }
532         return $result;
533     }
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     }
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;
564         foreach (self::typo3()->synonyms as $enc) {
565             $enc = strtoupper($enc);
566             $encodings[$enc] = $enc;
567         }
568         return $encodings;
569     }
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     }
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         }
606         if (function_exists('mb_convert_case')) {
607             return mb_convert_case($text, MB_CASE_TITLE, 'UTF-8');
608         }
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;
617             } else if ($length == 1) {
618                 $words[$i] = self::strtoupper($word);
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     }
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     }
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;
656     /** @const compare items as strings, equivalent to Collator::SORT_STRING */
657     const SORT_STRING = 1;
659     /** @const compare items as numbers, equivalent to Collator::SORT_NUMERIC */
660     const SORT_NUMERIC = 2;
662     /** @const compare items like natsort(), equivalent to SORT_NATURAL */
663     const SORT_NATURAL = 6;
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;
668     /** @var Collator|false|null **/
669     protected static $collator = null;
671     /** @var string|null The locale that was used in instantiating the current collator **/
672     protected static $locale = null;
674     /**
675      * Prevent class instances, all methods are static.
676      */
677     private function __construct() {
678     }
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     }
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     }
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     }
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     }
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         }
787         $original = null;
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         }
795         if (self::ensure_collator_available()) {
796             if ($sortflag == collatorlib::SORT_NUMERIC) {
797                 $flag = Collator::SORT_NUMERIC;
799             } else if ($sortflag == collatorlib::SORT_REGULAR) {
800                 $flag = Collator::SORT_REGULAR;
802             } else {
803                 $flag = Collator::SORT_STRING;
804             }
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         }
826         // try some fallback that works at least for English
828         if ($sortflag == collatorlib::SORT_NUMERIC) {
829             return asort($arr, SORT_NUMERIC);
831         } else if ($sortflag == collatorlib::SORT_REGULAR) {
832             return asort($arr, SORT_REGULAR);
833         }
835         if (!$casesensitive) {
836             $original = $arr;
837             foreach ($arr as $key => $value) {
838                 $arr[$key] = textlib::strtolower($value);
839             }
840         }
842         if ($sortflag == collatorlib::SORT_NATURAL) {
843             $result = natsort($arr);
845         } else {
846             $result = asort($arr, SORT_LOCALE_STRING);
847         }
849         if ($original) {
850             self::restore_array($arr, $original);
851         }
853         return $result;
854     }
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     }
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     }
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         }
914         return true;
915     }