|
| 1 | +--- |
| 2 | +description: Pre-output checklist, naming, typing, comparisons, and PHPDoc rules for all PHP files in libraries. |
| 3 | +paths: |
| 4 | + - "src/**/*.php" |
| 5 | + - "tests/**/*.php" |
| 6 | +--- |
| 7 | + |
| 8 | +# Code style |
| 9 | + |
| 10 | +Semantic code rules for all PHP files. Formatting rules (PSR-1, PSR-4, PSR-12, line length) are enforced by `phpcs.xml` |
| 11 | +and are not repeated here. Refer to `rules/domain.md` for domain modeling rules. |
| 12 | + |
| 13 | +## Pre-output checklist |
| 14 | + |
| 15 | +Verify every item before producing any PHP code. If any item fails, revise before outputting. |
| 16 | + |
| 17 | +1. `declare(strict_types=1)` is present. |
| 18 | +2. All classes are `final readonly` by default. Use `class` (without `final` or `readonly`) only when the class is |
| 19 | + designed as an extension point for consumers (e.g., `Collection`, `ValueObject`). Use `final class` without |
| 20 | + `readonly` only when the parent class is not readonly (e.g., extending a third-party abstract class). |
| 21 | +3. All parameters, return types, and properties have explicit types. |
| 22 | +4. Constructor property promotion is used. |
| 23 | +5. Named arguments are used at call sites for own code, tests, and third-party library methods (e.g., tiny-blocks). |
| 24 | + Never use named arguments on native PHP functions (`array_map`, `in_array`, `preg_match`, `is_null`, |
| 25 | + `iterator_to_array`, `sprintf`, `implode`, etc.) or PHPUnit assertions (`assertEquals`, `assertSame`, |
| 26 | + `assertTrue`, `expectException`, etc.). |
| 27 | +6. No `else` or `else if` exists anywhere. Use early returns, polymorphism, or map dispatch instead. |
| 28 | +7. No abbreviations appear in identifiers. Use `$index` instead of `$i`, `$account` instead of `$acc`. |
| 29 | +8. No generic identifiers exist. Use domain-specific names instead: |
| 30 | + `$data` → `$payload`, `$value` → `$totalAmount`, `$item` → `$element`, |
| 31 | + `$info` → `$currencyDetails`, `$result` → `$conversionOutcome`. |
| 32 | +9. No raw arrays exist where a typed collection or value object is available. Use `tiny-blocks/collection` |
| 33 | + (`Collection`, `Collectible`) instead of raw `array` for any list of domain objects. Raw arrays are acceptable |
| 34 | + only for primitive configuration data, variadic pass-through, or interop at system boundaries. |
| 35 | +10. No private methods exist except private constructors for factory patterns. Inline trivial logic at the call site |
| 36 | + or extract it to a collaborator or value object. |
| 37 | +11. Members are ordered: constants first, then constructor, then static methods, then instance methods. Within each |
| 38 | + group, order by body size ascending (number of lines between `{` and `}`). Constants and enum cases, which have |
| 39 | + no body, are ordered by name length ascending. |
| 40 | +12. Constructor parameters are ordered by parameter name length ascending (count the name only, without `$` or type), |
| 41 | + except when parameters have an implicit semantic order (e.g., `$start/$end`, `$from/$to`, `$startAt/$endAt`), |
| 42 | + which takes precedence. The same rule applies to named arguments at call sites. |
| 43 | + Example: `$id` (2) → `$value` (5) → `$status` (6) → `$precision` (9). |
| 44 | +13. No O(N²) or worse complexity exists. |
| 45 | +14. No logic is duplicated across two or more places (DRY). |
| 46 | +15. No abstraction exists without real duplication or isolation need (KISS). |
| 47 | +16. All identifiers, comments, and documentation are written in American English. |
| 48 | +17. No justification comments exist (`// NOTE:`, `// REASON:`, etc.). Code speaks for itself. |
| 49 | +18. `// TODO: <reason>` is used when implementation is unknown, uncertain, or intentionally deferred. |
| 50 | + Never leave silent gaps. |
| 51 | +19. All class references use `use` imports at the top of the file. Fully qualified names inline are prohibited. |
| 52 | +20. No dead or unused code exists. Remove unreferenced classes, methods, constants, and imports. |
| 53 | +21. Never create public methods, constants, or classes in `src/` solely to serve tests. If production code does not |
| 54 | + need it, it does not exist. |
| 55 | +22. Always use the most current and clean syntax available in the target PHP version. Prefer match to switch, |
| 56 | + first-class callables over `Closure::fromCallable()`, readonly promotion over manual assignment, enum methods |
| 57 | + over external switch/if chains, named arguments over positional ambiguity (except where excluded by rule 5), |
| 58 | + and `Collection::map` over foreach accumulation. |
| 59 | +23. No vertical alignment of types in parameter lists or property declarations. Use a single space between |
| 60 | + type and variable name. Never pad with extra spaces to align columns: |
| 61 | + `public OrderId $id` — not `public OrderId $id`. |
| 62 | +24. Opening brace `{` goes on the same line as the closing parenthesis `)` for constructors, methods, and |
| 63 | + closures: `): ReturnType {` — not `): ReturnType\n {`. Parameters with default values go last. |
| 64 | + |
| 65 | +## Casing conventions |
| 66 | + |
| 67 | +- Internal code (variables, methods, classes): **`camelCase`**. |
| 68 | +- Constants and enum-backed values when representing codes: **`SCREAMING_SNAKE_CASE`**. |
| 69 | + |
| 70 | +## Naming |
| 71 | + |
| 72 | +- Names describe **what** in domain terms, not **how** technically: `$monthlyRevenue` instead of `$calculatedValue`. |
| 73 | +- Generic technical verbs (`process`, `handle`, `execute`, `mark`, `enforce`, `manage`, `ensure`, `validate`, |
| 74 | + `check`, `verify`, `assert`, `transform`, `parse`, `compute`, `sanitize`, `normalize`) **should be avoided**. |
| 75 | + Prefer names that describe the domain operation. |
| 76 | +- Booleans use predicate form: `isActive`, `hasPermission`, `wasProcessed`. |
| 77 | +- Collections are always plural: `$orders`, `$lines`. |
| 78 | +- Methods returning bool use prefixes: `is`, `has`, `can`, `was`, `should`. |
| 79 | + |
| 80 | +## Comparisons |
| 81 | + |
| 82 | +1. Null checks: use `is_null($variable)`, never `$variable === null`. |
| 83 | +2. Empty string checks on typed `string` parameters: use `$variable === ''`. Avoid `empty()` on typed strings |
| 84 | + because `empty('0')` returns `true`. |
| 85 | +3. Mixed or untyped checks (value may be `null`, empty string, `0`, or `false`): use `empty($variable)`. |
| 86 | + |
| 87 | +## American English |
| 88 | + |
| 89 | +All identifiers, enum values, comments, and error codes use American English spelling: |
| 90 | +`canceled` (not `cancelled`), `organization` (not `organisation`), `initialize` (not `initialise`), |
| 91 | +`behavior` (not `behaviour`), `modeling` (not `modelling`), `labeled` (not `labelled`), |
| 92 | +`fulfill` (not `fulfil`), `color` (not `colour`). |
| 93 | + |
| 94 | +## PHPDoc |
| 95 | + |
| 96 | +- PHPDoc is restricted to interfaces only, documenting obligations and `@throws`. |
| 97 | +- Never add PHPDoc to concrete classes. |
| 98 | + |
| 99 | +## Collection usage |
| 100 | + |
| 101 | +When a property or parameter is `Collectible`, use its fluent API. Never break out to raw array functions. |
| 102 | + |
| 103 | +**Prohibited — `array_map` + `iterator_to_array` on a Collectible:** |
| 104 | + |
| 105 | +```php |
| 106 | +$names = array_map( |
| 107 | + static fn(Element $element): string => $element->name(), |
| 108 | + iterator_to_array($collection) |
| 109 | +); |
| 110 | +``` |
| 111 | + |
| 112 | +**Correct — fluent chain with `map()` + `toArray()`:** |
| 113 | + |
| 114 | +```php |
| 115 | +$names = $collection |
| 116 | + ->map(transformations: static fn(Element $element): string => $element->name()) |
| 117 | + ->toArray(keyPreservation: KeyPreservation::DISCARD); |
| 118 | +``` |
| 119 | + |
| 120 | +The same applies to `filter()`, `reduce()`, `each()`, and all other `Collectible` operations. Chain them |
| 121 | +fluently. Never materialize with `iterator_to_array` to then pass into a raw `array_*` function. |
0 commit comments