Backwards Compatibility Guide

Backwards Compatibility Guide

Ensuring that you can upgrade your applications easily and smoothly is importantto us. That’s why we only break compatibility at major release milestones.You might be familiar with semantic versioning, which isthe general guideline we use on all CakePHP projects. In short, semanticversioning means that only major releases (such as 2.0, 3.0, 4.0) can breakbackwards compatibility. Minor releases (such as 2.1, 3.1, 3.2) may introduce newfeatures, but are not allowed to break compatibility. Bug fix releases (such as 2.1.2,3.0.1) do not add new features, but fix bugs or enhance performance only.

Note

Deprecations are removed with the next major version of the framework.It is advised to early on adapt your code already each minor as outlined inthe deprecation comments and the migration guides.

To clarify what changes you can expect in each release tier we have moredetailed information for developers using CakePHP, and for developers working onCakePHP that helps set expectations of what can be done in minor releases. Majorreleases can have as many breaking changes as required.

Migration Guides

For each major and minor release, the CakePHP team will provide a migrationguide. These guides explain the new features and any breaking changes that arein each release. They can be found in the Appendices section of thecookbook.

Using CakePHP

If you are building your application with CakePHP, the following guidelinesexplain the stability you can expect.

Interfaces

Outside of major releases, interfaces provided by CakePHP will not have anyexisting methods changed. New methods may be added, but no existing methods willbe changed.

Classes

Classes provided by CakePHP can be constructed and have their public methods andproperties used by application code and outside of major releases backwardscompatibility is ensured.

Note

Some classes in CakePHP are marked with the @internal API doc tag. Theseclasses are not stable and do not have any backwards compatibilitypromises.

In minor releases, new methods may be added to classes, and existing methods mayhave new arguments added. Any new arguments will have default values, but ifyou’ve overridden methods with a differing signature you may see fatal errors.Methods that have new arguments added will be documented in the migration guidefor that release.

The following table outlines several use cases and what compatibility you canexpect from CakePHP:

If you…	Backwards compatibility?
Typehint against the class	Yes
Create a new instance	Yes
Extend the class	Yes
Access a public property	Yes
Call a public method	Yes
Extend a class and…
Override a public property	Yes
Access a protected property	No [1]
Override a protected property	No [1]
Override a protected method	No [1]
Call a protected method	No [1]
Add a public property	No
Add a public method	No
Add an argumentto an overridden method	No [1]
Add a default argument valueto an existing methodargument	Yes

Working on CakePHP

If you are helping make CakePHP even better please keep the following guidelinesin mind when adding/changing functionality:

In a minor release you can:

In a minor release can you…
Classes
Remove a class	No
Remove an interface	No
Remove a trait	No
Make final	No
Make abstract	No
Change name	Yes [2]
Properties
Add a public property	Yes
Remove a public property	No
Add a protected property	Yes
Remove a protected property	Yes [3]
Methods
Add a public method	Yes
Remove a public method	No
Add a protected method	Yes
Move to parent class	Yes
Remove a protected method	Yes [3]
Reduce visibility	No
Change method name	Yes [2]
Add a new argument withdefault value	Yes
Add a new required argumentto an existing method.	No
Remove a default value froman existing argument	No
Change method type void	Yes

[1]	(1, 2, 3, 4, 5) Your code may be broken by minor releases. Check the migration guidefor details.

[2]	(1, 2) You can change a class/method name as long as the old name remainsavailable. This is generally avoided unless renaming has significantbenefit.

[3]	(1, 2) Avoid whenever possible. Any removals need to be documented inthe migration guide.

Deprecations

In each minor release, features may be deprecated. If features are deprecated,API documentation and runtime warnings will be added. Runtime errors help youlocate code that needs to be updated before it breaks. If you wish to disableruntime warnings you can do so using the Error.errorLevel configurationvalue:

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

Will disable runtime deprecation warnings.