vendor/wikimedia/utfnormal/README.md

   1 [![Latest Stable Version](https://poser.pugx.org/wikimedia/utfnormal/v/stable.svg)](https://packagist.org/packages/wikimedia/utfnormal) [![License](https://poser.pugx.org/wikimedia/utfnormal/license.svg)](https://packagist.org/packages/wikimedia/utfnormal)
   2
   3 utfnormal
   4 =========
   5
   6 utfnormal is a library that contains Unicode normalization routines, including
   7 both pure PHP implementations and automatic use of the 'intl' PHP extension when
   8  present.
   9
  10 The main function to care about is UtfNormal\Validator::cleanUp(). This will
  11 strip illegal UTF-8 sequences and characters that are illegal in XML, and
  12 if necessary convert to normalization form C.
  13
  14 If you know the string is already valid UTF-8, you can directly call
  15 UtfNormal\Validator::toNFC(), toNFK(), or toNFKC(); this will convert a given
  16 UTF-8 string to Normalization Form C, K, or KC if it's not already such.
  17 The function assumes that the input string is already valid UTF-8; if there
  18 are corrupt characters this may produce erroneous results.
  19
  20 Performance is kind of stinky in absolute terms, though it should be speedy
  21 on pure ASCII text. ;) On text that can be determined quickly to already be
  22 in NFC it's not too awful but it can quickly get uncomfortably slow,
  23 particularly for Korean text (the hangul decomposition/composition code is
  24 extra slow).
  25
  26 Bugs should be filed in [Wikimedia's Phabricator] under the "utfnormal" project.
  27
  28
  29 Regenerating data tables
  30 ------------------------
  31 UtfNormalData.inc and UtfNormalDataK.inc are generated from the Unicode
  32 Character Database by the script "generate.php". Run "composer generate"
  33 to rebuild the tables. To fetch updated unicode data from the internet,
  34 run "composer generate -- --fetch".
  35
  36
  37 Testing
  38 -------
  39
  40 Running "composer test" will run a syntax checker, PHPUnit conformance tests,
  41 and run some benchmarks using sample texts from Wikipedia. Take all benchmark
  42 numbers with large grains of salt.
  43
  44
  45 PHP module extension
  46 --------------------
  47
  48 If the 'intl' PHP extension is present, ICU library functions are used which
  49 are *MUCH* faster than doing this work in pure PHP code.
  50
  51 It is strongly recommended to enable this module if possible:
  52 http://php.net/manual/en/intro.intl.php
  53
  54 Older versions of this library supported a one-off custom PHP extension,
  55 which has been dropped. If you were using this, please migrate to the
  56 intl extension.
  57
  58
  59 History
  60 -------
  61 This library was first introduced in [MediaWiki 1.3][] ([r4965]). It was
  62 split out of the MediaWiki codebase and published as an independent library
  63 during the [MediaWiki 1.25][] development cycle.
  64
  65 ---
  66 [Wikimedia's Phabricator]: https://phabricator.wikimedia.org/maniphest/task/create/?projects=utfnormal
  67 [MediaWiki 1.3]: https://www.mediawiki.org/wiki/MediaWiki_1.3
  68 [r4965]: https://www.mediawiki.org/wiki/Special:Code/MediaWiki/4965
  69 [MediaWiki 1.25]: https://www.mediawiki.org/wiki/MediaWiki_1.25