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