Laravel 13.x 中文文档

主题

贡献指南 ​

Bug 报告 ​

为了鼓励积极的协作，Laravel 强烈鼓励提交 pull request，而不仅仅是 bug 报告。Pull request 只有在标记为「ready for review」（而不是「draft」状态）并且新功能的所有测试都通过时才会被审查。留在「draft」状态的长期不活跃 pull request 将在几天后被关闭。

但是，如果你提交 bug 报告，你的问题应该包含标题和对问题的清晰描述。你还应该包含尽可能多的相关信息和演示问题的代码示例。Bug 报告的目标是让你自己和其他人能够轻松地复现 bug 并开发修复方案。

请记住，创建 bug 报告是希望其他遇到相同问题的人能够与你协作解决问题。不要期望 bug 报告会自动看到任何活动或其他人会立即修复它。创建 bug 报告是为了帮助你自己和其他人开始解决问题的道路。如果你想参与，你可以通过修复我们问题跟踪器中列出的任何 bug 来提供帮助。你必须通过 GitHub 认证才能查看 Laravel 的所有问题。

如果你在使用 Laravel 时发现不正确的 DocBlock、PHPStan 或 IDE 警告，不要创建 GitHub 问题。相反，请提交 pull request 来修复问题。

Laravel 源代码在 GitHub 上管理，每个 Laravel 项目都有仓库：

支持问题 ​

Laravel 的 GitHub 问题跟踪器不用于提供 Laravel 帮助或支持。相反，请使用以下渠道之一：

核心开发讨论 ​

你可以在 Laravel 框架仓库的 GitHub 讨论板中提出新功能或改进现有 Laravel 行为的建议。如果你提出新功能，请愿意实现至少一些完成该功能所需的代码。

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

选择哪个分支？ ​

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

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

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

编译资源 ​

如果你提交的更改会影响编译文件，例如 laravel/laravel 仓库中 resources/css 或 resources/js 中的大多数文件，不要提交编译文件。由于其大小，维护者无法实际审查它们。这可能被利用作为向 Laravel 注入恶意代码的方式。为了防御性地防止这种情况，所有编译文件将由 Laravel 维护者生成和提交。

AI 生成的贡献 ​

我们感谢提交给 Laravel 的每一个 pull request。但是，主要是 AI 生成而没有经过深思熟虑的人工审查和考虑的贡献是不可接受的。

如果你选择使用 AI 工具来协助你的贡献，生成的代码必须在提交之前由你彻底审查、测试和理解。

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

我们鼓励贡献者熟悉现有代码库，与社区互动，并提交反映他们自己理解和仔细考虑所解决问题的 pull request。

安全漏洞 ​

如果你在 Laravel 中发现安全漏洞，请发送电子邮件至 Taylor Otwell taylor@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
/**
 * 执行任务。
 */
public function handle(AudioProcessor $processor): void
{
    // ...
}

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

php
/**
 * 获取消息的附件。
 *
 * @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) 报告：

  • 参与者将容忍反对意见。
  • 参与者必须确保他们的语言和行为没有个人攻击和贬低性个人言论。
  • 在解释他人的言行时，参与者应始终假设善意。
  • 可以合理地被视为骚扰的行为将不被容忍。