後方互換性ガイド

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

1(1,2,3,4,5)

マイナーリリースでコードが破壊される 恐れが あります。 詳細は移行ガイドをチェックしてください。

2(1,2)

古いクラス名・メソッド名を利用可能なようの残すことで名前の変更ができます。 通常、名前の変更は重要な利点を持っていない限り避けられます。

3(1,2)

出来る限り避けましょう。削除したことは移行ガイドに掲載する必要があります。

非推奨

各マイナーリリースでは、機能が非推奨になる可能性があります。 機能が非推奨になると、API ドキュメントや実行時の警告が追加されます。 実行時エラーは、コードが壊れる前に更新する必要があるコードを見つけるのに役立ちます。 実行時の警告を無効にするには、 Error.errorLevel 設定値を使用します。

// config/app.php の中で
// ...
'Error' => [
    'errorLevel' => E_ALL ^ E_USER_DEPRECATED,
]
// ...

これで、実行時の非推奨警告を無効にします。