========================================== README for I18N Package ========================================== o Name and location of package Name: php-3.0.18-i18n-ja-2 Location: http://www.happysize.co.jp/techie/php-ja-jp/ ftp://ftp.happysize.co.jp/php-ja-jp/ http://php.vdomains.org/ ftp://ftp.vdomains.org/pub/php-ja-jp/ http://php.jpnnet.com/ Currently, this I18N version of PHP only adds Japanese support to base PHP. It allows you to use Japanese in scripts, as well as conversion between various Japanese encodings. It will work perfectly fine with ASCII with i18n option enabled. (note: executable is bit larger due to UNICODE table). The basic design aproach is to allow for other languages to be added in the future. Developers are encourage to join us! For more information on Japanese encodings, please refer to the section "Additional Notes." o What is this package? This package allows you to handle multiple Japanese encodings (SJIS, EUC, UTF-8, JIS) in PHP. If you find any bugs in this package, please report them to the appropriate mailing list. For now, the PHP-jp mailing list is the best place for this. PHP-jp ML mailto:PHP-jp@sidecar.ics.es.osaka-u.ac.jp http://sidecar.ics.es.osaka-u.ac.jp/php-jp/ (discussions are in Japanese) o Who should use this Due to lack of documentation, it's not intended for beginners. If something goes wrong, be prepared to fix it on your own. o Warranty and Copyright There is no warranty with this package. Use it at your own risk. Please refer to the source code for the copyrights. In general, each program's copyright is owned by the programmer. Unless you obey the copyright holders restrictions, you are not allowed to use it in any form. o Redistribution As described in the source code, this package and the components are allowed to be redistributed with certain restrictions. Due to this package being still in beta, please try to redistribute it as an entire package. Please try not to distribute it as a form of patch. Because we would prefer to have this package distributed as one single package (not patch of patch of patch), avoid releasing any patch to this package. o Who made this A team of volunteers, PHP3 Internationalization, has been contributing their free time producing it. Although we are not related to the core PHP programmers, we are hoping to have our modifications merged into the core distribution in the near future. Thus, we did not call this a "Japanese Patch" (or distribution). Our final goal is to have true i18nized PHP! For anyone interested in this project, please drop us a line. Contact Address: phpj-dev@kage.net (Discussions are in Japanese, but feel free to write us in English) Webpage (English and Japanese): http://php.jpnnet.com/ Project Outline (Japanese): http://www.happysize.co.jp/techie/php-ja-jp/spec.htm Developers: Hironori Sato Shigeru Kanemoto Tsukada Takuya U. Kenkichi Tateyama Other gracious contributors o Future plans - fulfilling what's written in outline - support for other languages other than Japanese - make the character conversion as a library (?) - more testing o Special Thanks to PHP Japanese webpage maintainer, Hirokawa-san http://www.cityfujisawa.ne.jp/%7Elouis/apps/phpfi/ PHP-JP ML's Yamamoto-san http://sidecar.ics.es.osaka-u.ac.jp/php-jp/ Previous jp-patch developers ========================================== Advantages of using I18N package ========================================== - allows you to use various character encodings for script files and http output - distinguish character encoding in POST/GET/COOKIE - proper mail output using JIS as body and MIME/Base64/JIS subject - if http output's Content-Type is text/html, it will set proper charset - stable character encoding conversion - multibyte regex ========================================== Installation ========================================== o Summary Add --enable-i18n option when running configure. For your own setup, add any other appropriate options as well. Don't forget to copy php3.ini-dist to desired location. (ex. /usr/local/lib/php3.ini) If you have already installed PHP3, copy all the entries in php3.ini-dist which start with "i18n.xxxx" to php3.ini. o configure option --enable-i18n include i18n features --enable-mbregex include multibyte regex library (without i18n enabled, mbregex functions will not function) o creating cgi version % tar xvzf php-3.0.18-i18n-ja-2.tar.gz % cd php-3.0.18-i18n-ja-2 % ./configure --enable-i18n --enable-mbregex % make o creating Apache version (regular module) % tar xvzf php-3.0.18-i18n-ja-2.tar.gz % tar xvzf apache_1.3.x.tar.gz % cd apache_1.3.x % ./configure % cd ../php-3.0.18-i18n-ja-2 % ./configure --with-apache=../apache_1.3.x --enable-i18n --enable-mbregex % make % make install % cd ../apache_1.3.x % ./configure --activate-module=src/modules/php3/libphp3.a % make % make install o creating Apache DSO version create DSO capable Apache first % tar xvzf apache_1.3.x.tar.gz % cd apache-1.3.x % ./configure --enable-shared=max % make % make install now create php3 % cd php-3.0.18-i18n-ja-2 % ./configure --with-apxs=/usr/local/apache/bin/apxs --enable-i18n \ --enable-mbregex % make % make install ========================================== Additional Notes ========================================== o Multibyte regex library From beta4, we have included the multibyte (mb) regex library which comes with Ruby. With this addition, you can now use regex in EUC, SJIS and UTF-8 encoding. To avoid any conflicts with HSREGEX included with Apache, each function name has been changed. Therefore, mb regex functions are named differently from the original ereg functions in PHP. The character encoding used in mb regex is configured in i18n.internal_encoding. o Binary Output If http output encoding is set to other than 'pass', conversion of encoding from internal encoding to http output is done automatically. Thus, if you prefer to spit out anything in raw binary format, your data may be corrupted. In such event, set http_output to 'pass'. ex. o Content-Type Depending on the setting of http_output, PHP will output the proper charset. ex. Content-Type: text/html; charset="..." Be aware of following: - If you set Content-Type header using header() function, that will override the automatic addition of charset. - Be cautious when you set i18n_http_output, since if any output is made prior to this, proper header may have been sent out to the client already. o In the event of trouble If you find any bugs or trouble, please contact us at the above address. It may help us to track the problem if you send us the script as well. If you encounter any memory related error such as segmentation violation, add --enable-debug when you run configure. This will give you more detail information on where error has occurred. The error is stored in the server log or regular http output in CGI mode. o About Japanese encodings Due to historical reason, there are multiple character encodings used for Japanese. The most common encodings are: SJIS, EUC, JIS, and UTF-8. Here are (very) brief description of them: EUC commonly used in UNIX environment 8bit-8bit combo always >=0x80 SJIS commonly used in Mac or PCs similar to EUC mostly 8bit-8bit (some 8bit-7bit) mostly >=0x80 there are some halfwidth (size of ASCII) multibytes JIS commonly used in 7bit environment (nntp and smtp) starts with escaping char, \033 and a few more characters UTF-8 16bit+ encoding defines many languages existing in this world see http://www.unicode.org/ for more detail Because of having all these character encodings, PHP needs to translate between these encodings on the fly. Also, the addition of the mb regex library allows you to handle mb strings without fear of getting mb char chopped in half. Since Japanese is not the only language with multiple encodings, we encourage other developers to modify our code to suit your needs. We definitely need people to work with Korean, Chinese (both traditional and simplified), and Russian. Let us know if you are interested in this project! ========================================== php3.ini setting ========================================== The following init options will allow you to change the default settings. Define these settings in the global section of php3.ini. All keywords are case-insensitive. o Encoding naming For each encoding, there are three names: standarized, alias, MIME - UTF-8 standard: UTF-8 alias: N/A mime: UTF-8 - ASCII standard: ASCII alias: N/A mime: US-ASCII - Japanese EUC standard: EUC-JP alias: EUC, EUC_JP, eucJP, x-euc-jp mime: EUC-JP - Shift JIS standard: SJIS alias: x-sjis, MS_Kanji mime: Shift_JIS - JIS standard: JIS alias: N/A mime: ISO-2022-JP - Quoted-Printable standard: Quoted-Printable alias: qprint mime: N/A - BASE64 standard: BASE64 alias: N/A mime: N/A - no conversion standard: pass alias: none mime: N/A - auto encoding detection standard: auto alias: unknown mime: N/A * N/A - Not Applicapable o i18n.http_output - default http output encoding i18n.http_output = EUC-JP|SJIS|JIS|UTF-8|pass EUC-JP : EUC SJIS: SJIS JIS : JIS UTF-8: UTF-8 pass: no conversion The default is pass (internal encoding is used) It can be re-configured on the fly using i18n_http_output(). o i18n.internal_encoding - internal encoding i18n.internal_encoding = EUC-JP|SJIS|UTF-8 EUC-JP : EUC SJIS: SJIS UTF-8: UTF-8 The default is EUC-JP. PHP parser is designed based on using ISO-8859-1. For other encodings, following conditions have to be satisfied in order to use them: - per byte encoding - single byte charactor in range of 00h-7fh which is compatible with ASCII - multibyte without 00h-7fh In case of Japanese, EUC-JP and UTF-8 are the only encoding that meets this criteria. If i18n.internal_encoding and i18n.http_output differs, conversion takes place at the time of output. If you convert any data within PHP scripts to URL encoding, BASE64 or Quoted-Printable, encoding stays as defined in i18n.internal_encoding. Thus, if you would prefer to encode in compliance with i18n.http_output, you need to manually convert encoding. ex. $str = urlencode( i18n_convert($str, i18n_http_output()) ); Encoding such as ISO-2022-** and HZ encoding which uses escape sequences can not be used as internal encoding. If used, they result in following errors: - parser pukes funky error - magic_quotes_*** breaks encoding (SJIS may have similar problem) - string manipulation and regex will malfunction o i18n.script_encoding - script encoding i18n.script_encoding = auto|EUC-JP|SJIS|JIS|UTF-8 auto: automatic EUC-JP : EUC SJIS: SJIS JIS : JIS UTF-8: UTF-8 The default is auto. The script's encoding is converted to i18n.internal_encoding before entering the script parser. Be aware that auto detection may fail under some conditions. For best auto detection, add multibyte charactor at beginning of script. o i18n.http_input - handling of http input (GET/POST/COOKIE) i18n.http_input = pass|auto auto: auto conversion pass: no conversion The default is auto. If set to pass, no conversion will take place. If set to auto, it will automatically detect the encoding. If detection is successful, it will convert to the proper internal encoding. If not, it will assume the input as defined in i18n.http_input_default. o i18n.http_input_default - default http input encoding i18n.http_input_default = pass|EUC-JP|SJIS|JIS|UTF-8 pass: no conversion EUC-JP : EUC SJIS: SJIS JIS : JIS UTF-8: UTF-8 The default is pass. This option is only effective as long as i18n.http_input is set to auto. If the auto detection fails, this encoding is used as an assumption to convert the http input to the internal encoding. If set to pass, no conversion will take place. o sample settings 1) For most flexibility, we recommend using following example. i18n.http_output = SJIS i18n.internal_encoding = EUC-JP i18n.script_encoding = auto i18n.http_input = auto i18n.http_input_default = SJIS 2) To avoid unexpected encoding problems, try these: i18n.http_output = pass i18n.internal_encoding = EUC-JP i18n.script_encoding = pass i18n.http_input = pass i18n.http_input_default = pass ========================================== PHP functions ========================================== The following describes the additional PHP functions. All keywords are case-insensitive. o i18n_http_output(encoding) o encoding = i18n_http_output() This will set the http output encoding. Any output following this function will be controlled by this function. If no argument is given, the current http output encode setting is returned. encodings EUC-JP : EUC SJIS: SJIS JIS : JIS UTF-8: UTF-8 pass: no conversion NONE is not allowed o encoding = i18n_internal_encoding() Returns the current internal encoding as a string. internal encoding EUC-JP : EUC SJIS: SJIS UTF-8: UTF-8 o encoding = i18n_http_input() Returns http input encoding. encodings EUC-JP : EUC SJIS: SJIS JIS : JIS UTF-8: UTF-8 pass: no conversion (only if i18n.http_input is set to pass) o string = i18n_convert(string, encoding) string = i18n_convert(string, encoding, pre-conversion-encoding) Returns converted string in desired encoding. If pre-conversion-encoding is not defined, the given string is assumed to be in internal encoding. encoding EUC-JP : EUC SJIS: SJIS JIS : JIS UTF-8: UTF-8 pass: no conversion pre-conversion-encoding EUC-JP : EUC SJIS: SJIS JIS : JIS UTF-8: UTF-8 pass: no conversion auto: auto detection o encoding = i18n_discover_encoding(string) Encoding of the given string is returned (as a string). encoding EUC-JP : EUC SJIS: SJIS JIS : JIS UTF-8: UTF-8 ASCII: ASCII (only 09h, 0Ah, 0Dh, 20h-7Eh) pass: unable to determine (text is too short to determine) unknown: unknown or possible error o int = mbstrlen(string) o int = mbstrlen(string, encoding) Returns character length of a given string. If no encoding is defined, the encoding of string is assumed to be the internal encoding. encoding EUC-JP : EUC SJIS: SJIS JIS : JIS UTF-8: UTF-8 auto: automatic o int = mbstrpos(string1, string2) o int = mbstrpos(string1, string2, start) o int = mbstrpos(string1, string2, start, encoding) Same as strpos. If no encoding is defined, the encoding of string is assumed to be the internal encoding. encoding EUC-JP : EUC SJIS: SJIS JIS : JIS UTF-8: UTF-8 o int = mbstrrpos(string1, string2) o int = mbstrrpos(string1, string2, encoding) Same as strrpos. If no encoding is defined, the encoding of string is assumed to be the internal encoding. encoding EUC-JP : EUC SJIS: SJIS JIS : JIS UTF-8: UTF-8 o string = mbsubstr(string, position) o string = mbsubstr(string, position, length) o string = mbsubstr(string, position, length, encoding) Same as substr. If no encoding is defined, the encoding of string is assumed to be the internal encoding. encoding EUC-JP : EUC SJIS: SJIS JIS : JIS UTF-8: UTF-8 o string = mbstrcut(string, position) o string = mbstrcut(string, position, length) o string = mbstrcut(string, position, length, encoding) Same as subcut. If position is the 2nd byte of a mb character, it will cut from the first byte of that character. It will cut the string without chopping a single byte from a mb character. In another words, if you set length to 5, you will only get two mb characters. If no encoding is defined, the encoding of string is assumed to be the internal encoding. encoding EUC-JP : EUC SJIS: SJIS JIS : JIS UTF-8: UTF-8 o string = i18n_mime_header_encode(string) MIME encode the string in the format of =?ISO-2022-JP?B?[string]?=. o string = i18n_mime_header_decode(string) MIME decodes the string. o string = i18n_ja_jp_hantozen(string) o string = i18n_ja_jp_hantozen(string, option) o string = i18n_ja_jp_hantozen(string, option, encoding) Conversion between full width character and halfwidth character. option The following options are allowed. The default is "KV". Acronym: FW = fullwidth, HW = halfwidth "r" : FW alphabet -> HW alphabet "R" : HW alphabet -> FW alphabet "n" : FW number -> HW number "N" : HW number -> FW number "a" : FW alpha numeric (21h-7Eh) -> HW alpha numeric "A" : HW alpha numeric (21h-7Eh) -> FW alpha numeric "k" : FW katakana -> HW katakana "K" : HW katakana -> FW katakana "h" : FW hiragana -> HW hiragana "H" : HW hiragana -> FW katakana "c" : FW katakana -> FW hiragana "C" : FW hiragana -> FW katakana "V" : merge dakuon character. only works with "K" and "H" option encoding If no encoding is defined, the encoding of string is assumed to be the internal encoding. EUC-JP : EUC SJIS: SJIS JIS : JIS UTF-8: UTF-8 int = mbereg(regex_pattern, string, string) int = mberegi(regex_pattern, string, string) mb version of ereg() and eregi() string = mbereg_replace(regex_pattern, string, string) string = mberegi_replace(regex_pattern, string, string) mb version of ereg_replace() and eregi_replace() string_array = mbsplit(regex, string, limit) mb version of split() ========================================== FAQ ========================================== Here, we have gathered some commonly asked questions on PHP-jp mailing list. o To use Japanese in GET method If you need to assign Japanese text in GET method with argument, such as; xxxx.php?data=, use urlencode function in PHP. If not, text may not be passed onto action php properly. ex: Link o When passing data via GET/POST/COOKIE, \ character sneaks in When using SJIS as internal encoding, or passed-on data includes '"\, PHP automatically inserts escaping character, \. Set magic_quotes_gpc in php3.ini from On to Off. An alternative work around to this problem is to use StripSlashes(). If $quote_str is in SJIS and you would like to extract Japanese text, use ereg_replace as follows: ereg_replace(sprintf("([%c-%c%c-%c]\\\\)\\\\",0x81,0x9f,0xe0,0xfc), "\\1",$quote_str); This will effectively extract Japanese text out of $quote_str. o Sometimes, encoding detection fails If i18n_http_input() returns 'pass', it's likely that PHP failed to detect whether it's SJIS or EUC. In such case, use to properly detect the incoming text's encoding. ========================================== Japanese Manual ========================================== Translated manual done by "PHP Japanese Manual Project" : http://www.php.net/manual/ja/manual.php Starting 3.0.18-i18n-ja, we have removed doc-jp from tarball package. ========================================== Change Logs ========================================== o 2000-10-28, Rui Hirokawa This patch is derived from php-3.0.15-i18n-ja as well as php-3.0.16 by Kuwamura applied to original php-3.0.18. It also includes following fixes: 1) allows you to set charset in mail(). 2) fixed mbregex definitions to avoid conflicts with system regex 3) php3.ini-dist now uses PASS for http_output instead of SJIS o 2000-11-24, Hironori Sato Applied above patched and added detection for gdImageStringTTF in configure. Following setups are known to work: gd-1.3-6, gd-devel-1.3-6, freetype-1.3.1-5, freetype-devel-1.3.1-5 ImageTTFText($im,$size,$angle,$x1,$y1,$color,"/path/to/font.ttf", i18n_convert("日本語", "UTF-8")); ImageGif($im); gd-1.7.3-1k1, gd-devel-1.7.3-1k1, freetype-1.3.1-5, freetype-devel-1.3.1-5 ImageTTFText($im,$size,$angle,$x1,$y1,$color,"/path/to/font.ttf","日本語"); ImagePng($im); * i18n_internal_encoding = EUC 又は SJIS For any gd libraries before 1.6.2, you need to use i18n_convert. For gd-1.5.2/3, upgrade to anything above 1.7 to use ImageTTFText without using i18n_convert. As long as you have internal_encoding set to EUC or SJIS, ImageTTFText should work without mojibake. Again, make sure you have i18n_http_output("pass") before calling ImageGif, ImagePng, ImageJpeg! o 2000-12-09, Rui Hirokawa Fixed mail() which was causing segmentation fault when header was null.