Laravel 中文文档

主题

贡献指南 ​

Bug 报告 ​

为了鼓励积极协作，Laravel 强烈建议提交用于解决问题的 pull request。我们大多数第一方 package 已禁用 GitHub issue。

如果你发现问题，请创建用于解决该问题的 pull request。你的 pull request 应包含标题，以及对问题和解决方案的清晰描述。你还应尽可能多地提供相关信息，以及能够演示该问题的代码示例。pull request 的目标是让你自己和他人能够轻松理解问题并验证修复。

如果你不清楚如何修复该问题，请向 coding agent 描述该问题，并借助它尝试提交一个 pull request。

仅当 pull request 标记为"ready for review"（处于非"draft"状态）且新功能的所有测试均通过时，才会接受审查。长期处于"draft"状态且无活动的 pull request 将在数日后关闭。

Laravel 源代码托管在 GitHub 上，每个 Laravel 项目都有对应的仓库：

支持问题 ​

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

提交到哪个分支？ ​

所有 bug 修复应发送到支持 bug 修复的最新版本（目前是 13.x）。Bug 修复绝不应发送到 master 分支，除非它们修复了仅存在于即将发布版本中的功能。

与当前发布版本完全向后兼容的次要功能可以发送到最新稳定分支（目前是 13.x）。

主要新功能或带有破坏性变更的功能应始终发送到 master 分支，该分支包含即将发布的版本。

编译资源 ​

如果你提交的变更会影响编译文件（如 laravel/laravel 仓库中 resources/css 或 resources/js 中的大多数文件），请不要提交编译后的文件。由于文件体积较大，维护者实际上无法对其进行审查。这可能被利用来向 Laravel 注入恶意代码。为了防范这一点，所有编译文件将由 Laravel 维护者生成并提交。

AI 生成的贡献 ​

我们感谢每一个提交到 Laravel 的 pull request。主要由 AI 生成且缺少深思熟虑的人工审查和考量的大型贡献无法被接受。

如果你选择使用 AI 工具协助完成对框架的大型或复杂贡献，生成的代码必须在提交前经过你的彻底审查、测试和理解。

Pull request 描述必须完全由贡献者自行撰写。包含 AI 生成描述的 pull request 将被关闭。

大量提交完全由 AI 生成的 issue 或 pull request 是不被容忍的。 此类 pull request 将在不经审查的情况下关闭，贡献用户可能会被禁止访问该仓库。

我们鼓励贡献者熟悉现有代码库，参与社区互动，并提交能够反映其自身理解和对所解决问题的深思熟虑的 pull request。

安全漏洞 ​

如果你在 Laravel 中发现安全漏洞，请发送电子邮件至我们的安全团队 security@laravel.com。所有安全漏洞将得到及时处理。

代码风格 ​

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

PHPDoc ​

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

php
/**
 * 向容器注册绑定。
 *
 * @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
/**
 * 执行该 job。
 * [tl! remove]
 * @return void [tl! remove]
 */
public function handle(AudioProcessor $processor): void
{
    // ...
}

但是，当原生类型是泛型时，请通过 @param 或 @return 属性指定泛型类型：

php
/**
 * 获取邮件的附件。
 * [tl! add]
 * @return array<int, \Illuminate\Mail\Mailables\Attachment> [tl! add]
 */
public function attachments(): array
{
    return [
        Attachment::fromStorage('/path/to/file'),
    ];
}

StyleCI ​

不必担心你的代码风格不够完美！StyleCI 会在 pull request 合并后自动将代码风格修复合并到 Laravel 仓库中。这让我们可以专注于贡献的内容，而不是代码风格。

行为准则 ​

Laravel 的行为准则源自 Ruby 行为准则。任何违反行为准则的行为均可向 Taylor Otwell (taylor@laravel.com) 举报：

  • 参与者应容忍不同意见。
  • 参与者必须确保其语言和行为不含有人身攻击或贬低他人的言论。
  • 在解读他人的言语和行为时，参与者应始终假设对方出于善意。
  • 可合理认定为骚扰的行为将不被容忍。