Laravel 中文文档

主题

全部文档

贡献指南 ​

缺陷报告 ​

为鼓励积极协作，Laravel 强烈建议通过 pull request 贡献，而不仅仅是缺陷报告。只有标记为「ready for review」（非「draft」状态），且新功能相关测试全部通过的 pull request 才会被审阅。长期停留在「draft」且无活动的 PR 会在数日后关闭。

不过，若提交缺陷报告，issue 应包含标题与清晰的问题描述。还应尽可能提供相关信息，以及能复现问题的代码示例。缺陷报告的目标是让你自己——以及其他人——容易复现缺陷并开发修复。

请记住，创建缺陷报告是希望遇到相同问题的人能与你一起协作解决。不要期望报告会自动产生任何进展，或他人会立刻动手修复。创建报告是为了帮助你自己和他人走上修复之路。若想参与，可以帮忙修复我们 issue 跟踪器中列出的缺陷。必须登录 GitHub 才能查看全部 Laravel issue。

若在使用 Laravel 时发现不当的 DocBlock、PHPStan 或 IDE 警告，请不要创建 GitHub issue，而是提交 pull request 修复。

Laravel 源代码托管在 GitHub 上，各 Laravel 项目均有对应仓库：

支持问题 ​

Laravel 的 GitHub issue 跟踪器不用于提供帮助或支持。请改用下列渠道之一：

核心开发讨论 ​

你可以在 Laravel 框架仓库的 GitHub discussion 中提议新功能或改进现有行为。若提议新功能，请愿意至少实现完成该功能所需的部分代码。

关于缺陷、新功能以及现有功能实现的非正式讨论，在 Laravel Discord 的 #internals 频道进行。Laravel 维护者 Taylor Otwell 通常在工作日上午 8 点至下午 5 点（UTC-06:00 或 America/Chicago）在线，其他时间也会偶尔出现。

应提交到哪个分支？ ​

所有缺陷修复应提交到仍提供缺陷修复的最新版本（当前为 12.x）。缺陷修复绝不应提交到 master 分支，除非修复的是仅存在于即将发布版本中的功能。

与当前发行版完全向后兼容的次要功能，可提交到最新稳定分支（当前为 12.x）。

重大新功能或包含破坏性变更的功能，应始终提交到包含即将发布版本的 master 分支。

编译后的资源 ​

若提交的变更会影响编译文件（例如 laravel/laravel 仓库中 resources/css 或 resources/js 的大多数文件），请不要提交编译产物。因其体积过大，维护者实际上无法审阅。这可能被利用来向 Laravel 注入恶意代码。为防御此类风险，所有编译文件将由 Laravel 维护者生成并提交。

AI 生成的贡献 ​

我们感谢每一份提交给 Laravel 的 pull request。但以 AI 生成为主、且未经认真人工审阅与思考的贡献是不可接受的。

若选择使用 AI 工具协助贡献，提交前必须由你本人充分审阅、测试并理解所生成的代码。

批量开启完全由 AI 生成的 issue 或 pull request 是不可容忍的。 此类 PR 将不予审阅直接关闭，贡献者可能被仓库封禁。

我们鼓励贡献者熟悉现有代码库、参与社区交流，并提交能体现本人对所解决问题的理解与认真思考的 pull request。

安全漏洞 ​

若发现 Laravel 中的安全漏洞，请发送邮件给 Taylor Otwell：taylor@laravel.com。所有安全漏洞都会得到及时处理。

编码风格 ​

Laravel 遵循 PSR-2 编码标准与 PSR-4 自动加载标准。

PHPDoc ​

下面是有效的 Laravel 文档块示例。注意 @param 属性后跟两个空格、参数类型、再两个空格，最后是变量名：

php
/**
 * Register a binding with the container.
 *
 * @param  string|array  $abstract
 * @param  \Closure|string|null  $concrete
 * @param  bool  $shared
 * @return void
 *
 * @throws \Exception
 */
public function bind($abstract, $concrete = null, $shared = false)
{
    // ...
}

当因使用原生类型而使 @param 或 @return 变得多余时，可以移除它们：

php
/**
 * Execute the job.
 */
public function handle(AudioProcessor $processor): void
{
    // ...
}

不过，当原生类型是泛型时，请通过 @param 或 @return 属性标明泛型类型：

php
/**
 * Get the attachments for the message.
 *
 * @return array<int, \Illuminate\Mail\Mailables\Attachment>
 */
public function attachments(): array
{
    return [
        Attachment::fromStorage('/path/to/file'),
    ];
}

StyleCI ​

不必担心代码风格不够完美！StyleCI 会在 pull request 合并后自动将风格修复合并进 Laravel 仓库。这样我们就能专注于贡献内容，而不是代码风格。

行为准则 ​

Laravel 行为准则源自 Ruby 行为准则。任何违反行为准则的情况可报告给 Taylor Otwell（taylor@laravel.com）：

  • 参与者应对相反观点保持宽容。
  • 参与者必须确保其言行不含人身攻击或贬低性个人评价。
  • 在解读他人言行时，参与者应始终假定对方出于善意。
  • 可合理认定为骚扰的行为将不被容忍。