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