bagisto-coding-standards

编码规范

所有 Bagisto 代码的规范依据都集中在此处，因此无论修改 DataGrid、支付类、主题还是软件包，都要遵循相同的标准。

格式问题以 Pint 的判断为准。 运行 vendor/bin/pint，并遵循它对空格、导入顺序、尾随逗号等问题的处理。以下内容是 Pint 无法检查的，也是评审人员可能会要求你修改的地方。

参考文件

文件	何时查看
code-style.md	编写任何 PHP 代码时——多子句条件、类成员顺序
comments.md	编写任何语言的注释或文档块时
laravel.md	使用框架惯用写法时——事件、迁移、配置、辅助函数、验证、队列
data-access.md	读取或写入数据库时——存储库规则及其唯一例外
database-compatibility.md	编写任何查询、迁移或原始 SQL 时——必须同时通过 MySQL、MariaDB 和 PostgreSQL 的检查
security.md	处理输出、输入、上传、SQL、密钥或支付时
security-authorization.md	处理路由、权限、守卫，或用户访问其他用户的数据时
blade.md	编写任何 .blade.php 文件时——命名空间、: 与 ::、组件、页面骨架
blade-formatting.md	处理缩进、属性布局、@props 对齐、代码示例时
localization.md	编写任何面向用户的字符串，或修改 Resources/lang/ 时

@php 代码块内也适用 PHP 规则，尽管 Pint 无法检查其中的代码。

一屏了解规则

• 每个方法和属性都必须有文档块，无论其可见性如何。描述须为首字母大写、以句号结尾的句子，且最多两行。类型信息应写在签名中；只有原生类型无法表达时，才添加 @param/@return。
• 类成员按常量 → 属性 → 构造函数 → public → protected → private 排列，每种可见性各自组成一个连续区块。即使某个辅助方法由 public 方法调用，也仍应放在底部的 protected 区块中。
• 包含多个子句的条件须分行书写，布尔运算符放在每行开头。单子句条件保持单行。判断依据是子句数量，而不是行长。
• 方法体、对象字面量或标记语言中不得有注释——即使是简短的“原因说明”也不行。不明显的原因应写在方法的文档块或提交说明中。如果某行需要文字说明才能理解，就提取为一个有名称的方法。参见 comments.md。
• 类上方不得有文档块——任何时候都不行。98.7% 的核心类都没有文档块。文档块应写在方法、属性或常量上，绝不能写在类、接口、trait 或 enum 上。
• 文档块最多两行。 通常一行即可。如果两行写不下，就不该放在文档块中——删减内容或移到提交说明中。
• 所有数据库访问都必须通过仓库进行。 控制器、监听器、作业或服务中不得使用 DB::，也不得查询模型。唯一获准的例外是 DataGrid 的 prepareQueryBuilder()。
• 每个查询都必须能在 MySQL、MariaDB 和 PostgreSQL 上运行。 应使用 db_grammar()，而不是字面值 'like' 或手写 SQL 函数；绝不能通过捕获约束冲突来解决冲突——语句失败会中止整个 PostgreSQL 事务。参见 database-compatibility.md。
• 事件使用点分隔字符串，而不是类——例如 catalog.product.update.after——并且成对触发 before/after 事件。参见 laravel.md。
• : 用于绑定 PHP 值，:: 用于将字面量 : 传递给 Vue，且 :: 仅适用于 Blade 组件标签。用错时不会报错。参见 blade.md。
• 在服务器端进行授权，并在插值时转义。 隐藏控件只是展示层的处理；是否允许访问由路由和控制器决定，而且某个值在元素文本中是安全的，在属性中却可能有危险。参见 security.md。
• 店面查询都必须限定到所属者。 请求中的 ID 不能单独用于选择记录——这是最容易引入的真实漏洞。参见 security-authorization.md。
• 所有面向用户的字符串都必须通过 trans() 处理，并将键添加到全部 23 种语言中，再通过 php artisan bagisto:translations:check 验证。
• 翻译键使用 kebab-case，路由名称使用 snake_case——同一功能的翻译键为 admin::app.eu-withdrawal.view.received-at，路由为 admin.sales.eu_withdrawals.index，因此绝不能通过搜索对方的拼写来重命名其中一个。URL 路径不受这两种规则约束。参见 localization.md。
• 修复你碰到的问题。 你编辑的文件中原有的违规问题也由你负责——检查整个类的成员顺序和文档块，而不只是自己修改的行。

代码与这些文件不一致时

以当前检出代码为准。遵循周边代码的做法，在总结中说明，并指出差异——这些文件只是某个时点的快照，并非事实标准。

这与文件本身写错的情况不同：未修改的类缺少文档块属于技术债务，而不是惯例。遵循规则，不要照搬最差的示例。

相关内容

• bagisto-code-review——将以上规则应用于他人的更改。
• bagisto-package-development——这些规则所依托的代码结构。