[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  use dokuwiki\Utf8\Unicode;
   4  
   5  /**
   6   * Class to safely store UTF-8 in a Filename
   7   *
   8   * Encodes a utf8 string using only the following characters 0-9a-z_.-%
   9   * characters 0-9a-z in the original string are preserved, "plain".
  10   * all other characters are represented in a substring that starts
  11   * with '%' are "converted".
  12   * The transition from converted substrings to plain characters is
  13   * marked with a '.'
  14   *
  15   * @author   Christopher Smith <chris@jalakai.co.uk>
  16   * @date     2010-04-02
  17   */
  18  class SafeFN
  19  {
  20      // 'safe' characters are a superset of $plain, $pre_indicator and $post_indicator
  21      private static $plain = '-./[_0123456789abcdefghijklmnopqrstuvwxyz'; // these characters aren't converted
  22      private static $pre_indicator = '%';
  23      private static $post_indicator = ']';
  24  
  25      /**
  26       * Convert an UTF-8 string to a safe ASCII String
  27       *
  28       *  conversion process
  29       *    - if codepoint is a plain or post_indicator character,
  30       *      - if previous character was "converted", append post_indicator to output, clear "converted" flag
  31       *      - append ascii byte for character to output
  32       *      (continue to next character)
  33       *
  34       *    - if codepoint is a pre_indicator character,
  35       *      - append ascii byte for character to output, set "converted" flag
  36       *      (continue to next character)
  37       *
  38       *    (all remaining characters)
  39       *    - reduce codepoint value for non-printable ASCII characters (0x00 - 0x1f).  Space becomes our zero.
  40       *    - convert reduced value to base36 (0-9a-z)
  41       *    - append $pre_indicator characater followed by base36 string to output, set converted flag
  42       *    (continue to next character)
  43       *
  44       * @param    string    $filename     a utf8 string, should only include printable characters - not 0x00-0x1f
  45       * @return   string    an encoded representation of $filename using only 'safe' ASCII characters
  46       *
  47       * @author   Christopher Smith <chris@jalakai.co.uk>
  48       */
  49      public static function encode($filename)
  50      {
  51          return self::unicodeToSafe(Unicode::fromUtf8($filename));
  52      }
  53  
  54      /**
  55       *  decoding process
  56       *    - split the string into substrings at any occurrence of pre or post indicator characters
  57       *    - check the first character of the substring
  58       *      - if its not a pre_indicator character
  59       *        - if previous character was converted, skip over post_indicator character
  60       *        - copy codepoint values of remaining characters to the output array
  61       *        - clear any converted flag
  62       *      (continue to next substring)
  63       *
  64       *     _ else (its a pre_indicator character)
  65       *       - if string length is 1, copy the post_indicator character to the output array
  66       *       (continue to next substring)
  67       *
  68       *       - else (string length > 1)
  69       *         - skip the pre-indicator character and convert remaining string from base36 to base10
  70       *         - increase codepoint value for non-printable ASCII characters (add 0x20)
  71       *         - append codepoint to output array
  72       *       (continue to next substring)
  73       *
  74       * @param    string    $filename     a 'safe' encoded ASCII string,
  75       * @return   string    decoded utf8 representation of $filename
  76       *
  77       * @author   Christopher Smith <chris@jalakai.co.uk>
  78       */
  79      public static function decode($filename)
  80      {
  81          return Unicode::toUtf8(self::safeToUnicode(strtolower($filename)));
  82      }
  83  
  84      public static function validatePrintableUtf8($printable_utf8)
  85      {
  86          return !preg_match('#[\x01-\x1f]#', $printable_utf8);
  87      }
  88  
  89      public static function validateSafe($safe)
  90      {
  91          return !preg_match('#[^' . self::$plain . self::$post_indicator . self::$pre_indicator . ']#', $safe);
  92      }
  93  
  94      /**
  95       * convert an array of unicode codepoints into 'safe_filename' format
  96       *
  97       * @param    array  int    $unicode    an array of unicode codepoints
  98       * @return   string        the unicode represented in 'safe_filename' format
  99       *
 100       * @author   Christopher Smith <chris@jalakai.co.uk>
 101       */
 102      private static function unicodeToSafe($unicode)
 103      {
 104  
 105          $safe = '';
 106          $converted = false;
 107  
 108          foreach ($unicode as $codepoint) {
 109              if ($codepoint < 127 && (strpos(self::$plain . self::$post_indicator, chr($codepoint)) !== false)) {
 110                  if ($converted) {
 111                      $safe .= self::$post_indicator;
 112                      $converted = false;
 113                  }
 114                  $safe .= chr($codepoint);
 115              } elseif ($codepoint == ord(self::$pre_indicator)) {
 116                  $safe .= self::$pre_indicator;
 117                  $converted = true;
 118              } else {
 119                  $safe .= self::$pre_indicator . base_convert((string)($codepoint - 32), 10, 36);
 120                  $converted = true;
 121              }
 122          }
 123          if ($converted) $safe .= self::$post_indicator;
 124          return $safe;
 125      }
 126  
 127      /**
 128       * convert a 'safe_filename' string into an array of unicode codepoints
 129       *
 130       * @param   string         $safe     a filename in 'safe_filename' format
 131       * @return  array   int    an array of unicode codepoints
 132       *
 133       * @author   Christopher Smith <chris@jalakai.co.uk>
 134       */
 135      private static function safeToUnicode($safe)
 136      {
 137  
 138          $unicode = [];
 139          $split = preg_split(
 140              '#(?=[' . self::$post_indicator . self::$pre_indicator . '])#',
 141              $safe,
 142              -1,
 143              PREG_SPLIT_NO_EMPTY
 144          );
 145  
 146          $converted = false;
 147          foreach ($split as $sub) {
 148              $len = strlen($sub);
 149              if ($sub[0] != self::$pre_indicator) {
 150                  // plain (unconverted) characters, optionally starting with a post_indicator
 151                  // set initial value to skip any post_indicator
 152                  for ($i = ($converted ? 1 : 0); $i < $len; $i++) {
 153                      $unicode[] = ord($sub[$i]);
 154                  }
 155                  $converted = false;
 156              } elseif ($len == 1) {
 157                  // a pre_indicator character in the real data
 158                  $unicode[] = ord($sub);
 159                  $converted = true;
 160              } else {
 161                  // a single codepoint in base36, adjusted for initial 32 non-printable chars
 162                  $unicode[] = 32 + (int)base_convert(substr($sub, 1), 36, 10);
 163                  $converted = true;
 164              }
 165          }
 166  
 167          return $unicode;
 168      }
 169  }