inc/SafeFN.class.php

   1 <?php
   2
   3 use dokuwiki\Utf8\Unicode;
   4 /**
   5  * Class to safely store UTF-8 in a Filename
   6  *
   7  * Encodes a utf8 string using only the following characters 0-9a-z_.-%
   8  * characters 0-9a-z in the original string are preserved, "plain".
   9  * all other characters are represented in a substring that starts
  10  * with '%' are "converted".
  11  * The transition from converted substrings to plain characters is
  12  * marked with a '.'
  13  *
  14  * @author   Christopher Smith <chris@jalakai.co.uk>
  15  * @date     2010-04-02
  16  */
  17 class SafeFN
  18 {
  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 }