後方互換性ガイド

アプリケーションを簡単に、円滑にアップグレードができるようになっていることは 重要なことです。 メジャーリリースのマイルストーンでのみ互換性を破棄するのはそのためです。 全ての 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]

既存の引数への デフォルト値の追加

不可

デフォルト値つき引数の追加

必須引数の追加

不可