1==========================================
2 README for I18N Package
3==========================================
4
5o Name and location of package
6
7Name: php-3.0.18-i18n-ja-2
8Location: http://www.happysize.co.jp/techie/php-ja-jp/
9 ftp://ftp.happysize.co.jp/php-ja-jp/
10 http://php.vdomains.org/
11 ftp://ftp.vdomains.org/pub/php-ja-jp/
12 http://php.jpnnet.com/
13
14Currently, this I18N version of PHP only adds Japanese support to base
15PHP. It allows you to use Japanese in scripts, as well as conversion
16between various Japanese encodings. It will work perfectly fine with
17ASCII with i18n option enabled. (note: executable is bit larger due
18to UNICODE table). The basic design aproach is to allow for other
19languages to be added in the future. Developers are encourage to join
20us!
21
22For more information on Japanese encodings, please refer to the
23section "Additional Notes."
24
25
26o What is this package?
27
28This package allows you to handle multiple Japanese encodings (SJIS, EUC,
29UTF-8, JIS) in PHP. If you find any bugs in this package, please report
30them to the appropriate mailing list. For now, the PHP-jp mailing list
31is the best place for this.
32
33PHP-jp ML mailto:PHP-jp@sidecar.ics.es.osaka-u.ac.jp
34 http://sidecar.ics.es.osaka-u.ac.jp/php-jp/
35 (discussions are in Japanese)
36
37
38o Who should use this
39
40Due to lack of documentation, it's not intended for beginners. If
41something goes wrong, be prepared to fix it on your own.
42
43
44o Warranty and Copyright
45
46There is no warranty with this package. Use it at your own risk.
47
48Please refer to the source code for the copyrights. In general, each
49program's copyright is owned by the programmer. Unless you obey the
50copyright holders restrictions, you are not allowed to use it in any
51form.
52
53
54o Redistribution
55
56As described in the source code, this package and the components are
57allowed to be redistributed with certain restrictions.
58
59Due to this package being still in beta, please try to redistribute
60it as an entire package. Please try not to distribute it as a form
61of patch. Because we would prefer to have this package distributed
62as one single package (not patch of patch of patch), avoid releasing
63any patch to this package.
64
65
66o Who made this
67
68A team of volunteers, PHP3 Internationalization, has been contributing
69their free time producing it. Although we are not related to the core
70PHP programmers, we are hoping to have our modifications merged into the
71core distribution in the near future. Thus, we did not call this a
72"Japanese Patch" (or distribution). Our final goal is to have true
73i18nized PHP!
74
75For anyone interested in this project, please drop us a line.
76
77Contact Address:
78 phpj-dev@kage.net
79 (Discussions are in Japanese, but feel free to write us in English)
80
81Webpage (English and Japanese):
82 http://php.jpnnet.com/
83
84Project Outline (Japanese):
85 http://www.happysize.co.jp/techie/php-ja-jp/spec.htm
86
87Developers:
88 Hironori Sato <satoh@jpnnet.com>
89 Shigeru Kanemoto <sgk@happysize.co.jp>
90 Tsukada Takuya <tsukada@fminn.nagano.nagano.jp>
91 U. Kenkichi <kenkichi@axes.co.jp>
92 Tateyama <tateyan@amy.hi-ho.ne.jp>
93 Other gracious contributors
94
95
96o Future plans
97
98- fulfilling what's written in outline
99- support for other languages other than Japanese
100- make the character conversion as a library (?)
101- more testing
102
103
104o Special Thanks to
105
106PHP Japanese webpage maintainer, Hirokawa-san
107 http://www.cityfujisawa.ne.jp/%7Elouis/apps/phpfi/
108PHP-JP ML's Yamamoto-san
109 http://sidecar.ics.es.osaka-u.ac.jp/php-jp/
110Previous jp-patch developers
111
112
113
114==========================================
115 Advantages of using I18N package
116==========================================
117
118- allows you to use various character encodings for script files and
119 http output
120- distinguish character encoding in POST/GET/COOKIE
121- proper mail output using JIS as body and MIME/Base64/JIS subject
122- if http output's Content-Type is text/html, it will set proper charset
123- stable character encoding conversion
124- multibyte regex
125
126
127
128==========================================
129 Installation
130==========================================
131
132o Summary
133
134Add --enable-i18n option when running configure. For your own setup,
135add any other appropriate options as well.
136
137Don't forget to copy php3.ini-dist to desired location.
138(ex. /usr/local/lib/php3.ini)
139
140If you have already installed PHP3, copy all the entries in php3.ini-dist
141which start with "i18n.xxxx" to php3.ini.
142
143
144o configure option
145 --enable-i18n
146 include i18n features
147
148 --enable-mbregex
149 include multibyte regex library
150 (without i18n enabled, mbregex functions will not function)
151
152
153o creating cgi version
154
155 % tar xvzf php-3.0.18-i18n-ja-2.tar.gz
156 % cd php-3.0.18-i18n-ja-2
157 % ./configure --enable-i18n --enable-mbregex
158 % make
159
160
161o creating Apache version (regular module)
162
163 % tar xvzf php-3.0.18-i18n-ja-2.tar.gz
164 % tar xvzf apache_1.3.x.tar.gz
165 % cd apache_1.3.x
166 % ./configure
167 % cd ../php-3.0.18-i18n-ja-2
168 % ./configure --with-apache=../apache_1.3.x --enable-i18n --enable-mbregex
169 % make
170 % make install
171 % cd ../apache_1.3.x
172 % ./configure --activate-module=src/modules/php3/libphp3.a
173 % make
174 % make install
175
176
177o creating Apache DSO version
178
179 create DSO capable Apache first
180 % tar xvzf apache_1.3.x.tar.gz
181 % cd apache-1.3.x
182 % ./configure --enable-shared=max
183 % make
184 % make install
185
186 now create php3
187 % cd php-3.0.18-i18n-ja-2
188 % ./configure --with-apxs=/usr/local/apache/bin/apxs --enable-i18n \
189 --enable-mbregex
190 % make
191 % make install
192
193
194==========================================
195 Additional Notes
196==========================================
197
198o Multibyte regex library
199
200From beta4, we have included the multibyte (mb) regex library which comes with
201Ruby. With this addition, you can now use regex in EUC, SJIS and UTF-8
202encoding. To avoid any conflicts with HSREGEX included with Apache,
203each function name has been changed. Therefore, mb regex functions are
204named differently from the original ereg functions in PHP. The character
205encoding used in mb regex is configured in i18n.internal_encoding.
206
207
208o Binary Output
209
210If http output encoding is set to other than 'pass', conversion of encoding
211from internal encoding to http output is done automatically. Thus,
212if you prefer to spit out anything in raw binary format, your data
213may be corrupted. In such event, set http_output to 'pass'.
214
215ex.
216 <?
217 i18n_http_output("pass");
218 ...
219 echo $the_binary_data_string;
220 ?>
221
222
223o Content-Type
224
225Depending on the setting of http_output, PHP will output the proper charset.
226ex. Content-Type: text/html; charset="..."
227
228Be aware of following:
229
230- If you set Content-Type header using header() function, that will
231 override the automatic addition of charset.
232- Be cautious when you set i18n_http_output, since if any output is
233 made prior to this, proper header may have been sent out to the
234 client already.
235
236
237o In the event of trouble
238
239If you find any bugs or trouble, please contact us at the above address.
240It may help us to track the problem if you send us the script as well.
241
242If you encounter any memory related error such as segmentation violation,
243add --enable-debug when you run configure. This will give you more
244detail information on where error has occurred. The error is stored
245in the server log or regular http output in CGI mode.
246
247
248o About Japanese encodings
249
250Due to historical reason, there are multiple character encodings used
251for Japanese. The most common encodings are: SJIS, EUC, JIS, and UTF-8.
252Here are (very) brief description of them:
253
254EUC
255 commonly used in UNIX environment
256 8bit-8bit combo
257 always >=0x80
258
259SJIS
260 commonly used in Mac or PCs
261 similar to EUC
262 mostly 8bit-8bit (some 8bit-7bit)
263 mostly >=0x80
264 there are some halfwidth (size of ASCII) multibytes
265
266JIS
267 commonly used in 7bit environment (nntp and smtp)
268 starts with escaping char, \033 and a few more characters
269
270UTF-8
271 16bit+ encoding
272 defines many languages existing in this world
273 see http://www.unicode.org/ for more detail
274
275Because of having all these character encodings, PHP needs to translate
276between these encodings on the fly. Also, the addition of the mb regex
277library allows you to handle mb strings without fear of getting mb char
278chopped in half.
279
280Since Japanese is not the only language with multiple encodings, we
281encourage other developers to modify our code to suit your needs. We
282definitely need people to work with Korean, Chinese (both traditional
283and simplified), and Russian. Let us know if you are interested in
284this project!
285
286
287
288==========================================
289 php3.ini setting
290==========================================
291
292The following init options will allow you to change the default settings.
293Define these settings in the global section of php3.ini.
294
295All keywords are case-insensitive.
296
297o Encoding naming
298
299 For each encoding, there are three names: standarized, alias, MIME
300
301 - UTF-8
302 standard: UTF-8
303 alias: N/A
304 mime: UTF-8
305
306 - ASCII
307 standard: ASCII
308 alias: N/A
309 mime: US-ASCII
310
311 - Japanese EUC
312 standard: EUC-JP
313 alias: EUC, EUC_JP, eucJP, x-euc-jp
314 mime: EUC-JP
315
316 - Shift JIS
317 standard: SJIS
318 alias: x-sjis, MS_Kanji
319 mime: Shift_JIS
320
321 - JIS
322 standard: JIS
323 alias: N/A
324 mime: ISO-2022-JP
325
326 - Quoted-Printable
327 standard: Quoted-Printable
328 alias: qprint
329 mime: N/A
330
331 - BASE64
332 standard: BASE64
333 alias: N/A
334 mime: N/A
335
336 - no conversion
337 standard: pass
338 alias: none
339 mime: N/A
340
341 - auto encoding detection
342 standard: auto
343 alias: unknown
344 mime: N/A
345
346 * N/A - Not Applicapable
347
348o i18n.http_output - default http output encoding
349
350 i18n.http_output = EUC-JP|SJIS|JIS|UTF-8|pass
351 EUC-JP : EUC
352 SJIS: SJIS
353 JIS : JIS
354 UTF-8: UTF-8
355 pass: no conversion
356
357 The default is pass (internal encoding is used)
358 It can be re-configured on the fly using i18n_http_output().
359
360
361o i18n.internal_encoding - internal encoding
362
363 i18n.internal_encoding = EUC-JP|SJIS|UTF-8
364 EUC-JP : EUC
365 SJIS: SJIS
366 UTF-8: UTF-8
367
368 The default is EUC-JP.
369
370 PHP parser is designed based on using ISO-8859-1. For other
371 encodings, following conditions have to be satisfied in order
372 to use them:
373 - per byte encoding
374 - single byte character in range of 00h-7fh which is compatible
375 with ASCII
376 - multibyte without 00h-7fh
377 In case of Japanese, EUC-JP and UTF-8 are the only encoding that
378 meets this criteria.
379
380 If i18n.internal_encoding and i18n.http_output differs, conversion
381 takes place at the time of output. If you convert any data within
382 PHP scripts to URL encoding, BASE64 or Quoted-Printable, encoding
383 stays as defined in i18n.internal_encoding. Thus, if you would
384 prefer to encode in compliance with i18n.http_output, you need
385 to manually convert encoding.
386
387 ex. $str = urlencode( i18n_convert($str, i18n_http_output()) );
388
389 Encoding such as ISO-2022-** and HZ encoding which uses escape
390 sequences can not be used as internal encoding. If used, they
391 result in following errors:
392 - parser pukes funky error
393 - magic_quotes_*** breaks encoding (SJIS may have similar problem)
394 - string manipulation and regex will malfunction
395
396
397o i18n.script_encoding - script encoding
398
399 i18n.script_encoding = auto|EUC-JP|SJIS|JIS|UTF-8
400 auto: automatic
401 EUC-JP : EUC
402 SJIS: SJIS
403 JIS : JIS
404 UTF-8: UTF-8
405
406 The default is auto.
407 The script's encoding is converted to i18n.internal_encoding before
408 entering the script parser.
409
410 Be aware that auto detection may fail under some conditions.
411 For best auto detection, add multibyte character at beginning of
412 script.
413
414
415o i18n.http_input - handling of http input (GET/POST/COOKIE)
416
417 i18n.http_input = pass|auto
418 auto: auto conversion
419 pass: no conversion
420
421 The default is auto.
422 If set to pass, no conversion will take place.
423 If set to auto, it will automatically detect the encoding. If
424 detection is successful, it will convert to the proper internal
425 encoding. If not, it will assume the input as defined in
426 i18n.http_input_default.
427
428o i18n.http_input_default - default http input encoding
429
430 i18n.http_input_default = pass|EUC-JP|SJIS|JIS|UTF-8
431 pass: no conversion
432 EUC-JP : EUC
433 SJIS: SJIS
434 JIS : JIS
435 UTF-8: UTF-8
436
437 The default is pass.
438 This option is only effective as long as i18n.http_input is set to
439 auto. If the auto detection fails, this encoding is used as an
440 assumption to convert the http input to the internal encoding.
441 If set to pass, no conversion will take place.
442
443o sample settings
444
445 1) For most flexibility, we recommend using following example.
446 i18n.http_output = SJIS
447 i18n.internal_encoding = EUC-JP
448 i18n.script_encoding = auto
449 i18n.http_input = auto
450 i18n.http_input_default = SJIS
451
452 2) To avoid unexpected encoding problems, try these:
453
454 i18n.http_output = pass
455 i18n.internal_encoding = EUC-JP
456 i18n.script_encoding = pass
457 i18n.http_input = pass
458 i18n.http_input_default = pass
459
460
461
462==========================================
463 PHP functions
464==========================================
465
466The following describes the additional PHP functions.
467
468All keywords are case-insensitive.
469
470o i18n_http_output(encoding)
471o encoding = i18n_http_output()
472
473 This will set the http output encoding. Any output following this
474 function will be controlled by this function. If no argument is given,
475 the current http output encode setting is returned.
476
477 encodings
478 EUC-JP : EUC
479 SJIS: SJIS
480 JIS : JIS
481 UTF-8: UTF-8
482 pass: no conversion
483
484 NONE is not allowed
485
486
487o encoding = i18n_internal_encoding()
488
489 Returns the current internal encoding as a string.
490
491 internal encoding
492 EUC-JP : EUC
493 SJIS: SJIS
494 UTF-8: UTF-8
495
496
497o encoding = i18n_http_input()
498
499 Returns http input encoding.
500
501 encodings
502 EUC-JP : EUC
503 SJIS: SJIS
504 JIS : JIS
505 UTF-8: UTF-8
506 pass: no conversion (only if i18n.http_input is set to pass)
507
508
509o string = i18n_convert(string, encoding)
510 string = i18n_convert(string, encoding, pre-conversion-encoding)
511
512 Returns converted string in desired encoding. If
513 pre-conversion-encoding is not defined, the given
514 string is assumed to be in internal encoding.
515
516 encoding
517 EUC-JP : EUC
518 SJIS: SJIS
519 JIS : JIS
520 UTF-8: UTF-8
521 pass: no conversion
522
523 pre-conversion-encoding
524 EUC-JP : EUC
525 SJIS: SJIS
526 JIS : JIS
527 UTF-8: UTF-8
528 pass: no conversion
529 auto: auto detection
530
531
532o encoding = i18n_discover_encoding(string)
533
534 Encoding of the given string is returned (as a string).
535
536 encoding
537 EUC-JP : EUC
538 SJIS: SJIS
539 JIS : JIS
540 UTF-8: UTF-8
541 ASCII: ASCII (only 09h, 0Ah, 0Dh, 20h-7Eh)
542 pass: unable to determine (text is too short to determine)
543 unknown: unknown or possible error
544
545
546o int = mbstrlen(string)
547o int = mbstrlen(string, encoding)
548
549 Returns character length of a given string. If no encoding is defined,
550 the encoding of string is assumed to be the internal encoding.
551
552 encoding
553 EUC-JP : EUC
554 SJIS: SJIS
555 JIS : JIS
556 UTF-8: UTF-8
557 auto: automatic
558
559
560o int = mbstrpos(string1, string2)
561o int = mbstrpos(string1, string2, start)
562o int = mbstrpos(string1, string2, start, encoding)
563
564 Same as strpos. If no encoding is defined, the encoding of string
565 is assumed to be the internal encoding.
566
567 encoding
568 EUC-JP : EUC
569 SJIS: SJIS
570 JIS : JIS
571 UTF-8: UTF-8
572
573
574o int = mbstrrpos(string1, string2)
575o int = mbstrrpos(string1, string2, encoding)
576
577 Same as strrpos. If no encoding is defined, the encoding of string
578 is assumed to be the internal encoding.
579
580 encoding
581 EUC-JP : EUC
582 SJIS: SJIS
583 JIS : JIS
584 UTF-8: UTF-8
585
586
587o string = mbsubstr(string, position)
588o string = mbsubstr(string, position, length)
589o string = mbsubstr(string, position, length, encoding)
590
591 Same as substr. If no encoding is defined, the encoding of string
592 is assumed to be the internal encoding.
593
594 encoding
595 EUC-JP : EUC
596 SJIS: SJIS
597 JIS : JIS
598 UTF-8: UTF-8
599
600
601o string = mbstrcut(string, position)
602o string = mbstrcut(string, position, length)
603o string = mbstrcut(string, position, length, encoding)
604
605 Same as subcut. If position is the 2nd byte of a mb character, it will cut
606 from the first byte of that character. It will cut the string without
607 chopping a single byte from a mb character. In another words, if you
608 set length to 5, you will only get two mb characters. If no encoding
609 is defined, the encoding of string is assumed to be the internal encoding.
610
611 encoding
612 EUC-JP : EUC
613 SJIS: SJIS
614 JIS : JIS
615 UTF-8: UTF-8
616
617
618o string = i18n_mime_header_encode(string)
619 MIME encode the string in the format of =?ISO-2022-JP?B?[string]?=.
620
621
622o string = i18n_mime_header_decode(string)
623 MIME decodes the string.
624
625
626o string = i18n_ja_jp_hantozen(string)
627o string = i18n_ja_jp_hantozen(string, option)
628o string = i18n_ja_jp_hantozen(string, option, encoding)
629
630 Conversion between full width character and halfwidth character.
631
632 option
633 The following options are allowed. The default is "KV".
634 Acronym: FW = fullwidth, HW = halfwidth
635
636 "r" : FW alphabet -> HW alphabet
637
638 "R" : HW alphabet -> FW alphabet
639
640 "n" : FW number -> HW number
641
642 "N" : HW number -> FW number
643
644 "a" : FW alpha numeric (21h-7Eh) -> HW alpha numeric
645
646 "A" : HW alpha numeric (21h-7Eh) -> FW alpha numeric
647
648 "k" : FW katakana -> HW katakana
649
650 "K" : HW katakana -> FW katakana
651
652 "h" : FW hiragana -> HW hiragana
653
654 "H" : HW hiragana -> FW katakana
655
656 "c" : FW katakana -> FW hiragana
657
658 "C" : FW hiragana -> FW katakana
659
660 "V" : merge dakuon character. only works with "K" and "H" option
661
662 encoding
663 If no encoding is defined, the encoding of string is assumed to be
664 the internal encoding.
665 EUC-JP : EUC
666 SJIS: SJIS
667 JIS : JIS
668 UTF-8: UTF-8
669
670
671int = mbereg(regex_pattern, string, string)
672int = mberegi(regex_pattern, string, string)
673 mb version of ereg() and eregi()
674
675
676string = mbereg_replace(regex_pattern, string, string)
677string = mberegi_replace(regex_pattern, string, string)
678 mb version of ereg_replace() and eregi_replace()
679
680
681string_array = mbsplit(regex, string, limit)
682 mb version of split()
683
684
685
686==========================================
687 FAQ
688==========================================
689
690Here, we have gathered some commonly asked questions on PHP-jp mailing
691list.
692
693o To use Japanese in GET method
694
695If you need to assign Japanese text in GET method with argument, such as;
696xxxx.php?data=<Japanese text>, use urlencode function in PHP. If not,
697text may not be passed onto action php properly.
698
699ex: <a href="hoge.php?data=<? echo urlencode($data) ?>">Link</a>
700
701
702o When passing data via GET/POST/COOKIE, \ character sneaks in
703
704When using SJIS as internal encoding, or passed-on data includes '"\,
705PHP automatically inserts escaping character, \. Set magic_quotes_gpc
706in php3.ini from On to Off. An alternative work around to this problem
707is to use StripSlashes().
708
709If $quote_str is in SJIS and you would like to extract Japanese text,
710use ereg_replace as follows:
711
712ereg_replace(sprintf("([%c-%c%c-%c]\\\\)\\\\",0x81,0x9f,0xe0,0xfc),
713 "\\1",$quote_str);
714
715This will effectively extract Japanese text out of $quote_str.
716
717
718o Sometimes, encoding detection fails
719
720If i18n_http_input() returns 'pass', it's likely that PHP failed to
721detect whether it's SJIS or EUC. In such case, use <input type=hidden
722value="some Japanese text"> to properly detect the incoming text's
723encoding.
724
725
726
727==========================================
728 Japanese Manual
729==========================================
730Translated manual done by "PHP Japanese Manual Project" :
731
732http://www.php.net/manual/ja/manual.php
733
734Starting 3.0.18-i18n-ja, we have removed doc-jp from tarball package.
735
736
737==========================================
738 Change Logs
739==========================================
740
741o 2000-10-28, Rui Hirokawa <hirokawa@php.net>
742
743This patch is derived from php-3.0.15-i18n-ja as well as php-3.0.16 by
744Kuwamura applied to original php-3.0.18. It also includes following fixes:
745
7461) allows you to set charset in mail().
7472) fixed mbregex definitions to avoid conflicts with system regex
7483) php3.ini-dist now uses PASS for http_output instead of SJIS
749
750o 2000-11-24, Hironori Sato <satoh@yyplanet.com>
751
752Applied above patched and added detection for gdImageStringTTF in configure.
753Following setups are known to work:
754
755gd-1.3-6, gd-devel-1.3-6, freetype-1.3.1-5, freetype-devel-1.3.1-5
756 ImageTTFText($im,$size,$angle,$x1,$y1,$color,"/path/to/font.ttf",
757 i18n_convert("���ܸ�", "UTF-8"));
758 ImageGif($im);
759
760gd-1.7.3-1k1, gd-devel-1.7.3-1k1, freetype-1.3.1-5, freetype-devel-1.3.1-5
761 ImageTTFText($im,$size,$angle,$x1,$y1,$color,"/path/to/font.ttf","���ܸ�");
762 ImagePng($im);
763 * i18n_internal_encoding = EUC ���� SJIS
764
765For any gd libraries before 1.6.2, you need to use i18n_convert. For
766gd-1.5.2/3, upgrade to anything above 1.7 to use ImageTTFText without
767using i18n_convert. As long as you have internal_encoding set to EUC or
768SJIS, ImageTTFText should work without mojibake. Again, make sure you
769have i18n_http_output("pass") before calling ImageGif, ImagePng, ImageJpeg!
770
771o 2000-12-09, Rui Hirokawa <hirokawa@php.net>
772
773Fixed mail() which was causing segmentation fault when header was null.
774
