annotate core/lib/Drupal/Component/Utility/Unicode.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents 129ea1e6d783
children
rev   line source
Chris@0 1 <?php
Chris@0 2
Chris@0 3 namespace Drupal\Component\Utility;
Chris@0 4
Chris@0 5 /**
Chris@0 6 * Provides Unicode-related conversions and operations.
Chris@0 7 *
Chris@0 8 * @ingroup utility
Chris@0 9 */
Chris@0 10 class Unicode {
Chris@0 11
Chris@0 12 /**
Chris@0 13 * Matches Unicode characters that are word boundaries.
Chris@0 14 *
Chris@0 15 * Characters with the following General_category (gc) property values are used
Chris@0 16 * as word boundaries. While this does not fully conform to the Word Boundaries
Chris@0 17 * algorithm described in http://unicode.org/reports/tr29, as PCRE does not
Chris@0 18 * contain the Word_Break property table, this simpler algorithm has to do.
Chris@0 19 * - Cc, Cf, Cn, Co, Cs: Other.
Chris@0 20 * - Pc, Pd, Pe, Pf, Pi, Po, Ps: Punctuation.
Chris@0 21 * - Sc, Sk, Sm, So: Symbols.
Chris@0 22 * - Zl, Zp, Zs: Separators.
Chris@0 23 *
Chris@0 24 * Non-boundary characters include the following General_category (gc) property
Chris@0 25 * values:
Chris@0 26 * - Ll, Lm, Lo, Lt, Lu: Letters.
Chris@0 27 * - Mc, Me, Mn: Combining Marks.
Chris@0 28 * - Nd, Nl, No: Numbers.
Chris@0 29 *
Chris@0 30 * Note that the PCRE property matcher is not used because we wanted to be
Chris@0 31 * compatible with Unicode 5.2.0 regardless of the PCRE version used (and any
Chris@0 32 * bugs in PCRE property tables).
Chris@0 33 *
Chris@0 34 * @see http://unicode.org/glossary
Chris@0 35 */
Chris@0 36 const PREG_CLASS_WORD_BOUNDARY = <<<'EOD'
Chris@0 37 \x{0}-\x{2F}\x{3A}-\x{40}\x{5B}-\x{60}\x{7B}-\x{A9}\x{AB}-\x{B1}\x{B4}
Chris@0 38 \x{B6}-\x{B8}\x{BB}\x{BF}\x{D7}\x{F7}\x{2C2}-\x{2C5}\x{2D2}-\x{2DF}
Chris@0 39 \x{2E5}-\x{2EB}\x{2ED}\x{2EF}-\x{2FF}\x{375}\x{37E}-\x{385}\x{387}\x{3F6}
Chris@0 40 \x{482}\x{55A}-\x{55F}\x{589}-\x{58A}\x{5BE}\x{5C0}\x{5C3}\x{5C6}
Chris@0 41 \x{5F3}-\x{60F}\x{61B}-\x{61F}\x{66A}-\x{66D}\x{6D4}\x{6DD}\x{6E9}
Chris@0 42 \x{6FD}-\x{6FE}\x{700}-\x{70F}\x{7F6}-\x{7F9}\x{830}-\x{83E}
Chris@0 43 \x{964}-\x{965}\x{970}\x{9F2}-\x{9F3}\x{9FA}-\x{9FB}\x{AF1}\x{B70}
Chris@0 44 \x{BF3}-\x{BFA}\x{C7F}\x{CF1}-\x{CF2}\x{D79}\x{DF4}\x{E3F}\x{E4F}
Chris@0 45 \x{E5A}-\x{E5B}\x{F01}-\x{F17}\x{F1A}-\x{F1F}\x{F34}\x{F36}\x{F38}
Chris@0 46 \x{F3A}-\x{F3D}\x{F85}\x{FBE}-\x{FC5}\x{FC7}-\x{FD8}\x{104A}-\x{104F}
Chris@0 47 \x{109E}-\x{109F}\x{10FB}\x{1360}-\x{1368}\x{1390}-\x{1399}\x{1400}
Chris@0 48 \x{166D}-\x{166E}\x{1680}\x{169B}-\x{169C}\x{16EB}-\x{16ED}
Chris@0 49 \x{1735}-\x{1736}\x{17B4}-\x{17B5}\x{17D4}-\x{17D6}\x{17D8}-\x{17DB}
Chris@0 50 \x{1800}-\x{180A}\x{180E}\x{1940}-\x{1945}\x{19DE}-\x{19FF}
Chris@0 51 \x{1A1E}-\x{1A1F}\x{1AA0}-\x{1AA6}\x{1AA8}-\x{1AAD}\x{1B5A}-\x{1B6A}
Chris@0 52 \x{1B74}-\x{1B7C}\x{1C3B}-\x{1C3F}\x{1C7E}-\x{1C7F}\x{1CD3}\x{1FBD}
Chris@0 53 \x{1FBF}-\x{1FC1}\x{1FCD}-\x{1FCF}\x{1FDD}-\x{1FDF}\x{1FED}-\x{1FEF}
Chris@0 54 \x{1FFD}-\x{206F}\x{207A}-\x{207E}\x{208A}-\x{208E}\x{20A0}-\x{20B8}
Chris@0 55 \x{2100}-\x{2101}\x{2103}-\x{2106}\x{2108}-\x{2109}\x{2114}
Chris@0 56 \x{2116}-\x{2118}\x{211E}-\x{2123}\x{2125}\x{2127}\x{2129}\x{212E}
Chris@0 57 \x{213A}-\x{213B}\x{2140}-\x{2144}\x{214A}-\x{214D}\x{214F}
Chris@0 58 \x{2190}-\x{244A}\x{249C}-\x{24E9}\x{2500}-\x{2775}\x{2794}-\x{2B59}
Chris@0 59 \x{2CE5}-\x{2CEA}\x{2CF9}-\x{2CFC}\x{2CFE}-\x{2CFF}\x{2E00}-\x{2E2E}
Chris@0 60 \x{2E30}-\x{3004}\x{3008}-\x{3020}\x{3030}\x{3036}-\x{3037}
Chris@0 61 \x{303D}-\x{303F}\x{309B}-\x{309C}\x{30A0}\x{30FB}\x{3190}-\x{3191}
Chris@0 62 \x{3196}-\x{319F}\x{31C0}-\x{31E3}\x{3200}-\x{321E}\x{322A}-\x{3250}
Chris@0 63 \x{3260}-\x{327F}\x{328A}-\x{32B0}\x{32C0}-\x{33FF}\x{4DC0}-\x{4DFF}
Chris@0 64 \x{A490}-\x{A4C6}\x{A4FE}-\x{A4FF}\x{A60D}-\x{A60F}\x{A673}\x{A67E}
Chris@0 65 \x{A6F2}-\x{A716}\x{A720}-\x{A721}\x{A789}-\x{A78A}\x{A828}-\x{A82B}
Chris@0 66 \x{A836}-\x{A839}\x{A874}-\x{A877}\x{A8CE}-\x{A8CF}\x{A8F8}-\x{A8FA}
Chris@0 67 \x{A92E}-\x{A92F}\x{A95F}\x{A9C1}-\x{A9CD}\x{A9DE}-\x{A9DF}
Chris@0 68 \x{AA5C}-\x{AA5F}\x{AA77}-\x{AA79}\x{AADE}-\x{AADF}\x{ABEB}
Chris@0 69 \x{E000}-\x{F8FF}\x{FB29}\x{FD3E}-\x{FD3F}\x{FDFC}-\x{FDFD}
Chris@0 70 \x{FE10}-\x{FE19}\x{FE30}-\x{FE6B}\x{FEFF}-\x{FF0F}\x{FF1A}-\x{FF20}
Chris@0 71 \x{FF3B}-\x{FF40}\x{FF5B}-\x{FF65}\x{FFE0}-\x{FFFD}
Chris@0 72 EOD;
Chris@0 73
Chris@0 74 /**
Chris@0 75 * Indicates that standard PHP (emulated) unicode support is being used.
Chris@0 76 */
Chris@0 77 const STATUS_SINGLEBYTE = 0;
Chris@0 78
Chris@0 79 /**
Chris@0 80 * Indicates that full unicode support with the PHP mbstring extension is
Chris@0 81 * being used.
Chris@0 82 */
Chris@0 83 const STATUS_MULTIBYTE = 1;
Chris@0 84
Chris@0 85 /**
Chris@0 86 * Indicates an error during check for PHP unicode support.
Chris@0 87 */
Chris@0 88 const STATUS_ERROR = -1;
Chris@0 89
Chris@0 90 /**
Chris@0 91 * Gets the current status of unicode/multibyte support on this environment.
Chris@0 92 *
Chris@0 93 * @return int
Chris@0 94 * The status of multibyte support. It can be one of:
Chris@0 95 * - \Drupal\Component\Utility\Unicode::STATUS_MULTIBYTE
Chris@0 96 * Full unicode support using an extension.
Chris@0 97 * - \Drupal\Component\Utility\Unicode::STATUS_SINGLEBYTE
Chris@0 98 * Standard PHP (emulated) unicode support.
Chris@0 99 * - \Drupal\Component\Utility\Unicode::STATUS_ERROR
Chris@0 100 * An error occurred. No unicode support.
Chris@0 101 */
Chris@0 102 public static function getStatus() {
Chris@17 103 switch (static::check()) {
Chris@17 104 case 'mb_strlen':
Chris@17 105 return Unicode::STATUS_SINGLEBYTE;
Chris@17 106 case '':
Chris@17 107 return Unicode::STATUS_MULTIBYTE;
Chris@17 108 }
Chris@17 109 return Unicode::STATUS_ERROR;
Chris@0 110 }
Chris@0 111
Chris@0 112 /**
Chris@0 113 * Sets the value for multibyte support status for the current environment.
Chris@0 114 *
Chris@0 115 * The following status keys are supported:
Chris@0 116 * - \Drupal\Component\Utility\Unicode::STATUS_MULTIBYTE
Chris@0 117 * Full unicode support using an extension.
Chris@0 118 * - \Drupal\Component\Utility\Unicode::STATUS_SINGLEBYTE
Chris@0 119 * Standard PHP (emulated) unicode support.
Chris@0 120 * - \Drupal\Component\Utility\Unicode::STATUS_ERROR
Chris@0 121 * An error occurred. No unicode support.
Chris@0 122 *
Chris@0 123 * @param int $status
Chris@0 124 * The new status of multibyte support.
Chris@17 125 *
Chris@17 126 * @deprecated in Drupal 8.6.0 and will be removed before Drupal 9.0.0. In
Chris@17 127 * Drupal 9 there will be no way to set the status and in Drupal 8 this
Chris@17 128 * ability has been removed because mb_*() functions are supplied using
Chris@17 129 * Symfony's polyfill.
Chris@17 130 *
Chris@17 131 * @see https://www.drupal.org/node/2850048
Chris@0 132 */
Chris@0 133 public static function setStatus($status) {
Chris@17 134 @trigger_error('\Drupal\Component\Utility\Unicode::setStatus() is deprecated in Drupal 8.6.0 and will be removed before Drupal 9.0.0. In Drupal 9 there will be no way to set the status and in Drupal 8 this ability has been removed because mb_*() functions are supplied using Symfony\'s polyfill. See https://www.drupal.org/node/2850048.', E_USER_DEPRECATED);
Chris@0 135 }
Chris@0 136
Chris@0 137 /**
Chris@0 138 * Checks for Unicode support in PHP and sets the proper settings if possible.
Chris@0 139 *
Chris@0 140 * Because of the need to be able to handle text in various encodings, we do
Chris@0 141 * not support mbstring function overloading. HTTP input/output conversion
Chris@0 142 * must be disabled for similar reasons.
Chris@0 143 *
Chris@0 144 * @return string
Chris@0 145 * A string identifier of a failed multibyte extension check, if any.
Chris@0 146 * Otherwise, an empty string.
Chris@0 147 */
Chris@0 148 public static function check() {
Chris@17 149 // Set appropriate configuration.
Chris@17 150 mb_internal_encoding('utf-8');
Chris@17 151 mb_language('uni');
Chris@17 152
Chris@0 153 // Check for mbstring extension.
Chris@17 154 if (!extension_loaded('mbstring')) {
Chris@0 155 return 'mb_strlen';
Chris@0 156 }
Chris@0 157
Chris@0 158 // Check mbstring configuration.
Chris@0 159 if (ini_get('mbstring.func_overload') != 0) {
Chris@0 160 return 'mbstring.func_overload';
Chris@0 161 }
Chris@0 162 if (ini_get('mbstring.encoding_translation') != 0) {
Chris@0 163 return 'mbstring.encoding_translation';
Chris@0 164 }
Chris@0 165 // mbstring.http_input and mbstring.http_output are deprecated and empty by
Chris@0 166 // default in PHP 5.6.
Chris@0 167 if (version_compare(PHP_VERSION, '5.6.0') == -1) {
Chris@0 168 if (ini_get('mbstring.http_input') != 'pass') {
Chris@0 169 return 'mbstring.http_input';
Chris@0 170 }
Chris@0 171 if (ini_get('mbstring.http_output') != 'pass') {
Chris@0 172 return 'mbstring.http_output';
Chris@0 173 }
Chris@0 174 }
Chris@0 175
Chris@0 176 return '';
Chris@0 177 }
Chris@0 178
Chris@0 179 /**
Chris@0 180 * Decodes UTF byte-order mark (BOM) into the encoding's name.
Chris@0 181 *
Chris@0 182 * @param string $data
Chris@0 183 * The data possibly containing a BOM. This can be the entire contents of
Chris@0 184 * a file, or just a fragment containing at least the first five bytes.
Chris@0 185 *
Chris@0 186 * @return string|bool
Chris@0 187 * The name of the encoding, or FALSE if no byte order mark was present.
Chris@0 188 */
Chris@0 189 public static function encodingFromBOM($data) {
Chris@0 190 static $bomMap = [
Chris@0 191 "\xEF\xBB\xBF" => 'UTF-8',
Chris@0 192 "\xFE\xFF" => 'UTF-16BE',
Chris@0 193 "\xFF\xFE" => 'UTF-16LE',
Chris@0 194 "\x00\x00\xFE\xFF" => 'UTF-32BE',
Chris@0 195 "\xFF\xFE\x00\x00" => 'UTF-32LE',
Chris@0 196 "\x2B\x2F\x76\x38" => 'UTF-7',
Chris@0 197 "\x2B\x2F\x76\x39" => 'UTF-7',
Chris@0 198 "\x2B\x2F\x76\x2B" => 'UTF-7',
Chris@0 199 "\x2B\x2F\x76\x2F" => 'UTF-7',
Chris@0 200 "\x2B\x2F\x76\x38\x2D" => 'UTF-7',
Chris@0 201 ];
Chris@0 202
Chris@0 203 foreach ($bomMap as $bom => $encoding) {
Chris@0 204 if (strpos($data, $bom) === 0) {
Chris@0 205 return $encoding;
Chris@0 206 }
Chris@0 207 }
Chris@0 208 return FALSE;
Chris@0 209 }
Chris@0 210
Chris@0 211 /**
Chris@0 212 * Converts data to UTF-8.
Chris@0 213 *
Chris@0 214 * Requires the iconv, GNU recode or mbstring PHP extension.
Chris@0 215 *
Chris@0 216 * @param string $data
Chris@0 217 * The data to be converted.
Chris@0 218 * @param string $encoding
Chris@0 219 * The encoding that the data is in.
Chris@0 220 *
Chris@0 221 * @return string|bool
Chris@0 222 * Converted data or FALSE.
Chris@0 223 */
Chris@0 224 public static function convertToUtf8($data, $encoding) {
Chris@17 225 return @iconv($encoding, 'utf-8', $data);
Chris@0 226 }
Chris@0 227
Chris@0 228 /**
Chris@0 229 * Truncates a UTF-8-encoded string safely to a number of bytes.
Chris@0 230 *
Chris@0 231 * If the end position is in the middle of a UTF-8 sequence, it scans backwards
Chris@0 232 * until the beginning of the byte sequence.
Chris@0 233 *
Chris@0 234 * Use this function whenever you want to chop off a string at an unsure
Chris@0 235 * location. On the other hand, if you're sure that you're splitting on a
Chris@0 236 * character boundary (e.g. after using strpos() or similar), you can safely
Chris@0 237 * use substr() instead.
Chris@0 238 *
Chris@0 239 * @param string $string
Chris@0 240 * The string to truncate.
Chris@0 241 * @param int $len
Chris@0 242 * An upper limit on the returned string length.
Chris@0 243 *
Chris@0 244 * @return string
Chris@0 245 * The truncated string.
Chris@0 246 */
Chris@0 247 public static function truncateBytes($string, $len) {
Chris@0 248 if (strlen($string) <= $len) {
Chris@0 249 return $string;
Chris@0 250 }
Chris@0 251 if ((ord($string[$len]) < 0x80) || (ord($string[$len]) >= 0xC0)) {
Chris@0 252 return substr($string, 0, $len);
Chris@0 253 }
Chris@0 254 // Scan backwards to beginning of the byte sequence.
Chris@0 255 // @todo Make the code more readable in https://www.drupal.org/node/2911497.
Chris@0 256 while (--$len >= 0 && ord($string[$len]) >= 0x80 && ord($string[$len]) < 0xC0) {
Chris@0 257 }
Chris@0 258
Chris@0 259 return substr($string, 0, $len);
Chris@0 260 }
Chris@0 261
Chris@0 262 /**
Chris@0 263 * Counts the number of characters in a UTF-8 string.
Chris@0 264 *
Chris@0 265 * This is less than or equal to the byte count.
Chris@0 266 *
Chris@0 267 * @param string $text
Chris@0 268 * The string to run the operation on.
Chris@0 269 *
Chris@0 270 * @return int
Chris@0 271 * The length of the string.
Chris@17 272 *
Chris@17 273 * @deprecated in Drupal 8.6.0, will be removed before Drupal 9.0.0. Use
Chris@17 274 * mb_strlen() instead.
Chris@17 275 *
Chris@17 276 * @see https://www.drupal.org/node/2850048
Chris@0 277 */
Chris@0 278 public static function strlen($text) {
Chris@17 279 @trigger_error('\Drupal\Component\Utility\Unicode::strlen() is deprecated in Drupal 8.6.0 and will be removed before Drupal 9.0.0. Use mb_strlen() instead. See https://www.drupal.org/node/2850048.', E_USER_DEPRECATED);
Chris@17 280 return mb_strlen($text);
Chris@0 281 }
Chris@0 282
Chris@0 283 /**
Chris@0 284 * Converts a UTF-8 string to uppercase.
Chris@0 285 *
Chris@0 286 * @param string $text
Chris@0 287 * The string to run the operation on.
Chris@0 288 *
Chris@0 289 * @return string
Chris@0 290 * The string in uppercase.
Chris@17 291 *
Chris@17 292 * @deprecated in Drupal 8.6.0, will be removed before Drupal 9.0.0. Use
Chris@17 293 * mb_strtoupper() instead.
Chris@17 294 *
Chris@17 295 * @see https://www.drupal.org/node/2850048
Chris@0 296 */
Chris@0 297 public static function strtoupper($text) {
Chris@17 298 @trigger_error('\Drupal\Component\Utility\Unicode::strtoupper() is deprecated in Drupal 8.6.0 and will be removed before Drupal 9.0.0. Use mb_strtoupper() instead. See https://www.drupal.org/node/2850048.', E_USER_DEPRECATED);
Chris@17 299 return mb_strtoupper($text);
Chris@0 300 }
Chris@0 301
Chris@0 302 /**
Chris@0 303 * Converts a UTF-8 string to lowercase.
Chris@0 304 *
Chris@0 305 * @param string $text
Chris@0 306 * The string to run the operation on.
Chris@0 307 *
Chris@0 308 * @return string
Chris@0 309 * The string in lowercase.
Chris@17 310 *
Chris@17 311 * @deprecated in Drupal 8.6.0, will be removed before Drupal 9.0.0. Use
Chris@17 312 * mb_strtolower() instead.
Chris@17 313 *
Chris@17 314 * @see https://www.drupal.org/node/2850048
Chris@0 315 */
Chris@0 316 public static function strtolower($text) {
Chris@17 317 @trigger_error('\Drupal\Component\Utility\Unicode::strtolower() is deprecated in Drupal 8.6.0 and will be removed before Drupal 9.0.0. Use mb_strtolower() instead. See https://www.drupal.org/node/2850048.', E_USER_DEPRECATED);
Chris@17 318 return mb_strtolower($text);
Chris@0 319 }
Chris@0 320
Chris@0 321 /**
Chris@0 322 * Capitalizes the first character of a UTF-8 string.
Chris@0 323 *
Chris@0 324 * @param string $text
Chris@0 325 * The string to convert.
Chris@0 326 *
Chris@0 327 * @return string
Chris@0 328 * The string with the first character as uppercase.
Chris@0 329 */
Chris@0 330 public static function ucfirst($text) {
Chris@17 331 return mb_strtoupper(mb_substr($text, 0, 1)) . mb_substr($text, 1);
Chris@0 332 }
Chris@0 333
Chris@0 334 /**
Chris@0 335 * Converts the first character of a UTF-8 string to lowercase.
Chris@0 336 *
Chris@0 337 * @param string $text
Chris@0 338 * The string that will be converted.
Chris@0 339 *
Chris@0 340 * @return string
Chris@0 341 * The string with the first character as lowercase.
Chris@0 342 *
Chris@0 343 * @ingroup php_wrappers
Chris@0 344 */
Chris@0 345 public static function lcfirst($text) {
Chris@0 346 // Note: no mbstring equivalent!
Chris@17 347 return mb_strtolower(mb_substr($text, 0, 1)) . mb_substr($text, 1);
Chris@0 348 }
Chris@0 349
Chris@0 350 /**
Chris@0 351 * Capitalizes the first character of each word in a UTF-8 string.
Chris@0 352 *
Chris@0 353 * @param string $text
Chris@0 354 * The text that will be converted.
Chris@0 355 *
Chris@0 356 * @return string
Chris@0 357 * The input $text with each word capitalized.
Chris@0 358 *
Chris@0 359 * @ingroup php_wrappers
Chris@0 360 */
Chris@0 361 public static function ucwords($text) {
Chris@0 362 $regex = '/(^|[' . static::PREG_CLASS_WORD_BOUNDARY . '])([^' . static::PREG_CLASS_WORD_BOUNDARY . '])/u';
Chris@0 363 return preg_replace_callback($regex, function (array $matches) {
Chris@17 364 return $matches[1] . mb_strtoupper($matches[2]);
Chris@0 365 }, $text);
Chris@0 366 }
Chris@0 367
Chris@0 368 /**
Chris@0 369 * Cuts off a piece of a string based on character indices and counts.
Chris@0 370 *
Chris@0 371 * Follows the same behavior as PHP's own substr() function. Note that for
Chris@0 372 * cutting off a string at a known character/substring location, the usage of
Chris@0 373 * PHP's normal strpos/substr is safe and much faster.
Chris@0 374 *
Chris@0 375 * @param string $text
Chris@0 376 * The input string.
Chris@0 377 * @param int $start
Chris@0 378 * The position at which to start reading.
Chris@0 379 * @param int $length
Chris@0 380 * The number of characters to read.
Chris@0 381 *
Chris@0 382 * @return string
Chris@0 383 * The shortened string.
Chris@17 384 *
Chris@17 385 * @deprecated in Drupal 8.6.0, will be removed before Drupal 9.0.0. Use
Chris@17 386 * mb_substr() instead.
Chris@17 387 *
Chris@17 388 * @see https://www.drupal.org/node/2850048
Chris@0 389 */
Chris@0 390 public static function substr($text, $start, $length = NULL) {
Chris@17 391 @trigger_error('\Drupal\Component\Utility\Unicode::substr() is deprecated in Drupal 8.6.0 and will be removed before Drupal 9.0.0. Use mb_substr() instead. See https://www.drupal.org/node/2850048.', E_USER_DEPRECATED);
Chris@17 392 return mb_substr($text, $start, $length);
Chris@0 393 }
Chris@0 394
Chris@0 395 /**
Chris@0 396 * Truncates a UTF-8-encoded string safely to a number of characters.
Chris@0 397 *
Chris@0 398 * @param string $string
Chris@0 399 * The string to truncate.
Chris@0 400 * @param int $max_length
Chris@0 401 * An upper limit on the returned string length, including trailing ellipsis
Chris@0 402 * if $add_ellipsis is TRUE.
Chris@0 403 * @param bool $wordsafe
Chris@0 404 * If TRUE, attempt to truncate on a word boundary. Word boundaries are
Chris@0 405 * spaces, punctuation, and Unicode characters used as word boundaries in
Chris@0 406 * non-Latin languages; see Unicode::PREG_CLASS_WORD_BOUNDARY for more
Chris@0 407 * information. If a word boundary cannot be found that would make the length
Chris@0 408 * of the returned string fall within length guidelines (see parameters
Chris@0 409 * $max_length and $min_wordsafe_length), word boundaries are ignored.
Chris@0 410 * @param bool $add_ellipsis
Chris@0 411 * If TRUE, add '...' to the end of the truncated string (defaults to
Chris@0 412 * FALSE). The string length will still fall within $max_length.
Chris@0 413 * @param int $min_wordsafe_length
Chris@0 414 * If $wordsafe is TRUE, the minimum acceptable length for truncation (before
Chris@0 415 * adding an ellipsis, if $add_ellipsis is TRUE). Has no effect if $wordsafe
Chris@0 416 * is FALSE. This can be used to prevent having a very short resulting string
Chris@0 417 * that will not be understandable. For instance, if you are truncating the
Chris@0 418 * string "See myverylongurlexample.com for more information" to a word-safe
Chris@0 419 * return length of 20, the only available word boundary within 20 characters
Chris@0 420 * is after the word "See", which wouldn't leave a very informative string. If
Chris@0 421 * you had set $min_wordsafe_length to 10, though, the function would realise
Chris@0 422 * that "See" alone is too short, and would then just truncate ignoring word
Chris@0 423 * boundaries, giving you "See myverylongurl..." (assuming you had set
Chris@0 424 * $add_ellipses to TRUE).
Chris@0 425 *
Chris@0 426 * @return string
Chris@0 427 * The truncated string.
Chris@0 428 */
Chris@0 429 public static function truncate($string, $max_length, $wordsafe = FALSE, $add_ellipsis = FALSE, $min_wordsafe_length = 1) {
Chris@0 430 $ellipsis = '';
Chris@0 431 $max_length = max($max_length, 0);
Chris@0 432 $min_wordsafe_length = max($min_wordsafe_length, 0);
Chris@0 433
Chris@17 434 if (mb_strlen($string) <= $max_length) {
Chris@0 435 // No truncation needed, so don't add ellipsis, just return.
Chris@0 436 return $string;
Chris@0 437 }
Chris@0 438
Chris@0 439 if ($add_ellipsis) {
Chris@0 440 // Truncate ellipsis in case $max_length is small.
Chris@17 441 $ellipsis = mb_substr('…', 0, $max_length);
Chris@17 442 $max_length -= mb_strlen($ellipsis);
Chris@0 443 $max_length = max($max_length, 0);
Chris@0 444 }
Chris@0 445
Chris@0 446 if ($max_length <= $min_wordsafe_length) {
Chris@0 447 // Do not attempt word-safe if lengths are bad.
Chris@0 448 $wordsafe = FALSE;
Chris@0 449 }
Chris@0 450
Chris@0 451 if ($wordsafe) {
Chris@0 452 $matches = [];
Chris@0 453 // Find the last word boundary, if there is one within $min_wordsafe_length
Chris@0 454 // to $max_length characters. preg_match() is always greedy, so it will
Chris@0 455 // find the longest string possible.
Chris@14 456 $found = preg_match('/^(.{' . $min_wordsafe_length . ',' . $max_length . '})[' . Unicode::PREG_CLASS_WORD_BOUNDARY . ']/us', $string, $matches);
Chris@0 457 if ($found) {
Chris@0 458 $string = $matches[1];
Chris@0 459 }
Chris@0 460 else {
Chris@17 461 $string = mb_substr($string, 0, $max_length);
Chris@0 462 }
Chris@0 463 }
Chris@0 464 else {
Chris@17 465 $string = mb_substr($string, 0, $max_length);
Chris@0 466 }
Chris@0 467
Chris@0 468 if ($add_ellipsis) {
Chris@0 469 // If we're adding an ellipsis, remove any trailing periods.
Chris@0 470 $string = rtrim($string, '.');
Chris@0 471
Chris@0 472 $string .= $ellipsis;
Chris@0 473 }
Chris@0 474
Chris@0 475 return $string;
Chris@0 476 }
Chris@0 477
Chris@0 478 /**
Chris@0 479 * Compares UTF-8-encoded strings in a binary safe case-insensitive manner.
Chris@0 480 *
Chris@0 481 * @param string $str1
Chris@0 482 * The first string.
Chris@0 483 * @param string $str2
Chris@0 484 * The second string.
Chris@0 485 *
Chris@0 486 * @return int
Chris@0 487 * Returns < 0 if $str1 is less than $str2; > 0 if $str1 is greater than
Chris@0 488 * $str2, and 0 if they are equal.
Chris@0 489 */
Chris@0 490 public static function strcasecmp($str1, $str2) {
Chris@17 491 return strcmp(mb_strtoupper($str1), mb_strtoupper($str2));
Chris@0 492 }
Chris@0 493
Chris@0 494 /**
Chris@0 495 * Encodes MIME/HTTP headers that contain incorrectly encoded characters.
Chris@0 496 *
Chris@0 497 * For example, Unicode::mimeHeaderEncode('tést.txt') returns
Chris@0 498 * "=?UTF-8?B?dMOpc3QudHh0?=".
Chris@0 499 *
Chris@0 500 * See http://www.rfc-editor.org/rfc/rfc2047.txt for more information.
Chris@0 501 *
Chris@0 502 * Notes:
Chris@0 503 * - Only encode strings that contain non-ASCII characters.
Chris@0 504 * - We progressively cut-off a chunk with self::truncateBytes(). This ensures
Chris@0 505 * each chunk starts and ends on a character boundary.
Chris@0 506 * - Using \n as the chunk separator may cause problems on some systems and
Chris@0 507 * may have to be changed to \r\n or \r.
Chris@0 508 *
Chris@0 509 * @param string $string
Chris@0 510 * The header to encode.
Chris@12 511 * @param bool $shorten
Chris@12 512 * If TRUE, only return the first chunk of a multi-chunk encoded string.
Chris@0 513 *
Chris@0 514 * @return string
Chris@0 515 * The mime-encoded header.
Chris@0 516 */
Chris@12 517 public static function mimeHeaderEncode($string, $shorten = FALSE) {
Chris@0 518 if (preg_match('/[^\x20-\x7E]/', $string)) {
Chris@0 519 // floor((75 - strlen("=?UTF-8?B??=")) * 0.75);
Chris@0 520 $chunk_size = 47;
Chris@0 521 $len = strlen($string);
Chris@0 522 $output = '';
Chris@0 523 while ($len > 0) {
Chris@0 524 $chunk = static::truncateBytes($string, $chunk_size);
Chris@0 525 $output .= ' =?UTF-8?B?' . base64_encode($chunk) . "?=\n";
Chris@12 526 if ($shorten) {
Chris@12 527 break;
Chris@12 528 }
Chris@0 529 $c = strlen($chunk);
Chris@0 530 $string = substr($string, $c);
Chris@0 531 $len -= $c;
Chris@0 532 }
Chris@0 533 return trim($output);
Chris@0 534 }
Chris@0 535 return $string;
Chris@0 536 }
Chris@0 537
Chris@0 538 /**
Chris@0 539 * Decodes MIME/HTTP encoded header values.
Chris@0 540 *
Chris@0 541 * @param string $header
Chris@0 542 * The header to decode.
Chris@0 543 *
Chris@0 544 * @return string
Chris@0 545 * The mime-decoded header.
Chris@0 546 */
Chris@0 547 public static function mimeHeaderDecode($header) {
Chris@0 548 $callback = function ($matches) {
Chris@0 549 $data = ($matches[2] == 'B') ? base64_decode($matches[3]) : str_replace('_', ' ', quoted_printable_decode($matches[3]));
Chris@0 550 if (strtolower($matches[1]) != 'utf-8') {
Chris@0 551 $data = static::convertToUtf8($data, $matches[1]);
Chris@0 552 }
Chris@0 553 return $data;
Chris@0 554 };
Chris@0 555 // First step: encoded chunks followed by other encoded chunks (need to collapse whitespace)
Chris@0 556 $header = preg_replace_callback('/=\?([^?]+)\?(Q|B)\?([^?]+|\?(?!=))\?=\s+(?==\?)/', $callback, $header);
Chris@0 557 // Second step: remaining chunks (do not collapse whitespace)
Chris@0 558 return preg_replace_callback('/=\?([^?]+)\?(Q|B)\?([^?]+|\?(?!=))\?=/', $callback, $header);
Chris@0 559 }
Chris@0 560
Chris@0 561 /**
Chris@0 562 * Flip U+C0-U+DE to U+E0-U+FD and back. Can be used as preg_replace callback.
Chris@0 563 *
Chris@0 564 * @param array $matches
Chris@0 565 * An array of matches by preg_replace_callback().
Chris@0 566 *
Chris@0 567 * @return string
Chris@0 568 * The flipped text.
Chris@0 569 */
Chris@0 570 public static function caseFlip($matches) {
Chris@0 571 return $matches[0][0] . chr(ord($matches[0][1]) ^ 32);
Chris@0 572 }
Chris@0 573
Chris@0 574 /**
Chris@0 575 * Checks whether a string is valid UTF-8.
Chris@0 576 *
Chris@0 577 * All functions designed to filter input should use drupal_validate_utf8
Chris@0 578 * to ensure they operate on valid UTF-8 strings to prevent bypass of the
Chris@0 579 * filter.
Chris@0 580 *
Chris@0 581 * When text containing an invalid UTF-8 lead byte (0xC0 - 0xFF) is presented
Chris@0 582 * as UTF-8 to Internet Explorer 6, the program may misinterpret subsequent
Chris@0 583 * bytes. When these subsequent bytes are HTML control characters such as
Chris@0 584 * quotes or angle brackets, parts of the text that were deemed safe by filters
Chris@0 585 * end up in locations that are potentially unsafe; An onerror attribute that
Chris@0 586 * is outside of a tag, and thus deemed safe by a filter, can be interpreted
Chris@0 587 * by the browser as if it were inside the tag.
Chris@0 588 *
Chris@0 589 * The function does not return FALSE for strings containing character codes
Chris@0 590 * above U+10FFFF, even though these are prohibited by RFC 3629.
Chris@0 591 *
Chris@0 592 * @param string $text
Chris@0 593 * The text to check.
Chris@0 594 *
Chris@0 595 * @return bool
Chris@0 596 * TRUE if the text is valid UTF-8, FALSE if not.
Chris@0 597 */
Chris@0 598 public static function validateUtf8($text) {
Chris@0 599 if (strlen($text) == 0) {
Chris@0 600 return TRUE;
Chris@0 601 }
Chris@0 602 // With the PCRE_UTF8 modifier 'u', preg_match() fails silently on strings
Chris@0 603 // containing invalid UTF-8 byte sequences. It does not reject character
Chris@0 604 // codes above U+10FFFF (represented by 4 or more octets), though.
Chris@0 605 return (preg_match('/^./us', $text) == 1);
Chris@0 606 }
Chris@0 607
Chris@0 608 /**
Chris@0 609 * Finds the position of the first occurrence of a string in another string.
Chris@0 610 *
Chris@0 611 * @param string $haystack
Chris@0 612 * The string to search in.
Chris@0 613 * @param string $needle
Chris@0 614 * The string to find in $haystack.
Chris@0 615 * @param int $offset
Chris@0 616 * If specified, start the search at this number of characters from the
Chris@0 617 * beginning (default 0).
Chris@0 618 *
Chris@0 619 * @return int|false
Chris@0 620 * The position where $needle occurs in $haystack, always relative to the
Chris@0 621 * beginning (independent of $offset), or FALSE if not found. Note that
Chris@0 622 * a return value of 0 is not the same as FALSE.
Chris@17 623 *
Chris@17 624 * @deprecated in Drupal 8.6.0, will be removed before Drupal 9.0.0. Use
Chris@17 625 * mb_strpos() instead.
Chris@17 626 *
Chris@17 627 * @see https://www.drupal.org/node/2850048
Chris@0 628 */
Chris@0 629 public static function strpos($haystack, $needle, $offset = 0) {
Chris@17 630 @trigger_error('\Drupal\Component\Utility\Unicode::strpos() is deprecated in Drupal 8.6.0 and will be removed before Drupal 9.0.0. Use mb_strpos() instead. See https://www.drupal.org/node/2850048.', E_USER_DEPRECATED);
Chris@17 631 return mb_strpos($haystack, $needle, $offset);
Chris@0 632 }
Chris@0 633
Chris@0 634 }