Laravel 中文文档

主题

贡献者指南 ​

缺陷报告 ​

为激发积极协作，Laravel 热忱欢迎提交拉取请求，而非仅限于缺陷报告。唯有标注为“准备审核”（非“草稿”状态）且新功能测试尽皆通过的拉取请求，方得接受审视。久滞于“草稿”状态的请求，若数日未见动静，将被悄然关闭。

若您欲报告缺陷，须附上标题与清晰的问题描述，辅以尽可能丰富的相关信息及展示问题的代码片段。缺陷报告之旨，在于便于您与他人重现瑕疵，进而构思修补之策。

须知，缺陷报告旨在期盼同病相怜者与您携手共解难题，切勿奢望其即刻获响应或他人争相修补。报告之设，乃助您与同道踏上修复征途。若有意襄助，可着手解决我们问题追踪器中列明的任何缺陷，惟需 GitHub 认证方可尽览 Laravel 所有事项。

若您在使用 Laravel 时察觉 DocBlock、PHPStan 或 IDE 警示之不当，请勿在 GitHub 上立帖，而应提交拉取请求以正其误。

Laravel 源代码由 GitHub 掌管，各项目皆有其专属仓库：

求助咨询 ​

Laravel 的 GitHub 问题追踪器非求助或支持之所。请转而借助以下渠道寻求启迪：

核心开发研讨 ​

您可于 Laravel 框架仓库的 GitHub 讨论板块 提议新功能或现有行为的改进。若倡议新功能，请备好亲自编织部分实现代码。

关于缺陷、新功能及现有功能实现的非正式探讨，于 Laravel Discord 服务器 的 #internals 频道中展开。Laravel 的守护者 Taylor Otwell 平日（周一至周五）上午 8 点至下午 5 点（UTC-06:00 或美洲/芝加哥时间）常驻该频道，其余时间则偶现身影。

分支抉择 ​

所有 缺陷修补须提交至支持修复的最新版本（当前为 11.x）。缺陷修补永不应投向 master 分支，除非其针对仅存于即将发布版本的功能。

小型、与当前版本完全向后兼容的功能，可提交至最新稳定分支（当前为 11.x）。

大型 新功能或具突破性变更的功能，须始终投向承载下一版本的 master 分支。

编译资源 ​

若您的变更影响编译文件——如 laravel/laravel 仓库中 resources/css 或 resources/js 的大多数文件——切勿提交已编译之物。其庞大体积难以由维护者审视，或可被恶意利用以植入祸コード。为防此患，所有编译文件将由 Laravel 维护者生成并提交。

安全漏洞 ​

若您发现 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 将在拉取请求合并后，自动为 Laravel 仓库润色代码风格。此举使我们得以专注于贡献之实质，而非形式。

行为准则 ​

Laravel 之行为准则承自 Ruby 准则。任何违背准则之举，可向 Taylor Otwell（taylor@laravel.com）举报：

  • 参与者应对异见宽容以待。
  • 参与者须确保言行无个人攻击与贬损之语。
  • 解读他人言行时，参与者应始终假定对方怀有善意。
  • 可合理视为骚扰之行为，绝不容忍。