このガイドは、様々なコアの1.2から1.3への移行に際して必要な変更について要約します。 各々のセクションは、既存のメソッドの変更点はもちろん、削除・名前の変更がされたメソッドに関連した情報を含みます。
(重要)Appファイルの置き換え
以下の定数はCakePHPから削除されました。 削除された定数にアプリケーションが依存しているなら、 app/config/bootstrap.php にこれらの定数を定義してください。
ブートストラップ時のパスの追加
app/config/bootstrap.php に、 $pluginPaths や $controllerPaths のような変数が置かれているかもしれません。 以下はパスを追加する新しい方法です。1.3 RC1 では $pluginPaths 変数はもはや働かないでしょう。 パスを更新するには App::build() を使う必要があります。
App::build(array(
'plugins' => array('/full/path/to/plugins/', '/next/full/path/to/plugins/'),
'models' => array('/full/path/to/models/', '/next/full/path/to/models/'),
'views' => array('/full/path/to/views/', '/next/full/path/to/views/'),
'controllers' => array('/full/path/to/controllers/', '/next/full/path/to/controllers/'),
'datasources' => array('/full/path/to/datasources/', '/next/full/path/to/datasources/'),
'behaviors' => array('/full/path/to/behaviors/', '/next/full/path/to/behaviors/'),
'components' => array('/full/path/to/components/', '/next/full/path/to/components/'),
'helpers' => array('/full/path/to/helpers/', '/next/full/path/to/helpers/'),
'vendors' => array('/full/path/to/vendors/', '/next/full/path/to/vendors/'),
'shells' => array('/full/path/to/shells/', '/next/full/path/to/shells/'),
'locales' => array('/full/path/to/locale/', '/next/full/path/to/locale/'),
'libs' => array('/full/path/to/libs/', '/next/full/path/to/libs/')
));
またブートストラップするときの順序が変更されました。 以前は、 app/config/bootstrap.php の 後に app/config/core.php が読み込まれていました。 これはアプリケーションのブートストラップ時の App::import() がキャッシュせず、キャッシュがヒットしたときよりかなりかなり遅くなっていました。 1.3では、core.php の読み込みと設定のキャッシュは bootstrap.php の読み込みの 前に されます。
カスタム inflections の読み込み
不必要なファイルの読み込みをしていた inflections.php は削除され、関連した機能は柔軟性を増強するため、メソッドに書き直されています。 今やカスタム inflections を読み込むためには、 Inflector::rules() を使います。
Inflector::rules('singular', array(
'rules' => array('/^(bil)er$/i' => '\1', '/^(inflec|contribu)tors$/i' => '\1ta'),
'uninflected' => array('singulars'),
'irregular' => array('spins' => 'spinor')
));
こうして設定されるルールは、コアのルールより優先的に inflection のセットにマージされます。
ライブラリ名の変更
ファイル名と含まれるメインクラスのマッピングのため、「libs/session.php」、「libs/socket.php」、「libs/model/schema.php」、「libs/model/behavior.php」のコアライブラリは名前が変更されています。:
ほとんどの場合、これらの名前の変更はユーザランドのコードには影響しません。
Objectからの継承
以下のクラスはもはやObjectを継承しません。
もしこれらのクラスでObjectのメソッドを使っているなら、それらのメソッドを使わないようにする必要があります。
コントローラ
コンポーネント
CookieComponent
AclComponent + DbAcl
検索時に無駄に中継ノードを浪費すること、貪欲に検索すること無くパスを用いたノード参照のチェックが成されるようになりました。 以前はこのような構造が与えられると:
ROOT/
Users/
Users/
edit
ROOT/Users パスは最初でなく最後のUsersノードにマッチしていました。 1.3では、最後のノードを期待するならば、 ROOT/Users/Users をパスとして使う必要があります。
RequestHandlerComponent
SessionヘルパーとSessionコンポーネント
SessionComponent::setFlash() の2番目の引数は、レイアウトを指定するために使われ、それに応じてレイアウトファイルをレンダリングしていました。 これはエレメントを使うことに修正されました。 アプリケーションでセッションflashレイアウトをカスタムしたものを指定しているならば、下記のような変更を加える必要があります。
SessionComponent と SessionHelper の両方とも、もはやあなたが求めない限り自動で読み込まれなくなりました。 Sessionヘルパーと Sessionコンポーネントは他のコンポーネントと同じように振る舞い、他のヘルパ・コンポーネントと同じように宣言されなければなりません。 既存の振る舞いを保持するなら、 AppController::$components と AppController::$helpers にこれらのクラスを読み込むように書き換えてください。
var $components = array('Session', 'Auth', ...);
var $helpers = array('Session', 'Html', 'Form' ...);
これらの変更はCakePHPが、これらクラスを明白的に、また宣言的にアプリケーション開発者が使いたいように成されました。 過去にはコアファイルを修正することなくセッションを読み込むのを避けることはできませんでした。 この変更はあなたがこれを避けることを可能にします。 加えてセッションクラスは唯一の不思議なコンポーネントとヘルパーでした。 この変更は、すべてのクラスの振舞いの統一と正常化のためにもなります。
CakeSession
SessionComponent
Folder
Set
String
Router
Routing.admin は非推奨となりました。 これはprefixが異なるルーティングの方式では、矛盾した振る舞いを提供していました。 代わりに Routing.prefixes を使用する必要があります。 1.3のprefixルートは手動でルート定義を追加する必要がありません。 全てのprefixルートは自動で生成されます。シンプルに変更するには、core.phpを変更してください。
// このような書き方から:
Configure::write('Routing.admin', 'admin');
// このような書き方へ:
Configure::write('Routing.prefixes', array('admin'));
prefixルートの更なる情報に関しては、新機能ガイドを見てください。 また、ルーティングパラメータに小さな変更があります。 ルーティングパラメータは今や英数字と「-」、「_」または /[A-Z0-9-_+]+/ から成る必要があります。
Router::connect('/:$%@#param/:action/*', array(...)); // ダメ
Router::connect('/:can/:anybody/:see/:m-3/*', array(...)); // 許容可能
1.3のために、Routerの内部はパフォーマンス向上とコードの乱雑さを減らすために大規模に書き直されました。 この副作用として、コードの基幹部分にあることと引き換えに、問題的でありバグを引き起こしやすかった二つのまれにしか使われない機能が削除されました。 まず、フル正規表現を使うパスセグメントが削除されました。もう次のようなルートは作れません。
Router::connect('/([0-9]+)-p-(.*)/', array('controller' => 'products', 'action' => 'show'));
これらのルートは複雑なルートを悪化させ、リバースルーティングを不可能にします。 もし同じようなルートを必要とするなら、ルーティングパラメータにキャプチャパターンを用いるのが推奨されます。 次に、ルートの中間でのワイルドカードのサポートが削除されました。以前はワイルドカードがルートの中間で使えました。
Router::connect(
'/pages/*/:event',
array('controller' => 'pages', 'action' => 'display'),
array('event' => '[a-z0-9_-]+')
);
不規則な振る舞いやルートのコンパイルを複雑にするようなワイルドカードはもはやサポートされません。 これら二つの境界ケースである機能と変更以外の振る舞いは、1.2のときと変わらず振舞います。
また、配列形式のURLに「id」キーを用いている人は、Router::url()がこれを名前付き(named)パラメータとして扱うことに気づくでしょう。 もし過去にこのようなアプローチでIDパラメータをアクションに渡していたなら、この変更を反映するために、全ての $html->link() と $this->redirect() を書き換える必要あります。
// 古いフォーマット:
$url = array('controller' => 'posts', 'action' => 'view', 'id' => $id);
// ユースケース:
Router::url($url);
$html->link($url);
$this->redirect($url);
// 1.2 の結果:
/posts/view/123
// 1.3 の結果:
/posts/view/id:123
// 正しいフォーマット:
$url = array('controller' => 'posts', 'action' => 'view', $id);
Dispatcher
Dispatcherはもはやリクエストパラメータを元にControllerのlayout/viewPathを設定しません。 これらのプロパティはDispatcherではなくControllerによって操作されるべきです。 この機能はドキュメント化、テストがされていませんでした。
Debugger
Object
Sanitize
Configure と App
Cache
アプリーション、コア、またはプラグインからキャッシュエンジンを読み込めることに加えて、CakePHP1.3ではCacheがいくらか書き直されました。 書き直した点はメソッドのコールの呼び出しの頻度と回数を減らすことに主眼が置かれました。 結果として、少しだけマイナーなAPIの変更があり、それに伴いかなりのパフォーマンスが向上しました。詳細は以下です。
Cacheはエンジン毎のシングルトンの使用をやめ、代わりに Cache::config() で設定されるユニークキー毎にインスタンスが作られるようになりました。 以来エンジンはシングルトンでなく、 Cache::engine() は必要なくなり、削除されました。 加えて Cache::isInitialized() は エンジン名 でなく、 設定名 をチェックするようになりました。 しかしまだ、 Cache::set() や Cache::engine() をキャッシュの設定を変更するのに使えます。 また Cache に追加されたメソッドの更なる情報は CakePHP 1.3の新機能 をチェックしてください。
デフォルトのキャッシュ設定でアプリーション、コア、またはプラグインにあるキャッシュエンジンを使用すると、これらのクラスの読み込みが常にキャッシュされない為にパフォーマンス問題を引き起こすことがあることに注意すべきです。 推奨されるのは、 default 設定にコアのキャッシュエンジンの一つを使用することか、もしくは設定をする以前に手動でキャッシュエンジンのクラスを include することです。 なおその上、コアでないキャッシュエンジンの設定は上記の理由のため、 app/config/bootstrap.php で終わらせておくべきです。
モデル
データソース
データベース
ほとんどのデータベース設定はもはや’connect’キー(1.2以前から非推奨)をサポートしません。 代わりに、データベースへの持続的接続をするかどうかに関わらず、 'persistent' => true もしくはfalseを指定してください。
SQLログのダンプ
よく聞かれる質問は、どうやったらページの下のほうにあるSQLログのダンプを無効または削除できるのかというものです。 前のバージョンでは、SQLログのHTML生成はDboSourceの中に埋め込まれていました。 1.3には sql_dump というエレメントがコアにあります。 DboSource はもはや自動でSQLログを吐き出しません。 もし1.3でSQLログを吐き出したいなら、下記のようにしてください。
echo $this->element('sql_dump'); ?>
このエレメントはレイアウトやビューのどこにでも置けます。 sql_dump エレメントは Configure::read('debug') が2のときのみSQLログを生成します。 もちろん app/views/elements/sql_dump.ctp を作ることでappでカスタムやオーバーライドをすることができます。
View
全てのコアヘルパーはもう Helper::output() を使いません。 このメソッドは矛盾した使われ方をしたり、多くのFormHelperの出力に問題を引き起こしてきたりしました。 自動的にechoするように AppHelper::output() をオーバーロードしているのなら、手動でヘルパーのアウトプットをechoするようにビューファイルを書き換える必要があるでしょう。
TextHelper
PaginatorHelper
PaginatorHelper にはスタイルをより簡単にするたくさんの機能強化があります。 prev() 、 next() 、 first() 、 last() のメソッドで、リンク先が無い場合リンクの代わりに <div> タグが返されていましたが、 <span> がデフォルトになりました。
passedArgs が「url」オプションに自動的にマージされるようになりました。
sort() 、 prev() 、 next() は生成されるHTMLにクラス名を付与するようになりました。 prev() は「prev」クラスを付与します。 next() は「next」クラスを付与します。 sort() は昇順なら「asc」クラス、降順なら「desc」クラスを付与します。
FormHelper
また、FormHelperの変更と新機能を form-improvements-1-3 をチェックして確かめてください。
HtmlHelper
SessionHelper
CacheHelper
CacheHelperの Controller::$cacheAction との相互作用は少し変更されました。 以前は $cacheAction に配列を用いていたら、ルーティング済みのURLをキーにする必要がありました。 これはルートが変更されたときキャッシュの破壊を引き起こしていました。 また「pass」引数ごとにキャッシュの保持期間を設定できましたが、「named」引数やクエリ文字列ではできませんでした。 これらの制限・矛盾は取り除かれました。 今や $cacheAction のキーにコントローラのアクション名を用います。 これは $cacheAction の設定をもはやルーティングを介さないようにし、簡単にできるようにします。 もしキャッシュの保持期間を特殊な引数でカスタマイズしたいなら、コントローラで cacheAction を見つけそれを更新する必要があります。
TimeHelper
TimeHelperは i18n をよりフレンドリーに扱えるように書き直されました。 内部で date() をコールしていたところは strftime() に置き換えられました。 新しいメソッド TimeHelper::i18nFormat() が追加され、app/locale にあるPOSIX標準の LC_TIME 定義ファイルからローカライゼーションのためのデータを取得します。 これらは以下の TimeHelper のAPIの変更によるものです。
非推奨になったHelper
JavascriptHelper と AjaxHelperは両方とも非推奨となり、JsHelper + HtmlHelper が代わって使われるべきです。
以下のように置き換える必要があります:
Shell
Shell::getAdmin() は ProjectTask::getAdmin() に移動されました。
Schema shell
コンソールでのエラーハンドリング
シェルのディスパッチャーは、シェルで呼ばれたメソッドが明確に false を返り値としてもつと、ステータスコード 1 を用いて exit するようになりました。 他の返り値ではステータスコード 0 を用います。 以前は返り値をダイレクトにステータスコードとして用いてました。
シェルのメソッドでエラーを示すために 1 を返り値としていたものは、代わりに false を返すように書き換えられるべきです。
Shell::error() はエラーメッセージを出力した後に、ステータスコード 1 で exit します。 また、メッセージのフォーマットに多少の変更があります。
$this->error('Invalid Foo', 'Please provide bar.');
// 出力:
Error: Invalid Foo
Please provide bar.
// ステータスコード1でexit()される
ShellDispatcher::stderr() はメッセージの前に「Error:」を付け加えなくなりました。 これは Shell::stdout() と同様となったことと言えます。
ShellDispatcher::shiftArgs()
このメソッドはシフトされた引数を返すようになりました。 前は引数がない場合 false を返していましたが、今は null を返すようになりました。 前は引数がある場合 true を返していましたが、今は代わりにシフトされた引数を返すようになりました。
vendors/cssとvendors/jsとvendors/img
これら3つのディレクトリは、 app/vendors と plugin/vendors の両方から削除されています。 これらはpluginとthemeのwebrootに置き換えられました。
Test Suiteとユニットテスト
グループテストは今や非推奨のGroupTestクラスの代わりにTestSuiteクラスを継承するべきです。 もしあなたのグループテストがうまく走らないなら、基底クラスを変更する必要があります。
Vendorとプラグインとテーマのアセット
プラグインとテーマのwebrootディレクトリのために、Vendorのアセットの供給が1.3では削除されました。
SchemaShellで使われるスキーマファイルは app/config/sql から app/config/schema に移動されました。 config/sql は1.3で続けて利用できますが、次期バージョンではそうならないでしょう。