後方互換性ガイド¶
アプリケーションを簡単に、円滑にアップグレードができるようになっていることは 重要なことです。 メジャーリリースのマイルストーンでのみ互換性を破棄するのはそのためです。 全ての CakePHP プロジェクトで使用する全般的なガイドラインである、 セマンティックバージョニング について理解したほうが 良いでしょう。 セマンティックバージョニングとは簡単に言うと、(2.0、3.0、4.0 のような) メジャーリリースのみ後方互換性を破棄することができ、(2.1、3.1、3.2 のような) マイナーリリースが新しい機能の導入をするが互換性を破棄することは許されず、 (2.1.2、3.0.1 のような) バグフィックスリリースは新機能の追加はせず、 バグの修正かパフォーマンスの向上のみにすることを意味します。
注釈
非推奨は、フレームワークの次のメジャーバージョンで削除されます。 非推奨のコメントや移行ガイドに記載されているように、コードに マイナーリリースの変更を早期に適用することをお勧めします。
それぞれのリリースに予定する変更を明確にするために、CakePHP を使う開発者と CakePHP の開発者のために、マイナーリリースでされ得る変更予定の助けとなる更に 詳しい情報があります。 メジャーリリースは必要に応じて多くの破壊的変更を含むことができます。
移行ガイド¶
メジャー・マイナーの各リリースについて、CakePHP チームは移行ガイドを提供します。 このガイドはそれぞれのリリースの新機能と非互換な変更を説明します。 これは Cookbook の 付録 セクションで見ることができます。
CakePHP の使用¶
CakePHP を用いてアプリケーションを構築している場合、次のガイドラインで示す堅牢性 (stability) が期待できます。
インターフェイス¶
メジャーリリース以外では、CakePHP が提供するどんな既存のメソッドの インターフェイスも変更 されません 。 新しいメソッドは、既存のインターフェイスには追加 されません 。
クラス¶
CakePHP が提供するクラスを構成する、アプリケーションから使われる public なメソッド とプロパティーがメジャーリリース以外で後方互換性が保証されます。
注釈
CakePHP のいくつかのクラスは @internal API ドキュメントタグがつけられています。
これらのクラスは堅牢 ではなく 、後方互換性は約束されていません。
マイナーリリースでは、クラスに新しいメソッドが追加されることがあり、 既存のメソッドは新しい引数が追加されることもあります。 新しい引数は必ずデフォルト値を持ちますが、異なる引数の形式でメソッドを オーバーライドしていると致命的な (fatal) エラーになることがあります。 新しい引数が追加されたメソッドは、そのリリースの移行ガイドに掲載されます。
下記のテーブルはいくつかのユースケースと CakePHP に予定する互換性についての 概要となります。
すること |
互換性 |
|---|---|
クラスに対するタイプヒント |
有り |
新しいインスタンスの作成 |
有り |
クラスの継承 |
有り |
public プロパティーへのアクセス |
有り |
public メソッドの呼び出し |
有り |
クラスを継承して... |
|
public プロパティーをオーバーライド |
有り |
protected プロパティーにアクセス |
無し [1] |
protected プロパティーをオーバーライド |
無し [1] |
protected メソッドをオーバーライド |
無し [1] |
protected メソッドの呼び出し |
無し [1] |
public プロパティーの追加 |
無し |
public メソッドの追加 |
無し |
オーバーライドされたメソッド への引数の追加 |
無し [1] |
既存メソッドの引数へのデフォルト値の の追加 |
有り |
CakePHP での作業¶
CakePHP をより良くする手助けをしようという場合、機能の追加・変更時に以下の ガイドラインに沿うように頭にとどめておいてください。
マイナーリリースでは次のことができます。
マイナーリリースでできること |
|
|---|---|
クラス |
|
クラスの削除 |
不可 |
インターフェイスの削除 |
不可 |
トレイトの削除 |
不可 |
final にする |
不可 |
abstract にする |
不可 |
名前の変更 |
可 [2] |
プロパティー |
|
public プロパティーの追加 |
可 |
public プロパティーの削除 |
不可 |
protected プロパティーの追加 |
可 |
protected プロパティーの削除 |
可 [3] |
メソッド |
|
public メソッドの追加 |
可 |
public メソッドの削除 |
不可 |
protected メソッドの追加 |
可 |
親クラスへの移動 |
可 |
protected メソッドの削除 |
可 [3] |
可視性の減少 |
不可 |
メソッド名の変更 |
可 [2] |
デフォルト値つき引数の新規追加 |
可 |
既存メソッドへの必須引数の 新規追加 |
不可 |
既存引数からのデフォルト値の 削除 |
不可 |
void 型メソッドの変更 |
可 |
非推奨¶
各マイナーリリースでは、機能が非推奨になる可能性があります。
機能が非推奨になると、API ドキュメントや実行時の警告が追加されます。
実行時エラーは、コードが壊れる前に更新する必要があるコードを見つけるのに役立ちます。
実行時の警告を無効にするには、 Error.errorLevel 設定値を使用します。
// config/app.php の中で
// ...
'Error' => [
'errorLevel' => E_ALL ^ E_USER_DEPRECATED,
]
// ...
これで、実行時の非推奨警告を無効にします。