Our Backward Compatibility Promise ¶

Ensuring smooth upgrades of your projects is our first priority. That's why we promise you backward compatibility (BC) for all minor Symfony releases. You probably recognize this strategy as Semantic Versioning. In short, Semantic Versioning means that only major releases (such as 5.0, 6.0 etc.) are allowed to break backward compatibility. Minor releases (such as 5.1, 5.2 etc.) may introduce new features, but must do so without breaking the existing API of that release branch (5.x in the previous example).

プロジェクトのスムーズなアップグレードを確実にすることが私たちの最優先事項です。そのため、Symfony のすべてのマイナーリリースに対して後方互換性 (BC) を約束します。おそらく、この戦略をセマンティックバージョニングと認識しているでしょう。つまり、セマンティックバージョニングとは、メジャーリリース (5.0、6.0 など) のみが下位互換性を破ることが許可されていることを意味します。マイナーリリース (5.1、5.2 など) では新しい機能が導入される場合がありますが、そのリリースブランチ (前の例では 5.x) の既存の API を壊さずに導入する必要があります。

We also provide deprecation message triggered in the code base to help you with the migration process across major releases.

また、メジャーリリース間の移行プロセスを支援するために、コードベースでトリガーされる非推奨メッセージも提供します。

However, backward compatibility comes in many different flavors. In fact, almost every change that we make to the framework can potentially break an application. For example, if we add a new method to a class, this will break an application which extended this class and added the same method, but with a different method signature.

ただし、下位互換性にはさまざまな種類があります。実際、フレームワークに加えるほぼすべての変更は、アプリケーションを壊す可能性があります。たとえば、クラスに新しいメソッドを追加すると、このクラスを拡張し、同じメソッドを追加したアプリケーションが壊れますが、メソッドシグネチャは異なります。

Also, not every BC break has the same impact on application code. While some BC breaks require you to make significant changes to your classes or your architecture, others are fixed by changing the name of a method.

また、すべての BC ブレークがアプリケーションコードに同じ影響を与えるわけではありません。一部の BCbreak では、クラスまたはアーキテクチャに大幅な変更を加える必要がありますが、メソッドの名前を変更することで修正されるものもあります。

That's why we created this page for you. The section "Using Symfony Code" will tell you how you can ensure that your application won't break completely when upgrading to a newer version of the same major release branch.

そのため、このページを作成しました。「Symfony コードの使用」セクションでは、同じメジャーリリースブランチの新しいバージョンにアップグレードするときに、アプリケーションが完全に壊れないようにする方法について説明します。

The second section, "Working on Symfony Code", is targeted at Symfony contributors. This section lists detailed rules that every contributor needs to follow to ensure smooth upgrades for our users.

2 番目のセクション「Symfony コードの作業」は、Symfony の貢献者を対象としています。このセクションでは、ユーザーがスムーズにアップグレードできるようにするために、すべての貢献者が従う必要がある詳細なルールを示します。

Caution

注意

Experimental Features and code marked with the @internal tags are excluded from our Backward Compatibility promise.

@internal タグでコードマークされた実験的な機能は、BackwardCompatibility の約束から除外されます。

Also note that backward compatibility breaks are tolerated if they are required to fix a security issue.

また、セキュリティ上の問題を修正する必要がある場合は、下位互換性の中断が許容されることにも注意してください。

Using Symfony Code ¶

If you are using Symfony in your projects, the following guidelines will help you to ensure smooth upgrades to all future minor releases of your Symfony version.

プロジェクトで Symfony を使用している場合、次のガイドラインは、Symfony バージョンの将来のすべてのマイナーリリースへのスムーズなアップグレードを保証するのに役立ちます。

Using our Interfaces ¶

All interfaces shipped with Symfony can be used in type hints. You can also call any of the methods that they declare. We guarantee that we won't break code that sticks to these rules.

Symfony に同梱されているすべてのインターフェースは、型ヒントで使用できます。それらが宣言する任意のメソッドを呼び出すこともできます。これらのルールに固執するコードを壊さないことを保証します。

Caution

注意

The exception to this rule are interfaces tagged with @internal. Such interfaces should not be used or implemented.

このルールの例外は、@internal でタグ付けされたインターフェイスです。このようなインターフェイスは使用または実装しないでください。

If you implement an interface, we promise that we won't ever break your code.

インターフェイスを実装する場合、コードを壊すことは決してないことをお約束します。

The following table explains in detail which use cases are covered by our backward compatibility promise:

次の表では、下位互換性に関する約束の対象となるユースケースについて詳しく説明しています。

Use Case	Backward Compatibility
If you...	Then we guarantee BC...
Type hint against the interface	Yes
Call a method	Yes [10]
If you implement the interface and...	Then we guarantee BC...
Implement a method	Yes
Add an argument to an implemented method	Yes
Add a default value to an argument	Yes
Add a return type to an implemented method	Yes

Using our Classes ¶

All classes provided by Symfony may be instantiated and accessed through their public methods and properties.

Symfony が提供するすべてのクラスは、パブリックメソッドとプロパティを介してインスタンス化およびアクセスできます。

Caution

注意

Classes, properties and methods that bear the tag @internal as well as the classes located in the various *\Tests\ namespaces are an exception to this rule. They are meant for internal use only and should not be accessed by your own code.

タグ @internal を持つクラス、プロパティ、メソッド、およびさまざまな *\Tests\ 名前空間にあるクラスは、この規則の例外です。これらは内部使用のみを目的としており、独自のコードからアクセスしないでください。

To be on the safe side, check the following table to know which use cases are covered by our backward compatibility promise:

安全を期すために、次の表を確認して、下位互換性の約束によってどのユースケースがカバーされているかを確認してください。

Use Case	Backward Compatibility
If you...	Then we guarantee BC...
Type hint against the class	Yes
Create a new instance	Yes
Extend the class	Yes
Access a public property	Yes
Call a public method	Yes [10]
If you extend the class and...	Then we guarantee BC...
Access a protected property	Yes
Call a protected method	Yes [10]
Override a public property	Yes
Override a protected property	Yes
Override a public method	Yes
Override a protected method	Yes
Add a new property	No
Add a new method	No
Add an argument to an overridden method	Yes
Add a default value to an argument	Yes
Call a private method (via Reflection)	No
Access a private property (via Reflection)	No

Using our Traits ¶

All traits provided by Symfony may be used in your classes.

Symfony が提供するすべてのトレイトは、クラスで使用できます。

Caution

注意

The exception to this rule are traits tagged with @internal. Such traits should not be used.

このルールの例外は、@internal でタグ付けされた特性です。そのような特性は使用しないでください。

To be on the safe side, check the following table to know which use cases are covered by our backward compatibility promise:

安全を期すために、次の表を確認して、下位互換性の約束によってどのユースケースがカバーされているかを確認してください。

Use Case	Backward Compatibility
If you...	Then we guarantee BC...
Use a trait	Yes
If you use the trait and...	Then we guarantee BC...
Use it to implement an interface	Yes
Use it to implement an abstract method	Yes
Use it to extend a parent class	Yes
Use it to define an abstract class	Yes
Use a public, protected or private property	Yes
Use a public, protected or private method	Yes

Working on Symfony Code ¶

Do you want to help us improve Symfony? That's great! However, please stick to the rules listed below in order to ensure smooth upgrades for our users.

Symfony の改善にご協力いただけますか?それは素晴らしいことです！ただし、ユーザーがスムーズにアップグレードできるように、以下のルールを守ってください。

Changing Interfaces ¶

This table tells you which changes you are allowed to do when working on Symfony's interfaces:

この表は、onSymfony のインターフェースを操作する際に許可されている変更を示しています。

Type of Change	Change Allowed	Notes
Remove entirely	No
Change name or namespace	No
Add parent interface	Yes	[2]
Remove parent interface	No
Methods
Add method	No
Remove method	No
Change name	No
Move to parent interface	Yes
Add argument without a default value	No
Add argument with a default value	No
Remove argument	No	[3]
Add default value to an argument	No
Remove default value of an argument	No
Add type hint to an argument	No
Remove type hint of an argument	No
Change argument type	No
Add return type	No
Remove return type	No	[9]
Change return type	No
Static Methods
Turn non static into static	No
Turn static into non static	No
Constants
Add constant	Yes
Remove constant	No
Change value of a constant	Yes	[1] [5]

Changing Classes ¶

This table tells you which changes you are allowed to do when working on Symfony's classes:

この表は、onSymfony のクラスを操作する際に許可されている変更を示しています。

Type of Change	Change Allowed	Notes
Remove entirely	No
Make final	No	[6]
Make abstract	No
Change name or namespace	No
Change parent class	Yes	[4]
Add interface	Yes
Remove interface	No
Public Properties
Add public property	Yes
Remove public property	No
Reduce visibility	No
Move to parent class	Yes
Protected Properties
Add protected property	Yes
Remove protected property	No	[7]
Reduce visibility	No	[7]
Make public	No	[7]
Move to parent class	Yes
Private Properties
Add private property	Yes
Make public or protected	Yes
Remove private property	Yes
Constructors
Add constructor without mandatory arguments	Yes	[1]
Remove constructor	No
Reduce visibility of a public constructor	No
Reduce visibility of a protected constructor	No	[7]
Move to parent class	Yes
Destructors
Add destructor	Yes
Remove destructor	No
Move to parent class	Yes
Public Methods
Add public method	Yes
Remove public method	No
Change name	No
Reduce visibility	No
Make final	No	[6]
Move to parent class	Yes
Add argument without a default value	No
Add argument with a default value	No	[7] [8]
Remove argument	No	[3]
Add default value to an argument	No	[7] [8]
Remove default value of an argument	No
Add type hint to an argument	No	[7] [8]
Remove type hint of an argument	No	[7] [8]
Change argument type	No	[7] [8]
Add return type	No	[7] [8]
Remove return type	No	[7] [8] [9]
Change return type	No	[7] [8]
Protected Methods
Add protected method	Yes
Remove protected method	No	[7]
Change name	No	[7]
Reduce visibility	No	[7]
Make final	No	[6]
Make public	No	[7] [8]
Move to parent class	Yes
Add argument without a default value	No	[7]
Add argument with a default value	No	[7] [8]
Remove argument	No	[3]
Add default value to an argument	No	[7] [8]
Remove default value of an argument	No	[7]
Add type hint to an argument	No	[7] [8]
Remove type hint of an argument	No	[7] [8]
Change argument type	No	[7] [8]
Add return type	No	[7] [8]
Remove return type	No	[7] [8] [9]
Change return type	No	[7] [8]
Private Methods
Add private method	Yes
Remove private method	Yes
Change name	Yes
Make public or protected	Yes
Add argument without a default value	Yes
Add argument with a default value	Yes
Remove argument	Yes
Add default value to an argument	Yes
Remove default value of an argument	Yes
Add type hint to an argument	Yes
Remove type hint of an argument	Yes
Change argument type	Yes
Add return type	Yes
Remove return type	Yes
Change return type	Yes
Static Methods and Properties
Turn non static into static	No	[7] [8]
Turn static into non static	No
Constants
Add constant	Yes
Remove constant	No
Change value of a constant	Yes	[1] [5]

Changing Traits ¶

This table tells you which changes you are allowed to do when working on Symfony's traits:

この表は、onSymfony の trait を操作する際に許可されている変更を示しています。

Type of Change	Change Allowed	Notes
Remove entirely	No
Change name or namespace	No
Use another trait	Yes
Public Properties
Add public property	Yes
Remove public property	No
Reduce visibility	No
Move to a used trait	Yes
Protected Properties
Add protected property	Yes
Remove protected property	No
Reduce visibility	No
Make public	No
Move to a used trait	Yes
Private Properties
Add private property	Yes
Remove private property	No
Make public or protected	Yes
Move to a used trait	Yes
Constructors and destructors
Have constructor or destructor	No
Public Methods
Add public method	Yes
Remove public method	No
Change name	No
Reduce visibility	No
Make final	No	[6]
Move to used trait	Yes
Add argument without a default value	No
Add argument with a default value	No
Remove argument	No
Add default value to an argument	No
Remove default value of an argument	No
Add type hint to an argument	No
Remove type hint of an argument	No
Change argument type	No
Change return type	No
Protected Methods
Add protected method	Yes
Remove protected method	No
Change name	No
Reduce visibility	No
Make final	No	[6]
Make public	No	[8]
Move to used trait	Yes
Add argument without a default value	No
Add argument with a default value	No
Remove argument	No
Add default value to an argument	No
Remove default value of an argument	No
Add type hint to an argument	No
Remove type hint of an argument	No
Change argument type	No
Change return type	No
Private Methods
Add private method	Yes
Remove private method	No
Change name	No
Make public or protected	Yes
Move to used trait	Yes
Add argument without a default value	No
Add argument with a default value	No
Remove argument	No
Add default value to an argument	No
Remove default value of an argument	No
Add type hint to an argument	No
Remove type hint of an argument	No
Change argument type	No
Add return type	No
Remove return type	No
Change return type	No
Static Methods and Properties
Turn non static into static	No
Turn static into non static	No

Notes ¶

[1] Should be avoided. When done, this change must be documented in the UPGRADE file.

[1] 避けるべき。完了したら、この変更をUPGRADEファイルに文書化する必要があります。

[2] The added parent interface must not introduce any new methods that don't exist in the interface already.

[2] 追加された親インターフェイスは、インターフェイスにまだ存在しない新しいメソッドを導入してはなりません。

[3] Only the last optional argument(s) of a method may be removed, as PHP does not care about additional arguments that you pass to a method.

[3] PHP はメソッドに渡された追加の引数を気にしないため、メソッドの最後のオプションの引数のみを削除できます。

[4] When changing the parent class, the original parent class must remain an ancestor of the class.

[4] 親クラスを変更する場合、元の親クラスはクラスの祖先のままである必要があります。

[5] The value of a constant may only be changed when the constants aren't used in configuration (e.g. Yaml and XML files), as these do not support constants and have to hardcode the value. For instance, event name constants can't change the value without introducing a BC break. Additionally, if a constant will likely be used in objects that are serialized, the value of a constant should not be changed.

[5] これらは定数をサポートしておらず、値をハードコードする必要があるため、定数の値は、定数が構成 (Yaml ファイルや XML ファイルなど) で使用されている場合にのみ変更できます。たとえば、イベント名の定数は、BC ブレークを導入しないと値を変更できません。さらに、シリアル化されたオブジェクトで aconstant が使用される可能性が高い場合は、aconstant の値を変更しないでください。

[6] Allowed using the @final annotation.

[6] @final アノテーションを使用して許可されます。

[7] Allowed if the class is final. Classes that received the @final annotation after their first release are considered final in their next major version. Changing an argument type is only possible with a parent type. Changing a return type is only possible with a child type.

[7] クラスが final の場合は許可されます。最初のリリース後に @finalannotation を受け取ったクラスは、次のメジャーバージョンで最終と見なされます。引数の型の変更は、親の型でのみ可能です。戻り型の変更は、子型でのみ可能です。

[8] Allowed if the method is final. Methods that received the @final annotation after their first release are considered final in their next major version. Changing an argument type is only possible with a parent type. Changing a return type is only possible with a child type.

[8] メソッドが final の場合に許可されます。最初のリリース後に @final アノテーションを受け取ったメソッドは、次のメジャーバージョンで最終と見なされます。引数の型の変更は、親の型でのみ可能です。戻り型の変更は、子型でのみ可能です。

[9] Allowed for the void return type.

[9] void 戻り値の型が許可されています。

[10] Parameter names are only covered by the compatibility promise for constructors of Attribute classes. Using PHP named arguments might break your code when upgrading to newer Symfony versions.

[10] パラメーター名は、属性クラスのコンストラクターの互換性の約束によってのみカバーされます。 PHP の名前付き引数を使用すると、Symfony の新しいバージョンにアップグレードするときにコードが壊れる可能性があります。