bagisto-coding-standards

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Coding Standards

编码规范

The canonical rules for all Bagisto code, in one place, so a change to a DataGrid, a payment class or a theme is held to the same bar as a change to a package.

Pint decides the mechanical questions. Run

vendor/bin/pint

and trust it for spacing, import order, trailing commas and the rest. What follows is what Pint cannot see — and what a reviewer will otherwise send back.

本文件汇总了所有Bagisto代码的权威规则，确保DataGrid、支付类、主题等任何模块的修改都遵循统一标准。

机械性格式问题由Pint决定。运行

vendor/bin/pint

命令，交由它处理缩进、导入顺序、尾随逗号等格式问题。下文将介绍Pint无法检测的规则——也是代码审核时会重点检查的内容。

Reference files

参考文件

File	Load when
code-style.md	Writing any PHP — multi-clause conditions, class member order
comments.md	Any comment or docblock, in any language
laravel.md	Framework idiom — events, migrations, config, helpers, validation, queues
data-access.md	Reading or writing the database — the repository rule and its one exception
security.md	Output, input, uploads, SQL, secrets, payments
security-authorization.md	Routes, permissions, guards, one user's access to another's data
blade.md	Any `.blade.php` — namespaces, `:` versus `::` , components, page skeleton
blade-formatting.md	Indentation, attribute layout, `@props` alignment, recipes
localization.md	Any user-facing string, or a `Resources/lang/` change

The PHP rules apply inside an

@php

block too, which Pint cannot reach.

文件	适用场景
code-style.md	编写任何PHP代码时——多条件语句、类成员顺序
comments.md	编写任何语言的注释或文档块时
laravel.md	Laravel框架惯用写法——事件、迁移、配置、助手函数、验证、队列
data-access.md	读写数据库时——仓库模式规则及其唯一例外
security.md	输出、输入、上传、SQL、密钥、支付相关操作时
security-authorization.md	路由、权限、守卫、用户间数据访问控制时
blade.md	编写任何 `.blade.php` 文件时——命名空间、 `:` 与 `::` 的区别、组件、页面骨架
blade-formatting.md	缩进、属性布局、 `@props` 对齐、常用写法
localization.md	处理任何面向用户的字符串，或修改 `Resources/lang/` 目录下内容时

PHP规则同样适用于

@php

代码块，而这部分是Pint无法检测到的。

The rules in one screen

核心规则一览

Every method and property carries a docblock, whatever its visibility. The description is a capitalised sentence ending in a full stop. Type information belongs in the signature; add
```
@param
```
/
```
@return
```
only for what a native type cannot express.
Class members run constants → properties → constructor → public → protected → private, each visibility one contiguous block. A helper called by a public method still lives in the protected block at the bottom.
A condition with more than one clause goes multiline, the boolean operator leading each line. Single-clause conditions stay inline. The rule keys off the number of clauses, not the line length.
No comments inside method bodies, object literals or markup — not even a one-line "why". A non-obvious reason belongs in the method's docblock or the commit message. If a line needs prose to be understood, extract a named method instead. See comments.md.
A class docblock defines what the class is. It is not the history of what it replaced or why the previous approach was wrong.
All database access goes through a repository. No
```
DB::
```
and no model queries in controllers, listeners, jobs or services. The single sanctioned exception is a DataGrid's
```
prepareQueryBuilder()
```
.
Events are dot-delimited strings, not classes —
```
catalog.product.update.after
```
— and fire in
```
before
```
/
```
after
```
pairs. See laravel.md.
:
binds a PHP value,
::
passes a literal
:
through to Vue, and
```
::
```
only works on a Blade component tag. Getting this wrong fails silently. See blade.md.
Authorize on the server and escape at the point of interpolation. Hiding a control is presentation; the route and the controller decide what is allowed, and a value is safe in element text yet dangerous inside an attribute. See security.md.
Scope every storefront query to its owner. An id from the request never selects a row on its own — that is the easiest real vulnerability to introduce here. See security-authorization.md.
Every user-facing string goes through
trans()
, with the key added to all 22 locales and verified by
```
php artisan bagisto:translations:check
```
.
Fix what you touch. A pre-existing violation in a file you edit is yours — scan the whole class's member order and docblocks, not just your own lines.

每个方法和属性都必须包含文档块（docblock），无论其可见性如何。描述内容需为大写开头、以句号结尾的完整句子。类型信息应写在方法签名中；仅当原生类型无法表达时，才添加
```
@param
```
/
```
@return
```
注释。
类成员顺序为：常量 → 属性 → 构造函数 → 公共方法 → 受保护方法 → 私有方法，同一可见性的成员需连续排列。即使是被公共方法调用的辅助方法，也应放在底部的受保护方法区块中。
包含多个子句的条件语句需换行书写，布尔运算符置于每行开头。仅含单个子句的条件语句保持单行。此规则依据子句数量而非行长度判断。
方法体、对象字面量或标记语言内部禁止添加注释——哪怕是单行的“原因说明”。非显而易见的逻辑原因应写在方法的文档块或提交信息中。如果某行代码需要文字注释才能理解，应将其提取为一个命名方法。详情请参考comments.md。
类的文档块应定义类的用途，而非记录它替代了什么或之前方案的问题所在。
所有数据库访问必须通过仓库（repository）实现。控制器、监听器、任务或服务中禁止使用
```
DB::
```
或模型查询。唯一允许的例外是DataGrid的
```
prepareQueryBuilder()
```
方法。
事件采用点分隔的字符串命名，而非类名——例如
```
catalog.product.update.after
```
——并且需成对触发
```
before
```
/
```
after
```
事件。详情请参考laravel.md。
:
用于绑定PHP值，
::
用于将字面量
:
传递给Vue，且
```
::
```
仅适用于Blade组件标签。使用错误不会抛出明显异常。详情请参考blade.md。
在服务器端做权限校验，在插值处做转义处理。隐藏控件属于展示层逻辑；路由和控制器才是权限控制的核心，元素文本中的值是安全的，但在属性中则可能存在风险。详情请参考security.md。
所有前台查询需限定到所属用户。直接使用请求中的ID查询数据是最容易引入的真实漏洞。详情请参考security-authorization.md。
所有面向用户的字符串必须通过
trans()
处理，且对应的键需添加到全部22种语言包中，并通过
```
php artisan bagisto:translations:check
```
命令验证。
修改一处，修复一片。如果你编辑的文件中存在之前违反规范的内容，你需要一并修复——检查整个类的成员顺序和文档块，而不仅仅是你修改的代码行。

Where the code and these files disagree

代码与本规范不一致时的处理方式

The checkout wins. Follow the surrounding code, say so in your summary, and raise the drift — these files are a snapshot, not the source of truth.

That is different from a file that is simply wrong: a missing docblock in an untouched class is debt, not a convention. Match the rule, not the worst example of it.

以现有代码为准。遵循周边代码的写法，在提交说明中注明情况，并提出规范偏差问题——本文件是当前规范的快照，而非唯一真理。

但这与代码本身存在错误不同：未修改过的类中缺少文档块属于技术债务，而非约定。此时应遵循规则，而非最差示例。