向后兼容性指南

确保您可以轻松顺利地升级您的应用程序，这对我们是很重要的。这就是为什么我们只在主要版本里程碑才会打破兼容性。你可能熟悉 语义版本控制 ，这就是我们在所有的 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 的 Appendices 一节中看到。

使用 CakePHP

如果你使用 CakePHP 来构建应用程序，下面的指南说明了你可以预期的稳定性。

接口

除了主要版本，CakePHP 提供的接口的任何现有的方法 不 会改变，现有的接口不会增加新的方法。

类

CakePHP 提供的类可以实例化，并且它们的公共方法和属性，可以被应用代码使用，除了主要版本，(其他的版本)可以保证向后兼容性。

注解

一些 CakePHP 的类标有 @internal API 文档标签(API doc tag)。这些类不 稳定，不能保证向后兼容性。

在次要版本中，类可以添加新方法，已有的方法可以添加新的参数。任何新参数必须有缺省值，但如果你用不同的签名重载方法，你可能会遇到致命错误(fatal errors)。添加了新参数的方法，会在那个版本的升级指南中说明。

下面的表格列出一些用例，以及你从 CakePHP 可以期望得到的兼容性：

如果你……向后兼容性？
使用类作为类型约束是
创建新的实例是
扩展类是
访问公共属性是
调用公共方法是
扩展类并且……
重载公共属性是
访问受保护的属性否 [1]
重载受保护的属性否 [1]
重载受保护的方法否 [1]
调用受保护的方法否 [1]
添加公共属性否
添加公共方法否
为重载的方法添加参数否 [1]
为已有的方法添加缺省参数是

开发 CakePHP

如果你帮助改进 CakePHP，在添加/修改功能时，请记住下面的指南：

在次要版本中，你可以：

在次要版本中你能……
类
删除类否
删除接口否
删除 trait否
改变为 final否
改变为 abstract否
改变名称是 [2]
属性
添加公共属性是
删除公共属性否
添加受保护的属性是
删除受保护的属性是 [3]
方法
添加公共方法是
删除公共方法否
添加受保护的方法是
迁移到父类是
删除受保护的方法是 [3]
降低访问控制（可见性）否
改变方法名称是 [2]
添加带缺省值的参数是
添加必需的参数否
[1](1, 2, 3, 4, 5) 你的代码可能会被次要版本打破(兼容性)。查看升级指南了解详情。
[2](1, 2) 只要原有的名称仍然可用，你可以改变类/方法的名称。通常应当避免，除非改名有明显的好处。
[3](1, 2) 尽可能避免。任何删除都需要在升级指南中说明。