後方互換性ガイド

アプリケーションを簡単に、円滑にアップグレードができるようになっていることは 重要なことです。 メジャーリリースのマイルストーンでのみ互換性を破棄するのはそのためです。 全ての CakePHP プロジェクトで使用する全般的なガイドラインである、 セマンティックバージョニング について理解したほうが 良いでしょう。 セマンティックバージョニングとは簡単に言うと、(2.0、3.0、4.0 のような) メジャーリリースのみ後方互換性を破棄することができ、(2.1、3.1、3.2 のような) マイナーリリースが新しい機能の導入をするが互換性を破棄することは許されず、 (2.1.2、3.0.1 のような) バグフィックスリリースは新機能の追加はせず、 バグの修正かパフォーマンスの向上のみにすることを意味します。

注釈

CakePHP はセマンティックバージョニングを 2.0.0 から採用を始めています。 これらのルールは 1.x 系には適用されません。

それぞれのリリースに予定する変更を明確にするために、CakePHP を使う開発者と CakePHP の開発者のために、マイナーリリースでされ得る変更予定の助けとなる更に 詳しい情報があります。 メジャーリリースは必要に応じて多くの破壊的変更を含むことができます。

移行ガイド

メジャー・マイナーの各リリースについて、CakePHP チームは移行ガイドを提供します。 このガイドはそれぞれのリリースの新機能と非互換な変更を説明します。 これは Cookbook の 付録 セクションで見ることができます。

CakePHP の使用

CakePHP を用いてアプリケーションを構築している場合、次のガイドラインで示す堅牢性 (stability) が期待できます。

インターフェース

メジャーリリース以外では、CakePHP が提供するどんな既存のメソッドの インターフェースも変更 されません 。 新しいメソッドは、既存のインターフェースには追加 されません

クラス

CakePHP が提供するクラスを構成する、アプリケーションから使われる public なメソッド とプロパティがメジャーリリース以外で後方互換性が保証されます。

注釈

CakePHP のいくつかのクラスは @internal API ドキュメントタグがつけられています。 これらのクラスは堅牢 ではなく 、後方互換性は約束されていません。

マイナーリリース (3.x.0) では、クラスに新しいメソッドが追加されることがあり、 既存のメソッドは新しい引数が追加されることもあります。 新しい引数は必ずデフォルト値を持ちますが、異なる引数の形式でメソッドを オーバーライドしているとエラーになることがあります。 新しい引数が追加されたメソッドは、そのリリースの移行ガイドに掲載されます。

下記のテーブルはいくつかのユースケースと CakePHP に予定する互換性についての 概要となります:

すること 互換性
クラスに対するタイプヒント 有り
新しいインスタンスの作成 有り
クラスの継承 有り
public プロパティへのアクセス 有り
public メソッドの呼び出し 有り
クラスを継承して…
protected メソッドの呼び出し 無し [1]
protected プロパティをオーバーライド 無し [1]
protected メソッドをオーバーライド 無し [1]
protected プロパティにアクセス 無し [1]
public メソッドの呼び出し 有り
public メソッドをオーバーライド 有り [1]
public プロパティをオーバーライド 有り
public プロパティの追加 無し
public メソッドの追加 無し
オーバーライドされたメソッド への引数の追加 無し [1]
既存メソッドへのデフォルト 引数の追加 有り

CakePHP での作業

CakePHP をより良くする手助けをしようという場合、機能の追加・変更時に以下の ガイドラインに沿うように頭にとどめておいてください:

マイナーリリースでは次のことができます:

マイナーリリースでできること
クラス
クラスの削除 不可
インターフェースの削除 不可
トレイトの削除 不可
final にする 不可
abstract にする 不可
名前の変更 [2]
プロパティ
public プロパティの追加
public プロパティの削除 不可
protected プロパティの追加
protected プロパティの削除 [3]
メソッド
public メソッドの追加
public メソッドの削除 不可
protected メソッドの追加
親クラスへのメンバーの移動
protected メソッドの削除 [3]
可視性の減少 不可
メソッド名の変更 [2]
既存の引数への デフォルト値の追加 不可
デフォルト値つき引数の追加
必須引数の追加 不可
[1](1, 2, 3, 4, 5, 6) マイナーリリースでコードが破壊される 恐れが あります。 詳細は移行ガイドをチェックしてください。
[2](1, 2) 古いクラス名・メソッド名を利用可能なようの残すことで名前の変更ができます。 通常、名前の変更は重要な利点を持っていない限り避けられます。
[3](1, 2) 出来る限り避けましょう。削除したことは移行ガイドに掲載する必要があります。