向后兼容性指南

确保您可以轻松顺利地升级您的应用程序,这对我们是很重要的。这就是为什么我们只在主 要版本里程碑才会打破兼容性。你可能熟悉 语义版本控制 ,这 就是我们在所有的 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) 尽可能避免。任何删除都需要在升级指南中说明。