php-conventions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PHP Conventions

PHP编码规范

These are non-negotiable personal conventions unless explicitly overridden by the user.

这些是不可妥协的个人规范，除非用户明确要求覆盖。

Language & Syntax

语言与语法

Strict types — Every PHP file must declare
```
declare(strict_types=1);
```
at the top. If it is an existing file, you do not need to add it, but mention it to the user.
Import function calls and constants — Always use function and constant imports rather than calling global functions inline:
php
```
use function array_key_exists;
use function sprintf;
use function count;

use const JSON_THROW_ON_ERROR;
```
#[Override]
attribute — Always add
```
#[Override]
```
to methods that override a parent or implement an interface method.
final readonly
classes — Prefer
```
final readonly
```
by default. Drop
```
readonly
```
only when mutability is genuinely needed (e.g., mutable DTOs, test cases). Drop
```
final
```
only when extension is a deliberate design choice. If either worsens developer experience, relax — but call it out.
PHPStan generics & iterables — Document iterables and generic types explicitly. Never mark iterables as
```
array<array-key, mixed>
```
— take the time to define the actual shape. Use
```
@phpstan-type
```
annotations when the type will likely be imported by other files:
php
```
/**
 * @phpstan-type OrderContext array{orderId: int, shopId: int, items: list<LineItemData>}
 */
```
Reference the phpstan-type (
```
phpstan-type-import
```
if defined in another class) instead of duplicating the array shape.
PHPStan discipline — Do not add entries to PHPStan baseline files. Fix the errors properly. When a
```
@phpstan-ignore
```
is genuinely necessary, always include a parenthetical explanation of why:
php
```
// @phpstan-ignore argument.type (We have already verified the type above)
```
A bare
```
@phpstan-ignore
```
without justification is not acceptable.

严格类型 — 每个PHP文件必须在顶部声明
```
declare(strict_types=1);
```
。如果是现有文件，你不需要添加，但要向用户提及该要求。

导入函数调用和常量 — 始终使用函数和常量导入，而非内联调用全局函数：

php

use function array_key_exists;
use function sprintf;
use function count;

use const JSON_THROW_ON_ERROR;

#[Override]
属性 — 重写父类方法或实现接口方法时，始终添加
```
#[Override]
```
。
final readonly
类 — 默认优先使用
```
final readonly
```
。只有当确实需要可变性时才去掉
```
readonly
```
（例如可变DTO、测试用例）。只有当扩展是经过深思熟虑的设计选择时才去掉
```
final
```
。如果两者会降低开发者体验，可以放宽要求，但要明确说明。
PHPStan泛型与可迭代对象 — 明确标注可迭代对象和泛型类型。永远不要将可迭代对象标记为
```
array<array-key, mixed>
```
— 花时间定义实际的结构。如果类型可能会被其他文件导入，使用
```
@phpstan-type
```
注解：
php
```
/**
 * @phpstan-type OrderContext array{orderId: int, shopId: int, items: list<LineItemData>}
 */
```
引用定义好的phpstan-type（如果定义在其他类中则使用
```
phpstan-type-import
```
），不要重复定义数组结构。
PHPStan使用规范 — 不要向PHPStan基线文件添加条目，要正确修复错误。如果确实需要使用
```
@phpstan-ignore
```
，必须附带括号说明理由：
php
```
// @phpstan-ignore argument.type (We have already verified the type above)
```
不接受没有正当理由的裸
```
@phpstan-ignore
```
注解。

Class Design & Dependencies

类设计与依赖

Single-use classes over service bloat — Prefer small, focused classes that encapsulate one piece of functionality. These may be called "UseCases" or "Actions" depending on team convention, but when possible, name them as
```
-er
```
nouns that describe what they do:
```
OrderCreator
```
,
```
FinancialOutcomeDeterminer
```
,
```
RefundCalculator
```
. Avoid adding methods to already-large service classes — you will encounter many of these, and they may be acceptable as-is, but don't contribute to the sprawl.
Dependency injection over service location — Avoid
```
resolve()
```
,
```
app()
```
, and similar service locator calls inside methods. These obscure dependencies and prevent unit testing. Acceptable only in rare infrastructure-layer bootstrap code — flag it to the user if encountered.
No model observers, ever — Never use Laravel model observers or listen for Eloquent model events (
```
creating
```
,
```
saved
```
, etc.). Dispatch explicit domain events instead. This is non-negotiable.
Prefer composition over deep inheritance — Avoid complex inheritance hierarchies. Before creating an abstract class with children, ask: could one child be replaceable with another? What is the hierarchy intended to communicate? If the answer is unclear, prefer:
- Interfaces with traits that fulfill them, giving concrete classes opt-in behavior.
- Coordinator/orchestrator classes that accept an interface and act upon it, rather than embedding orchestration logic in an abstract parent.
Deep inheritance chains make code harder to reason about, test, and extend. Flat, composable designs are almost always preferable.

Rich, contextual exceptions — Exceptions should carry meaningful messages and contextual data. Custom exception classes are good, but they shine when they expose public properties with the relevant context — the entity being operated on, whether the failure is retryable, the external request/response that caused it, etc. This also makes testing easier since you can assert against those properties rather than parsing message strings.

When helpful, add static factory methods that build a default message and set properties from the inputs:

php

final class ShopifyFailure extends RuntimeException
{
    public function __construct(
        string $message,
        public readonly Response $response,
        public readonly bool $isRetryable = false,
    ) {
        parent::__construct($message);
    }

    public static function fromResponse(Response $response): self
    {
        return new self(
            message: sprintf('Shopify returned %d: %s', $response->status(), $response->body()),
            response: $response,
            isRetryable: $response->status() >= 500,
        );
    }
}

Domain knowledge as comments — When a planning doc, JIRA ticket, or external context reveals domain knowledge not obvious from the code, add it as a comment. This helps future developers and LLM agents. These are among the most valuable comments possible.
Not everything needs an interface - If there is likely going to be exactly one instance of an implementation, an interface may not be necessary. Remember: hand-rolled mocks/spies/stubs/fakes used in testing are a second implementation. Not using an interface may potentially make testing harder, so you'll need to weigh these tradeoffs. Since this requires taste, you may need input from the user.

优先使用单一用途类而非臃肿的服务类 — 优先使用封装单一功能的小型聚焦类。根据团队规范，这类类可以被称为"UseCases"或"Actions"，如果可能的话，使用描述其功能的
```
-er
```
后缀名词命名：
```
OrderCreator
```
、
```
FinancialOutcomeDeterminer
```
、
```
RefundCalculator
```
。避免向已经很庞大的服务类添加方法 — 你可能会遇到很多这类类，保持现有状态是可以接受的，但不要加剧代码膨胀。
优先使用依赖注入而非服务定位 — 避免在方法内部使用
```
resolve()
```
、
```
app()
```
以及类似的服务定位器调用。这些调用会隐藏依赖，阻碍单元测试。仅在极少数基础设施层引导代码中可以使用 — 如果遇到这类情况要向用户标记。
永远不要使用模型观察者 — 永远不要使用Laravel模型观察者，也不要监听Eloquent模型事件（
```
creating
```
、
```
saved
```
等），而是主动派发显式的领域事件。这一条不可妥协。
优先使用组合而非深度继承 — 避免复杂的继承层级。在创建带有子类的抽象类之前，先思考：一个子类是否可以替换另一个？这个层级的设计目的是什么？如果答案不明确，优先选择：
- 接口搭配实现接口的** trait **，让具体类可以选择所需的行为。
- 协调/编排类接收接口并基于其执行操作，而不是将编排逻辑嵌入抽象父类中。
深度继承链会让代码更难理解、测试和扩展。扁平、可组合的设计几乎总是更优选择。

丰富的上下文异常 — 异常应该携带有意义的消息和上下文数据。自定义异常类是很好的选择，当它们通过公共属性暴露相关上下文时价值会更高：正在操作的实体、故障是否可重试、导致故障的外部请求/响应等。这也会让测试更简单，因为你可以直接断言这些属性，而不需要解析消息字符串。

有帮助的情况下，可以添加静态工厂方法来构建默认消息，并根据输入设置属性：

php

final class ShopifyFailure extends RuntimeException
{
    public function __construct(
        string $message,
        public readonly Response $response,
        public readonly bool $isRetryable = false,
    ) {
        parent::__construct($message);
    }

    public static function fromResponse(Response $response): self
    {
        return new self(
            message: sprintf('Shopify returned %d: %s', $response->status(), $response->body()),
            response: $response,
            isRetryable: $response->status() >= 500,
        );
    }
}

将领域知识写入注释 — 当规划文档、JIRA工单或外部上下文提供了代码中不明显的领域知识时，将其作为注释添加。这对未来的开发者和LLM Agent都有帮助，是价值最高的注释之一。
不是所有内容都需要接口 - 如果某个实现大概率只会有一个实例，那么可能不需要接口。记住：测试中使用的手动模拟/间谍/存根/伪造类就是第二个实现。不使用接口可能会增加测试难度，所以你需要权衡利弊。这需要经验判断，你可能需要用户的意见。

Testing Philosophy

测试理念

Prefer PHPUnit (unit) tests — Unit tests are dramatically faster than feature tests. When writing new code, design it to be unit-testable: use dependency injection, avoid Laravel facades in business logic, accept interfaces. If code is untestable without booting Laravel, that's a design signal worth discussing.
Avoid mocking frameworks — Mocking frameworks (Mockery, PHPUnit mocks) usually test the wrong layer and indicate a design flaw. Acceptable uses:
- Stubs: providing a canned return value from a dependency
- Classical mocks: verifying a specific interaction that is the point of the test (e.g., "did we dispatch this event?")
If you find yourself reaching for a mock, pause and discuss refactoring opportunities with the user before proceeding. Mocks are a last resort.
NEVER mock Data objects. NEVER mock Laravel models. — Instantiate them. If a Data object or Model is hard to construct, that's a test-design or code-design problem to address, not a reason to mock.

Test structure — Delimit test sections with comments:

php

// Given a user without permissions
$user = User::factory()->create(['role' => 'viewer']);

// When they attempt to update settings
$response = $this->actingAs($user)->put('/settings', ['theme' => 'dark']);

// Then the request is forbidden
$response->assertForbidden();

Add a brief description after

Given

When

, or

Then

when it clarifies intent.

Test method naming - The method of a test name should be
```
{condition}_{theMethodBeingCalled}_{then}
```
and should use the
```
#[Test]
```
attribute rather than prefixing the method with
```
test_
```
. Be descriptive, but avoid making the test method name more than 60 characters.
Reference assertion methods statically - PHPUnit allows you to call either
```
$this->assertEquals()
```
or
```
self::assertEquals()
```
. Unless the rest of the test class is already using
```
$this->assert*
```
, prefer calling them statically.
Mark tests as final - This is the recommendation from PHPUnit's creator.
Never test private/protected methods directly — If you feel the need to test a private or protected method on code we own, that's a design smell. Extract the logic into a collaborator class with public methods and test that instead. The need to reach into private internals means the class is doing too much or the boundaries are wrong.
Don't assert against log statements — Unless you're testing a logger or logging infrastructure itself, avoid asserting that specific log messages were produced. Logs are observability, not behavior.

优先使用PHPUnit（单元）测试 — 单元测试比功能测试快得多。编写新代码时，要将其设计为可单元测试：使用依赖注入、避免在业务逻辑中使用Laravel门面、接收接口参数。如果不启动Laravel就无法测试代码，这是一个值得讨论的设计信号。
避免使用模拟框架 — 模拟框架（Mockery、PHPUnit mocks）通常测试了错误的层级，也意味着存在设计缺陷。可接受的使用场景：
- 存根：为依赖提供预设的返回值
- 经典模拟：验证作为测试核心目标的特定交互（例如："我们是否派发了这个事件？"）
如果你想使用模拟，先暂停，和用户讨论重构机会后再继续。模拟是最后的手段。
永远不要模拟数据对象，永远不要模拟Laravel模型。 — 直接实例化它们。如果数据对象或模型很难构造，这是需要解决的测试设计或代码设计问题，而不是使用模拟的理由。

测试结构 — 用注释分隔测试的不同阶段：

php

// Given a user without permissions
$user = User::factory()->create(['role' => 'viewer']);

// When they attempt to update settings
$response = $this->actingAs($user)->put('/settings', ['theme' => 'dark']);

// Then the request is forbidden
$response->assertForbidden();

如果能明确意图，可在

Given

、

When

或

Then

后添加简短描述。

测试方法命名 - 测试方法的名称应为
```
{condition}_{theMethodBeingCalled}_{then}
```
格式，并且使用
```
#[Test]
```
属性而非给方法添加
```
test_
```
前缀。命名要具备描述性，但避免测试方法名称超过60个字符。
静态调用断言方法 - PHPUnit允许调用
```
$this->assertEquals()
```
或
```
self::assertEquals()
```
。除非测试类的其余部分已经使用
```
$this->assert*
```
，否则优先使用静态调用。
将测试类标记为final - 这是PHPUnit创建者的建议。
永远不要直接测试私有/受保护方法 — 如果你觉得需要测试我们自有代码中的私有或受保护方法，这是一个设计坏味道。将逻辑提取到带有公共方法的协作类中，然后测试这个协作类。需要访问私有内部成员意味着类承担了过多职责，或者边界定义错误。
不要断言日志语句 — 除非你正在测试日志记录器或日志基础设施本身，否则不要断言生成了特定的日志消息。日志是可观测性工具，不是业务行为。

Working in Existing Code

在现有代码中工作

Accept the team's conventions — When modifying existing code, follow the conventions already in place in that area. You may mention that refactoring opportunities exist and how the current code conflicts with these rules, but deliver value first. Being opinionated is secondary to shipping.
No drive-by refactors in ticketed work — Never make unrelated refactors inside a PR/MR tied to a ticket. Unrelated changes increase blast radius for bugs and make reviews harder. Instead:
- During planning, identify code that would benefit from refactoring.
- Propose a separate refactoring MR that ships independently, ahead of the feature work.
- Follow the principle: "Make the change easy, then make the easy change."
- This requires judgment — always flag it to the user.

遵循团队现有规范 — 修改现有代码时，遵循该区域已有的规范。你可以提及存在重构机会，以及当前代码与这些规则的冲突，但首先要交付价值。坚持己见的优先级低于功能交付。
工单相关工作中不要做顺手重构 — 永远不要在绑定工单的PR/MR中进行不相关的重构。不相关的变更会扩大bug影响范围，也会增加代码评审难度。正确的做法是：
- 在规划阶段，识别可受益于重构的代码。
- 提出独立的重构MR，在功能开发之前先行交付。
- 遵循原则："先让变更变得容易，再做容易的变更。"
- 这需要判断 — 始终向用户标记这类情况。

Observability

可观测性

Think about the 3 AM oncall engineer — When writing code, imagine a sleep-deprived human investigating an incident involving this code. Add context to logs, use structured logging keys (following key structure per repo convention; if none is defined, default to snake-case), and make error paths descriptive.
Metrics cardinality — Be mindful of high-cardinality tags on metrics (e.g., user IDs, order IDs). These explode storage costs and degrade query performance.
Suggest monitors - If during coding there is an obvious opportunity for "this would make a great monitor to signal application health," you should mention it to the user. If you have awareness of the user's observablity platform, offer to help them construct the monitor. Features are not done until observability is in place.

站在凌晨3点值班工程师的角度思考 — 编写代码时，想象一个睡眠不足的工程师正在排查涉及这段代码的故障。给日志添加上下文，使用结构化日志键（遵循代码库的键结构规范；如果没有定义，默认使用蛇形命名），让错误路径具备描述性。
指标基数 — 注意指标上的高基数标签（例如用户ID、订单ID）。这些会大幅增加存储成本，降低查询性能。
建议监控规则 - 如果编码过程中明显发现"这可以作为一个很好的监控指标来反映应用健康状态"，你应该向用户提及。如果你了解用户的可观测性平台，可以主动帮助他们构建监控规则。可观测性落地之前，功能开发不算完成。

Planning

规划

Upfront planning docs — When planning work, produce a planning document before writing code. Structure it for humans who will skim:
- TL;DR section at the top — summary of approach, key decisions, risks.
- Detailed sections below for those who want depth.
Multi-model plan review — If sub-agents are available, pass the plan to a different thinking model (ideally from a different provider) for review with no context about your findings. Iterate between multiple models until general consensus emerges. Challenge sub-agent feedback when it's wrong — consensus doesn't mean capitulation.
Include failure scenarios - Make sure to think of different failure scenarios, how we should recover from them (or IF we should attempt to recover from them), and how we will communicate those failures.
Identify refactoring prerequisites during planning — If the current code structure will make the planned change difficult, call this out early. Propose preparatory refactoring MRs that ship first.
Plans should mention observability - Iterate with the user to determine how the feature or code change can be observed and what monitors would indicate code health.

前置规划文档 — 规划工作时，在编写代码之前产出规划文档。面向会快速浏览的人员设计结构：
- 顶部放置TL;DR部分 — 总结实现方案、关键决策、风险。
- 下方放置供需要深入了解的人员阅读的详细章节。
多模型规划评审 — 如果有子Agent可用，将规划提交给不同的思考模型（最好来自不同的提供商）评审，且不要提供你自己的结论相关上下文。在多个模型之间迭代，直到达成普遍共识。如果子Agent的反馈有误，可以提出质疑 — 共识不意味着妥协。
包含故障场景 - 确保考虑不同的故障场景，我们应该如何从中恢复（或者是否应该尝试恢复），以及我们将如何传递这些故障信息。
在规划阶段识别重构前置条件 — 如果现有代码结构会让规划的变更难以实施，尽早提出来。提出先行交付的预备重构MR。
规划中应提及可观测性 - 与用户迭代确认如何观测功能或代码变更，以及哪些监控规则可以反映代码健康状态。