diff --git a/zh/contributing/backwards-compatibility.rst b/zh/contributing/backwards-compatibility.rst index 95106ed170..683b4b3b9e 100644 --- a/zh/contributing/backwards-compatibility.rst +++ b/zh/contributing/backwards-compatibility.rst @@ -1,23 +1,27 @@ 向后兼容性指南 -############################# +############## -确保您可以轻松顺利地升级您的应用程序，这对我们是很重要的。这就是为什么我们只在主要版本里程碑才会打破兼容性。你可能熟悉 -`语义版本控制 `_，这就是我们在所有的 CakePHP 项目中使用的通用准则。总之，语义版本控制意味着只有主要版本(比 -如2.0，3.0，4.0)可以打破向后兼容性。次要版本(比如2.1，3.1，3.2)可能会引入新的功能，但不能破坏兼容性。错误修复版本(比如2.1.2， -3.0.1)不增加新的功能，但仅修复漏洞或改善性能。 +确保您可以轻松顺利地升级您的应用程序，这对我们是很重要的。这就是为什么我们只在主 +要版本里程碑才会打破兼容性。你可能熟悉 `语义版本控制 `_ ，这 +就是我们在所有的 CakePHP 项目中使用的通用准则。总之，语义版本控制意味着只有主要版 +本(比如2.0，3.0，4.0)可以打破向后兼容性。次要版本(比如2.1，3.1，3.2)可能会引入新 +的功能，但不能破坏兼容性。错误修复版本(比如2.1.2，3.0.1)不增加新的功能，但仅修复 +漏洞或改善性能。 .. note:: CakePHP 从2.0.0开始遵循语义版本控制。这些规则不适用于1.x。 -为了澄清在每个版本层次可以预期到哪些变化，我们为使用 CakePHP 的开发人员以及开发 CakePHP 的开发人员准备了更详细的信息，以便于建立预期在次要版本 -中能做什么。主要版本根据需要可以有任意多个打破兼容性的变化。 +为了澄清在每个版本层次可以预期到哪些变化，我们为使用 CakePHP 的开发人员以及开发 +CakePHP 的开发人员准备了更详细的信息，以便于建立预期在次要版本中能做什么。主要版 +本根据需要可以有任意多个打破兼容性的变化。 升级指南 -================ +======== -对每个主要和次要版本，CakePHP 开发团队会提供一份升级指南。这些指南说明每一个版本中的新功能及任何打破兼容性的变化，可以在 cookbook 的 -:doc:`/appendices` 一节中看到。 +对每个主要和次要版本，CakePHP 开发团队会提供一份升级指南。这些指南说明每一个版本 +中的新功能及任何打破兼容性的变化，可以在 cookbook 的 :doc:`/appendices` 一节中看 +到。 使用 CakePHP ============= @@ -25,21 +29,25 @@ 如果你使用 CakePHP 来构建应用程序，下面的指南说明了你可以预期的稳定性。 接口 ----------- +---- -除了主要版本，CakePHP 提供的接口的任何现有的方法**不**会改变。可能会增加新的方法，但不会改变任何现有的方法。 +除了主要版本，CakePHP 提供的接口的任何现有的方法 **不** 会改变。可能会增加新的方 +法，但不会改变任何现有的方法。 类 -------- +-- -CakePHP 提供的类可以实例化，并有它们的公共方法和属性，可以被应用代码使用，除了主要版本，(其他的版本)可以保证向后兼容性。 +CakePHP 提供的类可以实例化，并且它们的公共方法和属性，可以被应用代码使用，除了主 +要版本，(其他的版本)可以保证向后兼容性。 .. note:: - 一些 CakePHP 的类标有``@internal`` API 文档标签(*API doc tag*)。这些类**不**稳定，不能保证向后兼容性。 + 一些 CakePHP 的类标有 ``@internal`` API 文档标签(*API doc tag*)。这些类 + **不** 稳定，不能保证向后兼容性。 -在次要版本中，类可以添加新方法，已有的方法可以添加新的参数。任何新参数必须有缺省值，但如果你用不同的签名重载方法，你可能会遇到致命错误(*fatal -errors*)。添加了新参数的方法，会在那个版本的升级指南中说明。 +在次要版本中，类可以添加新方法，已有的方法可以添加新的参数。任何新参数必须有缺省 +值，但如果你用不同的签名重载方法，你可能会遇到致命错误(*fatal errors*)。添加了新 +参数的方法，会在那个版本的升级指南中说明。 下面的表格列出一些用例，以及你从 CakePHP 可以期望得到的兼容性： @@ -78,7 +86,7 @@ errors*)。添加了新参数的方法，会在那个版本的升级指南中说 +-------------------------------+--------------------------+ 开发 CakePHP -================== +============ 如果你帮助改进 CakePHP，在添加/修改功能时，请记住下面的指南： diff --git a/zh/contributing/cakephp-coding-conventions.rst b/zh/contributing/cakephp-coding-conventions.rst index 48b676eca6..84205e6874 100644 --- a/zh/contributing/cakephp-coding-conventions.rst +++ b/zh/contributing/cakephp-coding-conventions.rst @@ -5,8 +5,9 @@ CakePHP 开发人员将使用下面的编码规范。 我们建议其他开发Cake组成部分的人员也应当遵循同样的规范。 -你可以使用`CakePHP Code Sniffer `_来检查 -你的代码是否遵循了必要的规范。 +你可以使用 +`CakePHP Code Sniffer `_ 来检查你 +的代码是否遵循了必要的规范。 添加新特性 ========== @@ -50,8 +51,8 @@ CakePHP 开发人员将使用下面的编码规范。 控制结构 ======== -控制结构是"``if``"，"``for``"，"``foreach``"，"``while``"，"``switch``"这些。下面是使用"``if``"的一 -个例子:: +控制结构是"``if``"、"``for``"、"``foreach``"、"``while``"、"``switch``"这些。下面 +是使用"``if``"的一个例子:: if ((expr_1) || (expr_2)) { // action_1; @@ -61,10 +62,12 @@ CakePHP 开发人员将使用下面的编码规范。 // default_action; } -* 在控制结构中，在第一个括号之前应该有一个空格，在最后一个括号和开始的大括号之间也应该有一个空格。 -* 在控制结构中总是使用大括号，即使他们是不必要的。这会提高代码的可读性，也导致较少的逻辑错误。 -* 开始的大括号应与控制结构放在同一行上。结束的大括号应该新起一行，并且与控制结构应该有相同的缩进级别。包括在大括号中的语句应该新起一行，其代码也应该再缩进一 - 层。 +* 在控制结构中，在第一个括号之前应该有一个空格，在最后一个括号和开始的大括号之间 + 也应该有一个空格。 +* 在控制结构中总是使用大括号，即使他们是不必要的。这会提高代码的可读性，也导致较 + 少的逻辑错误。 +* 开始的大括号应与控制结构放在同一行上。结束的大括号应该新起一行，并且与控制结构 + 应该有相同的缩进级别。包括在大括号中的语句应该新起一行，其代码也应该再缩进一层。 * 在控制结构中不应该使用内嵌赋值(*inline assignment*)。 :: @@ -95,8 +98,9 @@ CakePHP 开发人员将使用下面的编码规范。 三元运算符 ---------- -当整个三元运算可以放在一行之内时，三元运算符是允许的。更长的三元运算就应该分成``if else``语句。三元运算符绝不允许嵌套。括号虽然不必须，但是可以用在三 -元运算的条件检查之外，使其更清晰:: +当整个三元运算可以放在一行之内时，三元运算符是允许的。更长的三元运算就应该分成 +``if else`` 语句。三元运算符绝对不允许嵌套。括号虽然不必须，但是可以用在三元运算 +的条件检查之外，使其更清晰:: //很好，简单，易读 $variable = isset($options['variable']) ? $options['variable'] : true; @@ -108,8 +112,9 @@ CakePHP 开发人员将使用下面的编码规范。 视图文件 -------- -在视图文件(.ctp files)中，开发人员使用关键词控制结构。关键词控制结构在复杂的视图文件中更容易阅读。控制结构可以放在一段大的PHP代码段落中，也可以放 -在单独的 PHP 标签中:: +在视图文件(.ctp files)中，开发人员使用关键词控制结构。关键词控制结构在复杂的视图 +文件中更容易阅读。控制结构可以放在一段大的 PHP 代码段落中，也可以放在单独的 PHP +标签中:: `_ * `@copyright `_ * `@deprecated `_ - 使用格式``@version ``，其中``version``和``description``是必须的。 + 使用格式 ``@version `` ，其中 ``version``和``description`` + 是必须的。 * `@example `_ * `@ignore `_ * `@internal `_ @@ -239,7 +248,8 @@ CakePHP 开发人员将使用下面的编码规范。 * `@since `_ * `@version `_ -PhpDoc 标签非常类似于 Java 中的 JavaDoc 标签。标签只有出现在 DocBlock 行的开头才会起作用, 例如:: +PhpDoc 标签非常类似于 Java 中的 JavaDoc 标签。标签只有出现在文档块(*DocBlock*)行 +的开头才会起作用, 例如:: /** * Tag example. @@ -273,7 +283,7 @@ PhpDoc 标签非常类似于 Java 中的 JavaDoc 标签。标签只有出现在 变量类型 -------- -DocBlock 中使用的变量类型: +文档块(*DocBlock*)中使用的变量类型: 类型 描述 @@ -299,13 +309,13 @@ resource callable 可调用的函数。 -你也可以用竖线(pipe char)组合多个类型:: +你也可以用竖线(*pipe char*)组合多个类型:: int|bool -对两种以上的类型，通常最好使用``mixed``。 +对两种以上的类型，通常最好使用 ``mixed`` 。 -当返回对象本身时，例如为了实现链式方法，应当使用``$this``:: +当返回对象本身时，例如为了实现链式方法，应当使用 ``$this`` :: /** * Foo function. @@ -328,7 +338,8 @@ callable require_once 'ClassFileName.php'; require_once $class; -当包括类或者库的文件时, 总是只使用`require\_once `_函数。 +当包括类或者库的文件时, 总是只使用 +`require\_once `_ 函数。 PHP 标签 ======== @@ -341,7 +352,7 @@ PHP 标签 函数 ---- -所有函数名都应为 camelBack:: +所有函数名都应为 camelBack 形式:: function longFunctionName() { } @@ -349,7 +360,7 @@ PHP 标签 类 -- -类名应为 CamelCase, 例如:: +类名应为驼峰命名法(*CamelCase*), 例如:: class ExampleClass { } @@ -357,8 +368,9 @@ PHP 标签 变量 ---- -变量名应当尽可能具有描述性, 但同时越短越好。普通变量应当以小写字母开头，如果含有多个词, 则应当为 camelBack。引用对象的变量的变量名应当以大写字母开 -头，并且与对象所属的类应当以某种方式相关联。例如:: +变量名应当尽可能具有描述性, 但同时越短越好。普通变量应当以小写字母开头，如果含 +有多个词, 则应当为 camelBack 形式。引用对象变量的变量名应当以大写字母开头，并且 +与对象所属的类应当以某种方式相关联。例如:: $user = 'John'; $users = array('John', 'Hans', 'Arne'); @@ -368,7 +380,8 @@ PHP 标签 成员的可见范围 -------------- -方法和变量应当使用 PHP5 的 private 和 protected 关键字。另外，protected 的方法和变量应当以一个下划线开头(``_``)。例如:: +方法和变量应当使用 PHP5 的 private 和 protected 关键字。另外，protected 的方法和 +变量应当以一个下划线开头(``_``)。例如:: class A { protected $_iAmAProtectedVariable; @@ -388,24 +401,26 @@ PHP 标签 } } -不过，尽可能避免私有方法或者变量，而使用保护(protected)的(方法或者变量)。后者可以被子类访问或者改变，而私有的(方法或者变量)阻止了扩展或重用。私有 -也使测试更加困难。 +不过，尽可能避免私有方法或者变量，而使用保护(protected)的(方法或者变量)。后者可以 +被子类访问或者改变，而私有的(方法或者变量)阻止了扩展或重用。私有也使测试更加困难。 示例地址 -------- -所有示例用的网址和电子邮箱地址应当使用"example.com", "example.org"和"example.net", 例如: +所有示例用的网址和电子邮箱地址应当使用"example.com"、"example.org"和"example.net"， +例如: * 电子邮箱地址: someone@example.com * 网址: `http://www.example.com `_ * FTP: `ftp://ftp.example.com `_ -"example.com" 域名已为此目的而保留(参见:rfc:`2606`), 建议在文档中或者作为例子使用。 +"example.com" 域名已为此目的而保留(参见 :rfc:`2606` )，建议在文档中或者作为例子使 +用。 文件 ---- -不包含类的文件, 其文件名应当小写, 并且以下划线分隔单词, 例如:: +不包含类的文件，其文件名应当小写，并且以下划线分隔单词，例如:: long_file_name.php @@ -429,7 +444,8 @@ PHP 标签 (object) 强制转换成对象类型。 -在适用时，请使用``(int)$var``，而不是``intval($var)``，使用``(float)$var``，而不是``floatval($var)``。 +在适用时，请使用 ``(int)$var``，而不是 ``intval($var)``，使用 ``(float)$var``，而 +不是 ``floatval($var)``。 常量 ---- diff --git a/zh/contributing/code.rst b/zh/contributing/code.rst index 496c02332a..b3e6d2d16d 100644 --- a/zh/contributing/code.rst +++ b/zh/contributing/code.rst @@ -1,8 +1,8 @@ 代码 #### -补丁和拉取请求是为 CakePHP 贡献代码的一种很棒的方式。拉取请求可以在 GitHub 中创建，是比附在问题报告的评论(*ticket comments*) -中的补丁更受青睐的方式。 +补丁和拉取请求是为 CakePHP 贡献代码的一种很棒的方式。拉取请求可以在 GitHub 中创建， +是比附在问题报告的评论(*ticket comments*)中的补丁更受青睐的方式。 初始设置 ======== @@ -20,11 +20,12 @@ .. note:: - 如果你对 Git 完全陌生，我们强烈建议你阅读优秀且免费的`ProGit `_这本书。 + 如果你对 Git 完全陌生，我们强烈建议你阅读优秀且免费的 + `ProGit `_ 这本书。 从 GitHub 获得一份 CakePHP 源程序的克隆(*clone*)。 -* 如果你没有`GitHub `_的账号，创建一个。 +* 如果你没有 `GitHub `_ 的账号，创建一个。 * 点击**Fork**按键，复制(*fork*)一份 `CakePHP repository `_ 的源码。 @@ -32,22 +33,26 @@ git clone git@github.com:你的账号/cakephp.git -把原始的 CakePHP 仓库添加为远程仓库(*remote repository*)。以后你会使用它来抓取 CakePHP 仓库的改动，保持与 CakePHP -仓库一致:: +把原始的 CakePHP 仓库添加为远程仓库(*remote repository*)。以后你会使用它来抓取 +CakePHP 仓库的改动，保持与 CakePHP 仓库一致:: cd cakephp git remote add upstream git://github.com/cakephp/cakephp.git -现在你已经搭建好了 CakePHP 的环境。你应该能够定义一个``$test`` :ref:`数据库连接 `，并且 +现在你已经搭建好了 CakePHP 的环境。你应该能够定义一个 ``$test`` +:ref:`数据库连接 `，并且 :ref:`运行所有的测试 ` 。 制作补丁 ======== -每次当你要修复一个臭虫(*bug*)、增加一个特性或做一个改进时，创建一个主题分支(*topic branch*)。 +每次当你要修复一个臭虫(*bug*)、增加一个特性或做一个改进时，创建一个主题分支 +(*topic branch*)。 -你创建的分支，应根据你的修复/改进所适用的版本。例如，如果你正在修复``2.3``版本中的一个臭虫，那么你就应当以``2.3``的分支为基础来创建你的分支。如果 -你做的改动是对当前的稳定版本的一个臭虫的修复，你就应当使用``master``分支。这样以后合并改动时就会简单多了:: +你创建的分支，应根据你的修复/改进所适用的版本。例如，如果你正在修复 ``2.3`` 版本 +中的一个臭虫，那么你就应当以 ``2.3`` 的分支为基础来创建你的分支。如果你做的改动是 +对当前的稳定版本的一个臭虫的修复，你就应当使用 ``master`` 分支。这样以后合并改动 +时就会简单多了:: # fixing a bug on 2.3 git fetch upstream @@ -55,11 +60,13 @@ .. tip:: - 作为一个良好的习惯，为你的分支起一个描述性的名称，可以引用问题跟踪报告或特性名称。例如 ticket-1234，超棒的特性 + 作为一个良好的习惯，为你的分支起一个描述性的名称，可以引用问题跟踪报告或特性 + 名称。例如 ticket-1234，超棒的特性 -上述命令将创建基于上游(CakePHP) 2.3分支的一个本地分支。进行你的臭虫修复工作，根据你的需要做任意多次的提交(*commit*)。不过你要牢记以下几点: +上述命令将创建基于上游(CakePHP) 2.3分支的一个本地分支。进行你的臭虫修复工作，根据 +你的需要做任意多次的提交(*commit*)。不过你要牢记以下几点: -* 遵循:doc:`/contributing/cakephp-coding-conventions` 。 +* 遵循 :doc:`/contributing/cakephp-coding-conventions` 。 * 添加一个测试用例来说明错误修复好了，或者新特性能够工作。 * 使你的提交保持逻辑性，提交信息应当清晰、简洁。 @@ -75,8 +82,10 @@ git checkout git rebase 2.3 -这将抓取+合并自从你开始之后 CakePHP 中的任何改动。然后，它将衍合(*rebase*) -- 或者说，在当前代码的基础上重新应用你的改动。在``衍合`` -过程中你可能会遇到冲突。如果衍合过早退出，你可以使用``git status``命令来查看哪些文件发生冲突/没有合并。解决每个冲突，然后继续衍合:: +这将抓取+合并自从你开始之后 CakePHP 中的任何改动。然后，它将衍合(*rebase*) -- 或 +者说，在当前代码的基础上重新应用你的改动。在 ``衍合`` 过程中你可能会遇到冲突。如 +果衍合过早退出，你可以使用 ``git status`` 命令来查看哪些文件发生冲突/没有合并。解 +决每个冲突，然后继续衍合:: git add # 针对每一个发生冲突的文件。 git rebase --continue @@ -86,27 +95,30 @@ git push origin 一旦你的分支在 GitHub 上，你就可以在 -`cakephp-core `_ 邮件列表上进行讨论或在 GitHub -上提交拉取请求。 +`cakephp-core `_ 邮件列表上进行讨论 +或在 GitHub 上提交拉取请求。 选择你的改动会被合并到哪里 -------------------------- -当提交拉取请求时，你应该确保你选择了正确的分支作为基础，因为拉取请求一经创建就无法更改。 +当提交拉取请求时，你应该确保你选择了正确的分支作为基础，因为拉取请求一经创建就无 +法更改。 -* 如果你的改动是一个**错误修正**，并不引入新功能，只是纠正当前版本中现有的行为，则请选择**master**为合并目标。 -* 如果你的改动是一个**新特性**或者为框架新增的功能，那么你应选择下一个版本号对应的分支。例如，如果目前的稳定版本是``2.2.2``，则接受新特性的分支将 - 是``2.3``。 -* 如果你的改动打破(*breaks*)了现有的功能或 API，那么你就应当选择再下一个主要版本。例如，如果当前的版本是``2.2.2``，那么下一次现有的功能 - 可以被打破(*broken*)就是在``3.0``版本了，所以你应该针对这一分支。 +* 如果你的改动是一个 **错误修正**，并不引入新功能，只是纠正当前版本中现有的行为， + 则请选择 **master** 为合并目标。 +* 如果你的改动是一个 **新特性** 或者为框架新增的功能，那么你应选择下一个版本号对 + 应的分支。例如，如果目前的稳定版本是 ``2.2.2``，则接受新特性的分支将是 ``2.3``。 +* 如果你的改动打破(*break*)了现有的功能或 API，那么你就应当选择再下一个主要版本。 + 例如，如果当前的版本是 ``2.2.2``，那么下一次现有的功能可以被打破(*broken*)就是 + 在 ``3.0`` 版本了，所以你应该针对这一分支。 .. note:: - 请记住，所有你贡献给CakePHP的代码将被置于MIT许可之下， - `Cake Software Foundation `_将会成为任何贡献出 - 去的代码的所有者。代码贡献者应当遵循 - `CakePHP Community Guidelines `_. + 请记住，所有你贡献给 CakePHP 的代码将被置于 MIT 许可之下， + `Cake Software Foundation `_ 将会成为 + 任何贡献出去的代码的所有者。代码贡献者应当遵循 + `CakePHP Community Guidelines `_ 。 所有合并到维护分支中的臭虫修复，也将被核心团队定期地合并到即将发布的下一个版本。 diff --git a/zh/contributing/documentation.rst b/zh/contributing/documentation.rst index b9ca4a68f8..e851ff6f03 100644 --- a/zh/contributing/documentation.rst +++ b/zh/contributing/documentation.rst @@ -1,29 +1,33 @@ 文档 #### -给文档做贡献是很简单的。这些文件都托管在 https://github.com/cakephp/docs。请自行复制(*fork*)代码仓库，加入你的更改/改进 -/翻译，然后发出拉取请求来提交你的改动。你甚至可以在 GitHub 上在线地编辑文档，而完全不用下载文件--在任何页面上的"Improve this Doc"按 -键将会引导你进入该页面的 GitHub 在线编辑器。 +给文档做贡献是很简单的。这些文件都托管在 https://github.com/cakephp/docs。请自行 +复制(*fork*)代码仓库，加入你的更改/改进/翻译，然后发出拉取请求来提交你的改动。你 +甚至可以在 GitHub 上在线地编辑文档，而完全不用下载文件--在任何页面上的"Improve +this Doc"按键将会引导你进入该页面的 GitHub 在线编辑器。 翻译 ==== -发邮件给文档小组(docs at cakephp dot org)，或者通过 IRC(freenode上的#cakephp)，来讨论任何你想参与的翻译工作。 +发邮件给文档小组(docs at cakephp dot org)，或者通过 IRC(freenode上的#cakephp)，来 +讨论任何你想参与的翻译工作。 关于翻译的一些忠告: - 用要翻译的语言来进行浏览、编辑 - 否则你将无法看到哪些已经翻译了。 - 如果你选择的语言在本书中已经存在，请自行加入。 -- 请使用 `Informal Form ` _。 +- 请使用 `Informal Form `_ 。 - 请将内容和标题一起翻译。 -- 在提交一个更正之前，请先和英文版本的内容进行比较(如果你改正了一些东西，却没有整合“上游”(*upstream*)的改动，你提交的东西将不会被接受)。 -- 如果你要写一个英文术语，请把它放在 ```` 标签之内。比如，"asdf asdf *Controller* asdf"或者"asdf asdf - Kontroller (*Controller*) asfd"，请适为选用。 +- 在提交一个更正之前，请先和英文版本的内容进行比较(如果你改正了一些东西，却没有整 + 合“上游”(*upstream*)的改动，你提交的东西将不会被接受)。 +- 如果你要写一个英文术语，请把它放在 ```` 标签之内。比如， + "asdf asdf *Controller* asdf"或者"asdf asdf Kontroller (*Controller*) asfd"，请 + 适为选用。 - 请不要提交不完整的翻译。 - 请不要编辑正在改动的部分。 - 对于标以重音符号的字符，请不要使用 - `html 字符实体 (*html entities*) `_ - 来表示，本书使用UTF-8。 + `html 字符实体 `_ + (*html entities*) 来表示，本书使用UTF-8。 - 请不要显著改变标记(HTML)或增加新的内容。 - 如果原始的内容遗漏了某些信息，请先提交(对原始内容的)更正。 @@ -31,9 +35,10 @@ ============ 这份新的 CakePHP 文档是以 -`ReST formatted text `_ 格式写的。ReST -(Re Structured Text)是与 markdown 或者 textile 类似的纯文本标记语法。在为 CakePHP 的文档做出贡献时，为了保持一致 -性，建议你遵循下面的准则，来你格式化和组织你的文字。 +`ReST formatted text `_ 格式写的。 +ReST (Re Structured Text)是与 markdown 或者 textile 类似的纯文本标记语法。在为 +CakePHP 的文档做出贡献时，为了保持一致性，建议你遵循下面的准则，来你格式化和组织 +你的文字。 每行的长度 ---------- @@ -43,7 +48,7 @@ 标题和小节 ---------- -小节的标题要在它的下一行以至少相同长度的标点符号来标识。 +小节的标题要在它的下一行用至少相同长度的标点符号来标识。 - ``#`` 用来标识网页标题。 - ``=`` 用于标识在一个页面中的小节。 @@ -58,8 +63,8 @@ 段落是简单的文本块，缩进在同一级别。段落之间应以一个以上的空行分隔。 -内嵌标记 --------- +内嵌(*inline*)标记 +------------------ * 一个星号： *文字* 为强调(斜体) @@ -79,12 +84,14 @@ * **不可以** 嵌套。 * 内容不可以以空格开始或结束: ``* 文本*`` 是错误的。 -* 内容必须与周围的文字由非文字字符分隔，这可以使用反斜杠转义的空格来解决：``一个长的\ *粗体*\ 词汇``。 +* 内容必须与周围的文字由非文字字符分隔，这可以使用反斜杠转义的空格来解决： + ``一个长的\ *粗体*\ 词汇``。 列表 ---- -列表与 markdown 非常相似。无序列表以一个星号和一个空格开始。有序列表可以数字开始，或以 ``#`` 进行自动编号:: +列表与 markdown 非常相似。无序列表以一个星号和一个空格开始。有序列表可以数字开始， +或以 ``#`` 进行自动编号:: * 这是一点 * 这也是。但这一点 @@ -134,18 +141,20 @@ .. rst:role:: doc - 指向文档中其他网页的链接可以使用 ``:doc:`` 角色(*role*)。你可以使用绝对路径或者相对路径，来链接到指定的文件中。请省略``.rst`` - 扩展名。例如，如果链接``:doc:`form```出现在文档``core-helpers/html``中，则该链接指向 - ``core-helpers/form``。如果链接是``:doc:`/core-helpers```，那么不论它用在那里，总是会指向 - ``/core-helpers`` 。 + 指向文档中其他网页的链接可以使用 ``:doc:`` 角色(*role*)。你可以使用绝对路径或 + 者相对路径，来链接到指定的文件中。请省略 ``.rst`` 扩展名。例如，如果链接 + ``:doc:`form``` 出现在文档 ``core-helpers/html`` 中，则该链接指向 + ``core-helpers/form`` 。如果链接是 ``:doc:`/core-helpers``` ，那么不论它用在 + 那里，总是会指向 ``/core-helpers`` 。 交叉引用链接 ~~~~~~~~~~~~ .. rst:role:: ref - 你可以使用 ``:ref:`` 角色交叉引用在任何文件中的任何标题。链接标签指向的目标在整个文档必须是唯一的。当为类的方法创建标签时，最好使用 - ``class-method`` 作为您的链接标签的格式。 + 你可以使用 ``:ref:`` 角色交叉引用在任何文件中的任何标题。链接标签指向的目标在 + 整个文档必须是唯一的。当为类的方法创建标签时，最好使用 ``class-method`` 作为 + 您的链接标签的格式。 标签最常见的用途是在标题之前。例如:: @@ -156,14 +165,15 @@ 更多内容在这里。 - 在其他地方你可以用 ``:ref:`标签名称``` 引用上面的小节。链接的文字可以是标签之后的标题。你也可以使用 ``:ref:`链接文字 <标签名称>``` - 的方式来提供自定义的链接文字。 + 在其他地方你可以用 ``:ref:`标签名称``` 引用上面的小节。链接的文字可以是标签之后的 + 标题。你也可以使用 ``:ref:`链接文字 <标签名称>``` 的方式来提供自定义的链接文字。 描述类和它们的内容 ------------------ -CakePHP 文档使用`phpdomain `_提供 -自定义指令描述 PHP 对象和结构。我们必须使用这些指令和角色，才能保证正确的索引和交叉引用。 +CakePHP 文档使用 `phpdomain `_ +提供自定义指令描述 PHP 对象和结构。我们必须使用这些指令和角色，才能保证正确的索引 +和交叉引用。 描述类及其组成 -------------- @@ -199,7 +209,7 @@ CakePHP 文档使用`phpdomain `_ 上。 报告臭虫 @@ -9,24 +10,29 @@ 写得好的问题报告都非常有用。下面的步骤可以帮助创建尽可能好的问题报告： -* **请** `搜索 `_ +* **请** + `搜索 `_ 类似的已有问题，并保证别人没有报告你的问题，或者在源代码仓库中还没有得到修复。 -* **请** 包括 **如何重现问题** 的详细说明。这可以是测试用例或代码片段，来展示所报告的问题。如果没有办法重现问题，则意味着它不太容易被修复。 -* **请** 尽可能详尽地提供关于你的(运行)环境的细节(操作系统，PHP 的版本，CakePHP 的版本)。 +* **请** 包括 **如何重现问题** 的详细说明。这可以是测试用例或代码片段，来展示所报 + 告的问题。如果没有办法重现问题，则意味着它不太容易被修复。 +* **请** 尽可能详尽地提供关于你的(运行)环境的细节(操作系统，PHP 的版本，CakePHP + 的版本)。 * **请不要** 使用问题跟踪系统来询问技术支持的问题。寻求技术支持，请使用 - `谷歌讨论组 `_ 或 #cakephp 的 IRC 渠道或者 - Stack Overflow 。 + `谷歌讨论组 `_ 或 #cakephp 的 IRC 渠道 + 或者 Stack Overflow 。 报告安全问题 ============ -如果你发现了 CakePHP 的安全问题，请使用以下过程，而不要使用平常的错误报告系统，比如问题跟踪系统、邮件列表或 IRC。请发送电子邮件至 -**security [at] cakephp.org**。发送到这个邮箱的电子邮件会进入一个 CakePHP 核心团队所在的内部邮件列表中。 +如果你发现了 CakePHP 的安全问题，请使用以下过程，而不要使用平常的错误报告系统，比 +如问题跟踪系统、邮件列表或 IRC。请发送电子邮件至 **security [at] cakephp.org** 。 +发送到这个邮箱的电子邮件会进入一个 CakePHP 核心团队所在的内部邮件列表中。 对于每一份报告，我们首先尝试确认该漏洞。一经确认，CakePHP 团队将采取以下措施： -* 向报告者确认我们已经收到了该问题报告，并正着手修复。我们请求报告者对该问题保密，直到我们对外宣布。 +* 向报告者确认我们已经收到了该问题报告，并正着手修复。我们请求报告者对该问题保密， + 直到我们对外宣布。 * 准备一个更正/补丁。 * 准备一份帖子，描述该漏洞以及可能的利用方式。 * 针对所有受影响的版本发布新版本。 diff --git a/zh/installation/advanced-installation.rst b/zh/installation/advanced-installation.rst new file mode 100644 index 0000000000..dd70cd340e --- /dev/null +++ b/zh/installation/advanced-installation.rst @@ -0,0 +1,156 @@ +高级安装 +##################### + +通过 PEAR 安装器安装 CakePHP +====================================== + +CakePHP 发行 PEAR 的安装包，故可以通过 PEAR 安装器安装。用 PEAR 安装，可以简化在 +多个应用程序间共享 CakePHP 类库的工作。要通过 PEAR 安装 CakePHP，需要执行下面的命 +令:: + + pear channel-discover pear.cakephp.org + pear install cakephp/CakePHP + +.. note:: + + 在一些操作系统中用 PEAR 命令安装类库需要 ``sudo``。 + +使用 PEAR 安装 CakePHP 之后，如果 PEAR 配置正确，可以使用 ``cake`` 命令来创建新的 +应用程序。由于 CakePHP 已经被包含在 PHP 的 ``include_path`` 中，就不需要再做任何 +其它改动了。 + + +通过 Composer 安装 CakePHP +================================ + +Composer 是一个适用于 PHP 5.3+ 的依赖管理工具，解决了通过 PEAR 安装的很多问题，并 +且简化了对类库的多个版本的管理。由于 CakePHP 有 PEAR 发行包，故而可以使用 +`composer `_ 安装 CakePHP。在安装 CakePHP 之前需要建立 +``composer.json`` 文件。CakePHP 应用程序的 composer.json 可以象下面这样:: + + { + "name": "example-app", + "require": { + "cakephp/cakephp": "2.5.*" + }, + "config": { + "vendor-dir": "Vendor/" + } + } + +把这段 JSON 保存在项目的 APP 目录中的 ``composer.json`` 文件中。接下来把 +composer.phar 文件下载到项目中。在 ``composer.json`` 所在的目录下运行如下命令:: + + $ php composer.phar install + +一旦 Composer 运行结束，目录结构应当如下所示:: + + example-app/ + composer.phar + composer.json + Vendor/ + bin/ + autoload.php + composer/ + cakephp/ + +现在可以生成应用程序骨架的其余部分:: + + $ Vendor/bin/cake bake project + +缺省情况下，``bake`` 把 :php:const:`CAKE_CORE_INCLUDE_PATH` 硬编码了。为了使应用 +程序更具移植性，应当修改 ``webroot/index.php`` ，将 ``CAKE_CORE_INCLUDE_PATH`` +改为相对路径:: + + define( + 'CAKE_CORE_INCLUDE_PATH', + ROOT . DS . APP_DIR . DS . 'Vendor' . DS . 'cakephp' . DS . 'cakephp' . DS . 'lib' + ); + +.. note:: + + 如果你计划为应用程序创建单元测试，你也需要对 ``webroot/test.php`` 做上面的修 + 改。 + +如果使用 Composer 安装其他任何类库，则需要设置自动加载(*autoloader*)，并绕过 +(*work around*) Composer 自动加载的一个问题。在 ``Config/bootstrap.php`` 文件中添 +加如下代码:: + + // 加载 Composer 的自动加载。 + require APP . 'Vendor/autoload.php'; + + // 删除并重新优先添加 CakePHP 的自动加载，因为 Composer 认为这是最重要的。 + // 参看：http://goo.gl/kKVJO7 + spl_autoload_unregister(array('App', 'load')); + spl_autoload_register(array('App', 'load'), true, true); + +现在这个用 Composer 安装的 CakePHP 应用程序应该可以运行了。注意确保 composer.json +和 composer.lock 文件与其它源代码在一起。(译注：比如一起添加到 Git 这样的源码控制 +仓库中。) + +在多个应用程序间共享 CakePHP 类库 +==================================================== + +在某些情况下，你会希望把 CakePHP 的目录放到文件系统的不同地方。这可能是因为共享主 +机的限制，或者你只是想让一些应用程序共享相同的 CakePHP 类库。本节将说明怎样把 +CakePHP 的目录分散到文件系统的的不同地方。 + +首先，明确 Cake 的应用程序有三个主要部分: + +#. CakePHP 核心类库，位于 /lib/Cake 目录。 +#. 应用程序的代码，位于 /app 目录。 +#. 应用程序的 webroot，通常位于 /app/webroot 目录。 + +这里的每个目录，都可以放到文件系统的任何位置，除了 webroot，它必须位于 web 服务器 +能够访问到的地方。甚至可以将 webroot 目录移动到 app 目录外面，只要你告诉 CakePHP +你把它放在了哪里。 + +配置 CakePHP 的安装时，需要对下面的文件做一些修改。 + + +- /app/webroot/index.php +- /app/webroot/test.php (如果你使用 + :doc:`Testing ` 的功能。) + +有三个常量需要修改： ``ROOT`` 、 ``APP_DIR`` 和 ``CAKE_CORE_INCLUDE_PATH``。 + +- ``ROOT`` 应当设置为包含你的 app 文件夹的目录路径。 +- ``APP_DIR`` 应当设置为 app 目录的目录名称(译注：即不包含前面的路径)。 +- ``CAKE_CORE_INCLUDE_PATH`` 应当设置为 CakePHP 类库目录的路径。 + +让我们通过下面的例子，让你明白高级安装实际上是怎样的。设想我要象下面这样设置 +CakePHP： + +- CakePHP 的核心类库位于 /usr/lib/cake。 +- 应用程序的 webroot 目录是 /var/www/mysite/。 +- 应用程序的 app 目录是 /home/me/myapp。 + +鉴于这种类型的设置，我需要编辑 webroot/index.php 文件(在本例中为 +/var/www/mysite/index.php)，(让它)像下面这样:: + + // /app/webroot/index.php (部分代码，删除了注释) + + if (!defined('ROOT')) { + define('ROOT', DS . 'home' . DS . 'me'); + } + + if (!defined('APP_DIR')) { + define ('APP_DIR', 'myapp'); + } + + if (!defined('CAKE_CORE_INCLUDE_PATH')) { + define('CAKE_CORE_INCLUDE_PATH', DS . 'usr' . DS . 'lib'); + } + +推荐使用 ``DS`` 常量而不是斜杠(译注：即 ``/`` 或 ``\``)来分隔文件路径，这样可以避 +免因为使用错误的分隔符而导致的文件无法找到的错误，并使代码更具移植性。 + +Apache 和 mod\_rewrite (以及 .htaccess) +======================================= + +本节内容被移到 :doc:`网址重写 `。 + + +.. meta:: + :title lang=zh_CN: Advanced Installation + :keywords lang=zh_CN: libraries folder,core libraries,application code,different places,filesystem,constants,webroot,restriction,apps,web server,lib,cakephp,directories,path diff --git a/zh/installation/url-rewriting.rst b/zh/installation/url-rewriting.rst index b815b1c822..26e46331cf 100644 --- a/zh/installation/url-rewriting.rst +++ b/zh/installation/url-rewriting.rst @@ -1,5 +1,5 @@ -网址重写 -######## +网址重写(*URL Rewriting*) +######################### Apache 和 mod\_rewrite (以及 .htaccess) =======================================