1<?php
2
3use 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 */
18class 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}
170