--- /dev/null
+* Ethna プロジェクト移行ガイド
+
+この文書には、Ethna のメジャーバージョンアップに伴う、古いプロジェクトの移行方法について
+の情報があります。
+
+* 2.3.x から 2.5.x への移行
+
+2.3.x から 2.5.x に移行する際の考慮点として、
+
+- 「必ずチェックし、対応すべき点」
+- 「移行の際に注意すべき点」
+
+の2つのレベルがあります。以下にそれを示しますので、留意の上移行作業及び検証作業を行うよう
+にして下さい。
+
+** 必ずチェックし、対応すべき点
+
+*** 1. 【重要】EUC-JP 依存からの脱却と移行
+
+2.5.x では、Ethna のソースコードそのものからエンコーディング依存のエラーメッセージを追い出
+し、プロジェクトで使用するエンコーディングをユーザが自由に指定できるように変更されました。
+これは Ethna が世に出てから脈々と息付いてきた「EUC-JP固定」の常識を破る一番大きな変更です。
+
+それにより、[appid]_Controller.php での ロケール指定、エンコーディング指定が必須になりまし
+た。2.3.x 以前で作ったプロジェクトを 2.5.x へ移行させる方は、[appid]_Controller.php で、
+Ethna_Controller#_getDefaultLanguage メソッドを以下の形で必ずオーバーライドするようにして
+ください。
+
+ /**
+ * デフォルト状態での使用言語を取得する
+ * 外部に出力されるEthnaのエラーメッセージ等のエンコーディングを
+ * 切り替えたい場合は、このメソッドをオーバーライドする。
+ *
+ * @access protected
+ */
+ function _getDefaultLanguage()
+ {
+ // ロケール名(e.x ja_JP, en_US 等),
+ // システムエンコーディング名,
+ // クライアントエンコーディング(= テンプレートのエンコーディング) の配列
+ //
+ // 古いプロジェクトで、テンプレートをEUC-JPで記述してきた人は、以下のよう
+ // に記述する。これが移行コストが一番小さい書き方。
+ return array('ja', 'EUC-JP', 'EUC-JP');
+
+ // ソースコードを強制的にUTF-8に変更してきた人は、以下のように記述
+ //return array('ja', 'UTF-8', 'UTF-8');
+ }
+
+上では、3つの要素からなる配列を返していますが、1番目と3番目が重要です。新しいやり方では、
+1番目の要素は ja_JP のようなロケールを指定するのが新しい流儀ですが、単に「ja」と指定して
+おけば 2. で述べるディレクトリ名の変更をする必要もなくなります。
+
+また、3番目の要素はテンプレートのエンコーディングを指定して下さい。このエンコーディングで
+ブラウザからの入力があることを 2.5.x では想定するため、この指定も非常に重要です。
+
+*** 2. ロケール指定
+
+2.5.x では、国際化対応も見据えた形で、テンプレートやメッセージファイルを格納するディレクト
+リをロケール単位で指定するように変更されました。よって、2.3.x より前に作られたプロジェクト
+を 2.5.x に移行させたい方で、国際化を考慮したいプロジェクトでは、以下のディレクトリ名を変更
+する必要があります。
+
+ (変更前)
+ - [appid]/locale/ja
+ - [appid]/template/ja
+
+ (変更後)
+ - [appid]/locale/ja_JP
+ - [appid]/template/ja_JP
+
+但し、上記 1. で [appid]_Controller#_getDefaultLanguage で返す配列の第1要素を 「ja」とオー
+バーライドした人は、この変更は必要ありません。
+
+*** 3. gettext の使用
+
+2.5.x では、gettext を利用した国際化を行う際には、[appid]/etc/[appid]-ini.php での設定が明
+示的に必須となりました。そのため、2.3.x 以前で gettext を使用していた方は、以下のように指定
+して下さい
+
+ ([appid]/etc/[appid]-ini.php)
+ $config = array(
+ // ....
+
+ // gettext を使用したい人は、明示的に指定
+ 'use_gettext' => true,
+ );
+
+*** 4. 国名指定の定数の削除
+
+Ethna 2.5.x では、ロケール指定への移行に伴い、国名を指定するための LANG_JA, LANG_EN の定数が
+Ethna.php から削除されました。これらは、Ethna_I18N.php でのみ使用されており、ロケール指定の観
+点から不要なためです。
+
+ (削除された定数定義)
+ /** クライアント言語定義: 英語 */
+ define('LANG_EN', 'en');
+ /** クライアント言語定義: 日本語 */
+ define('LANG_JA', 'ja');
+
+よって、これらの定数を万が一使用していた古いプロジェクトでは、[appid]_Controller.php の先頭
+で再定義する必要があります。
+
+** 移行の際に注意すべき点
+
+以下では、2.5.x への移行にあたって必須ではないものの、2.3.x とは非互換であることから、使い
+方によってはハマりどころとなる可能性がある項目を注意喚起の目的で記します。
+
+*** Ethna_ActionForm のバリデータ
+
+2.5.x では、フォームの入力値検証にプラグインのみを使用し、プラグインを使用しないコードは全
+て削除されました。2.3.x からの移行の観点からは、明示的な影響はないようにコードは書かれている
+はずですが、自動生成されるアクションスクリプトの $use_validator_plugin = true; の指定は最早
+不要です。
+
+*** include_path の順番
+
+2.5.x では、include_path の順番が [appid]/app,lib を最も優先するように変更されました。これは
+自由に外部スクリプトをインストールできないレンタルサーバを考慮した変更であり、新しいプロジェ
+クトのみに適用されます。
+
+* 2.1.x から 2.3.x への移行
+
+以下の URL をご覧ください。
+http://ethna.jp/ethna-document-dev_guide-misc-migrate_project.html#ef00d70f
'filelistgenerator' => 'file',
'ignore' => array('CVS/', '.svn/', 'package.xml', 'ethna_make_package.php', 'ethna_make_package.sh', '*optional_package*', ),
'changelogoldtonew' => false,
- 'exceptions' => array('README' => 'doc', 'LICENSE' => 'doc', 'CHANGES' => 'doc'),
+ 'exceptions' => array('README' => 'doc', 'LICENSE' => 'doc', 'CHANGES' => 'doc', 'UPGRADE' => 'doc'),
'description' => $description,
'exceptions' => array('bin/ethna.sh' => 'script', 'bin/ethna.bat' => 'script'),
'installexceptions' => array('bin/ethna.sh' => '/', 'bin/ethna.bat' => '/'),
OSDN Git Service
