The Cookbook へようこそ

以下の定数はCakePHPから削除されました。削除された定数にアプリケーションが依存しているなら、app/config/bootstrap.phpにこれらの定数を定義してください。

• CIPHER_SEED - Configureのクラス変数Security.cipherSeedに置き換えられました。 この変更はapp/config/core.phpに書かれるべきです。
• PEAR
• INFLECTIONS
• VALID_NOT_EMPTY
• VALID_EMAIL
• VALID_NUMBER
• VALID_YEAR

ブートストラップ時のパスの追加

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/')
));

1. App::build(array(
2. 'plugins' => array('/full/path/to/plugins/', '/next/full/path/to/plugins/'),
3. 'models' => array('/full/path/to/models/', '/next/full/path/to/models/'),
4. 'views' => array('/full/path/to/views/', '/next/full/path/to/views/'),
5. 'controllers' => array('/full/path/to/controllers/', '/next/full/path/to/controllers/'),
6. 'datasources' => array('/full/path/to/datasources/', '/next/full/path/to/datasources/'),
7. 'behaviors' => array('/full/path/to/behaviors/', '/next/full/path/to/behaviors/'),
8. 'components' => array('/full/path/to/components/', '/next/full/path/to/components/'),
9. 'helpers' => array('/full/path/to/helpers/', '/next/full/path/to/helpers/'),
10. 'vendors' => array('/full/path/to/vendors/', '/next/full/path/to/vendors/'),
11. 'shells' => array('/full/path/to/shells/', '/next/full/path/to/shells/'),
12. 'locales' => array('/full/path/to/locale/', '/next/full/path/to/locale/')
13. ));

またブートストラップするときの順序が変更されました。以前は、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')
));

1. Inflector::rules('singular', array(
2. 'rules' => array('/^(bil)er$/i' => '\1', '/^(inflec|contribu)tors$/i' => '\1ta'),
3. 'uninflected' => array('singulars'),
4. 'irregular' => array('spins' => 'spinor')
5. ));

こうして設定されるルールは、コアのルールより優先的に inflection のセットにマージされます。

ライブラリの名前の変更

ファイル名と含まれるメインクラスのマッピングのため、「libs/session.php」、「libs/socket.php」、「libs/model/schema.php」、「libs/model/behavior.php」のコアライブラリは名前が変更されています。:

• session.php -> cake_session.php

  • App::import('Core', 'Session') -> App::import('Core', 'CakeSession')

• socket.php -> cake_socket.php

  • App::import('Core', 'Socket') -> App::import('Core', 'CakeSocket')

• schema.php -> cake_schema.php

  • App::import('Model', 'Schema') -> App::import('Model', 'CakeSchema')

• behavior.php -> model_behavior.php

  • App::import('Core', 'Behavior') -> App::import('Core', 'ModelBehavior')

ほとんどの場合、これらの名前の変更はユーザランドのコードには影響しません。

Objectからの継承

以下のクラスはもはやObjectを継承しません。

• Router
• Set
• Inflector
• Cache
• CacheEngine

もしこれらのクラスでObjectのメソッドを使っているなら、それらのメソッドを使わないようにする必要があります。

CakeSession

• delは非推奨となりました。deleteを使用してください。

Folder

• mkdirは非推奨となりました。createを使用してください。
• mvは非推奨となりました。moveを使用してください。
• lsは非推奨となりました。readを使用してください。
• cpは非推奨となりました。copyを使用してください。
• rmは非推奨となりました。deleteを使用してください。

Set

• isEqualは非推奨となりました。PHP演算子「==」、「===」を使用してください。

String

• getInstanceは非推奨となりました。Stringは静的にアクセスしてください。

Router

Routing.adminは非推奨となりました。これはprefixが異なるルーティングの方式では、矛盾した振る舞いを提供していました。代わりにRouting.prefixesを使用すべきです。1.3のprefixルートは手動でルート定義を追加する必要がありません。全てのprefixルートは自動で生成されます。シンプルに変更するには、core.phpを変更してください。

// このような書き方から:
Configure::write('Routing.admin', 'admin');

// このような書き方へ:
Configure::write('Routing.prefixes', array('admin'));

1. // このような書き方から:
2. Configure::write('Routing.admin', 'admin');
3. // このような書き方へ:
4. Configure::write('Routing.prefixes', array('admin'));

prefixルートの更なる情報に関しては、新機能ガイドを見てください。また、ルーティングパラメータに小さな変更があります。ルーティングパラメータは今や英数字と「-」、「_」または/[A-Z0-9-_+]+/から成るべきです。

Router::connect('/:$%@#param/:action/*', array(...)); // BAD
Router::connect('/:can/:anybody/:see/:m-3/*', array(...)); //Acceptable

1. Router::connect('/:$%@#param/:action/*', array(...)); // BAD
2. Router::connect('/:can/:anybody/:see/:m-3/*', array(...)); //Acceptable

1.3のために、Routerの内部はパフォーマンス向上とコードの乱雑さを減らすために大規模に書き直されました。この副作用として、コードの基幹部分にあることと引き換えに、問題的でありバグを引き起こしやすかった二つのまれにしか使われない機能が削除されました。まず、フル正規表現を使うパスセグメントが削除されました。もう次のようなルートは作れません。

Router::connect('/([0-9]+)-p-(.*)/', array('controller' => 'products', 'action' => 'show'));

1. 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. Router::connect(
2. '/pages/*/:event',
3. array('controller' => 'pages', 'action' => 'display'),
4. array('event' => '[a-z0-9_-]+')
5. );

不規則な振る舞いやルートのコンパイルを複雑にするようなワイルドカードはもはやサポートされません。これら二つの境界ケースである機能と変更以外の振る舞いは、1.2のときと変わらず振舞います。

Dispatcher

Dispatcherはもはやリクエストパラメータを元にControllerのlayout/viewPathを設定しません。これらのプロパティはDispatcherではなくControllerによって操作されるべきです。この機能はドキュメント化、テストがされませんでした。

Debugger

• Debugger::checkSessionKey()はDebugger::checkSecurityKeys()に名前が変更されました。
• Debugger::output("text")といったコールはもはや正しく動きません。Debugger::output("txt")を使ってください。

Object

• Object::$_logは削除されました。今はCakeLog::writeが静的に呼び出されます。ログに加えられた変更の更なる情報はログの新しい機能をみてください。

Sanitize

• Sanitize::html()は、$remove引数を使うことによってHTMLエンティティのエンコーディングをせず、危険な内容を返すことを許してしまっていましたが、今や常にエスケープされた文字列を返します。
• Sanitize::clean()にはremove_htmlオプションが付け加えられています。これはencodeオプションと共に使われなければならず、Sanitize::html()のstrip_tagsの機能へのトリガとなります。

Configure と App

• Configure::listObjects() は App::objects() に置き換えられました。
• Configure::corePaths() は App::core() に置き換えられました。
• Configure::buildPaths() は App::build() に置き換えられました。
• Configure no longer manages paths.
• Configure::write('modelPaths', array...) は App::build(array('models' => array...)) に置き換えられました。
• Configure::read('modelPaths')は App::path('models') に置き換えられました。
• debug = 3はもうありません。この設定によって生成されるコントローラのダンプは、度々メモリの消費問題を引き起こし、非実用的で使用不可能な設定でした。また$cakeDebug変数はView::renderLayoutから削除されました。エラーを避けるためこの変数の参照を削除してください。
• Configure::load()を使ってプラグインから設定ファイルを読み込めるようになりました。Configure::load('plugin.file');として使ってください。.（訳注：ピリオド）を設定ファイル名に使っている場合は、_（アンダースコア）に置き換えるべきです。

Cache

アプリーション、コア、またはプラグインからキャッシュエンジンを読み込めることに加えて、CakePHP1.3ではCacheがいくらか書き直されました。書き直した点はメソッドのコールの呼び出しの頻度と回数を減らすことに主眼が置かれました。結果として、少しだけマイナーなAPIの変更があり、それに伴いかなりのパフォーマンスが向上しました。詳細は以下です。

Cacheはエンジン毎のシングルトンの使用をやめ、代わりにCache::config()で設定されるユニークキー毎にインスタンスが作られるようになりました。以来エンジンはシングルトンでなく、Cache::engine()は必要なくなり、削除されました。加えてCache::isInitialized()は今やエンジン名でなく、設定名をチェックするようになりました。しかしまだ、Cache::set()やCache::engine()をキャッシュの設定を変更するのに使えます。またCacheに追加されたメソッドの更なる情報は新機能ガイドをチェックしてください。

デフォルトのキャッシュ設定でアプリーション、コア、またはプラグインにあるキャッシュエンジンを使用すると、これらのクラスの読み込みが常にキャッシュされない為にパフォーマンス問題を引き起こすことがあることに注意すべきです。推奨されるのは、default設定にコアのキャッシュエンジンの一つを使用することか、もしくは設定をする以前に手動でキャッシュエンジンのクラスを include することです。なおその上、コアでないキャッシュエンジンの設定は上記の理由のため、app/config/bootstrap.phpで終わらせておくべきです。

View

• View::renderElementは削除されました。 代わりにView::element()を使用してください。
• ビューファイルの拡張子、.thtmlはもはや自動で読み込まれません。コントローラで$this->ext = 'thtml';を宣言するか、ビューファイルの拡張子を.ctpに変更してください。
• View::set('title', $var)をしてもレイアウト中で、 $title_for_layoutにセットされなくなりました。$title_for_layoutはデフォルトのままです。もしカスタマイズしたいなら、$this->set('title_for_layout', $var)を使用してください。
• View::$pageTitleは削除されました。代わりに$this->set('title_for_layout', $var);を使用してください。
• debug = 3 に関するレイアウト変数$cakeDebugは削除されました。この変数を参照してもエラーを引き起こしますので、レイアウト中にあるなら削除してください。また、更なる情報に関してはSQLログのダンプとConfigureに関するノートを見てください。

全てのコアヘルパーはもはやHelper::output()を使いません。このメソッドは矛盾した使われ方をしたり、多くのFormHelperのアウトプット問題を引き起こしてきたりしました。自動的にechoするようにAppHelper::output()をオーバーロードしているのなら、手動でヘルパーのアウトプットをechoするようにビューファイルを書き換える必要があるでしょう。

TextHelper

• TextHelper::trim()は非推奨となりました。代わりに truncate()を使用してください。
• TextHelper::highlight():
• $highlighter引数は削除されました。代わりに$options['format']を使用してください。
• $considerHtml引数は削除されました。代わりに$options['html']を使用してください。
• TextHelper::truncate():
• $ending引数は削除されました。代わりに$options['ending']を使用してください。
• $exact引数は削除されました。代わりに$options['exact']を使用してください。
• $considerHtml引数は削除されました。代わりに$options['html']を使用してください。

PaginatorHelper

PaginatorHelper にはスタイルをより簡単にするたくさんの機能強化があります。

prev()、next()、first()、last() のメソッドで、リンク先が無い場合リンクの代わりに<div>タグが返されていましたが、<span>がデフォルトになりました。

passedArgs が「url」オプションに自動的にマージされるようになりました。

sort()、prev()、next()は生成されるhtmlにクラス名を付与するようになりました。prev()は「prev」クラスを付与します。next()は「next」クラスを付与します。sort()は昇順なら「asc」クラス、降順なら「desc」クラスを付与します。

FormHelper

• FormHelper::dateTime()の$showEmpty引数は削除されました。代わりに$attributes['empty']を使用してください。
• FormHelper::year()の$showEmpty引数は削除されました。代わりに$attributes['empty']を使用してください。
• FormHelper::month()の$showEmpty引数は削除されました。代わりに$attributes['empty']を使用してください。
• FormHelper::day()の$showEmpty引数は削除されました。代わりに$attributes['empty']を使用してください。
• FormHelper::minute()の$showEmpty引数は削除されました。代わりに$attributes['empty']を使用してください。
• FormHelper::meridian()の$showEmpty引数は削除されました。代わりに$attributes['empty']を使用してください。
• FormHelper::select()の$showEmpty引数は削除されました。代わりに$attributes['empty']を使用してください。
• FormHelperが生成するデフォルトのURLはもはや「id」を含めません。これはデフォルトURLとユーザランドのルートの記述との矛盾をなくし、また、FormHelperのデフォルトURLを用いてより直感的な感覚でリバースルーティングを動作させるのを可能にします。
• FormHelper::submit()は type=submit 以外のタイプの input を作れるようになりました。「type」オプションを用いて生成される input をコントロールしてください。
• FormHelper::button()は「reset」や「clear」タイプの input の代わりに<button>タグを生成するようになりました。もし「reset」や「clear」タイプの input を生成したいなら、FormHelper::submit()のオプションを'type' => 'reset'などとして使ってください。
• FormHelper::secure()とFormHelper::create()はもはや隠し fieldset タグを作らなくなりました。代わりに隠し div タグが作られます。これは HTML4 の妥当性を向上させます。

また、FormHelperの変更と新機能をFormHelperの向上をチェックして確かめてください。

HtmlHelper

• HtmlHelper::meta()の$inline引数は削除されました。代わりに$options['inline']を使用してください。
• HtmlHelper::link()の$escapeTitle引数は削除されました。代わりに$options['escape']を使用してください。
• HtmlHelper::para()の$escape引数は削除されました。代わりに$options['escape']を使用してください。
• HtmlHelper::div()の$escape引数は削除されました。代わりに$options['escape']を使用してください。
• HtmlHelper::tag()の$escape引数は削除されました。代わりに$options['escape']を使用してください。
• HtmlHelper::css()の$inline引数は削除されました。代わりに$options['inline']を使用してください。

SessionHelper

• flash()はもはや自動的にechoされません。echo $session->flash();のようにしてください。flash() はヘルパメソッドの中で唯一自動的に出力されるメソッドでしたが、ヘルパメソッドとしての整合性をとるため変更されました。

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の変更によるものです。

• TimeHelper::format() は第一引数に時間文字列をとり、フォーマット文字列を第二引数、フォーマットはstrftime() の書式、とすることができるようになりました。このような引数の呼び出しがあった場合、自動的に現在のロケールに合わせた日付フォーマットに変換されます。また1.2.xバージョンの後方互換性を保った引数もとることが出来ますが、この場合はフォーマット文字列が date() の書式と互換性がなければなりません。
• TimeHelper::i18nFormat() が追加されました。

非推奨のHelper

JavascriptHelper と AjaxHelperは両方とも非推奨となり、JsHelper + HtmlHelper が代わって使われるべきです。

• $javascript->link()は $html->script()
に、
• $javascript->codeBlock()は $html->scriptBlock()もしくは $html->scriptStart()と $html->scriptEnd()に、用法に従って置き換えるべきです。

Shell

Shell::getAdmin()はProjectTask::getAdmin()に移動されました。

Schema shell

• cake schema run createはcake schema createに名前が変更されました。
• cake schema run updateはcake schema updateに名前が変更されました。

コンソールでのエラーハンドリング

シェルのディスパッチャーは、シェルで呼ばれたメソッドが明確に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()される

1. $this->error('Invalid Foo', 'Please provide bar.');
2. // 出力:
3. Error: Invalid Foo
4. Please provide bar.
5. // ステータスコード1でexit()される

ShellDispatcher::stderr()はメッセージの前に「Error:」を付け加えなくなりました。Shell::stdout()と同様になりました。

ShellDispatcher::shiftArgs()

このメソッドはシフトされた引数を返すようになりました。前は引数がない場合 false を返していましたが、今は null を返すようになりました。前は引数がある場合 true を返していましたが、今は代わりにシフトされた引数を返すようになりました。