Laravel 中文文档

主题

全部文档

贡献指南 ​

缺陷报告 ​

为鼓励积极协作，Laravel 强烈建议通过能解决问题的 pull request 贡献，而不是提交 GitHub issue。我们大多数官方包已关闭 GitHub issues。

若发现问题，请创建能解决问题的 pull request。PR 应包含标题，以及对问题与解决方案的清晰描述。还应尽可能提供相关信息，以及能复现问题的代码示例。PR 的目标是让你自己——以及其他人——容易理解问题并验证修复。

若不知道如何修复，可将问题描述给编程 agent，并借助它尝试提交 pull request。

只有标记为「ready for review」（非「draft」状态），且新功能相关测试全部通过的 pull request 才会被审阅。长期停留在「draft」且无活动的 PR 会在数日后关闭。

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

支持问题 ​

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

应提交到哪个分支？ ​

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

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

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

编译后的资源 ​

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

AI 生成的贡献 ​

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

若选择使用 AI 工具协助对框架进行大型或复杂贡献，提交前必须由你本人充分审阅、测试并理解所生成的代码。

Pull request 描述必须完全由贡献者本人撰写。带有 AI 生成描述的 PR 将被关闭。

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

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

安全漏洞 ​

若发现 Laravel 中的安全漏洞，请发送邮件至我们的安全团队 security@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.
 * [tl! remove]
 * @return void [tl! remove]
 */
public function handle(AudioProcessor $processor): void
{
    // ...
}

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

php
/**
 * Get the attachments for the message.
 * [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）：

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