From d4ed46fe0dffe0cc48558f07eff1aa75634fbead Mon Sep 17 00:00:00 2001 From: Gustavo Freze Date: Sat, 16 May 2026 13:13:30 -0300 Subject: [PATCH 01/11] chore: Restructure Claude rules and Copilot instructions. --- .claude/CLAUDE.md | 48 +- .claude/rules/github-workflows.md | 78 -- .claude/rules/php-library-architecture.md | 145 ++++ .claude/rules/php-library-code-style.md | 674 +++++++++++++++--- .claude/rules/php-library-commits.md | 111 +++ .claude/rules/php-library-documentation.md | 325 ++++++++- .claude/rules/php-library-github-workflows.md | 287 ++++++++ .claude/rules/php-library-modeling.md | 315 +++++--- .claude/rules/php-library-testing.md | 335 +++++++-- .claude/rules/php-library-tooling.md | 464 ++++++++++++ .github/copilot-instructions.md | 9 +- 11 files changed, 2381 insertions(+), 410 deletions(-) delete mode 100644 .claude/rules/github-workflows.md create mode 100644 .claude/rules/php-library-architecture.md create mode 100644 .claude/rules/php-library-commits.md create mode 100644 .claude/rules/php-library-github-workflows.md create mode 100644 .claude/rules/php-library-tooling.md diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 11885b0..a561aa6 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -1,32 +1,16 @@ -# Project - -PHP library (tiny-blocks ecosystem). Self-contained package: immutable models, zero infrastructure -dependencies in core, small public surface area. Public API at `src/` root; implementation details -under `src/Internal/`. - -## Rules - -All coding standards, architecture, naming, testing, and documentation conventions -are defined in `rules/`. Read the applicable rule files before generating any code or documentation. - -## Commands - -- `make test` — run tests with coverage. -- `make mutation-test` — run mutation testing (Infection). -- `make review` — run lint. -- `make help` — list all available commands. - -## Post-change validation - -After any code change, run `make review`, `make test`, and `make mutation-test`. -If any fails, iterate on the fix while respecting all project rules until all pass. -Never deliver code that breaks lint, tests, or leaves surviving mutants. - -## File formatting - -Every file produced or modified must: - -- Use **LF** line endings. Never CRLF. -- Have no trailing whitespace on any line. -- End with a single trailing newline. -- Have no consecutive blank lines (max one blank line between blocks). +# CLAUDE.md + +This is a PHP library in the tiny-blocks ecosystem. Detailed rules live in `.claude/rules/`. +Each file is scoped via its `paths` frontmatter. Read the relevant file before producing or +editing content under its scope. + +## Rule files + +- `php-library-architecture.md` — folder structure, public API boundary, `Internal/` semantics. +- `php-library-code-style.md` — semantic code rules for `.php` files in `src/` and `tests/`. +- `php-library-commits.md` — Conventional Commits format. Applied only when generating commit messages. +- `php-library-documentation.md` — README and Markdown documentation standards. +- `php-library-github-workflows.md` — CI workflow structure and action pinning. +- `php-library-modeling.md` — nomenclature, value objects, exceptions, enums, complexity. +- `php-library-testing.md` — BDD Given/When/Then, PHPUnit conventions, coverage discipline. +- `php-library-tooling.md` — canonical config files (`composer.json`, `phpcs.xml`, etc). diff --git a/.claude/rules/github-workflows.md b/.claude/rules/github-workflows.md deleted file mode 100644 index a369ba4..0000000 --- a/.claude/rules/github-workflows.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -description: Naming, ordering, inputs, security, and structural rules for all GitHub Actions workflow files. -paths: - - ".github/workflows/**/*.yml" - - ".github/workflows/**/*.yaml" ---- - -# Workflows - -Structural and stylistic rules for GitHub Actions workflow files. Refer to `shell-scripts.md` for Bash conventions used -inside `run:` steps, and to `terraforms.md` for Terraform conventions used in `terraform/`. - -## Pre-output checklist - -Verify every item before producing any workflow YAML. If any item fails, revise before outputting. - -1. File name follows the convention: `ci-.yml` for reusable CI, `cd-.yml` for dispatch CD. -2. `name` field follows the pattern `CI — ` or `CD — `, using sentence case after the dash - (e.g., `CD — Run migration`, not `CD — Run Migration`). -3. Reusable workflows use `workflow_call` trigger. CD workflows use `workflow_dispatch` trigger. -4. Each workflow has a single responsibility. CI tests code. CD deploys it. Never combine both. -5. Every input has a `description` field. Descriptions use American English and end with a period. -6. Input names use `kebab-case`: `service-name`, `dry-run`, `skip-build`. -7. Inputs are ordered: required first, then optional. Each group by **name length ascending**. -8. Choice input options are in **alphabetical order**. -9. `env`, `outputs`, and `with` entries are ordered by **key length ascending**. -10. `permissions` keys are ordered by **key length ascending** (`contents` before `id-token`). -11. Top-level workflow keys follow canonical order: `name`, `on`, `concurrency`, `permissions`, `env`, `jobs`. -12. Job-level properties follow canonical order: `if`, `name`, `needs`, `uses`, `with`, `runs-on`, - `environment`, `timeout-minutes`, `strategy`, `outputs`, `permissions`, `env`, `steps`. -13. All other YAML property names within a block are ordered by **name length ascending**. -14. Jobs follow execution order: `load-config` → `lint` → `test` → `build` → `deploy`. -15. Step names start with a verb and use sentence case: `Setup PHP`, `Run lint`, `Resolve image tag`. -16. Runtime versions are resolved from the service repo's native dependency file (`composer.json`, `go.mod`, - `package.json`). No version is hardcoded in any workflow. -17. Service-specific overrides live in a pipeline config file (e.g., `.pipeline.yml`) in the service repo, - not in the workflows repository. -18. The `load-config` job reads the pipeline config file at runtime with safe fallback to defaults when absent. -19. Top-level `permissions` defaults to read-only (`contents: read`). Jobs escalate only the permissions they - need. -20. AWS authentication uses OIDC federation exclusively. Static access keys are forbidden. -21. Secrets are passed via `secrets: inherit` from callers. No secret is hardcoded. -22. Sensitive values fetched from SSM are masked with `::add-mask::` before assignment. -23. Third-party actions are pinned to the latest available full commit SHA with a version comment: - `uses: aws-actions/configure-aws-credentials@ # v4.0.2`. Always verify the latest - version before generating a workflow. -24. First-party actions (`actions/*`) are pinned to the latest major version tag available: - `actions/checkout@v4`. Always check for the most recent major version before generating a workflow. -25. Production deployments require GitHub Environments protection rules (manual approval). -26. Every job sets `timeout-minutes` to prevent indefinite hangs. CI jobs: 10–15 minutes. CD jobs: 20–30 - minutes. Adjust only with justification in a comment. -27. CI workflows set `concurrency` with `group` scoped to the PR and `cancel-in-progress: true` to avoid - redundant runs. -28. CD workflows set `concurrency` with `group` scoped to the environment and `cancel-in-progress: false` to - prevent interrupted deployments. -29. CD workflows use `if: ${{ !cancelled() }}` to allow to deploy after optional build steps. -30. Inline logic longer than 3 lines is extracted to a script in `scripts/ci/` or `scripts/cd/`. - -## Style - -- All text (workflow names, step names, input descriptions, comments) uses American English with correct - spelling and punctuation. Sentences and descriptions end with a period. - -## Callers - -- Callers trigger on `pull_request` targeting `main` only. No `push` trigger. -- Callers in service repos are static (~10 lines) and pass only `service-name` or `app-name`. -- Callers reference workflows with `@main` during development. Pin to a tag or SHA for production. - -## Image tagging - -- CD deploy builds: `-sha-` + `latest`. - -## Migrations - -- Migrations run **before** service deployment (schema first, code second). -- `cd-migrate.yml` supports `dry-run` mode (`flyway validate`) for pre-flight checks. -- Database credentials are fetched from SSM at runtime, never stored in workflow files. diff --git a/.claude/rules/php-library-architecture.md b/.claude/rules/php-library-architecture.md new file mode 100644 index 0000000..7e4be10 --- /dev/null +++ b/.claude/rules/php-library-architecture.md @@ -0,0 +1,145 @@ +--- +description: Folder structure, public API boundary, and Internal/ semantics for PHP libraries. +paths: + - "src/**/*.php" +--- + +# Architecture + +Covers the physical layout of the library. Folder structure, the boundary between public API and +implementation detail, and where each type of class lives. Semantic rules (value objects, +exceptions, enums, complexity, nomenclature) live in `php-library-modeling.md`. Code style lives +in `php-library-code-style.md`. + +## Pre-output checklist + +Verify every item before producing or relocating any file. If any item fails, revise before +outputting. + +1. None of the following folder names exist in `src/`: `Models/`, `Entities/`, `ValueObjects/`, + `Enums/`, `Domain/`. They carry no semantic content and conflate technical role with domain + meaning. +2. The `src/` root contains only interfaces, extension points, public enums, thin orchestration + classes, and primary implementations or façades. Substantial logic (algorithms, state machines, + I/O) lives in `src/Internal/`, never at the root. +3. `src/Internal/` is implementation detail and not part of the public API. Breaking changes + inside `src/Internal/` are not semver-breaking. +4. Consumers must not reference, extend, or depend on any type inside `src/Internal/`. The + namespace itself is the boundary. +5. Public exception classes live in `src/Exceptions/`. +6. Internal exception classes live in `src/Internal/Exceptions/`. +7. Public enums live at the `src/` root or inside a public `/` folder. Enums used + only by internals live in `src/Internal/`. +8. Public interfaces live at the `src/` root or inside a public `/` folder. +9. A `/` folder at the `src/` root groups related public types under a shared + concept. Each group has its own namespace and is part of the public API. +10. `/` is optional. Use it only when the library exposes several coherent groups of + types (for example, aggregates and events) rather than a flat set of types around a single + concept. +11. Test fixtures representing domain concepts live in `tests/Models/`. Test doubles for system + boundaries live at the root of `tests/Unit/` or `tests/Integration/`. No dedicated `Mocks/` + or `Doubles/` subdirectory exists. `tests/Drivers//` is permitted when the library + exposes a port exercised against multiple third-party implementations (PSR adapters, + framework integrations). Each `/` subdir holds tests against one specific + implementation. +12. The `tests/Integration/` folder exists only when the library interacts with external + infrastructure (filesystem, database, network). Otherwise, the folder is absent. + +## Folder structure + +Canonical layout for a PHP library in the tiny-blocks ecosystem. + +``` +src/ +├── .php # public contract at root +├── .php # main implementation or extension point at root +├── .php # public enum at root +├── / # public folder grouping related public types under a shared concept +│ ├── .php +│ └── ... +├── Internal/ # implementation details, not part of the public API +│ ├── .php +│ └── Exceptions/ # internal exception classes +└── Exceptions/ # public exception classes + +tests/ +├── Models/ # domain fixtures reused across tests +├── Unit/ # unit tests targeting the public API +│ ├── .php # test doubles at root of Unit/ +│ └── .php +└── Integration/ # only present when the library interacts with infrastructure + └── .php # test doubles at root of Integration/ when needed +``` + +Never use `Models/`, `Entities/`, `ValueObjects/`, `Enums/`, or `Domain/` as folder names. They +carry no semantic content and describe technical role instead of domain meaning. + +## Public API boundary + +The `src/` root is the contract. Everything at the root, plus everything inside public +`/` folders and the public `Exceptions/` folder, is what consumers depend on. Changes +to these types follow semver rules. + +`src/Internal/` is implementation detail. The namespace itself signals the boundary. Consumers +must not depend on any type inside `src/Internal/`. Breaking changes inside `src/Internal/` are +not semver-breaking for the library. + +### What lives at the public boundary + +- Interfaces that define contracts for consumers. +- Extension points designed to be subclassed or composed by consumers. +- Public enums and value objects consumers manipulate directly. +- Thin orchestration classes that wire collaborators together without containing substantial logic. +- Public exception classes consumers may catch. + +### What lives in `src/Internal/` + +- Algorithms, state machines, and complex transformations. +- Adapters for I/O (filesystem, network, database). +- Collaborators that exist purely to break a public class into testable units. +- Implementation details that may change between minor or patch releases. +- Internal exception classes raised by collaborators. + +## Reference examples + +### Small library with flat root + +``` +src/ +├── Timezone.php # public value object +├── Timezones.php # public collection +├── Clock.php # public interface +└── Internal/ + ├── SystemClock.php # default Clock implementation + └── Exceptions/ + └── InvalidTimezone.php +``` + +Everything lives at the root or inside `Internal/`. No `/` folders. Suitable when +the library exposes a small, cohesive set of types around a single concept. + +### Library with public concept groups + +``` +src/ +├── ValueObject.php # public extension point at root +├── Aggregate/ # public namespace grouping aggregate types +│ ├── AggregateRoot.php +│ ├── EventualAggregateRoot.php +│ └── ModelVersion.php +├── Event/ # public namespace grouping event types +│ ├── EventRecord.php +│ ├── EventRecords.php +│ └── SequenceNumber.php +├── Internal/ +│ ├── DefaultModelVersionResolver.php +│ └── Exceptions/ +│ └── InvalidSequenceNumber.php +└── Exceptions/ + └── EventRecordingFailure.php +``` + +`Aggregate/` and `Event/` are public folders at the root, each grouping a coherent set of public +types under one shared concept. Consumers import directly, for example +`TinyBlocks\\Aggregate\AggregateRoot`. Suitable when the library exposes several distinct +concept areas, each with its own set of related types. diff --git a/.claude/rules/php-library-code-style.md b/.claude/rules/php-library-code-style.md index 7ec196e..8485df7 100644 --- a/.claude/rules/php-library-code-style.md +++ b/.claude/rules/php-library-code-style.md @@ -1,5 +1,5 @@ --- -description: Pre-output checklist, naming, typing, complexity, and PHPDoc rules for all PHP files in libraries. +description: Semantic code rules for all PHP files in libraries. paths: - "src/**/*.php" - "tests/**/*.php" @@ -7,136 +7,447 @@ paths: # Code style -Semantic code rules for all PHP files. Formatting rules (PSR-1, PSR-4, PSR-12, line length) are enforced by `phpcs.xml` -and are not repeated here. Refer to `php-library-modeling.md` for library modeling rules. +Semantic rules for all PHP files in libraries. Formatting rules covered by `PSR-12` are enforced +by `phpcs.xml`. Two formatting rules outside `PSR-12` (no vertical alignment, no trailing comma in +multi-line lists) are documented at the end of this file under "Formatting overrides". Complexity +rules live in `php-library-modeling.md`. Folder structure, public API boundary, and the semantics +of `Internal/` live in `php-library-architecture.md`. ## Pre-output checklist Verify every item before producing any PHP code. If any item fails, revise before outputting. 1. `declare(strict_types=1)` is present. -2. All classes are `final readonly` by default. Use `class` (without `final` or `readonly`) only when the class is - designed as an extension point for consumers (e.g., `Collection`, `ValueObject`). Use `final class` without - `readonly` only when the parent class is not readonly (e.g., extending a third-party abstract class). -3. All parameters, return types, and properties have explicit types. -4. Constructor property promotion is used. -5. Named arguments are used at call sites for own code, tests, and third-party library methods (e.g., tiny-blocks). - Never use named arguments on native PHP functions (`array_map`, `in_array`, `preg_match`, `is_null`, - `iterator_to_array`, `sprintf`, `implode`, etc.) or PHPUnit assertions (`assertEquals`, `assertSame`, - `assertTrue`, `expectException`, etc.). -6. No `else` or `else if` exists anywhere. Use early returns, polymorphism, or map dispatch instead. -7. No abbreviations appear in identifiers. Use `$index` instead of `$i`, `$account` instead of `$acc`. -8. No generic identifiers exist. Use domain-specific names instead: - `$data` → `$payload`, `$value` → `$totalAmount`, `$item` → `$element`, - `$info` → `$currencyDetails`, `$result` → `$conversionOutcome`. -9. No raw arrays exist where a typed collection or value object is available. Use the `tiny-blocks/collection` - fluent API (`Collection`, `Collectible`) when data is `Collectible`. Use `createLazyFrom` when elements are - consumed once. Raw arrays are acceptable only for primitive configuration data, variadic pass-through, and - interop at system boundaries. See "Collection usage" below for the full rule and example. -10. No private methods exist except private constructors for factory patterns. Inline trivial logic at the call site - or extract it to a collaborator or value object. -11. Members are ordered: constants first, then constructor, then static methods, then instance methods. Within each - group, order by body size ascending (number of lines between `{` and `}`). Constants and enum cases, which have - no body, are ordered by name length ascending. -12. Constructor parameters are ordered by parameter name length ascending (count the name only, without `$` or type), - except when parameters have an implicit semantic order (e.g., `$start/$end`, `$from/$to`, `$startAt/$endAt`), - which takes precedence. Parameters with default values go last, regardless of name length. The same rule - applies to named arguments at call sites. - Example: `$id` (2) → `$value` (5) → `$status` (6) → `$precision` (9). -13. Time and space complexity are first-class design concerns. - - No `O(N²)` or worse time complexity exists unless the problem inherently requires it and the cost is - documented in PHPDoc on the interface method. - - Space complexity is kept minimal: prefer lazy/streaming pipelines (`createLazyFrom`) over materializing - intermediate collections. - - Never re-iterate the same source; fuse stages when possible. - - Public interface methods document time and space complexity in Big O form (see "PHPDoc" section). +2. All parameters, return types, and properties have explicit types. +3. Constructor property promotion is used. +4. Named arguments are used at call sites for own code, tests, and third-party library methods + (for example, tiny-blocks). Never use named arguments on: + - Native PHP functions (`array_map`, `in_array`, `preg_match`, `is_null`, + `iterator_to_array`, `sprintf`, `implode`, and similar). + - Native PHP enum methods (`from`, `tryFrom`, `cases`). + - PHPUnit assertions and expectations (`assertEquals`, `assertSame`, `assertTrue`, + `expectException`, and similar). + - Interfaces from PHP-FIG PSR standards (PSR-7 `withHeader`, PSR-18 `sendRequest`, etc.). + The PSR contract does not include parameter names. Implementations may rename parameters. + - Calls that include variadic spread (`...$args`). PHP rejects positional argument unpacking + after named arguments. When the caller passes through a `...$variadic`, all arguments are + positional. New own-code APIs should prefer a typed collection parameter over a variadic + so named-argument call sites remain possible. + + Native PHP **class constructors** (`parent::__construct` calls to `\Exception`, + `\RuntimeException`, `\InvalidArgumentException`, `\LogicException`, and similar) are not + in the list above. They accept named arguments, and rule 8 requires using them whenever + the positional call would pass an argument whose value equals the parameter's default. + Example: `parent::__construct(message: sprintf(...), previous: $previous)` instead of + `parent::__construct(sprintf(...), 0, $previous)`. The exclusion above covers native + functions and enum methods, not native class instantiation. +5. Classes follow the rules in "Inheritance and constructors". `final readonly` is the default, + with documented exceptions for extension points and for parents that are not `readonly`. +6. Members are ordered constants first, then constructor, then static methods, then instance + methods. Within each group, order by body size ascending (number of lines between `{` and `}`). + Constants and enum cases, which have no body, are ordered by name length ascending. This + ordering may be overridden only when the alternative carries explicit documentation value: + grouping by domain class with section markers (HTTP status codes by 1xx/2xx/3xx/etc), + mirroring the order of an implemented interface, or similar evident structure. The override + must be obvious at first reading. + + **At call sites** (chained method calls in production code, tests, or documentation + examples), consecutive method invocations on the same receiver are ordered by the **visible + width** of each call expression ascending. The body is not visible at the call site, so the + visible width is the practical proxy for body size. Boolean toggles such as `->secure()` and + `->httpOnly()` come before parameterized `with*` builders for the same reason. When two + calls have equal width, order them alphabetically by method name. + + **Terminal methods that change the receiver type** stay at the end of the chain regardless + of width. A `build()` that returns the built value, a `commit()` that finalizes a unit of + work, a `send()` that flushes a request, are terminal: the chain ends with them. The + ordering rule applies only to consecutive calls on the same receiver type; calls that + transition to a different type are not reorderable. The same applies in reverse to the + factory or accessor that starts the chain (`Cookie::create(...)`, `$repository`) — it stays + at its position. +7. Constructor parameters are ordered by parameter name length ascending (count the name only, + without `$` or type), except when parameters have an implicit semantic order (for example, + `$start/$end`, `$from/$to`, `$startAt/$endAt`), which takes precedence. Parameters with default + values go last, regardless of name length. The same rule applies to named arguments at call + sites. Example order: `$id` (2), `$value` (5), `$status` (6), `$precision` (9). +8. Never pass an argument whose value equals the parameter's default. Omit the argument entirely. + Example with `toArray(KeyPreservation $keyPreservation = KeyPreservation::PRESERVE)`. The call + `$collection->toArray(keyPreservation: KeyPreservation::PRESERVE)` becomes + `$collection->toArray()`. Only pass the argument when the value differs from the default. +9. No `else` or `else if` exists anywhere. Use early returns, polymorphism, or map dispatch instead. +10. No abbreviations appear in identifiers. Use `$index` instead of `$i`, `$account` instead of + `$acc`. +11. No generic identifiers exist. Use domain-specific names instead. Examples are `$data` to + `$payload`, `$value` to `$totalAmount`, `$item` to `$element`, `$info` to `$currencyDetails`, + `$result` to `$conversionOutcome`. +12. No raw arrays exist where a typed collection or value object is available. When data is + `Collectible`, use the `tiny-blocks/collection` fluent API (`Collection`, `Collectible`). Use + `createLazyFrom` when elements are consumed once. Raw arrays are acceptable only for primitive + configuration data, variadic pass-through, and interop at system boundaries. See "Collection + usage" for the full rule and example. +13. No private methods exist except for private constructors in factory patterns, methods inside + `src/Internal/` (implementation detail by definition, where the namespace is the abstraction + boundary), and `setUp` or `tearDown` overrides in PHPUnit test classes. Outside these cases, + inline trivial logic at the call site or extract it to a collaborator or value object. 14. No logic is duplicated across two or more places (DRY). 15. No abstraction exists without real duplication or isolation need (KISS). -16. All identifiers, comments, and documentation are written in American English. -17. No justification comments exist (`// NOTE:`, `// REASON:`, etc.). Code speaks for itself. -18. `// TODO: ` is used when implementation is unknown, uncertain, or intentionally deferred. - Never leave silent gaps. -19. All class references use `use` imports at the top of the file. Fully qualified names inline are prohibited. -20. No dead or unused code exists. Remove unreferenced classes, methods, constants, and imports. -21. Never create public methods, constants, or classes in `src/` solely to serve tests. If production code does not - need it, it does not exist. -22. Always use the most current and clean syntax available in the target PHP version. Prefer match to switch, - first-class callables over `Closure::fromCallable()`, readonly promotion over manual assignment, enum methods - over external switch/if chains, named arguments over positional ambiguity (except where excluded by rule 5), - and `Collection::map` over foreach accumulation. -23. No vertical alignment of types in parameter lists or property declarations. Use a single space between - type and variable name. Never pad with extra spaces to align columns: - `public OrderId $id` — not `public OrderId $id`. -24. Opening brace `{` follows PSR-12: on a **new line** for classes, interfaces, traits, enums, and methods - (including constructors); on the **same line** for closures and control structures (`if`, `for`, `foreach`, - `while`, `switch`, `match`, `try`). -25. Never pass an argument whose value equals the parameter's default. Omit the argument entirely. - Example — `toArray(KeyPreservation $keyPreservation = KeyPreservation::PRESERVE)`: - `$collection->toArray(keyPreservation: KeyPreservation::PRESERVE)` → `$collection->toArray()`. - Only pass the argument when the value differs from the default. -26. No trailing comma in any multi-line list. This applies to parameter lists (constructors, methods, - closures), argument lists at call sites, array literals, match arms, and any other comma-separated - multi-line structure. The last element never has a comma after it. PHP accepts trailing commas in - parameter lists, but this project prohibits them for visual consistency. - Example — correct: - ``` - new Precision( - value: 2, - rounding: RoundingMode::HALF_UP - ); - ``` - Example — prohibited: - ``` - new Precision( - value: 2, - rounding: RoundingMode::HALF_UP, - ); - ``` +16. No inline comments exist in `src/` or `tests/`, except `# TODO: ` when implementation + is unknown, uncertain, or intentionally deferred. Code is the documentation. Block comments + (`/* */`) never appear outside docblocks (`/** */`). The `#` style for inline PHP comments + applies only to code examples inside Markdown files (see `php-library-documentation.md`). +17. No dead or unused code exists. Remove unreferenced classes, methods, constants, and imports. +18. Never create public methods, constants, or classes in `src/` solely to serve tests. If + production code does not need it, it does not exist. +19. Format strings with placeholders (`%s`, `%d`, `%f`, etc.) are assigned to a `$template` + variable before being passed to `sprintf`. The variable assignment and the `sprintf` call live + on separate statements. See "Format strings" for examples. +20. All class references use `use` imports at the top of the file. Fully qualified names inline are + prohibited. +21. Return types and `new` calls use the explicit class name. `self` is prohibited as a type, + as a return type, and in `new self()` instantiation. Constant access via `self::CONST_NAME` + is permitted. `static` is permitted only inside extension-point classes (declared `class` + without `final readonly`) and inside traits, where late static binding lets subclasses or + consuming classes instantiate the correct concrete type. In every other context, use the + class name. +22. Always use the most current and clean syntax available in the target PHP version. Prefer + `match` over `switch`, first-class callables over `Closure::fromCallable()`, readonly promotion + over manual assignment, enum methods over external switch or if chains, named arguments over + positional ambiguity (except where excluded by rule 4), `Collection::map` over foreach + accumulation, and **unparenthesized constructor chaining** (PHP 8.4+): + `new Foo()->bar()` instead of `(new Foo())->bar()`. The parentheses around the `new` + expression are no longer required and add visual noise. +23. All identifiers, comments, and documentation use American English. See "American English" for + the spelling list. -## Casing conventions +## Naming -- Internal code (variables, methods, classes): **`camelCase`**. -- Constants and enum-backed values when representing codes: **`SCREAMING_SNAKE_CASE`**. +- Internal code (variables, methods, classes) uses `camelCase`. +- Constants and enum-backed values when representing codes use `SCREAMING_SNAKE_CASE`. +- Names describe what in domain terms, not how technically. `$monthlyRevenue` instead of + `$calculatedValue`. Generic technical verbs are avoided. See `php-library-modeling.md` for the + full banlist of generic and anemic names. +- Booleans use predicate form. Examples are `isActive`, `hasPermission`, `wasProcessed`. +- Collections are always plural. Examples are `$orders`, `$lines`. +- Methods returning `bool` use prefixes `is`, `has`, `can`, `was`, `should`. -## Naming +## Class self-references + +Type declarations, return types, and `new` calls inside a class use the explicit class name. +The class name is unambiguous, survives refactors that move the method to a different class, +and reads identically inside the class body and at the call site. + +- `self` is prohibited everywhere as a type, as a return type, and in `new self()` + instantiation. Constant access via `self::CONST_NAME` is **permitted**. The prohibition + covers the forms that carry refactoring ambiguity when a method moves to a different class + (the type-or-instantiation forms). Constant access does not have that ambiguity because the + constant is declared in the same class body. +- `static` is permitted only inside extension-point classes (declared `class` without + `final readonly`) and inside traits, where late static binding is required for subclasses or + consuming classes to instantiate the correct concrete type. +- In every other context (the default `final readonly class`, factory methods, return types), + use the class name. + +**Prohibited.** `self` as return type and `new self()` inside a final class: + +```php +final readonly class UserAgent +{ + public static function from(string $product): self + { + return new self(product: $product); + } +} +``` + +**Correct.** Explicit class name in a final class: + +```php +final readonly class UserAgent +{ + public static function from(string $product): UserAgent + { + return new UserAgent(product: $product); + } +} +``` -- Names describe **what** in domain terms, not **how** technically: `$monthlyRevenue` instead of `$calculatedValue`. -- Generic technical verbs are avoided. See `php-library-modeling.md` — Nomenclature. -- Booleans use predicate form: `isActive`, `hasPermission`, `wasProcessed`. -- Collections are always plural: `$orders`, `$lines`. -- Methods returning bool use prefixes: `is`, `has`, `can`, `was`, `should`. +**Correct.** `static` permitted in an extension-point class: + +```php +class Collection +{ + public static function createFrom(iterable $elements): static + { + return new static(elements: $elements); + } +} +``` + +## Inheritance and constructors + +- All classes are `final readonly` by default. +- Use `class` (without `final` or `readonly`) only when the class is designed as an extension point + for consumers, for example `Collection` or `ValueObject`. +- Use `final class` without `readonly` only when the parent class is not readonly, for example + when extending a third-party abstract class. +- Use `final class` without `readonly` is also permitted for `src/Internal/` collaborators that + carry intrinsically mutable state (resource handles, counters, cursors) where the mutation is + central to the class's responsibility (`Stream` closing a resource, `Cursor` advancing a + position). The class must remain confined to `src/Internal/`. +- Use `final class` without `readonly` for classes that consist exclusively of `static` methods + (no instance properties, no instance methods, only static factories or utilities). Pair it + with `private function __construct() {}` to prevent instantiation. `readonly` is meaningless + without instance state, and the private constructor signals that the class is a static + surface, not a value type. +- Inheritance between concrete classes is prohibited. Every concrete class is `final`. +- Polymorphism uses interfaces plus composition, never extension of concrete types. +- The only allowed `extends` is against framework or SPL base classes that the language requires. + Examples are `RuntimeException`, `LogicException`, `PHPUnit\Framework\TestCase`. +- Constructors of `final` classes are `private` when paired with named factory methods, `public` + otherwise. `protected` constructors are prohibited because no subclasses exist to call them. ## Comparisons -1. Null checks: use `is_null($variable)`, never `$variable === null`. -2. Empty string checks on typed `string` parameters: use `$variable === ''`. Avoid `empty()` on typed strings - because `empty('0')` returns `true`. -3. Mixed or untyped checks (value may be `null`, empty string, `0`, or `false`): use `empty($variable)`. +1. Null checks use `is_null($variable)`, never `$variable === null`. +2. Empty string checks on typed `string` parameters use `$variable === ''`. Avoid `empty()` on + typed strings because `empty('0')` returns `true`. +3. Mixed or untyped checks (value may be `null`, empty string, `0`, or `false`) use + `empty($variable)`. ## American English -All identifiers, enum values, comments, and error codes use American English spelling: -`canceled` (not `cancelled`), `organization` (not `organisation`), `initialize` (not `initialise`), -`behavior` (not `behaviour`), `modeling` (not `modelling`), `labeled` (not `labelled`), -`fulfill` (not `fulfil`), `color` (not `colour`). +All identifiers, enum values, comments, and error codes use American English spelling. Examples +are `canceled` (not `cancelled`), `organization` (not `organisation`), `initialize` (not +`initialise`), `behavior` (not `behaviour`), `modeling` (not `modelling`), `labeled` (not +`labelled`), `fulfill` (not `fulfil`), `color` (not `colour`). ## PHPDoc -- PHPDoc is restricted to interfaces only, documenting obligations, `@throws`, and complexity. -- Never add PHPDoc to concrete classes. +### When required + +- Every method of an interface, **including interfaces declared inside `src/Internal/`**. + Interfaces define contracts. The contract is documentation by definition, regardless of + namespace. The `Internal/` boundary applies to implementations, not to the contracts that + internal collaborators expose to each other. +- Every public method of a concrete class outside `src/Internal/`. Public classes are at the + public API boundary by definition. Consumers call every public method directly, and the + PHPDoc is the contract for each call. Trivial getters and `with*` methods are not exempt. + The only exception is a public method whose contract is already documented on an implemented + interface (the interface carries the docblock). + +### When prohibited + +- Constructors. The constructor signature with property promotion is self-documenting. Parameter + types are already explicit in the signature. +- Private and protected methods. +- Public methods of concrete classes whose contract is already documented on an implemented + interface. The interface carries the docblock. +- Anything inside `src/Internal/`. Internal types are implementation detail and must not carry + PHPDoc. The namespace itself is the boundary. See `php-library-architecture.md` for the + architectural meaning of `Internal/`. **Exception**: interfaces and their methods. An + interface declared inside `src/Internal/` still defines a contract, and the contract is + documented per `### When required` regardless of namespace. The prohibition covers concrete + classes, traits, enums, and anonymous classes inside `Internal/`, never interfaces. +- Anywhere inside `tests/`. Test methods name the scenario via the `testXxxWhenYyyGivenThenZzz` + naming convention, and the `@Given`/`@When`/`@Then`/`@And` annotation blocks defined in + `php-library-testing.md` describe the steps. PHPDoc documentation (summary plus + `@param`/`@return` descriptions) is prohibited on test methods, data providers, fixtures, + setUp/tearDown overrides, and anonymous classes inside tests. The BDD annotations are not + PHPDoc documentation in the sense of this section and remain required per the testing rule. +- Single-line PHPDocs with only a tag (`/** @param ... */`, `/** @return ... */`, + `/** @throws ... */`). PHPDoc always opens with a summary line. Bare-tag docblocks are + prohibited regardless of how few tags they carry. + +The prohibitions above apply to **every form of PHPDoc** in the prohibited scope: +method-level docblocks, property-level docblocks, inline `@var` annotations on local variables, +and PHPDoc blocks placed above anonymous functions or closures inside method bodies. Inside +`src/Internal/` and `tests/`, zero PHPDoc is the rule with no exception. PHPStan errors that +result from the missing annotations route through `ignoreErrors` (see below). + +The PHPDoc prohibitions above take priority over the typed-array case. When PHPStan at +`level: max` flags a missing iterable value type (`missingType.iterableValue`, +`argument.type`, `return.type`): + +- On a **constructor parameter** → suppress via `ignoreErrors` in `phpstan.neon.dist`. Do not + add PHPDoc. +- On anything inside **`src/Internal/`** (concrete classes, traits, enums) → suppress via + `ignoreErrors`. Do not add PHPDoc. Interfaces inside `src/Internal/` are the exception: + they carry PHPDoc per `### When required`, and the PHPStan errors they raise are resolved + through the PHPDoc, never through `ignoreErrors`. +- On anything inside **`tests/`** → suppress via `ignoreErrors`. Do not add PHPDoc. +- On a **public method of a public (non-Internal) class** → add full PHPDoc with summary, + `@param` descriptions, and the typed-array information. The bare-tag form remains + prohibited. This is the normal case where PHPDoc is permitted by "When required" above. + +The summary requirement and the bare-tag prohibition are never waived. Use `ignoreErrors` only +when the context (constructor, `src/Internal/`, `tests/`) makes PHPDoc impossible. Every public +method of a public concrete class carries PHPDoc per "When required", whether the method +has typed-array parameters. + +### Style + +- Summary on the first line, in domain terms. **Mandatory.** PHPDoc without a summary line is + prohibited, even when it carries a single `@param` or `@return`. +- Optional detailed body in `

` paragraphs below the summary. +- Tags use the form `@param Type $name Description.`, `@return Type Description.`, + `@throws ExceptionClass If .`. - Document `@throws` for every exception the method may raise. -- Document time and space complexity in Big O form. When a method participates in a fused pipeline (e.g., collection - pipelines), express cost as a two-part form: call-site cost + fused-pass contribution. Include a legend defining - variables (e.g., `N` for input size, `K` for number of stages). +- HTML tags allowed inside descriptions are `

` for paragraphs, `

  • ` for lists, + `` for inline code, `` and `` for emphasis. + +### Summary patterns + +The summary line is not a creative intent statement. It is a template selected by the method's +name prefix. Apply the matching template. Only methods with no matching prefix require a +free-form one-line summary in domain terms. + +| Method shape | Template | +|-------------------------------------------------------------------------|--------------------------------------------------------------------------------| +| Static factory (`create`, `from`, `fromX`, `with*` when static) | `Creates a {ClassName} from {input}.` or `Builds a {ClassName} with {fields}.` | +| `with*` instance method | `Returns a copy of the {ClassName} with the {field} replaced.` | +| Getter (no prefix, returns a property: `code()`, `body()`, `headers()`) | `Returns the {field}.` | +| Predicate (`is*`, `has*`, `can*`, `was*`, `should*`) | `Tells whether {condition}.` | +| Converter (`toArray`, `toString`, `asX`) | `Returns the {ClassName} as {target shape}.` | +| `apply*`, `merge*`, `add*`, and other side-effect-free operations | One-line summary in domain terms describing the operation. | + +The patterns are mandatory when applicable. They make summary lines mechanical: substitute +`{ClassName}` and `{field}` and the summary is complete. No per-method intent decision is +required. Volume is never a reason to skip the summary. Many methods just mean applying the +template many times. + +### Cross-references + +- `{@see ClassName}` for links to other types in the codebase. +- `@see Author, Title (Publisher, Year), Chapter X.` for bibliographical references. + +### Examples + +**Prohibited.** Single-line bare-tag PHPDoc, no summary: + +```php +/** @param array|null $body */ +public static function with(Code $code, ?array $body = null): Response +``` + +**Prohibited.** PHPDoc on a constructor: + +```php +/** @param array $entries */ +public function __construct(public array $entries) +{ +} +``` + +**Prohibited.** PHPDoc on a **concrete class** inside `src/Internal/` (the prohibition does +not extend to interfaces; see "Correct" below for an Internal/ interface): + +```php +namespace TinyBlocks\Http\Internal\Client; + +final readonly class Url +{ + /** @param array|null $query */ + public static function compose(string $path, ?array $query, string $baseUrl): string + { + } +} +``` + +**Correct.** Interface declared **inside `src/Internal/`** still carries PHPDoc on every +method. The Internal/ prohibition covers concrete classes; interfaces are exempt because they +are the contract: + +```php +namespace TinyBlocks\Http\Internal\Client; + +interface RequestResolver +{ + /** + * Resolves the given URL against the configured base URL. + * + * @param string $url The path or absolute URL to resolve. + * @return string The absolute URL to dispatch. + * @throws MalformedPath If the URL violates RFC 3986. + */ + public function resolve(string $url): string; +} +``` + +**Correct.** Generic array type with summary and `@param` description: + +```php +/** + * Builds a synthesized response from a status code and an optional body. + * + * @param array|null $body The response body as an associative array. + * @return Response The synthesized response instance. + */ +public static function with(Code $code, ?array $body = null): Response +``` + +**Correct.** Interface with rich description, paragraphs, cross-references, and bibliography: + +```php +/** + * Money tied to a specific currency. + * + *

    Operations between different currencies raise CurrencyMismatch. Arithmetic + * preserves the currency.

    + * + *

    Sibling of {@see Quantity}, not a parent. Money carries currency semantics.

    + * + * @see Eric Evans, Domain-Driven Design (Addison-Wesley, 2003), Chapter 5. + */ +interface Money +{ + /** + * Adds the given amount. + * + * @param Money $other The amount to add. + * @return Money A new instance with the summed amount. + * @throws CurrencyMismatch If $other has a different currency. + */ + public function add(Money $other): Money; +} +``` + +**Correct.** Concrete class with a short summary and direct tags: + +```php +/** + * IANA timezone identifier (e.g. America/Sao_Paulo). + */ +final readonly class Timezone +{ + /** + * Creates a Timezone from a valid IANA identifier. + * + * @param string $identifier The IANA timezone identifier. + * @return Timezone The created instance. + * @throws InvalidTimezone If the identifier is not a valid IANA timezone. + */ + public static function from(string $identifier): Timezone + { + # ... + } +} +``` + +## Dependencies + +When the library needs an external dependency, prefer packages from the `tiny-blocks` ecosystem +(https://github.com/tiny-blocks) whenever a suitable option exists. Reach for outside packages +only when the ecosystem has no equivalent that fits the use case. ## Collection usage -When a property or parameter is `Collectible`, use its fluent API. Never break out to raw array functions such as -`array_map`, `array_filter`, `iterator_to_array`, or `foreach` + accumulation. The same applies to `filter()`, -`reduce()`, `each()`, and all other `Collectible` operations. Chain them fluently. Never materialize with -`iterator_to_array` to then pass into a raw `array_*` function. +When a property or parameter is `Collectible`, use its fluent API. Never break out to raw array +functions such as `array_map`, `array_filter`, `iterator_to_array`, or `foreach` plus accumulation. +The same applies to `filter()`, `reduce()`, `each()`, and every other `Collectible` operation. +Chain them fluently. Never materialize with `iterator_to_array` to then pass into a raw `array_*` +function. -**Prohibited — `array_map` + `iterator_to_array` on a Collectible:** +**Prohibited.** `array_map` plus `iterator_to_array` on a `Collectible`: ```php $names = array_map( @@ -145,10 +456,161 @@ $names = array_map( ); ``` -**Correct — fluent chain with `map()` + `toArray()`:** +**Correct.** Fluent chain with `map()` plus `toArray()`: ```php $names = $collection ->map(transformations: static fn(Element $element): string => $element->name()) ->toArray(keyPreservation: KeyPreservation::DISCARD); ``` + +## Format strings + +When building a message with placeholders, assign the format string to a `$template` variable +first. Pass it to `sprintf` on a separate statement. The format and the data are visually +separated, and the template line stays scannable. + +**Prohibited.** Format string inline with the call: + +```php +if ($value < 0 || $value > 16) { + throw new PrecisionOutOfRange( + message: sprintf('Precision must be between 0 and 16, got %d.', $value) + ); +} +``` + +**Correct.** Format string in a `$template` variable: + +```php +if ($value < 0 || $value > 16) { + $template = 'Precision must be between 0 and 16, got %d.'; + + throw new PrecisionOutOfRange(message: sprintf($template, $value)); +} +``` + +## Constructor chaining + +PHP 8.4 allows chained method calls directly on a `new` expression without wrapping it in +parentheses. The parentheses are no longer required and only add visual noise. Apply this +everywhere a `new` is followed by a method call. + +**Prohibited.** Parentheses around the `new` expression: + +```php +$body = (new ServerRequest(method: 'GET', uri: 'https://api.example.com')) + ->withHeader('Accept', 'application/json') + ->getBody(); +``` + +**Correct.** No parentheses: + +```php +$body = new ServerRequest(method: 'GET', uri: 'https://api.example.com') + ->withHeader('Accept', 'application/json') + ->getBody(); +``` + +## Formatting overrides + +Three formatting rules are not covered by the canonical `phpcs.xml` (which references `PSR-12` +only). Apply them manually. + +### No vertical alignment in parameter lists + +Use a single space between the type and the variable name in parameter lists (constructors, +function signatures, closures). Never pad with extra spaces to align columns. This rule applies +only to parameter lists, not to other contexts that use `=>` alignment (see "Vertical alignment +of `=>`" below). + +**Prohibited.** Vertical alignment of types: + +```php +public function __construct( + public OrderId $id, + public Money $total, + public Customer $customer, + public Precision $precision +) {} +``` + +**Correct.** Single space between type and variable: + +```php +public function __construct( + public OrderId $id, + public Money $total, + public Customer $customer, + public Precision $precision +) {} +``` + +### Vertical alignment of `=>` in match arms and array literals + +Multi-line `match` expressions and multi-line array literals with `=>` align the `=>` column +across all arms or entries by padding shorter left-hand sides with spaces. Single-line cases +(one-arm match, single-line array) keep the standard PSR-12 single-space form. + +**Prohibited.** Unaligned `=>` in match: + +```php +return match ($this) { + self::MAX_AGE => sprintf($template, $this->value, $value), + default => $this->value +}; +``` + +**Correct.** Aligned `=>` in match: + +```php +return match ($this) { + self::MAX_AGE => sprintf($template, $this->value, $value), + default => $this->value +}; +``` + +**Prohibited.** Unaligned `=>` in array literal: + +```php +return [ + 'name' => 'Gustavo', + 'role' => 'developer', + 'company' => 'Anthropic' +]; +``` + +**Correct.** Aligned `=>` in array literal: + +```php +return [ + 'name' => 'Gustavo', + 'role' => 'developer', + 'company' => 'Anthropic' +]; +``` + +### No trailing comma in multi-line lists + +Never place a trailing comma after the last element of any multi-line list. Applies to parameter +lists, argument lists, array literals, match arms, and every other comma-separated multi-line +structure. PHP accepts trailing commas in these positions, but this ecosystem prohibits them for +visual consistency. + +**Prohibited.** Trailing comma after the last argument: + +```php +new Precision( + value: 2, + rounding: RoundingMode::HALF_UP, +); +``` + +**Correct.** No trailing comma: + +```php +new Precision( + value: 2, + rounding: RoundingMode::HALF_UP +); +``` diff --git a/.claude/rules/php-library-commits.md b/.claude/rules/php-library-commits.md new file mode 100644 index 0000000..feefcf5 --- /dev/null +++ b/.claude/rules/php-library-commits.md @@ -0,0 +1,111 @@ +--- +description: Conventional Commits format. Applied on request when generating commit messages. +--- + +# Commits + +Applied only when generating commit messages, never automatically. All commit messages are +written in English. + +## Format + +`: ` + +The description starts with a capital letter, uses imperative present tense ("Add", "Fix", +"Change", not "Added", "Adds", or "Adding"), and ends with a period. Subject under 300 +characters. If it does not fit, split the change into multiple commits or move detail into the +body. + +Scopes are prohibited. `feat(orders): ...` is wrong. The type stands alone. + +## Allowed types + +Each entry below is a bullet that starts with a capital letter and ends with a period. This is +the canonical example of bullet punctuation enforced everywhere in this document. + +- `ci` for CI configuration changes. +- `fix` for a bug fix. +- `feat` for a user-facing feature. +- `docs` for documentation only. +- `test` for adding or correcting tests. +- `chore` for maintenance with no production code change. +- `build` for build or dependency changes. +- `revert` for reverting a previous commit. +- `refactor` for a code change that neither fixes a bug nor adds a feature. + +`style` is not used. Formatting is enforced by the linter and never appears as a standalone +commit. + +## Subject examples + +Good: + +- `fix: Handle zero-amount transactions.` +- `feat: Add order cancellation endpoint.` +- `refactor: Extract OrderStatus into its own enum.` + +Bad: + +- `Added order cancellation` is past tense, missing type, missing period. +- `feat: Adds order cancellation.` is third-person singular instead of imperative. +- `feat: added order cancellation.` starts lowercase and is past tense. +- `feat: Add cancellation, and fix billing rounding.` bundles two changes. Split. +- `feat(orders): Add cancellation.` uses a scope. Prohibited. + +## Body + +The body is **optional and rarely needed**. Single-purpose commits never have a body. Add a body +ONLY when the reason cannot be inferred from the diff (a non-obvious trade-off, a workaround for +an external bug, a decision worth recording). + +Separate the body from the subject with a blank line. Wrap at 72 characters per line. Explain +why, not what. The diff already shows what. + +## Prose vs. bullets in the body + +**Default to prose.** One or two paragraphs fits almost every commit that has a body at all. + +**Use bullets only when ALL of these are true:** + +1. The commit covers 3 or more independent changes that genuinely belong in the same commit. +2. The list cannot be expressed as continuous prose without becoming disconnected sentences. +3. Each item is independently meaningful (no sub-bullets, no continuation across bullets). + +A two-item bullet list is the wrong shape. Use prose. + +## Bullet formatting (when used) + +Every bullet starts with a capital letter and ends with a period. Imperative verb in present +tense, same as the subject line. Without exception. + +Wrong (do NOT generate): + +- `add the OrderCancelling port` lowercase, missing period. +- `Add the OrderCancelling port` capital but missing period. +- `Adds the OrderCancelling port.` third-person singular instead of imperative. + +## Body example with bullets + +``` +feat: Add order cancellation flow. + +- Add the OrderCancelling inbound port and OrderCancellingHandler. +- Add the CancelOrder command and its validator. +- Cover the cancellation path in the integration test suite. +``` + +## Body example with prose (preferred for most commits) + +``` +fix: Handle zero-amount transactions. + +The payment gateway rejects zero-amount charges with a generic 400 instead +of a documented error code, so the adapter short-circuits before the HTTP +call and raises ZeroAmountNotAllowed directly. +``` + +## Commit splitting + +Prefer one logical change per commit. Refactor commits never modify behavior. When a task +requires multiple types of change, produce multiple commits in order: `refactor` first, then +`feat` or `fix` on top. diff --git a/.claude/rules/php-library-documentation.md b/.claude/rules/php-library-documentation.md index d7ac6da..b7e0da4 100644 --- a/.claude/rules/php-library-documentation.md +++ b/.claude/rules/php-library-documentation.md @@ -1,40 +1,313 @@ --- -description: Standards for README files and all project documentation in PHP libraries. +description: Standards for README and other public-facing Markdown docs in PHP libraries. paths: - "**/*.md" --- # Documentation +Standards for `README.md` and other public-facing Markdown files in the repository. PHPDoc rules +for `.php` files live in `php-library-code-style.md`. American English applies everywhere (see +the American English section in `php-library-code-style.md`). + +The `CONTRIBUTING.md` file is centralized at +`https://github.com/tiny-blocks/tiny-blocks/blob/main/CONTRIBUTING.md`. Each library's README and +pull request template link to that location. No local `CONTRIBUTING.md` is created per library. + +## Pre-output checklist + +Verify every item before producing any Markdown documentation. If any item fails, revise before +outputting. + +1. README title is `# ` with spaces between words (`# Building Blocks`, not + `# BuildingBlocks`). +2. License badge is the only badge. No build, coverage, Packagist, or version badges. +3. Header is followed by an anchor-linked table of contents. +4. Table of contents uses `*` for top-level (H2) entries, `+` indented by 4 spaces for + second-level (H3) entries, and `-` indented by 8 spaces for third-level (H4) entries. Every + heading from the document appears in the TOC, except FAQ entries: the FAQ is represented by + a single `* [FAQ](#faq)` line regardless of how many questions it contains. +5. Sections appear in the canonical order: Overview, Installation, How to use, FAQ (optional), + License, Contributing. +6. FAQ exists only when there are genuine points of confusion or unusual design decisions. Skip + it entirely when not needed. +7. **Self-contained code examples** are blocks that include any of: a `use` statement, a + `class`/`enum`/`interface`/`trait`/`function` declaration, or more than 3 lines of + executable code. Self-contained blocks open with `?` with zero-padded numbering + (`### 01.`, `### 02.`). +12. FAQ bibliographic citations use the format + `> Author, *Title* (Publisher, Year), Chapter X, "Section Name".` +13. License and Contributing sections each follow the canonical one-line template. +14. Repository includes `SECURITY.md`, `.github/ISSUE_TEMPLATE/bug_report.md`, + `.github/ISSUE_TEMPLATE/feature_request.md`, and `.github/PULL_REQUEST_TEMPLATE.md`, each + matching the canonical template in "Other documentation files". + ## README -1. Include an anchor-linked table of contents. -2. Start with a concise one-line description of what the library does. -3. Include a **badges** section (license, build status, coverage, latest version, PHP version). -4. Provide an **Overview** section explaining the problem the library solves and its design philosophy. -5. **Installation** section: Composer command (`composer require vendor/package`). -6. **How to use** section: complete, runnable code examples covering the primary use cases. Each example - includes a brief heading describing what it demonstrates. -7. If the library exposes multiple entry points, strategies, or container types, document each with its own - subsection and example. -8. **FAQ** section: include entries for common pitfalls, non-obvious behaviors, or design decisions that users - frequently ask about. Each entry is a numbered question as heading (e.g., `### 01. Why does X happen?`) - followed by a concise explanation. Only include entries that address real confusion points. -9. **License** and **Contributing** sections at the end. -10. Write strictly in American English. See `php-library-code-style.md` American English section for spelling - conventions. +### Structure + +The README follows a fixed section order: + +1. **Overview**. One or more paragraphs explaining the problem the library solves and its design + philosophy. Cross-references to related `tiny-blocks` libraries belong here. +2. **Installation**. Composer command in a code block, with no surrounding prose unless strictly + necessary. +3. **How to use**. Runnable examples covering the primary use cases. Each subsection demonstrates + one capability with a heading and a self-contained code block. +4. **FAQ** (optional). Numbered questions that address real points of confusion or unusual design + decisions. +5. **License**. One-line link to the `LICENSE` file. +6. **Contributing**. One-line link to the centralized `CONTRIBUTING.md` in + `tiny-blocks/tiny-blocks`. + +### Header and license badge + +The first line is `# ` followed by a blank line and the license badge: + +```markdown +# Outbox + +[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/tiny-blocks//blob/main/LICENSE) +``` + +Replace `` with the library's repository name. The badge is the only badge in the document. + +### Table of contents + +The table of contents is anchor-linked. Top-level (H2) entries use `*`. Second-level (H3) +entries use `+` indented by 4 spaces. Third-level (H4) entries use `-` indented by 8 spaces. +Every heading from the document appears, with one exception: the FAQ is represented by a single +`* [FAQ](#faq)` line. Its questions never appear as TOC sub-entries, regardless of how many +exist. + +```markdown +* [Overview](#overview) +* [Installation](#installation) +* [How to use](#how-to-use) + + [Subtopic A](#subtopic-a) + + [Subtopic B](#subtopic-b) +* [FAQ](#faq) +* [License](#license) +* [Contributing](#contributing) +``` + +Use the third level whenever the document has H4 headings, regardless of whether they form a +two-axis split. The TOC mirrors the document structure exactly. + +```markdown +* [How to use](#how-to-use) + + [Entity](#entity) + - [Single-field identity](#single-field-identity) + - [Compound identity](#compound-identity) + + [Aggregate](#aggregate) +``` + +### Code examples + +Code examples fall into two categories. + +**Self-contained examples** include at least one of: + +- A `use` statement. +- A `class`, `enum`, `interface`, `trait`, or `function` declaration. +- More than 3 lines of executable code. + +They open with `push(records: $order->recordedEvents()); +``` + +**Inline fragment examples** have all of: + +- At most 3 lines of executable code. +- No `use` statements. +- No type declarations. + +Fragments may omit the prologue. + +```php +Code::OK->value; +``` + +The criteria are mechanical: a block that meets any self-contained condition gets the prologue. A block that meets every fragment condition may omit it. There is no middle ground. + +The `#` convention for inline comments applies only to code examples inside Markdown files. PHP +files under `src/` and `tests/` have no inline comments at all, except `# TODO: ` (see +item 16 in `php-library-code-style.md`). + +### FAQ + +FAQ entries are numbered with zero-padded prefixes and end with a question mark: + +```markdown +### 01. Why is DomainEvent close to a marker interface? + +A domain event is a fact about something that happened in the domain. The contract carries only +`revision()` so the library can route schema migrations through upcasters. Everything else +(aggregate identity, sequence number, aggregate type, occurrence timestamp) is envelope metadata +that belongs to `EventRecord`. + +> Vaughn Vernon, *Implementing Domain-Driven Design* (Addison-Wesley, 2013), Chapter 8, +> "Domain Events". +``` + +Bibliographic citations follow the format +`> Author, *Title* (Publisher, Year), Chapter X, "Section Name".` The chapter and section +fragments are optional when the title is precise enough on its own. Multiple citations can be +stacked as separate blockquote lines. + +### License and Contributing + +The License section is a single line: + +```markdown +## License + + is licensed under [MIT](LICENSE). +``` + +The Contributing section is a single line pointing to the centralized guideline: + +```markdown +## Contributing + +Please follow the [contributing guidelines](https://github.com/tiny-blocks/tiny-blocks/blob/main/CONTRIBUTING.md) to +contribute to the project. +``` ## Structured data -1. When documenting constructors, factory methods, or configuration options with more than 3 parameters, - use tables with columns: Parameter, Type, Required, Description. -2. Prefer tables to prose for any structured information. +Tables are preferred to prose for any structured information: constructor parameter lists, +builder method catalogs, default value tables, complexity tables, and configuration matrices. +Column layout is chosen per case. No fixed column set is mandated. + +## Other documentation files + +Every library repository includes the following files in addition to the README. Each follows +the canonical template below. + +### SECURITY.md + +```markdown +# Security Policy + +## Supported versions + +Only the latest release receives security updates. + +## Reporting a vulnerability + +Report security vulnerabilities privately via +[GitHub Security Advisories](https://github.com/tiny-blocks//security/advisories/new). + +Please do not disclose the vulnerability publicly until it has been addressed. +``` + +Replace `` with the repository name. + +### .github/ISSUE_TEMPLATE/bug_report.md + +```markdown +--- +name: Bug report +about: Report a bug to help improve the library +labels: bug +--- + +## Description + +A clear and concise description of the bug. + +## Steps to reproduce + +1. +2. +3. + +## Expected behavior + +What should happen. + +## Actual behavior + +What actually happens. + +## Environment + +- PHP version: +- Library version: +- OS: +``` + +### .github/ISSUE_TEMPLATE/feature_request.md + +```markdown +--- +name: Feature request +about: Suggest a feature for the library +labels: enhancement +--- + +## Problem + +What problem does this feature solve? + +## Proposed solution + +How should the feature work? + +## Alternatives considered + +Other approaches considered. +``` + +### .github/PULL_REQUEST_TEMPLATE.md + +```markdown +> Please follow the [contributing guidelines](https://github.com/tiny-blocks/tiny-blocks/blob/main/CONTRIBUTING.md). + +## Summary + +What this pull request does. + +## Related issue + +Closes #... -## Style +## Checklist -1. Keep language concise and scannable. -2. Never include placeholder content (`TODO`, `TBD`). -3. Code examples must be syntactically correct and self-contained. -4. Code examples include every `use` statement needed to compile. Each example stands alone — copyable into - a fresh file without modification. -5. Do not document `Internal/` classes or private API. Only document what consumers interact with. +- [ ] Tests added or updated. +- [ ] Documentation updated when applicable. +- [ ] `composer review` passes. +- [ ] `composer tests` passes. +``` diff --git a/.claude/rules/php-library-github-workflows.md b/.claude/rules/php-library-github-workflows.md new file mode 100644 index 0000000..396c40a --- /dev/null +++ b/.claude/rules/php-library-github-workflows.md @@ -0,0 +1,287 @@ +--- +description: Structure, ordering, and pinning rules for GitHub Actions workflows in PHP libraries. +paths: + - ".github/workflows/**/*.yml" + - ".github/workflows/**/*.yaml" +--- + +# Workflows + +Conventions for GitHub Actions workflows in PHP libraries. CD does not apply. Libraries publish +to Packagist via tags and never deploy. + +`.github/workflows/ci.yml` is mandatory and follows the canonical structure defined in the +"ci.yml" section below. Additional workflow files (security scanning, automated triage, +scheduled tasks, dependency updates, etc.) may exist and follow the general rules in this file. +Their trigger, job structure, and steps are chosen by their purpose. + +The Composer scripts invoked by `ci.yml` (`composer review`, `composer tests`) are defined in +`php-library-tooling.md`. + +## Pre-output checklist + +Verify every item before producing or editing any workflow YAML. If any item fails, revise +before outputting. + +### Rules for every workflow + +These rules apply to `ci.yml` and to every additional workflow in `.github/workflows/`. + +1. Keys at the workflow root follow the canonical order `name`, `on`, `concurrency`, + `permissions`, `jobs`. Keys absent in a given workflow are simply omitted. The relative order + of the remaining keys is preserved. +2. Properties inside a job follow the canonical order `name`, `needs`, `runs-on`, + `timeout-minutes`, `outputs`, `env`, `steps`. Same omission rule as above. +3. Inside any block (`env`, `outputs`, `with`, `permissions`), entries are ordered by key length + ascending. +4. The workflow `name`, every job `name`, and every step `name` are mandatory and use sentence + case (`Resolve PHP version`, not `RESOLVE_PHP_VERSION` or `resolve_php_version`). Step names + start with a verb. Job keys describe the job's purpose. Generic keys (`run`, `job`, `do`) are + discouraged in favor of descriptive identifiers (`auto-assign`, `analyze`, `notify`). +5. `concurrency` is set at the workflow root with `cancel-in-progress: true` and a `group` + expression scoped by the workflow's trigger: + - `pull_request`: `-${{ github.event.pull_request.number }}`. + - `issues`, or `issues` combined with `pull_request`: + `-${{ github.event.issue.number || github.event.pull_request.number }}`. + - `push`, `schedule`, or both: `-${{ github.ref }}`. + + `` is the workflow's short name (`ci`, `codeql`, `auto-assign`). +6. `permissions` is declared at the workflow root with the minimum scope every job needs. + Job-level `permissions` blocks are allowed only when a specific job needs a narrower scope + than the root, never broader. +7. Every job sets `timeout-minutes`. Defaults: 5 for trivial steps (single API call, lightweight + script), 15 for jobs with PHP setup or test runs, 30 for analysis-heavy jobs (CodeQL, + security scanning). Adjust based on observed runtime when prior runs exist. +8. Every action is pinned to a fixed major version tag written explicitly. Examples are + `actions/checkout@v6` and `shivammathur/setup-php@v2`. Never use `@latest`, `@main`, a branch + name, or a commit SHA. When the existing pin is an explicit minor or patch, derive the major + version while **preserving the prefix style** of the original tag: `@v2.1.0` → `@v2`, + `@2.1.0` → `@2`. The action's tag convention is reflected in the existing pin. Web lookup is + required only when the existing pin is missing, ambiguous, or pointing to a non-version + reference. Example versions cited in this file may be outdated and are not a license to skip + the lookup when it is required. +9. Inline shell logic longer than 3 lines is extracted to a script in `scripts/ci/`. +10. All text (workflow name, job names, step names, comments) uses American English with correct + spelling and punctuation. Sentences and descriptions end with a period. + +### Rules specific to ci.yml + +These rules apply only to `.github/workflows/ci.yml`. Additional workflows are not bound by them. + +1. File path is `.github/workflows/ci.yml`. The workflow `name` field is exactly `CI`. +2. Trigger is `pull_request` only. No `push`, no branch filter, no `workflow_dispatch`. +3. Jobs run in the fixed sequence `resolve-php-version`, `build`, `auto-review`, `tests`. Each + downstream job lists its upstream jobs in `needs`. +4. PHP version is never hardcoded. The `resolve-php-version` job reads `.require.php` from + `composer.json` at runtime and exposes the minor version (for example, `8.5`) as the job + output `php-version`. Downstream jobs reference + `${{ needs.resolve-php-version.outputs.php-version }}` when setting up PHP. +5. The `auto-review` job runs `composer review`. The `tests` job runs `composer tests`. Both + scripts are defined in `composer.json` per `php-library-tooling.md`. No other command is + invoked in either job. +6. The `build` job uploads `vendor/` and `composer.lock` as a single artifact named + `vendor-artifact`. The `auto-review` and `tests` jobs download that artifact instead of + running `composer install` again. +7. The `tests` job is the only job that may extend with extra setup required by the library, + such as service containers, fixture preparation, or environment variables used during + testing. The other three jobs are identical across every library in the ecosystem. +8. `concurrency.group` is `pr-${{ github.event.pull_request.number }}`. `timeout-minutes` is 5 + for `resolve-php-version` and 15 for `build`, `auto-review`, and `tests`. `permissions` is + `contents: read`. + +## ci.yml + +`ci.yml` is the mandatory workflow that gates every pull request. It contains four jobs in the +exact order below. The first three jobs are identical across every library. Only `tests` may +extend with extra setup required by the library. + +### Resolve PHP version + +Reads `.require.php` from `composer.json` and exposes the minor version (for example, `8.5`) as the +output `php-version`. A single step uses `jq` and a short regex to extract the value. Downstream jobs +consume the output to configure their PHP setup. + +### Build + +Sets up PHP using the resolved version, validates `composer.json`, installs dependencies with +`--no-progress --optimize-autoloader --prefer-dist --no-interaction`, and uploads `vendor/` and +`composer.lock` as the artifact `vendor-artifact`. + +### Auto review + +Depends on `resolve-php-version` and `build`. Downloads `vendor-artifact`, sets up PHP, and runs +`composer review`. The `review` script in `composer.json` aggregates lint, static analysis, and style +checks for the library. + +### Tests + +Depends on `resolve-php-version` and `auto-review`. Downloads `vendor-artifact`, sets up PHP, and runs +`composer tests`. Any setup required by the library's tests (service containers, fixture preparation, +environment variables used during testing) lives in this job only. + +## Reference shape + +The YAML below is the canonical minimal form. Every library starts from this exact shape and extends +only the `tests` job when its tests require extra setup. Action versions cited here may be outdated. +Look up the current major version of every action via web search before adopting this shape verbatim. + +### Minimal workflow + +```yaml +name: CI + +on: + pull_request: + +concurrency: + group: pr-${{ github.event.pull_request.number }} + cancel-in-progress: true + +permissions: + contents: read + +jobs: + resolve-php-version: + name: Resolve PHP version + runs-on: ubuntu-latest + timeout-minutes: 5 + outputs: + php-version: ${{ steps.config.outputs.php-version }} + steps: + - name: Checkout + uses: actions/checkout@v6 + + - name: Resolve PHP version from composer.json + id: config + run: | + version=$(jq -r '.require.php' composer.json | grep -oP '\d+\.\d+' | head -1) + echo "php-version=$version" >> "$GITHUB_OUTPUT" + + build: + name: Build + needs: resolve-php-version + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - name: Checkout + uses: actions/checkout@v6 + + - name: Setup PHP + uses: shivammathur/setup-php@v2 + with: + tools: composer:2 + php-version: ${{ needs.resolve-php-version.outputs.php-version }} + + - name: Validate composer.json + run: composer validate --no-interaction + + - name: Install dependencies + run: composer install --no-progress --optimize-autoloader --prefer-dist --no-interaction + + - name: Upload vendor and composer.lock as artifact + uses: actions/upload-artifact@v7 + with: + name: vendor-artifact + path: | + vendor + composer.lock + + auto-review: + name: Auto review + needs: [resolve-php-version, build] + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - name: Checkout + uses: actions/checkout@v6 + + - name: Setup PHP + uses: shivammathur/setup-php@v2 + with: + tools: composer:2 + php-version: ${{ needs.resolve-php-version.outputs.php-version }} + + - name: Download vendor artifact from build + uses: actions/download-artifact@v8 + with: + name: vendor-artifact + path: . + + - name: Run review + run: composer review + + tests: + name: Tests + needs: [resolve-php-version, auto-review] + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - name: Checkout + uses: actions/checkout@v6 + + - name: Setup PHP + uses: shivammathur/setup-php@v2 + with: + tools: composer:2 + php-version: ${{ needs.resolve-php-version.outputs.php-version }} + + - name: Download vendor artifact from build + uses: actions/download-artifact@v8 + with: + name: vendor-artifact + path: . + + - name: Run tests + run: composer tests +``` + +### Extending the tests job + +When the library's tests need external services, env vars, or fixture preparation, the additions live +inside the `tests` job only. The example below shows the same `tests` job extended with a MySQL service +container and the env vars consumed by the test suite. + +```yaml +tests: + name: Tests + needs: [resolve-php-version, auto-review] + runs-on: ubuntu-latest + timeout-minutes: 15 + env: + DB_HOST: 127.0.0.1 + DB_NAME: library_test + DB_PORT: '3306' + DB_USER: library + DB_PASSWORD: library + services: + mysql: + image: mysql:8 + ports: + - 3306:3306 + env: + MYSQL_DATABASE: library_test + MYSQL_ROOT_PASSWORD: library + options: >- + --health-cmd="mysqladmin ping" + --health-interval=10s + --health-timeout=5s + --health-retries=5 + steps: + - name: Checkout + uses: actions/checkout@v6 + + - name: Setup PHP + uses: shivammathur/setup-php@v2 + with: + tools: composer:2 + php-version: ${{ needs.resolve-php-version.outputs.php-version }} + + - name: Download vendor artifact from build + uses: actions/download-artifact@v8 + with: + name: vendor-artifact + path: . + + - name: Run tests + run: composer tests +``` diff --git a/.claude/rules/php-library-modeling.md b/.claude/rules/php-library-modeling.md index bedb733..127413c 100644 --- a/.claude/rules/php-library-modeling.md +++ b/.claude/rules/php-library-modeling.md @@ -1,112 +1,199 @@ --- -description: Library modeling rules — folder structure, public API boundary, naming, value objects, exceptions, enums, extension points, and complexity. +description: Semantic modeling rules for PHP libraries (nomenclature, value objects, exceptions, enums, extension points, complexity). paths: - "src/**/*.php" --- -# Library modeling +# Modeling + +Library modeling rules. How to model the concepts the library exposes. Folder structure and +public API boundary live in `php-library-architecture.md`. Code style lives in +`php-library-code-style.md`. Tooling lives in `php-library-tooling.md`. + +## Pre-output checklist + +Verify every item before producing any PHP code that defines a model, an exception, or an +algorithm. If any item fails, revise before outputting. + +1. Each model has a single, clear responsibility. Apply DDD, SOLID, DRY, and KISS where they + sharpen the design, not as dogma. +2. Concept names. Every class, property, method, and exception name reflects the concept the + library represents, not a technical role. +3. No always-banned names. Never use `Data`, `Info`, `Utils`, `Item`, `Record`, `Entity` as + class suffix, prefix, or method name. Never use `Exception` as a class suffix. Exception: + names that correspond to externally standardized identifiers (HTTP status text from RFC + documents, PSR interface names being mirrored, etc.) are permitted. The standard reference + is the meaning carrier. +4. No anemic verbs as the primary operation name (`ensure`, `validate`, `check`, `verify`, + `assert`, `mark`, `enforce`, `sanitize`, `normalize`, `compute`, `transform`, `parse`) unless + the verb is the library's reason to exist. +5. Architectural role names (`Manager`, `Handler`, `Processor`, `Service`, and their verb forms + `process`, `handle`, `execute`) are allowed only when the class IS that role for consumers + integrating with the library. +6. Value objects are immutable. No setters. Operations return new instances. +7. Value objects compare by value, never by reference. No identity field. +8. Value objects validate invariants in the constructor and throw a dedicated exception on + invalid input. +9. Value objects with multiple creation paths use static factory methods (`from`, `of`, `zero`) + with a private constructor. +10. Every failure throws a dedicated exception class named after the invariant it guards. Never + `throw new DomainException(...)`, `throw new InvalidArgumentException(...)`, or any other + generic native exception directly. +11. Dedicated exception classes extend the appropriate native PHP exception (`DomainException`, + `InvalidArgumentException`, `OverflowException`, etc.). +12. Exceptions are pure. No transport-specific fields (HTTP status in `code`, formatted message + for end-user display). They signal invariant violations only, never control flow. +13. Enums are PHP backed enums. They include methods only when those methods carry vocabulary + meaning. +14. Extension points use `class` instead of `final readonly class`. They expose a private + constructor with static factory methods as the only creation path. Internal state is + injected via the constructor. +15. Algorithms run in O(N) or O(N log N) unless the problem inherently requires worse. O(N²) + or worse needs explicit justification. +16. Prefer lazy or streaming evaluation over materializing intermediate results. Memory usage + is bounded and proportional to the output, not to the sum of intermediate stages. + +## Modeling principles + +Apply the following principles where they sharpen the design. Treat them as guides, not as dogma. + +- Single responsibility. Each model represents one concept, has one reason to change, and + exposes operations that belong to that concept. +- DDD ubiquitous language. Names, types, and operations match the vocabulary the library's + domain uses. Code and conversation share the same terms. +- SOLID. Interfaces define narrow contracts. Composition is preferred to inheritance. + Substitutability holds at every interface boundary. +- DRY. No duplicated logic across two or more places. +- KISS. No abstraction without real duplication or isolation need. -Libraries are self-contained packages. The core has no dependency on frameworks, databases, or I/O. Refer to -`php-library-code-style.md` for the pre-output checklist applied to all PHP code. +## Nomenclature -## Folder structure +- Every class, property, method, and exception name reflects the concept the library represents. + A math library uses `Precision` and `RoundingMode`. A money library uses `Currency` and + `Amount`. A collection library uses `Collectible` and `Order`. +- Name classes after what they represent, not after what they do technically. Use `Money`, + `Color`, `Pipeline`, not `MoneyCalculator`, `ColorHelper`, `PipelineProcessor`. +- Name methods after the operation in the library's vocabulary. Use `add()`, `convertTo()`, + `splitAt()`, not `compute()`, `process()`, `handle()`. -``` -src/ -├── .php # Primary contract for consumers -├── .php # Main implementation or extension point -├── .php # Public enum -├── Contracts/ # Interfaces for data returned to consumers -├── Internal/ # Implementation details (not part of public API) -│ ├── .php -│ └── Exceptions/ # Internal exception classes -├── / # Feature-specific subdirectory when needed -└── Exceptions/ # Public exception classes (when part of the API) -``` +### Always banned -Never use `Models/`, `Entities/`, `ValueObjects/`, `Enums/`, or `Domain/` as folder names. +These names carry zero semantic content. Never use them anywhere as class suffix, prefix, or +method name. -## Public API boundary +- `Data`, `Info`, `Utils`, `Item`, `Record`, `Entity`. +- `Exception` as a class suffix (e.g., `FooException`). Use the invariant name when extending a + native exception (e.g., `PrecisionOutOfRange`, not `InvalidPrecisionException`). -Only interfaces, extension points, enums, and thin orchestration classes live at the `src/` root. These classes -define the contract consumers interact with and delegate all real work to collaborators inside `src/Internal/`. -If a class contains substantial logic (algorithms, state machines, I/O), it belongs in `Internal/`, not at the root. +### Externally standardized names (exception to the banlist) -The `Internal/` namespace signals classes that are implementation details. Consumers must not depend on them. -Breaking changes inside `Internal/` are not semver-breaking for the library. +Names that correspond to externally standardized identifiers are exempt from the banlist. The +standard reference is the meaning carrier. Renaming weakens it. Examples: -## Nomenclature +- HTTP status text from RFC documents (`unprocessableEntity` from RFC 4918, `noContent`). +- PSR interface names being mirrored as test doubles (`ClientException` mirroring + `Psr\Http\Client\ClientExceptionInterface`). +- Unicode category names, locale identifiers, MIME type tokens, and similar registered names. -1. Every class, property, method, and exception name reflects the **concept** the library represents. A math library - uses `Precision`, `RoundingMode`; a money library uses `Currency`, `Amount`; a collection library uses - `Collectible`, `Order`. -2. Name classes after what they represent: `Money`, `Color`, `Pipeline` — not after what they do technically. -3. Name methods after the operation in the library's vocabulary: `add()`, `convertTo()`, `splitAt()`. +This exception applies only when the external standard is the actual source of the name. It +does not authorize using `Data` or `Entity` as generic suffixes when no external reference is +involved. -### Always banned +### Anemic verbs -These names carry zero semantic content. Never use them anywhere, as class suffixes, prefixes, or method names: +These verbs hide what is actually happening behind a generic action. Banned unless the verb IS +the operation that constitutes the library's reason to exist (e.g., a JSON parser may have +`parse()`, a hashing library may have `compute()`). -- `Data`, `Info`, `Utils`, `Item`, `Record`, `Entity`. -- `Exception` as a class suffix (e.g., `FooException` — use `Foo` when it already extends a native exception). +- `ensure`, `validate`, `check`, `verify`, `assert`, `mark`, `enforce`, `sanitize`, `normalize`, + `compute`, `transform`, `parse`. -### Anemic verbs (banned by default) +When in doubt, prefer the domain operation name. `Password::hash()` beats `Password::compute()`. +`Email::parse()` is fine in a parser library but suspicious elsewhere. Use `Email::from()` +instead. -These verbs hide what is actually happening behind a generic action. Banned unless the verb **is** the operation -that constitutes the library's reason to exist (e.g., a JSON parser may have `parse()`; a hashing library may -have `compute()`): +### Architectural roles -- `ensure`, `validate`, `check`, `verify`, `assert`, `mark`, `enforce`, `sanitize`, `normalize`, `compute`, - `transform`, `parse`. +These names describe a role the library offers as a building block. Acceptable when the class IS +that role (e.g., `EventHandler` in an events library, `CacheManager` in a cache library, +`Upcaster` in an event-sourcing library). Not acceptable on domain objects inside the library +(value objects, enums, contract interfaces). -When in doubt, prefer the domain operation name. `Password::hash()` beats `Password::compute()`; `Email::parse()` -is fine in a parser library but suspicious elsewhere (use `Email::from()` instead). +- `Manager`, `Handler`, `Processor`, `Service`. +- Verb forms: `process`, `handle`, `execute`. -### Architectural roles (allowed with justification) +The test. If the consumer instantiates or extends this class to integrate with the library, the +role name is legitimate. If the class models a concept the consumer manipulates (a money amount, +a country code, a color), the role name is wrong. -These names describe a role the library offers as a building block. Acceptable when the class **is** that role -(e.g., `EventHandler` in an events library, `CacheManager` in a cache library, `Upcaster` in an event-sourcing -library). Not acceptable on domain objects inside the library (value objects, enums, contract interfaces): +## Value objects -- `Manager`, `Handler`, `Processor`, `Service`, and their verb forms `process`, `handle`, `execute`. +- Are immutable. No setters. No mutation after construction. Operations return new instances. +- Compare by value, not by reference. +- Validate invariants in the constructor and throw a dedicated exception on invalid input. +- Have no identity field. +- Use static factory methods (`from`, `of`, `zero`) with a private constructor when multiple + creation paths exist. The factory name communicates the semantic intent. -The test: if the consumer instantiates or extends this class to integrate with the library, the role name is -legitimate. If the class models a concept the consumer manipulates (a money amount, a country code, a color), -the role name is wrong. +**Prohibited.** Public constructor with multiple creation paths. Semantics are unclear at the +call site: -## Value objects +```php +final readonly class Money +{ + public function __construct(public int $amount, public Currency $currency) {} +} + +new Money(amount: 1000, currency: Currency::BRL); +new Money(amount: 0, currency: Currency::USD); +``` + +**Correct.** Private constructor with named factory methods. Each factory name communicates +intent: + +```php +final readonly class Money +{ + private function __construct(public int $amount, public Currency $currency) {} -1. Are immutable: no setters, no mutation after construction. Operations return new instances. -2. Compare by value, not by reference. -3. Validate invariants in the constructor and throw on invalid input. -4. Have no identity field. -5. Use static factory methods (e.g., `from`, `of`, `zero`) with a private constructor when multiple creation paths - exist. The factory name communicates the semantic intent. + public static function of(int $amount, Currency $currency): Money + { + return new Money(amount: $amount, currency: $currency); + } + + public static function zero(Currency $currency): Money + { + return new Money(amount: 0, currency: $currency); + } +} + +Money::of(amount: 1000, currency: Currency::BRL); +Money::zero(currency: Currency::USD); +``` ## Exceptions -1. Every failure throws a **dedicated exception class** named after the invariant it guards — never - `throw new DomainException('...')`, `throw new InvalidArgumentException('...')`, - `throw new RuntimeException('...')`, or any other generic native exception thrown directly. If the invariant - is worth throwing for, it is worth a named class. -2. Dedicated exception classes **extend** the appropriate native PHP exception (`DomainException`, - `InvalidArgumentException`, `OverflowException`, etc.) — the native class is the parent, never the thing that - is thrown. Consumers that catch the broad standard types continue to work; consumers that need precise handling - can catch the specific classes. -3. Exceptions are pure: no transport-specific fields (`code` populated with HTTP status, formatted `message` meant - for end-user display). Formatting to any transport happens at the consumer's boundary, not inside the library. -4. Exceptions signal invariant violations only, not control flow. -5. Name the class after the invariant violated, never after the technical type: - - `PrecisionOutOfRange` — not `InvalidPrecisionException`. - - `CurrencyMismatch` — not `BadCurrencyException`. - - `ContainerWaitTimeout` — not `TimeoutException`. -6. A descriptive `message` argument is allowed and encouraged when it carries **debugging context** — the violating - value, the boundary that was crossed, the state the library was in. The class name identifies the invariant; - the message describes the specific violation for stack traces and test assertions. Do not build messages meant - for end-user display or transport rendering. Keep them short, factual, and in American English. -7. Public exceptions live in `src/Exceptions/`. Internal exceptions live in `src/Internal/Exceptions/`. - -**Prohibited** — throwing a native exception directly: +- Every failure throws a dedicated exception class named after the invariant it guards. Never + `throw new DomainException(...)`, `throw new InvalidArgumentException(...)`, + `throw new RuntimeException(...)`, or any other generic native exception directly. If the + invariant is worth throwing for, it is worth a named class. +- Dedicated exception classes extend the appropriate native PHP exception (`DomainException`, + `InvalidArgumentException`, `OverflowException`, etc.). The native class is the parent, never + the thing that is thrown. Consumers that catch the broad standard types continue to work. + Consumers that need precise handling can catch the specific classes. +- Exceptions are pure. No transport-specific fields (`code` populated with HTTP status, + formatted `message` meant for end-user display). Formatting to any transport happens at the + consumer's boundary, not inside the library. +- Exceptions signal invariant violations only, not control flow. +- Name the class after the invariant violated, never after the technical type. Use + `PrecisionOutOfRange`, not `InvalidPrecisionException`. Use `CurrencyMismatch`, not + `BadCurrencyException`. Use `ContainerWaitTimeout`, not `TimeoutException`. +- A descriptive `message` argument is allowed and encouraged when it carries debugging context + (the violating value, the boundary crossed, the state the library was in). The class name + identifies the invariant. The message describes the specific violation for stack traces and + test assertions. Keep messages short, factual, and in American English. + +**Prohibited.** Throwing a native exception directly: ```php if ($value < 0) { @@ -114,50 +201,76 @@ if ($value < 0) { } ``` -**Correct** — dedicated class, no message (class name is sufficient): +**Correct.** Dedicated class, no message (class name is sufficient): ```php -// src/Exceptions/PrecisionOutOfRange.php final class PrecisionOutOfRange extends InvalidArgumentException { } -// at the callsite if ($value < 0) { throw new PrecisionOutOfRange(); } ``` -**Correct** — dedicated class with debugging context: +**Correct.** Dedicated class with debugging context in the message: ```php if ($value < 0 || $value > 16) { - throw new PrecisionOutOfRange(sprintf('Precision must be between 0 and 16, got %d.', $value)); + $template = 'Precision must be between 0 and 16, got %d.'; + + throw new PrecisionOutOfRange(message: sprintf($template, $value)); } ``` ## Enums -1. Are PHP backed enums. -2. Include methods when they carry vocabulary meaning (e.g., `Order::ASCENDING_KEY`, `RoundingMode::apply()`). -3. Live at the `src/` root when public. Enums used only by internals live in `src/Internal/`. +- Are PHP backed enums. +- Include methods only when those methods carry vocabulary meaning. Examples are + `Order::ASCENDING_KEY` and `RoundingMode::apply()`. ## Extension points -1. When a class is designed to be extended by consumers (e.g., `Collection`, `ValueObject`), it uses `class` instead - of `final readonly class`. All other classes use `final readonly class`. -2. Extension point classes use a private constructor with static factory methods (`createFrom`, `createFromEmpty`) - as the only creation path. -3. Internal state is injected via the constructor and stored in a `private readonly` property. +- A class designed to be extended by consumers (e.g., `Collection`, `ValueObject`) uses `class` + instead of `final readonly class`. All other classes use `final readonly class`. See + "Inheritance and constructors" in `php-library-code-style.md`. +- Extension point classes use a private constructor with static factory methods (`createFrom`, + `createFromEmpty`) as the only creation path. +- Internal state is injected via the constructor and stored in a `private readonly` property. ## Time and space complexity -1. Every public method has predictable, documented complexity. Document Big O in PHPDoc on the interface - (see `php-library-code-style.md`, "PHPDoc" section). -2. Algorithms run in `O(N)` or `O(N log N)` unless the problem inherently requires worse. `O(N²)` or worse must - be justified and documented. -3. Prefer lazy/streaming evaluation over materializing intermediate results. In pipeline-style libraries, fuse - stages so a single pass suffices. -4. Memory usage is bounded and proportional to the output, not to the sum of intermediate stages. -5. Validate complexity claims with benchmarks against a reference implementation when optimizing critical paths. - Parity testing against the reference library is the validation standard for optimization work. +- Algorithms run in O(N) or O(N log N) unless the problem inherently requires worse. O(N²) or + worse needs explicit justification at the point of definition. +- Prefer lazy or streaming evaluation over materializing intermediate results. In pipeline-style + libraries, fuse stages so a single pass suffices over the input. +- Memory usage is bounded and proportional to the output, not to the sum of intermediate stages. +- Never re-iterate the same source. When a sequence is consumed once, use lazy creation + primitives (`createLazyFrom`) instead of materializing. + +**Prohibited.** Eager pipeline that materializes between stages: + +```php +$paidTotals = array_map( + static fn(Order $order): float => $order->total(), + array_filter( + $orders->toArray(), + static fn(Order $order): bool => $order->isPaid() + ) +); +``` + +Each stage allocates a full intermediate array. Memory grows with the input size, even when only +the final scalar matters. + +**Correct.** Fused pipeline that runs in a single pass: + +```php +$paidTotals = $orders + ->filter(predicates: static fn(Order $order): bool => $order->isPaid()) + ->map(transformations: static fn(Order $order): float => $order->total()) + ->toArray(keyPreservation: KeyPreservation::DISCARD); +``` + +Operations stack on the same iterator. No intermediate array is built. Memory stays bounded by +the final output. diff --git a/.claude/rules/php-library-testing.md b/.claude/rules/php-library-testing.md index 610b928..86a0c10 100644 --- a/.claude/rules/php-library-testing.md +++ b/.claude/rules/php-library-testing.md @@ -1,17 +1,79 @@ --- -description: BDD Given/When/Then structure, PHPUnit conventions, test organization, and fixture rules for PHP libraries. +description: BDD Given/When/Then structure, PHPUnit conventions, fixture rules, and coverage discipline. paths: - "tests/**/*.php" --- -# Testing conventions +# Testing -Framework: **PHPUnit**. Refer to `php-library-code-style.md` for the code style checklist, which also applies to -test files. +PHPUnit conventions for tests in PHP libraries. Covers BDD structure, fixture rules, and coverage +discipline. Code style applies to test files as well. See `php-library-code-style.md`. Folder +structure for `tests/` lives in `php-library-architecture.md`. Canonical thresholds (MSI 100, +covered MSI 100) live in `php-library-tooling.md`. + +## Pre-output checklist + +Verify every item before producing any test code. If any item fails, revise before outputting. + +1. Each test contains exactly one `@When` block. Two actions require two tests. +2. Use `@And` for complementary preconditions or actions within the same scenario, avoiding + consecutive `@Given` or `@When` tags. +3. Each `@Given` or `@And` block contains exactly one annotation line followed by one expression + or assignment. Never place multiple variable declarations or object constructions under a + single annotation. **Exception for data-provider tests.** When the test method binds its + inputs through a `#[DataProvider]` attribute (or the equivalent `@dataProvider` annotation), + the `@Given` block may declare the input shape in prose form, without an expression below + it. The values are bound by PHPUnit before the test body runs, so the prose annotation + replaces the assignment that would otherwise sit under the `@Given`. + + `@When` blocks follow the same one-expression rule by default: the block represents the + single action under test. **Exception for repeated-invocation tests** (idempotence, caching, + memoization). When the purpose of the test is asserting that the same operation produces the + same outcome across N invocations, the `@When` block may contain N consecutive identical + invocations, each captured in a numbered variable (`$first`, `$second`, ...), and the + annotation reads `@When invoked twice` (or thrice, etc.) to make the composite-action + semantic explicit. Two unrelated actions still require two tests. +4. No intermediate variables used only once. Chain method calls when the intermediate state is + not referenced elsewhere (e.g., `Money::of(...)->add(...)` instead of + `$money = Money::of(...)` followed by `$money->add(...)`). +5. No private or helper methods in test classes. The only non-test methods allowed are data + providers. Setup logic complex enough to extract belongs in a dedicated fixture class. +6. Test only the public API. Never assert on private state or `Internal/` classes directly. +7. Test the behavior that **raises** an exception, never the exception itself. Exception classes + represent invariant violations and are value objects, not the subject of behavior tests. A + test constructs the conditions, invokes the public method that is supposed to fail, and + asserts the expected exception class is raised (plus its accessor values when they carry + information relevant to the failure). Constructing an exception directly + (`new HttpRequestInvalid(...)`) and asserting on its accessors is **prohibited**: the + exception's structure is exercised through the call path that produces it. If a method does + not exist whose call path produces the exception, the exception is dead code and should be + removed. +8. Never mock internal collaborators. Use real objects. Test doubles are used only at system + boundaries (filesystem, clock, network) when the library interacts with external resources. +9. Name tests after behavior, not method names. +10. Use domain-specific names in variables and properties. Never `$spy`, `$mock`, `$stub`, + `$fake`, `$dummy` as variable or property names. Use the domain concept the object + represents (`$collection`, `$amount`, `$currency`, `$sortedElements`). Class names like + `ClientMock` or `GatewaySpy` are acceptable. The variable holding the instance is what matters. +11. Annotations use domain language. Write `/** @Given a collection of amounts */`, not + `/** @Given a mocked collection in test state */`. +12. Never use the `/** @test */` annotation. Test methods are discovered by the `test` prefix in + the method name. +13. Never use named arguments on PHPUnit assertions (`assertEquals`, `assertSame`, `assertTrue`, + `expectException`, etc.). Pass arguments positionally. +14. Never include conditional logic inside tests. Each `@Then` block expresses one logical + concept. The only allowed `try`/`catch` is when the assertion target is a property of the + caught exception that cannot be expressed via `expectException*` methods (notably + `getPrevious()` for chain inspection). The catch block contains only assertions against the + caught exception, no branching. +15. Never use `@codeCoverageIgnore`, attributes, or configuration that exclude code from + coverage. Never suppress mutants via `infection.json.dist` or any other mechanism. See + "Coverage and mutation discipline". ## Structure: Given/When/Then (BDD) -Every test uses `/** @Given */`, `/** @And */`, `/** @When */`, `/** @Then */` doc comments without exception. +Every test uses `/** @Given */`, `/** @And */`, `/** @When */`, `/** @Then */` doc comments +without exception. ### Happy path example @@ -20,26 +82,30 @@ public function testAddMoneyWhenSameCurrencyThenAmountsAreSummed(): void { /** @Given two money instances in the same currency */ $ten = Money::of(amount: 1000, currency: Currency::BRL); + + /** @And another money instance with the same currency */ $five = Money::of(amount: 500, currency: Currency::BRL); /** @When adding them together */ $total = $ten->add(other: $five); /** @Then the result contains the sum of both amounts */ - self::assertEquals(expected: 1500, actual: $total->amount()); + self::assertEquals(1500, $total->amount()); } ``` ### Exception example -When testing that an exception is thrown, place `@Then` (expectException) **before** `@When`. PHPUnit requires this -ordering. +When testing that an exception is thrown, place `@Then` (`expectException`) before `@When`. +PHPUnit requires this ordering. ```php public function testAddMoneyWhenDifferentCurrenciesThenCurrencyMismatch(): void { /** @Given two money instances in different currencies */ $brl = Money::of(amount: 1000, currency: Currency::BRL); + + /** @And another money instance with a different currency */ $usd = Money::of(amount: 500, currency: Currency::USD); /** @Then an exception indicating currency mismatch should be thrown */ @@ -50,67 +116,210 @@ public function testAddMoneyWhenDifferentCurrenciesThenCurrencyMismatch(): void } ``` -Use `@And` for complementary preconditions or actions within the same scenario, avoiding consecutive `@Given` or -`@When` tags. - -## Rules - -1. Include exactly one `@When` per test. Two actions require two tests. -2. Test only the public API. Never assert on private state or `Internal/` classes directly. -3. Never mock internal collaborators. Use real objects. Use test doubles only at system boundaries (filesystem, - clock, network) when the library interacts with external resources. -4. Name tests to describe behavior, not method names. -5. Never include conditional logic inside tests. -6. Include one logical concept per `@Then` block. -7. Maintain strict independence between tests. No inherited state. -8. Use domain-specific model classes in `tests/Models/` for test fixtures that represent domain concepts - (e.g., `Amount`, `Invoice`, `Order`). -9. Use mock classes in `tests/Mocks/` (or `tests/Unit/Mocks/`) for test doubles of system boundaries - (e.g., `ClientMock`, `ExecutionCompletedMock`). -10. Exercise invariants and edge cases through the library's public entry point. Create a dedicated test class - for an internal model only when the condition cannot be reached through the public API. -11. Never use `/** @test */` annotation. Test methods are discovered by the `test` prefix in the method name. -12. Never use named arguments on PHPUnit assertions (`assertEquals`, `assertSame`, `assertTrue`, - `expectException`, etc.). Pass arguments positionally. +Use `@And` for complementary preconditions or actions within the same scenario, avoiding +consecutive `@Given` or `@When` tags. + +## Testing exceptions + +Exception classes are value objects describing an invariant violation. They are not the subject +of behavior tests. A test verifies that a public method, under specific conditions, raises a +specific exception. Constructing the exception directly and asserting on its accessors is +prohibited. The exception's structure is exercised through the call path that produces it. + +**Prohibited.** Testing the exception as a value object: + +```php +public function testFromWhenAllFieldsGivenThenExposesEveryAccessor(): void +{ + /** @Given a URL */ + $url = 'https://api.example.com'; + + /** @And an HTTP method */ + $method = Method::GET; + + /** @And a reason */ + $reason = 'Connection refused.'; + + /** @When the exception is constructed */ + $exception = HttpNetworkFailed::from(url: $url, method: $method, reason: $reason); + + /** @Then it exposes the URL */ + self::assertSame($url, $exception->url()); +} +``` + +The test constructs the exception in isolation and asserts on its accessors. No production code +is exercised. The same coverage is achieved (and made meaningful) by the test below, which +drives the path that raises the exception. + +**Correct.** Testing the behavior that raises the exception: + +```php +public function testSendRequestWhenTransportCannotReachServerThenThrowsHttpNetworkFailed(): void +{ + /** @Given an HTTP client backed by a transport that always raises a network error */ + $http = Http::usingTransport(transport: new ThrowingClient()); + + /** @And a target request to that transport */ + $request = Request::create(url: 'https://api.example.com', method: Method::GET); + + /** @Then a network failure exception describing the unreachable target is raised */ + $this->expectException(HttpNetworkFailed::class); + + /** @When the request is sent */ + $http->send(request: $request); +} +``` + +When the accessor values on the raised exception are part of the assertion, `expectException` +alone is not enough (it asserts only the class). Use a `try`/`catch` block as permitted by +rule 14. The catch block contains only assertions against the caught exception, no branching. + +```php +public function testSendRequestWhenTargetUnreachableThenExceptionCarriesUrlAndMethod(): void +{ + /** @Given an HTTP client backed by a transport that always raises a network error */ + $http = Http::usingTransport(transport: new ThrowingClient()); + + /** @And a target request to that transport */ + $request = Request::create(url: 'https://api.example.com', method: Method::GET); + + try { + /** @When the request is sent */ + $http->send(request: $request); + } catch (HttpNetworkFailed $failure) { + /** @Then the exception exposes the target URL and method */ + self::assertSame('https://api.example.com', $failure->url()); + self::assertSame(Method::GET, $failure->method()); + } +} +``` + +If a method does not exist whose call path produces the exception, the exception itself is dead +code. Remove it instead of writing a behavior test against a constructor. + +**The `try`/`catch` form is reserved for assertions that PHPUnit's `expectException*` family +does not cover.** Message, code, and class are covered by PHPUnit (`expectException`, +`expectExceptionMessage`, `expectExceptionMessageMatches`, `expectExceptionCode`): use those +methods, not `try`/`catch`. The only case that warrants `try`/`catch` is inspecting accessors +that PHPUnit cannot reach — notably `getPrevious()` for chain inspection, or domain-specific +accessors on a `TransportFailure` (`url()`, `method()`, `reason()`). + +**Prohibited.** `try`/`catch` to assert message: + +```php +try { + $http->send(request: $request); + self::fail('NoMoreResponses was expected.'); +} catch (NoMoreResponses $exception) { + self::assertStringContainsString('queue exhausted', $exception->getMessage()); +} +``` + +**Correct.** PHPUnit's `expectExceptionMessage`: + +```php +$this->expectException(NoMoreResponses::class); +$this->expectExceptionMessage('queue exhausted'); + +$http->send(request: $request); +``` ## Test setup and fixtures -1. **One annotation = one statement.** Each `@Given` or `@And` block contains exactly one annotation line - followed by one expression or assignment. Never place multiple variable declarations or object - constructions under a single annotation. -2. **No intermediate variables used only once.** If a value is consumed in a single place, inline it at the - call site. Chain method calls when the intermediate state is not referenced elsewhere - (e.g., `Money::of(...)->add(...)` instead of `$money = Money::of(...); $money->add(...);`). -3. **No private or helper methods in test classes.** The only non-test methods allowed are data providers. - If setup logic is complex enough to extract, it belongs in a dedicated fixture class, not in a - private method on the test class. -4. **Domain terms in variables and annotations.** Never use technical testing jargon (`$spy`, `$mock`, - `$stub`, `$fake`, `$dummy`) as variable or property names. Use the domain concept the object - represents: `$collection`, `$amount`, `$currency`, `$sortedElements`. Class names like - `ClientMock` or `GatewaySpy` are acceptable — the variable holding the instance is what matters. -5. **Annotations use domain language.** Write `/** @Given a collection of amounts */`, not - `/** @Given a mocked collection in test state */`. The annotation describes the domain - scenario, not the technical setup. - -## Test organization +- Each `@Given` or `@And` block contains exactly one annotation followed by one expression or + assignment. Never place multiple declarations under a single annotation. The exception for + data-provider tests applies here as well (see rule 3). +- No intermediate variables used only once. Chain method calls when the intermediate state is + not referenced elsewhere. +- No private or helper methods in test classes. The only non-test methods allowed are data + providers. Setup logic complex enough to extract belongs in a dedicated fixture class, not in + a private method on the test class. +- Domain terms in variables and properties. Never use technical testing jargon (`$spy`, `$mock`, + `$stub`, `$fake`, `$dummy`) as variable or property names. Use the domain concept the object + represents (`$collection`, `$amount`, `$currency`, `$sortedElements`). Class names like + `ClientMock` or `GatewaySpy` are acceptable. The variable holding the instance is what + matters. +- Annotations use domain language. Write `/** @Given a collection of amounts */`, not + `/** @Given a mocked collection in test state */`. The annotation describes the domain + scenario, not the technical setup. + +**Prohibited.** Multiple declarations under a single annotation: + +```php +/** @And two money instances in different currencies */ +$usd = Money::of(amount: 500, currency: Currency::USD); +$eur = Money::of(amount: 300, currency: Currency::EUR); +``` + +**Correct.** One annotation per declaration: +```php +/** @And a money instance in USD */ +$usd = Money::of(amount: 500, currency: Currency::USD); + +/** @And a money instance in EUR */ +$eur = Money::of(amount: 300, currency: Currency::EUR); ``` -tests/ -├── Models/ # Domain-specific fixtures reused across tests -├── Mocks/ # Test doubles for system boundaries -├── Unit/ # Unit tests for public API -│ └── Mocks/ # Alternative location for test doubles -├── Integration/ # Tests requiring real external resources (Docker, filesystem) -└── bootstrap.php # Test bootstrap when needed + +**Also prohibited.** Setup multi-statement grouped under a single annotation because "the +statements build one coherent concept": + +```php +/** @Given transport seeded with two responses */ +$first = Response::with(code: Code::OK); +$second = Response::with(code: Code::CREATED); +$transport = InMemoryTransport::with(responses: [$first, $second]); +``` + +Three statements, one annotation. The fact that the three lines together build a single +setup concept is **not** a license to share one annotation. Each declaration takes its own +`@And` block. The same applies under `@When` when the test prepares the input alongside the +action: the input preparation goes back to `@And` under `@Given`, and `@When` contains only +the action under test. + +**Correct.** Each statement keeps its own annotation: + +```php +/** @Given a first queued response */ +$first = Response::with(code: Code::OK); + +/** @And a second queued response */ +$second = Response::with(code: Code::CREATED); + +/** @And transport with both responses */ +$transport = InMemoryTransport::with(responses: [$first, $second]); ``` -`tests/Integration/` is only present when the library interacts with infrastructure. +## Test doubles + +Conventions for naming and locating test doubles (mocks, spies, stubs, fakes, dummies). + +### Naming + +- Variables and properties never carry the technical role in their name. Never `$spy`, `$mock`, + `$stub`, `$fake`, `$dummy`. Use the domain concept the object represents (`$gateway`, + `$clock`, `$repository`, `$client`). +- Class names may carry the technical role as suffix when the class IS a test double + (`ClientMock`, `GatewaySpy`, `ClockFake`). The suffix signals that the file is a collaborator + built for tests, not a production type. + +### Location + +- Test doubles live at the root of `tests/Unit/`. When integration tests exist, doubles used + there live at the root of `tests/Integration/`. +- No dedicated `Mocks/` or `Doubles/` subdirectory exists. +- Domain fixtures that represent real domain concepts live in `tests/Models/`. See + `php-library-architecture.md` for the canonical `tests/` folder layout. + +## Coverage and mutation discipline -## Coverage and mutation testing +- Never use `@codeCoverageIgnore`, attributes, or configuration that exclude code from coverage. +- Never suppress mutants via `infection.json.dist` or any other mechanism. +- If a line or mutation cannot be covered or killed, the design is wrong. Refactor the + production code to make it testable. Never work around the tool. -1. Line and branch coverage must be **100%**. No annotations (`@codeCoverageIgnore`), attributes, or configuration - that exclude code from coverage are allowed. -2. All mutations reported by Infection must be **killed**. Never ignore or suppress mutants via `infection.json.dist` - or any other mechanism. -3. If a line or mutation cannot be covered or killed, it signals a design problem in the production code. Refactor - the code to make it testable, do not work around the tool. +Canonical thresholds (MSI 100, covered MSI 100) live in `php-library-tooling.md`. They are +enforced by `infection.json.dist`. Achieving MSI 100 implies effective full coverage of `src/` +because every mutation must be killed by an assertion. This file covers only the behavioral +rules that complement those thresholds. diff --git a/.claude/rules/php-library-tooling.md b/.claude/rules/php-library-tooling.md new file mode 100644 index 0000000..3b55111 --- /dev/null +++ b/.claude/rules/php-library-tooling.md @@ -0,0 +1,464 @@ +--- +description: Canonical config files for PHP libraries in the tiny-blocks ecosystem. +paths: + - "composer.json" + - "phpcs.xml" + - "phpstan.neon.dist" + - "phpunit.xml" + - "infection.json.dist" + - ".editorconfig" + - ".gitattributes" + - ".gitignore" + - "Makefile" +--- + +# Tooling + +Canonical configuration files for a PHP library in the tiny-blocks ecosystem. Each file has a +fixed shape. Deviations require justification. Folder structure lives in +`php-library-architecture.md`. Code style lives in `php-library-code-style.md`. + +## Pre-output checklist + +Verify every item before creating, editing, or relocating any of the files below. If any item +fails, revise before outputting. + +1. The library repository contains all the following files at its root: `composer.json`, + `phpcs.xml`, `phpstan.neon.dist`, `phpunit.xml`, `infection.json.dist`, `.editorconfig`, + `.gitattributes`, `.gitignore`, `Makefile`. +2. `composer.json` exposes exactly five scripts: `configure`, `configure-and-update`, `review`, + `test-file`, `tests`. No other public scripts are defined. +3. `composer.json` fixed fields use the canonical values defined in the "composer.json" section + (`license`, `type`, `minimum-stability`, `prefer-stable`, `authors`, `config`, `require.php`). +4. `composer.json` `description` is a single short sentence describing what the library does. + Multi-sentence or multi-paragraph descriptions belong in the README Overview, not in Composer + metadata. +5. `composer.json` includes a `keywords` array. The first keyword is always `"tiny-blocks"`. + Additional keywords are topic tokens derived from the library's purpose (`psr-7`, + `http-client`, `event-sourcing`, etc.). +6. `phpcs.xml` references only the `PSR12` ruleset. No additional sniffs are added. +7. `phpunit.xml` sets all five `failOn*` flags to `true`: `failOnDeprecation`, `failOnNotice`, + `failOnPhpunitDeprecation`, `failOnRisky`, `failOnWarning`. +8. `phpunit.xml` sets `executionOrder="random"` and `beStrictAboutOutputDuringTests="true"`. +9. `infection.json.dist` sets `minMsi: 100` and `minCoveredMsi: 100`. Lowering either value is + prohibited. +10. `.editorconfig` sets `max_line_length = 120`, `indent_size = 4`, `indent_style = space`, and + `end_of_line = lf` for PHP files. YAML uses `indent_size = 2`. Makefile uses `indent_style = tab`. +11. `.gitattributes` sets `* text=auto eol=lf` and lists every dev-only file under `export-ignore`. + The Packagist tarball contains only `src/`, `composer.json`, `README.md`, and `LICENSE`. + `.claude/` is listed under `export-ignore` (versioned on GitHub for contributor parity, + excluded from the published package). +12. `.gitignore` follows the canonical content in the ".gitignore" section. `.claude/` is **not** + listed (it is versioned on GitHub). +13. `Makefile` wraps every PHP and Composer command in a Docker container using the canonical + image `gustavofreze/php:8.5-alpine`. No PHP command runs on the host directly. +14. All test artifact paths use `reports/` (plural). The directory is consistent across + `composer tests`, `infection.json.dist`, `phpunit.xml`, and `Makefile`. +15. The `reports/` directory is listed under `export-ignore` in `.gitattributes`. + +## composer.json + +Fixed fields, identical in every library: `license`, `type`, `minimum-stability`, `prefer-stable`, +`require.php`, `authors`, `config.allow-plugins`, `config.sort-packages`, `scripts`, and the five +universal dev dependencies (`ergebnis/composer-normalize`, `infection/infection`, `phpstan/phpstan`, +`phpunit/phpunit`, `squizlabs/php_codesniffer`). + +Per-library fields, vary by library: `name`, `description`, `keywords`, `homepage`, `support`, +`autoload`, `autoload-dev`. The `require-dev` section may add libraries needed by tests (for +example, HTTP client implementations in a PSR-7 library) on top of the five universal tools. + +```json +{ + "name": "tiny-blocks/", + "description": "", + "license": "MIT", + "type": "library", + "keywords": [ + "tiny-blocks", + "", + "" + ], + "authors": [ + { + "name": "Gustavo Freze de Araujo Santos", + "homepage": "https://github.com/gustavofreze" + } + ], + "homepage": "https://github.com/tiny-blocks/", + "support": { + "issues": "https://github.com/tiny-blocks//issues", + "source": "https://github.com/tiny-blocks/" + }, + "require": { + "php": "^8.5" + }, + "require-dev": { + "ergebnis/composer-normalize": "^2.51", + "infection/infection": "^0.32", + "phpstan/phpstan": "^2.1", + "phpunit/phpunit": "^13.1", + "squizlabs/php_codesniffer": "^4.0" + }, + "minimum-stability": "stable", + "prefer-stable": true, + "autoload": { + "psr-4": { + "TinyBlocks\\\\": "src/" + } + }, + "autoload-dev": { + "psr-4": { + "Test\\TinyBlocks\\\\": "tests/" + } + }, + "config": { + "allow-plugins": { + "ergebnis/composer-normalize": true, + "infection/extension-installer": true + }, + "sort-packages": true + }, + "scripts": { + "configure": [ + "@composer install --optimize-autoloader", + "@composer normalize" + ], + "configure-and-update": [ + "@composer update --optimize-autoloader", + "@composer normalize" + ], + "review": [ + "@php ./vendor/bin/phpcs --standard=phpcs.xml --extensions=php ./src ./tests", + "@php ./vendor/bin/phpstan analyse -c phpstan.neon.dist --quiet --no-progress" + ], + "test-file": "@php ./vendor/bin/phpunit --configuration phpunit.xml --no-coverage --filter", + "tests": [ + "@php -d memory_limit=2G ./vendor/bin/phpunit --configuration phpunit.xml tests", + "@php ./vendor/bin/infection --threads=max --logger-html=reports/coverage/mutation-report.html --coverage=reports/coverage" + ] + } +} +``` + +Script usage: + +- `composer configure` runs `composer install --optimize-autoloader` followed by `composer normalize`. + Use this after cloning the repository or pulling new changes. +- `composer configure-and-update` runs `composer update --optimize-autoloader` followed by + `composer normalize`. Use this when intentionally updating dependencies. +- `composer review` runs `phpcs` and `phpstan` in sequence. Used by CI and local validation. +- `composer tests` runs `phpunit` followed by `infection`. Used by CI. +- `composer test-file ` runs a filtered subset of tests without coverage. Local + development only. + +## phpcs.xml + +References only the `PSR12` ruleset. Additional formatting rules (vertical alignment, trailing +comma, etc.) live in `php-library-code-style.md` under "Formatting overrides". + +```xml + + + Code style for the tiny-blocks library. + + src + tests + +``` + +## phpstan.neon.dist + +Static analysis configuration. Runs at the highest level on both `src/` and `tests/`. Invoked +by the `review` Composer script. + +```neon +parameters: + level: max + paths: + - src + - tests + reportUnmatchedIgnoredErrors: true +``` + +`ignoreErrors` is permitted to suppress legitimate false positives produced by `level: max` +(third-party type signatures with `mixed`, PHP-FIG interfaces returning untyped arrays, trait +unused-method warnings on shared behavior, etc.). Each entry follows these rules: + +- A short comment above the entry justifies its existence. +- Prefer scoping via `identifier:` plus `path:` over raw `#...#` message patterns. +- `reportUnmatchedIgnoredErrors: true` is mandatory. Obsolete entries fail the build, forcing + cleanup. + +Example with `ignoreErrors`: + +```neon +parameters: + level: max + paths: + - src + - tests + ignoreErrors: + # Trait method intentionally unused by the consuming aggregate; reflection wires it. + - identifier: trait.unused + path: src/Internal/EventualAggregateRootBehavior.php + + # json_encode signature carries `mixed` for backward compatibility at level max. + - identifier: argument.type + path: src/Internal/Serialization/JsonEncoder.php + reportUnmatchedIgnoredErrors: true +``` + +## phpunit.xml + +Strict configuration. All `failOn*` flags are `true`. `executionOrder="random"` forces tests to be +independent of one another. Coverage and JUnit reports go under `reports/`. + +```xml + + + + + + src + + + + + + tests + + + + + + + + + + + + + + + + + +``` + +Root attributes are sorted alphabetically. + +## infection.json.dist + +Mutation testing configuration. `minMsi` and `minCoveredMsi` are both `100`. Mutants that escape +make the build fail. + +```json +{ + "logs": { + "text": "reports/infection/logs/infection-text.log", + "summary": "reports/infection/logs/infection-summary.log" + }, + "tmpDir": "reports/infection/", + "minMsi": 100, + "timeout": 30, + "source": { + "directories": [ + "src" + ] + }, + "phpUnit": { + "configDir": "", + "customPath": "./vendor/bin/phpunit" + }, + "mutators": { + "@default": true + }, + "minCoveredMsi": 100, + "testFramework": "phpunit" +} +``` + +## .editorconfig + +Whitespace and line ending rules applied by editor integrations. + +```ini +root = true + +[*] +charset = utf-8 +end_of_line = lf +indent_size = 4 +indent_style = space +max_line_length = 120 +insert_final_newline = true +trim_trailing_whitespace = true + +[*.{yml,yaml}] +indent_size = 2 + +[Makefile] +indent_style = tab + +[*.md] +trim_trailing_whitespace = false +``` + +## .gitattributes + +Normalizes line endings to LF and excludes every dev-only file from the Packagist tarball. The +published package contains only `src/`, `composer.json`, `README.md`, and `LICENSE`. + +``` +* text=auto eol=lf + +*.php text diff=php + +# Dev-only, excluded from the Packagist tarball +/.github export-ignore +/tests export-ignore +/.claude export-ignore +/.editorconfig export-ignore +/.gitattributes export-ignore +/.gitignore export-ignore +/phpunit.xml export-ignore +/phpunit.xml.dist export-ignore +/phpstan.neon export-ignore +/phpstan.neon.dist export-ignore +/phpcs.xml export-ignore +/phpcs.xml.dist export-ignore +/infection.json export-ignore +/infection.json.dist export-ignore +/Makefile export-ignore +/CONTRIBUTING.md export-ignore +/CHANGES.md export-ignore +/reports export-ignore +/.phpunit.cache export-ignore +``` + +## .gitignore + +Keeps the repository working tree clean of artifacts that should never be committed. Entries +are grouped from most fundamental (PHP dependencies) to least critical (OS files). The +`.claude/` directory is **not** listed here. It is versioned on GitHub so other contributors +share the same rules, and it is excluded from the published Packagist tarball through +`export-ignore` in `.gitattributes` (see above). + +``` +# PHP dependencies +/vendor/ +composer.lock + +# Tooling cache +.phpcs-cache +.phpunit.cache/ +.php-cs-fixer.cache +.phpunit.result.cache + +# Coverage and reports +build/ +reports/ +coverage/ +infection.log + +# Editors and agents +.idea/ +.cursor/ +.vscode/ + +# OS +Thumbs.db +.DS_Store +Desktop.ini +``` + +## Makefile + +Thin wrapper over Composer scripts. Every PHP and Composer command runs inside a Docker container +using the canonical image `gustavofreze/php:8.5-alpine`. Targets that match a Composer script +delegate to it directly, avoiding duplication. + +```makefile +PWD := $(CURDIR) +ARCH := $(shell uname -m) +PLATFORM := + +ifeq ($(ARCH),arm64) + PLATFORM := --platform=linux/amd64 +endif + +DOCKER_RUN = docker run ${PLATFORM} --rm -it --net=host -v ${PWD}:/app -w /app gustavofreze/php:8.5-alpine + +RESET := \033[0m +GREEN := \033[0;32m +YELLOW := \033[0;33m + +.DEFAULT_GOAL := help + +.PHONY: configure +configure: ## Configure development environment + @${DOCKER_RUN} composer configure + +.PHONY: configure-and-update +configure-and-update: ## Configure development environment and update dependencies + @${DOCKER_RUN} composer configure-and-update + +.PHONY: tests +tests: ## Run unit and mutation tests with coverage + @${DOCKER_RUN} composer tests + +.PHONY: test-file +test-file: ## Run tests for a specific file (usage: make test-file FILE=ClassNameTest) + @${DOCKER_RUN} composer test-file ${FILE} + +.PHONY: review +review: ## Run lint and static analysis + @${DOCKER_RUN} composer review + +.PHONY: show-reports +show-reports: ## Open coverage and mutation reports in the browser + @sensible-browser reports/coverage/coverage-html/index.html reports/coverage/mutation-report.html + +.PHONY: show-outdated +show-outdated: ## Show outdated direct dependencies + @${DOCKER_RUN} composer outdated --direct + +.PHONY: clean +clean: ## Remove dependencies and generated artifacts + @sudo chown -R ${USER}:${USER} ${PWD} + @rm -rf reports vendor .phpunit.cache *.lock + +.PHONY: help +help: ## Display this help message + @echo "Usage: make [target]" + @echo "" + @echo "$$(printf '$(GREEN)')Setup$$(printf '$(RESET)')" + @grep -E '^(configure|configure-and-update):.*?## .*$$' $(MAKEFILE_LIST) \ + | awk 'BEGIN {FS = ":.*? ## "}; {printf "$(YELLOW)%-25s$(RESET) %s\n", $$1, $$2}' + @echo "" + @echo "$$(printf '$(GREEN)')Testing$$(printf '$(RESET)')" + @grep -E '^(tests|test-file):.*?## .*$$' $(MAKEFILE_LIST) \ + | awk 'BEGIN {FS = ":.*?## "}; {printf "$(YELLOW)%-25s$(RESET) %s\n", $$1, $$2}' + @echo "" + @echo "$$(printf '$(GREEN)')Quality$$(printf '$(RESET)')" + @grep -E '^(review):.*?## .*$$' $(MAKEFILE_LIST) \ + | awk 'BEGIN {FS = ":.*?## "}; {printf "$(YELLOW)%-25s$(RESET) %s\n", $$1, $$2}' + @echo "" + @echo "$$(printf '$(GREEN)')Reports$$(printf '$(RESET)')" + @grep -E '^(show-reports|show-outdated):.*?## .*$$' $(MAKEFILE_LIST) \ + | awk 'BEGIN {FS = ":.*?## "}; {printf "$(YELLOW)%-25s$(RESET) %s\n", $$1, $$2}' + @echo "" + @echo "$$(printf '$(GREEN)')Cleanup$$(printf '$(RESET)')" + @grep -E '^(clean):.*?## .*$$' $(MAKEFILE_LIST) \ + | awk 'BEGIN {FS = ":.*?## "}; {printf "$(YELLOW)%-25s$(RESET) %s\n", $$1, $$2}' +``` diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 77c2bb8..e34c801 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -2,10 +2,11 @@ ## Context -PHP library (tiny-blocks). Immutable domain models, zero infrastructure dependencies in core. +PHP library in the tiny-blocks ecosystem. ## Mandatory pre-task step -Before starting any task, read and strictly follow all instruction files located in `.claude/CLAUDE.md` and -`.claude/rules/`. These files are the absolute source of truth for code generation. Apply every rule strictly. Do not -deviate from the patterns, folder structure, or naming conventions defined in them. +Before starting any task, read and strictly follow `.claude/CLAUDE.md` and every rule file in +`.claude/rules/`. These files are the absolute source of truth for code generation. Apply every +rule strictly. Do not deviate from the patterns, folder structure, or naming conventions defined +in them. From afbaf68c0dd87231be25085dacb82a364ca50b1e Mon Sep 17 00:00:00 2001 From: Gustavo Freze Date: Sat, 16 May 2026 13:13:37 -0300 Subject: [PATCH 02/11] ci: Refresh workflows and add issue and pull request templates. --- .github/ISSUE_TEMPLATE/bug_report.md | 29 ++++++++++++++ .github/ISSUE_TEMPLATE/feature_request.md | 17 +++++++++ .github/PULL_REQUEST_TEMPLATE.md | 16 ++++++++ .github/workflows/auto-assign.yml | 19 +++++++--- .github/workflows/ci.yml | 46 ++++++++++++++++------- .github/workflows/codeql.yml | 6 ++- 6 files changed, 112 insertions(+), 21 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..8ddd1db --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,29 @@ +--- +name: Bug report +about: Report a bug to help improve the library +labels: bug +--- + +## Description + +A clear and concise description of the bug. + +## Steps to reproduce + +1. +2. +3. + +## Expected behavior + +What should happen. + +## Actual behavior + +What actually happens. + +## Environment + +- PHP version: +- Library version: +- OS: diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..b344d9e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,17 @@ +--- +name: Feature request +about: Suggest a feature for the library +labels: enhancement +--- + +## Problem + +What problem does this feature solve? + +## Proposed solution + +How should the feature work? + +## Alternatives considered + +Other approaches considered. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..7a2c836 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,16 @@ +> Please follow the [contributing guidelines](https://github.com/tiny-blocks/tiny-blocks/blob/main/CONTRIBUTING.md). + +## Summary + +What this pull request does. + +## Related issue + +Closes #... + +## Checklist + +- [ ] Tests added or updated. +- [ ] Documentation updated when applicable. +- [ ] `composer review` passes. +- [ ] `composer tests` passes. diff --git a/.github/workflows/auto-assign.yml b/.github/workflows/auto-assign.yml index d0ba49e..fe2b34c 100644 --- a/.github/workflows/auto-assign.yml +++ b/.github/workflows/auto-assign.yml @@ -8,18 +8,25 @@ on: types: - opened +concurrency: + group: auto-assign-${{ github.event.issue.number || github.event.pull_request.number }} + cancel-in-progress: true + +permissions: + issues: write + pull-requests: write + jobs: - run: + auto-assign: + name: Auto assign runs-on: ubuntu-latest - permissions: - issues: write - pull-requests: write + timeout-minutes: 5 steps: - name: Assign issues and pull requests - uses: gustavofreze/auto-assign@2.1.0 + uses: gustavofreze/auto-assign@2 with: assignees: '${{ vars.ASSIGNEES }}' github_token: '${{ secrets.GITHUB_TOKEN }}' allow_self_assign: 'true' allow_no_assignees: 'true' - assignment_options: 'ISSUE,PULL_REQUEST' \ No newline at end of file + assignment_options: 'ISSUE,PULL_REQUEST' diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 71e59e0..d395d35 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -3,26 +3,44 @@ name: CI on: pull_request: +concurrency: + group: pr-${{ github.event.pull_request.number }} + cancel-in-progress: true + permissions: contents: read -env: - PHP_VERSION: '8.5' - jobs: + resolve-php-version: + name: Resolve PHP version + runs-on: ubuntu-latest + timeout-minutes: 5 + outputs: + php-version: ${{ steps.config.outputs.php-version }} + steps: + - name: Checkout + uses: actions/checkout@v6 + + - name: Resolve PHP version from composer.json + id: config + run: | + version=$(jq -r '.require.php' composer.json | grep -oP '\d+\.\d+' | head -1) + echo "php-version=$version" >> "$GITHUB_OUTPUT" + build: name: Build + needs: resolve-php-version runs-on: ubuntu-latest - + timeout-minutes: 15 steps: - name: Checkout uses: actions/checkout@v6 - - name: Configure PHP + - name: Setup PHP uses: shivammathur/setup-php@v2 with: - php-version: ${{ env.PHP_VERSION }} tools: composer:2 + php-version: ${{ needs.resolve-php-version.outputs.php-version }} - name: Validate composer.json run: composer validate --no-interaction @@ -40,18 +58,18 @@ jobs: auto-review: name: Auto review + needs: [resolve-php-version, build] runs-on: ubuntu-latest - needs: build - + timeout-minutes: 15 steps: - name: Checkout uses: actions/checkout@v6 - - name: Configure PHP + - name: Setup PHP uses: shivammathur/setup-php@v2 with: - php-version: ${{ env.PHP_VERSION }} tools: composer:2 + php-version: ${{ needs.resolve-php-version.outputs.php-version }} - name: Download vendor artifact from build uses: actions/download-artifact@v8 @@ -64,18 +82,18 @@ jobs: tests: name: Tests + needs: [resolve-php-version, auto-review] runs-on: ubuntu-latest - needs: auto-review - + timeout-minutes: 15 steps: - name: Checkout uses: actions/checkout@v6 - - name: Configure PHP + - name: Setup PHP uses: shivammathur/setup-php@v2 with: - php-version: ${{ env.PHP_VERSION }} tools: composer:2 + php-version: ${{ needs.resolve-php-version.outputs.php-version }} - name: Download vendor artifact from build uses: actions/download-artifact@v8 diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 4c6d7f7..0634bbf 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -8,6 +8,10 @@ on: schedule: - cron: "0 0 * * *" +concurrency: + group: codeql-${{ github.ref }} + cancel-in-progress: true + permissions: actions: read contents: read @@ -17,11 +21,11 @@ jobs: analyze: name: Analyze runs-on: ubuntu-latest + timeout-minutes: 30 strategy: fail-fast: false matrix: language: [ "actions" ] - steps: - name: Checkout repository uses: actions/checkout@v6 From d7976004b99bf7e08e44baddae845e122f8feb9d Mon Sep 17 00:00:00 2001 From: Gustavo Freze Date: Sat, 16 May 2026 13:13:43 -0300 Subject: [PATCH 03/11] docs: Add security policy and update README. --- README.md | 17 ++++++----------- SECURITY.md | 12 ++++++++++++ 2 files changed, 18 insertions(+), 11 deletions(-) create mode 100644 SECURITY.md diff --git a/README.md b/README.md index 419bab4..aec9f2d 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,28 @@ # Mapper -[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE) +[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/tiny-blocks/mapper/blob/main/LICENSE) * [Overview](#overview) * [Installation](#installation) * [How to use](#how-to-use) + + [Create an object from an iterable](#create-an-object-from-an-iterable) + + [Map object to array](#map-object-to-array) + + [Map object to JSON](#map-object-to-json) * [License](#license) * [Contributing](#contributing) -
    - ## Overview Maps PHP objects to and from arrays, JSON, and iterables through reflection and pluggable strategies. Handles enums, value objects, nested objects, date-time types, and collections out of the box. Designed for DTO hydration, serialization at the HTTP boundary, and data transfer between bounded contexts. -
    - ## Installation ```bash composer require tiny-blocks/mapper ``` -
    - ## How to use The examples demonstrate how to create objects from iterables, map objects to arrays, and convert objects to JSON. @@ -110,6 +107,8 @@ Now you can map data into a `Shipping` object using `fromIterable`: ```php - ## License Mapper is licensed under [MIT](LICENSE). -
    - ## Contributing Please follow the [contributing guidelines](https://github.com/tiny-blocks/tiny-blocks/blob/main/CONTRIBUTING.md) to diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..3ec4904 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,12 @@ +# Security Policy + +## Supported versions + +Only the latest release receives security updates. + +## Reporting a vulnerability + +Report security vulnerabilities privately via +[GitHub Security Advisories](https://github.com/tiny-blocks/mapper/security/advisories/new). + +Please do not disclose the vulnerability publicly until it has been addressed. From e0e58632cb811e97cffe8ecc6010e6ccba732c18 Mon Sep 17 00:00:00 2001 From: Gustavo Freze Date: Sat, 16 May 2026 13:13:43 -0300 Subject: [PATCH 04/11] build: Update project tooling configuration. --- .editorconfig | 1 + .gitattributes | 4 ++- .gitignore | 27 +++++++++++-------- Makefile | 29 ++++++++++---------- composer.json | 34 ++++++++++++++--------- infection.json.dist | 10 +++---- phpcs.xml | 7 +++++ phpstan.neon.dist | 66 ++++++++++++++++++++++++++++++++++++--------- phpunit.xml | 22 ++++++++------- 9 files changed, 131 insertions(+), 69 deletions(-) create mode 100644 phpcs.xml diff --git a/.editorconfig b/.editorconfig index 73e3c9a..be5640e 100644 --- a/.editorconfig +++ b/.editorconfig @@ -5,6 +5,7 @@ charset = utf-8 end_of_line = lf indent_size = 4 indent_style = space +max_line_length = 120 insert_final_newline = true trim_trailing_whitespace = true diff --git a/.gitattributes b/.gitattributes index 744a43b..eedb473 100644 --- a/.gitattributes +++ b/.gitattributes @@ -2,7 +2,7 @@ *.php text diff=php -# Dev-only — excluded from the Packagist tarball +# Dev-only, excluded from the Packagist tarball /.github export-ignore /tests export-ignore /.claude export-ignore @@ -20,3 +20,5 @@ /Makefile export-ignore /CONTRIBUTING.md export-ignore /CHANGES.md export-ignore +/reports export-ignore +/.phpunit.cache export-ignore diff --git a/.gitignore b/.gitignore index bd5baa3..6107765 100644 --- a/.gitignore +++ b/.gitignore @@ -1,20 +1,25 @@ -# Agent/IDE -.claude/ -.idea/ -.vscode/ -.cursor/ - -# Composer +# PHP dependencies /vendor/ composer.lock -# PHPUnit / coverage +# Tooling cache +.phpcs-cache .phpunit.cache/ +.php-cs-fixer.cache .phpunit.result.cache -report/ -coverage/ + +# Coverage and reports build/ +reports/ +coverage/ +infection.log + +# Editors and agents +.idea/ +.cursor/ +.vscode/ # OS -.DS_Store Thumbs.db +.DS_Store +Desktop.ini diff --git a/Makefile b/Makefile index 07acc3b..4f0e85d 100644 --- a/Makefile +++ b/Makefile @@ -16,28 +16,27 @@ YELLOW := \033[0;33m .PHONY: configure configure: ## Configure development environment - @${DOCKER_RUN} composer update --optimize-autoloader - @${DOCKER_RUN} composer normalize + @${DOCKER_RUN} composer configure -.PHONY: test -test: ## Run all tests with coverage +.PHONY: configure-and-update +configure-and-update: ## Configure development environment and update dependencies + @${DOCKER_RUN} composer configure-and-update + +.PHONY: tests +tests: ## Run unit and mutation tests with coverage @${DOCKER_RUN} composer tests .PHONY: test-file test-file: ## Run tests for a specific file (usage: make test-file FILE=ClassNameTest) @${DOCKER_RUN} composer test-file ${FILE} -.PHONY: test-no-coverage -test-no-coverage: ## Run all tests without coverage - @${DOCKER_RUN} composer tests-no-coverage - .PHONY: review -review: ## Run static code analysis +review: ## Run lint and static analysis @${DOCKER_RUN} composer review .PHONY: show-reports -show-reports: ## Open static analysis reports (e.g., coverage, lints) in the browser - @sensible-browser report/coverage/coverage-html/index.html report/coverage/mutation-report.html +show-reports: ## Open coverage and mutation reports in the browser + @sensible-browser reports/coverage/coverage-html/index.html reports/coverage/mutation-report.html .PHONY: show-outdated show-outdated: ## Show outdated direct dependencies @@ -46,18 +45,18 @@ show-outdated: ## Show outdated direct dependencies .PHONY: clean clean: ## Remove dependencies and generated artifacts @sudo chown -R ${USER}:${USER} ${PWD} - @rm -rf report vendor .phpunit.cache *.lock + @rm -rf reports vendor .phpunit.cache *.lock .PHONY: help -help: ## Display this help message +help: ## Display this help message @echo "Usage: make [target]" @echo "" @echo "$$(printf '$(GREEN)')Setup$$(printf '$(RESET)')" - @grep -E '^(configure):.*?## .*$$' $(MAKEFILE_LIST) \ + @grep -E '^(configure|configure-and-update):.*?## .*$$' $(MAKEFILE_LIST) \ | awk 'BEGIN {FS = ":.*? ## "}; {printf "$(YELLOW)%-25s$(RESET) %s\n", $$1, $$2}' @echo "" @echo "$$(printf '$(GREEN)')Testing$$(printf '$(RESET)')" - @grep -E '^(test|test-file|test-no-coverage):.*?## .*$$' $(MAKEFILE_LIST) \ + @grep -E '^(tests|test-file):.*?## .*$$' $(MAKEFILE_LIST) \ | awk 'BEGIN {FS = ":.*?## "}; {printf "$(YELLOW)%-25s$(RESET) %s\n", $$1, $$2}' @echo "" @echo "$$(printf '$(GREEN)')Quality$$(printf '$(RESET)')" diff --git a/composer.json b/composer.json index 698a08b..2ce4fdf 100644 --- a/composer.json +++ b/composer.json @@ -3,6 +3,14 @@ "description": "Maps PHP objects to and from arrays, JSON, and iterables through reflection and pluggable strategies.", "license": "MIT", "type": "library", + "keywords": [ + "dto", + "mapper", + "hydration", + "tiny-blocks", + "object-mapper", + "serialization" + ], "authors": [ { "name": "Gustavo Freze de Araujo Santos", @@ -44,22 +52,22 @@ "sort-packages": true }, "scripts": { - "mutation-test": "php ./vendor/bin/infection --threads=max --logger-html=report/coverage/mutation-report.html --coverage=report/coverage", - "phpcs": "php ./vendor/bin/phpcs --standard=PSR12 --extensions=php ./src", - "phpstan": "php ./vendor/bin/phpstan analyse -c phpstan.neon.dist --quiet --no-progress", + "configure": [ + "@composer install --optimize-autoloader", + "@composer normalize" + ], + "configure-and-update": [ + "@composer update --optimize-autoloader", + "@composer normalize" + ], "review": [ - "@phpcs", - "@phpstan" + "@php ./vendor/bin/phpcs --standard=phpcs.xml --extensions=php ./src ./tests", + "@php ./vendor/bin/phpstan analyse -c phpstan.neon.dist --quiet --no-progress" ], - "test": "php -d memory_limit=2G ./vendor/bin/phpunit --configuration phpunit.xml tests", - "test-file": "php ./vendor/bin/phpunit --configuration phpunit.xml --no-coverage --filter", - "test-no-coverage": "php ./vendor/bin/phpunit --configuration phpunit.xml --no-coverage tests", + "test-file": "@php ./vendor/bin/phpunit --configuration phpunit.xml --no-coverage --filter", "tests": [ - "@test", - "@mutation-test" - ], - "tests-no-coverage": [ - "@test-no-coverage" + "@php -d memory_limit=2G ./vendor/bin/phpunit --configuration phpunit.xml tests", + "@php ./vendor/bin/infection --threads=max --logger-html=reports/coverage/mutation-report.html --coverage=reports/coverage" ] } } diff --git a/infection.json.dist b/infection.json.dist index 8d2a74e..aab8c7e 100644 --- a/infection.json.dist +++ b/infection.json.dist @@ -1,9 +1,9 @@ { "logs": { - "text": "report/infection/logs/infection-text.log", - "summary": "report/infection/logs/infection-summary.log" + "text": "reports/infection/logs/infection-text.log", + "summary": "reports/infection/logs/infection-summary.log" }, - "tmpDir": "report/infection/", + "tmpDir": "reports/infection/", "minMsi": 100, "timeout": 30, "source": { @@ -16,9 +16,7 @@ "customPath": "./vendor/bin/phpunit" }, "mutators": { - "@default": true, - "PublicVisibility": false, - "ProtectedVisibility": false + "@default": true }, "minCoveredMsi": 100, "testFramework": "phpunit" diff --git a/phpcs.xml b/phpcs.xml new file mode 100644 index 0000000..a52372c --- /dev/null +++ b/phpcs.xml @@ -0,0 +1,7 @@ + + + Code style for the tiny-blocks library. + + src + tests + diff --git a/phpstan.neon.dist b/phpstan.neon.dist index f699dd9..2e6df14 100644 --- a/phpstan.neon.dist +++ b/phpstan.neon.dist @@ -1,14 +1,54 @@ parameters: - paths: - - src - level: 9 - tmpDir: report/phpstan - ignoreErrors: - - '#T of#' - - '#mixed#' - - '#UnitEnum#' - - '#Reflection#' - - '#Traversable#' - - '#is used zero times#' - - '#type specified in iterable type#' - reportUnmatchedIgnoredErrors: false + level: max + paths: + - src + - tests + ignoreErrors: + # PHPDoc is prohibited inside src/Internal/ and tests/; typed-array information cannot be expressed. + - identifier: missingType.iterableValue + + # PHPDoc is prohibited inside src/Internal/ and tests/; generic class types cannot be expressed. + - identifier: missingType.generics + + # Reflection-driven mapping crosses the mixed-to-concrete boundary, where PHPStan cannot narrow. + - identifier: argument.type + + # Reflection-driven mapping returns concrete types that PHPStan cannot infer from mixed input. + - identifier: return.type + + # Enum casting iterates over cases() of a dynamic class resolved at runtime. + - identifier: foreach.nonIterable + path: src/Internal/Mappers/Object/Casters/EnumCaster.php + + # Enum casting reads $case->name on a value typed as mixed by the dynamic class lookup. + - identifier: property.nonObject + path: src/Internal/Mappers/Object/Casters/EnumCaster.php + + # Strategy dispatch invokes supports() on a strategy whose concrete type is not statically known. + - identifier: method.nonObject + path: src/Internal/Resolvers/StrategyResolver.php + + # Transformer operates on values typed as mixed at the public boundary of the mapper. + - identifier: method.nonObject + path: src/Internal/Transformers/DateTimeTransformer.php + + # Transformer operates on values typed as mixed at the public boundary of the mapper. + - identifier: property.nonObject + path: src/Internal/Transformers/EnumTransformer.php + + # Late static binding in the test collection fixture mirrors tiny-blocks/collection's extension-point shape. + - identifier: new.static + path: tests/Models/Collection.php + + # Test fixture properties are hydrated by the mapper; toArray reads them through reflection. + - identifier: property.onlyWritten + path: tests/Models/Configuration.php + + # Test fixture properties are hydrated by the mapper; toArray reads them through reflection. + - identifier: property.onlyWritten + path: tests/Models/Dragon.php + + # Iterator aggregate yields values whose concrete type is not statically known. + - identifier: property.nonObject + path: tests/Models/InvoiceSummaries.php + reportUnmatchedIgnoredErrors: true diff --git a/phpunit.xml b/phpunit.xml index 40c80a2..9cc6d13 100644 --- a/phpunit.xml +++ b/phpunit.xml @@ -1,13 +1,15 @@ + failOnDeprecation="true" + failOnNotice="true" + failOnPhpunitDeprecation="true" + failOnRisky="true" + failOnWarning="true"> @@ -23,15 +25,15 @@ - - - - + + + + - + From 7c55d9afb003e38a57644d8c805d7237aa2f5922 Mon Sep 17 00:00:00 2001 From: Gustavo Freze Date: Sat, 16 May 2026 13:13:51 -0300 Subject: [PATCH 05/11] refactor: Promote InvalidCast to the public Exceptions namespace. --- src/Exceptions/InvalidCast.php | 27 +++++++++++++++++++ src/Internal/Exceptions/InvalidCast.php | 16 ----------- .../Mappers/Object/Casters/Caster.php | 2 +- .../Mappers/Object/Casters/EnumCaster.php | 2 +- src/ObjectMapper.php | 2 +- 5 files changed, 30 insertions(+), 19 deletions(-) create mode 100644 src/Exceptions/InvalidCast.php delete mode 100644 src/Internal/Exceptions/InvalidCast.php diff --git a/src/Exceptions/InvalidCast.php b/src/Exceptions/InvalidCast.php new file mode 100644 index 0000000..db05afc --- /dev/null +++ b/src/Exceptions/InvalidCast.php @@ -0,0 +1,27 @@ + for enum <%s>.'; + + return new InvalidCast(message: sprintf($template, $value, $class)); + } +} diff --git a/src/Internal/Exceptions/InvalidCast.php b/src/Internal/Exceptions/InvalidCast.php deleted file mode 100644 index f70e5a0..0000000 --- a/src/Internal/Exceptions/InvalidCast.php +++ /dev/null @@ -1,16 +0,0 @@ - for enum <%s>.', $value, $class); - return new InvalidCast(message: $message); - } -} diff --git a/src/Internal/Mappers/Object/Casters/Caster.php b/src/Internal/Mappers/Object/Casters/Caster.php index 1f60990..83dc343 100644 --- a/src/Internal/Mappers/Object/Casters/Caster.php +++ b/src/Internal/Mappers/Object/Casters/Caster.php @@ -4,7 +4,7 @@ namespace TinyBlocks\Mapper\Internal\Mappers\Object\Casters; -use TinyBlocks\Mapper\Internal\Exceptions\InvalidCast; +use TinyBlocks\Mapper\Exceptions\InvalidCast; /** * Responsible for applying a cast to values, based on a specific type. diff --git a/src/Internal/Mappers/Object/Casters/EnumCaster.php b/src/Internal/Mappers/Object/Casters/EnumCaster.php index 73c78a1..bb69c9c 100644 --- a/src/Internal/Mappers/Object/Casters/EnumCaster.php +++ b/src/Internal/Mappers/Object/Casters/EnumCaster.php @@ -5,7 +5,7 @@ namespace TinyBlocks\Mapper\Internal\Mappers\Object\Casters; use BackedEnum; -use TinyBlocks\Mapper\Internal\Exceptions\InvalidCast; +use TinyBlocks\Mapper\Exceptions\InvalidCast; use UnitEnum; final readonly class EnumCaster implements Caster diff --git a/src/ObjectMapper.php b/src/ObjectMapper.php index c71df03..0db1620 100644 --- a/src/ObjectMapper.php +++ b/src/ObjectMapper.php @@ -4,7 +4,7 @@ namespace TinyBlocks\Mapper; -use TinyBlocks\Mapper\Internal\Exceptions\InvalidCast; +use TinyBlocks\Mapper\Exceptions\InvalidCast; /** * Defines methods for converting objects or collections of objects to JSON, arrays, From 6e2dac752310d40dcc80cc4dcedae8387cfdf64b Mon Sep 17 00:00:00 2001 From: Gustavo Freze Date: Sat, 16 May 2026 13:13:51 -0300 Subject: [PATCH 06/11] refactor: Inline construction logic in ObjectBuilder. --- src/Internal/Builders/ObjectBuilder.php | 82 ++++--------------- .../Extractors/ReflectionExtractor.php | 18 +--- src/ObjectMappability.php | 5 +- 3 files changed, 18 insertions(+), 87 deletions(-) diff --git a/src/Internal/Builders/ObjectBuilder.php b/src/Internal/Builders/ObjectBuilder.php index dc134ff..41e2ef9 100644 --- a/src/Internal/Builders/ObjectBuilder.php +++ b/src/Internal/Builders/ObjectBuilder.php @@ -5,48 +5,29 @@ namespace TinyBlocks\Mapper\Internal\Builders; use ReflectionClass; -use ReflectionException; -use ReflectionMethod; -use ReflectionParameter; -use TinyBlocks\Mapper\Internal\Extractors\ReflectionExtractor; use TinyBlocks\Mapper\Internal\Mappers\Object\Casters\CasterResolver; final readonly class ObjectBuilder { - public function __construct(private ReflectionExtractor $extractor) - { - } - - /** - * @template T of object - * @param class-string $class - * @return T - * @throws ReflectionException - */ public function build(iterable $iterable, string $class): object { $reflection = new ReflectionClass(objectOrClass: $class); - $parameters = $this->extractor->extractConstructorParameters(class: $class); - $inputProperties = iterator_to_array(iterator: $iterable); - - $arguments = $this->buildArguments( - parameters: $parameters, - inputProperties: $inputProperties - ); + $constructor = $reflection->getConstructor(); + $inputProperties = iterator_to_array($iterable); - return $this->instantiate(reflection: $reflection, arguments: $arguments); - } + if (is_null($constructor)) { + return $reflection->newInstance(); + } - protected function buildArguments(array $parameters, array $inputProperties): array - { $arguments = []; - /** @var ReflectionParameter $parameter */ - foreach ($parameters as $parameter) { + foreach ($constructor->getParameters() as $parameter) { $name = $parameter->getName(); if (!array_key_exists($name, $inputProperties)) { - $arguments[] = $this->getDefaultValue(parameter: $parameter); + $arguments[] = $parameter->isDefaultValueAvailable() + ? $parameter->getDefaultValue() + : null; continue; } @@ -57,51 +38,16 @@ protected function buildArguments(array $parameters, array $inputProperties): ar continue; } - $arguments[] = $this->castValue(parameter: $parameter, value: $value); - } - - return $arguments; - } - - protected function castValue(ReflectionParameter $parameter, mixed $value): mixed - { - $caster = new CasterResolver(parameter: $parameter); - return $caster->castValue(value: $value); - } - - protected function getDefaultValue(ReflectionParameter $parameter): mixed - { - return $parameter->isDefaultValueAvailable() - ? $parameter->getDefaultValue() - : null; - } - - protected function instantiate(ReflectionClass $reflection, array $arguments): object - { - $constructor = $reflection->getConstructor(); - - if ($constructor === null) { - return $reflection->newInstance(); + $arguments[] = new CasterResolver(parameter: $parameter)->castValue(value: $value); } if ($constructor->isPrivate()) { - return $this->instantiateWithPrivateConstructor( - reflection: $reflection, - constructor: $constructor, - arguments: $arguments - ); + $instance = $reflection->newInstanceWithoutConstructor(); + $constructor->invokeArgs(object: $instance, args: $arguments); + + return $instance; } return $reflection->newInstanceArgs(args: $arguments); } - - protected function instantiateWithPrivateConstructor( - ReflectionClass $reflection, - ReflectionMethod $constructor, - array $arguments - ): object { - $instance = $reflection->newInstanceWithoutConstructor(); - $constructor->invokeArgs(object: $instance, args: $arguments); - return $instance; - } } diff --git a/src/Internal/Extractors/ReflectionExtractor.php b/src/Internal/Extractors/ReflectionExtractor.php index 20dfbea..cbc6201 100644 --- a/src/Internal/Extractors/ReflectionExtractor.php +++ b/src/Internal/Extractors/ReflectionExtractor.php @@ -13,9 +13,9 @@ public function extractProperties(object $object): array { $reflection = new ReflectionClass(objectOrClass: $object); $properties = $reflection->getProperties( - ReflectionProperty::IS_PUBLIC - | ReflectionProperty::IS_PROTECTED - | ReflectionProperty::IS_PRIVATE + filter: ReflectionProperty::IS_PUBLIC + | ReflectionProperty::IS_PROTECTED + | ReflectionProperty::IS_PRIVATE ); $extracted = []; @@ -30,16 +30,4 @@ public function extractProperties(object $object): array return $extracted; } - - public function extractConstructorParameters(string $class): array - { - $reflection = new ReflectionClass(objectOrClass: $class); - $constructor = $reflection->getConstructor(); - - if (is_null($constructor)) { - return []; - } - - return $constructor->getParameters(); - } } diff --git a/src/ObjectMappability.php b/src/ObjectMappability.php index ce50b99..fb20c50 100644 --- a/src/ObjectMappability.php +++ b/src/ObjectMappability.php @@ -5,7 +5,6 @@ namespace TinyBlocks\Mapper; use TinyBlocks\Mapper\Internal\Builders\ObjectBuilder; -use TinyBlocks\Mapper\Internal\Extractors\ReflectionExtractor; use TinyBlocks\Mapper\Internal\MappabilityBehavior; trait ObjectMappability @@ -14,8 +13,6 @@ trait ObjectMappability public static function fromIterable(iterable $iterable): static { - $extractor = new ReflectionExtractor(); - - return new ObjectBuilder(extractor: $extractor)->build(iterable: $iterable, class: static::class); + return new ObjectBuilder()->build(iterable: $iterable, class: static::class); } } From 2740e6fccae951b631dfac41a35e4f9013de70ca Mon Sep 17 00:00:00 2001 From: Gustavo Freze Date: Sat, 16 May 2026 13:14:00 -0300 Subject: [PATCH 07/11] refactor: Apply named arguments and tidy internal classes. --- src/Internal/Detectors/ValueObjectDetector.php | 8 ++++---- src/Internal/Extractors/ValuePropertyExtractor.php | 2 +- src/Internal/Mappers/Object/Casters/DefaultCaster.php | 2 +- src/Internal/Mappers/Object/Casters/GeneratorCaster.php | 6 +++--- src/Internal/Mappers/Object/Casters/Reflector.php | 4 ++-- src/Internal/Resolvers/RecursiveValueResolver.php | 2 +- src/Internal/Resolvers/StrategyResolverContainer.php | 8 ++++---- src/Internal/Strategies/IterableMappingStrategy.php | 2 +- 8 files changed, 17 insertions(+), 17 deletions(-) diff --git a/src/Internal/Detectors/ValueObjectDetector.php b/src/Internal/Detectors/ValueObjectDetector.php index d9f0f93..2965bda 100644 --- a/src/Internal/Detectors/ValueObjectDetector.php +++ b/src/Internal/Detectors/ValueObjectDetector.php @@ -14,11 +14,11 @@ public function matches(mixed $value): bool { - $reflection = new ReflectionClass($value); + $reflection = new ReflectionClass(objectOrClass: $value); $properties = $reflection->getProperties( - ReflectionProperty::IS_PUBLIC - | ReflectionProperty::IS_PROTECTED - | ReflectionProperty::IS_PRIVATE + filter: ReflectionProperty::IS_PUBLIC + | ReflectionProperty::IS_PROTECTED + | ReflectionProperty::IS_PRIVATE ); return !$value instanceof UnitEnum && count($properties) === self::SINGLE_PROPERTY; diff --git a/src/Internal/Extractors/ValuePropertyExtractor.php b/src/Internal/Extractors/ValuePropertyExtractor.php index c37abe7..43b3ad4 100644 --- a/src/Internal/Extractors/ValuePropertyExtractor.php +++ b/src/Internal/Extractors/ValuePropertyExtractor.php @@ -10,6 +10,6 @@ { public function extract(object $object): mixed { - return new ReflectionClass($object)->getProperties()[0]->getValue($object); + return new ReflectionClass(objectOrClass: $object)->getProperties()[0]->getValue(object: $object); } } diff --git a/src/Internal/Mappers/Object/Casters/DefaultCaster.php b/src/Internal/Mappers/Object/Casters/DefaultCaster.php index c9d9757..45df0a5 100644 --- a/src/Internal/Mappers/Object/Casters/DefaultCaster.php +++ b/src/Internal/Mappers/Object/Casters/DefaultCaster.php @@ -12,7 +12,7 @@ public function __construct(private string $class) public function castValue(mixed $value): mixed { - if (!class_exists(class: $this->class) || $value instanceof $this->class) { + if (!class_exists($this->class) || $value instanceof $this->class) { return $value; } diff --git a/src/Internal/Mappers/Object/Casters/GeneratorCaster.php b/src/Internal/Mappers/Object/Casters/GeneratorCaster.php index 4f1af87..227114a 100644 --- a/src/Internal/Mappers/Object/Casters/GeneratorCaster.php +++ b/src/Internal/Mappers/Object/Casters/GeneratorCaster.php @@ -10,9 +10,9 @@ { public function castValue(mixed $value): Generator { - if (is_iterable(value: $value)) { - foreach ($value as $item) { - yield $item; + if (is_iterable($value)) { + foreach ($value as $element) { + yield $element; } return; diff --git a/src/Internal/Mappers/Object/Casters/Reflector.php b/src/Internal/Mappers/Object/Casters/Reflector.php index 813fa60..c54ba9f 100644 --- a/src/Internal/Mappers/Object/Casters/Reflector.php +++ b/src/Internal/Mappers/Object/Casters/Reflector.php @@ -14,11 +14,11 @@ private function __construct(private ReflectionClass $reflectionClass) public static function reflectFrom(string $class): Reflector { - return new Reflector(reflectionClass: new ReflectionClass($class)); + return new Reflector(reflectionClass: new ReflectionClass(objectOrClass: $class)); } public function newInstance(array $constructorArguments): object { - return $this->reflectionClass->newInstanceArgs($constructorArguments); + return $this->reflectionClass->newInstanceArgs(args: $constructorArguments); } } diff --git a/src/Internal/Resolvers/RecursiveValueResolver.php b/src/Internal/Resolvers/RecursiveValueResolver.php index f6b2b38..370e3bb 100644 --- a/src/Internal/Resolvers/RecursiveValueResolver.php +++ b/src/Internal/Resolvers/RecursiveValueResolver.php @@ -30,7 +30,7 @@ public function resolve(mixed $value, KeyPreservation $keyPreservation): mixed if (is_array($value)) { $mapped = array_map( - fn(mixed $item): mixed => $this->resolve(value: $item, keyPreservation: $keyPreservation), + fn(mixed $element): mixed => $this->resolve(value: $element, keyPreservation: $keyPreservation), $value ); diff --git a/src/Internal/Resolvers/StrategyResolverContainer.php b/src/Internal/Resolvers/StrategyResolverContainer.php index ddde1de..6357557 100644 --- a/src/Internal/Resolvers/StrategyResolverContainer.php +++ b/src/Internal/Resolvers/StrategyResolverContainer.php @@ -8,13 +8,13 @@ final class StrategyResolverContainer { private StrategyResolver $resolver; - public function set(StrategyResolver $resolver): void + public function get(): StrategyResolver { - $this->resolver = $resolver; + return $this->resolver; } - public function get(): StrategyResolver + public function set(StrategyResolver $resolver): void { - return $this->resolver; + $this->resolver = $resolver; } } diff --git a/src/Internal/Strategies/IterableMappingStrategy.php b/src/Internal/Strategies/IterableMappingStrategy.php index 19a69c6..6ee18ef 100644 --- a/src/Internal/Strategies/IterableMappingStrategy.php +++ b/src/Internal/Strategies/IterableMappingStrategy.php @@ -18,7 +18,7 @@ public function __construct(private IterableExtractor $extractor, private Recurs public function map(mixed $value, KeyPreservation $keyPreservation): array { $mapped = array_map( - fn(mixed $item): mixed => $this->resolver->resolve(value: $item, keyPreservation: $keyPreservation), + fn(mixed $element): mixed => $this->resolver->resolve(value: $element, keyPreservation: $keyPreservation), $this->extractor->extract(object: $value) ); From 2c95410a4aa11cb9d610f1d672ac06bb45e41031 Mon Sep 17 00:00:00 2001 From: Gustavo Freze Date: Sat, 16 May 2026 13:14:00 -0300 Subject: [PATCH 08/11] docs: Improve PHPDoc for transformer contract and public traits. --- src/Internal/Transformers/Transformer.php | 20 +++++++++++++++++--- src/IterableMapper.php | 2 +- src/KeyPreservation.php | 2 +- 3 files changed, 19 insertions(+), 5 deletions(-) diff --git a/src/Internal/Transformers/Transformer.php b/src/Internal/Transformers/Transformer.php index 470b70a..05fa2ef 100644 --- a/src/Internal/Transformers/Transformer.php +++ b/src/Internal/Transformers/Transformer.php @@ -5,15 +5,29 @@ namespace TinyBlocks\Mapper\Internal\Transformers; /** - * Defines the contract for value transformation strategies. + * Transforms a value into a different representation as part of the mapping pipeline. + * + *

    The verb transform is intentional. Value transformation is the operation + * that motivates this library: every strategy, caster, resolver, and mapper exists to drive + * concrete Transformer implementations. The anemic-verb prohibition from + * php-library-modeling.md exempts verbs that constitute the library's reason to + * exist; this method is the canonical case.

    + * + * @see TinyBlocks\Mapper\Internal\Transformers\DateTimeTransformer + * @see TinyBlocks\Mapper\Internal\Transformers\EnumTransformer + * @see TinyBlocks\Mapper\Internal\Transformers\ValueObjectUnwrapper */ interface Transformer { /** - * Transforms a value according to the implementation strategy. + * Transforms the given value according to this transformer's contract. + * + *

    Each implementation describes the specific transformation it performs (date + * formatting, enum-to-scalar, value object unwrapping). The base contract guarantees + * the input is not mutated.

    * * @param mixed $value The value to transform. - * @return mixed The transformed value. + * @return mixed The transformed value, as the concrete implementation defines it. */ public function transform(mixed $value): mixed; } diff --git a/src/IterableMapper.php b/src/IterableMapper.php index 3fd5161..23c1de4 100644 --- a/src/IterableMapper.php +++ b/src/IterableMapper.php @@ -10,7 +10,7 @@ interface IterableMapper extends Mapper { /** - * Get the type of the iterable collection of objects. + * Returns the type of the iterable collection of objects. * * @return string The type of the objects in the collection. */ diff --git a/src/KeyPreservation.php b/src/KeyPreservation.php index 494f247..cdd44c5 100644 --- a/src/KeyPreservation.php +++ b/src/KeyPreservation.php @@ -20,7 +20,7 @@ enum KeyPreservation case PRESERVE; /** - * Determines if keys should be preserved. + * Tells whether keys should be preserved. * * @return bool Returns true if the keys should be preserved, false otherwise. */ From 2a5ef1f6120fd27a62a67d17043e561b273f8d78 Mon Sep 17 00:00:00 2001 From: Gustavo Freze Date: Sat, 16 May 2026 13:14:00 -0300 Subject: [PATCH 09/11] test: Move tests under Unit namespace and cover enum passthrough. --- tests/{ => Unit}/CollectionMappingTest.php | 2 +- tests/{ => Unit}/EnumMappingTest.php | 28 +++-- tests/{ => Unit}/ObjectMappingTest.php | 127 ++++++++++++++------- 3 files changed, 105 insertions(+), 52 deletions(-) rename tests/{ => Unit}/CollectionMappingTest.php (99%) rename tests/{ => Unit}/EnumMappingTest.php (82%) rename tests/{ => Unit}/ObjectMappingTest.php (81%) diff --git a/tests/CollectionMappingTest.php b/tests/Unit/CollectionMappingTest.php similarity index 99% rename from tests/CollectionMappingTest.php rename to tests/Unit/CollectionMappingTest.php index 7ac48df..bc4a67b 100644 --- a/tests/CollectionMappingTest.php +++ b/tests/Unit/CollectionMappingTest.php @@ -2,7 +2,7 @@ declare(strict_types=1); -namespace Test\TinyBlocks\Mapper; +namespace Test\TinyBlocks\Mapper\Unit; use ArrayIterator; use DateTimeImmutable; diff --git a/tests/EnumMappingTest.php b/tests/Unit/EnumMappingTest.php similarity index 82% rename from tests/EnumMappingTest.php rename to tests/Unit/EnumMappingTest.php index 2f39c31..ca39610 100644 --- a/tests/EnumMappingTest.php +++ b/tests/Unit/EnumMappingTest.php @@ -2,7 +2,7 @@ declare(strict_types=1); -namespace Test\TinyBlocks\Mapper; +namespace Test\TinyBlocks\Mapper\Unit; use PHPUnit\Framework\TestCase; use Test\TinyBlocks\Mapper\Models\Alert; @@ -10,9 +10,10 @@ use Test\TinyBlocks\Mapper\Models\Dragon; use Test\TinyBlocks\Mapper\Models\DragonSkills; use Test\TinyBlocks\Mapper\Models\DragonType; +use Test\TinyBlocks\Mapper\Models\Priority; use Test\TinyBlocks\Mapper\Models\Severity; use Test\TinyBlocks\Mapper\Models\Task; -use TinyBlocks\Mapper\Internal\Exceptions\InvalidCast; +use TinyBlocks\Mapper\Exceptions\InvalidCast; final class EnumMappingTest extends TestCase { @@ -99,18 +100,13 @@ public function testEnumBackedString(): void public function testEnumWhenInvalidCast(): void { - /** @Given data with an invalid currency value */ - $data = [ - 'value' => 250.00, - 'currency' => 'INVALID' - ]; - + /** @Given an iterable with an invalid currency value */ /** @Then an exception should be thrown */ $this->expectException(InvalidCast::class); $this->expectExceptionMessage('Invalid value for enum .'); - /** @When creating from iterable */ - Amount::fromIterable(iterable: $data); + /** @When creating an Amount from the iterable */ + Amount::fromIterable(iterable: ['value' => 250.00, 'currency' => 'INVALID']); } public function testPureEnumRoundTripsByCaseName(): void @@ -132,4 +128,16 @@ public function testPureEnumWhenInvalidCaseName(): void /** @When mapping an Alert with a case name that does not exist */ Alert::fromIterable(iterable: ['severity' => 'UNKNOWN']); } + + public function testEnumCasterPassesThroughExistingEnumInstance(): void + { + /** @Given an iterable that already holds an enum instance for the priority value */ + $iterable = ['title' => 'Build feature', 'priority' => Priority::HIGH]; + + /** @When the Task is hydrated from the iterable */ + $task = Task::fromIterable(iterable: $iterable); + + /** @Then the priority is the same enum instance, untouched by any cast path */ + self::assertSame(Priority::HIGH, $task->priority); + } } diff --git a/tests/ObjectMappingTest.php b/tests/Unit/ObjectMappingTest.php similarity index 81% rename from tests/ObjectMappingTest.php rename to tests/Unit/ObjectMappingTest.php index a635524..d33c702 100644 --- a/tests/ObjectMappingTest.php +++ b/tests/Unit/ObjectMappingTest.php @@ -2,7 +2,7 @@ declare(strict_types=1); -namespace Test\TinyBlocks\Mapper; +namespace Test\TinyBlocks\Mapper\Unit; use ArrayIterator; use DateTimeImmutable; @@ -38,12 +38,9 @@ final class ObjectMappingTest extends TestCase { #[DataProvider('objectProvider')] - public function testObject(string $class, iterable $iterable, array $expected): void + public function testObject(ObjectMapper $object, array $expected): void { - /** @Given an Object */ - /** @var ObjectMapper $class */ - $object = $class::fromIterable(iterable: $iterable); - + /** @Given an ObjectMapper bound by the provider */ /** @When mapping the object to an array */ $actual = $object->toArray(); @@ -57,23 +54,43 @@ public function testObject(string $class, iterable $iterable, array $expected): self::assertJsonStringEqualsJsonString((string)json_encode($expected), $actual); } - public function testObjectWithGenerator(): void + public function testObjectWithGeneratorMapsToArray(): void { - /** @Given an Order with a Generator of items */ + /** @Given a generator yielding three order items */ + $items = (function (): Generator { + yield ['sku' => 'ITEM-001', 'quantity' => 2]; + yield ['sku' => 'ITEM-002', 'quantity' => 1]; + yield ['sku' => 'ITEM-003', 'quantity' => 5]; + })(); + + /** @And an order built from the generator with an id and timestamp */ $order = new Order( id: new Uuid(value: '123e4567-e89b-12d3-a456-426614174000'), - items: (function (): Generator { - yield ['sku' => 'ITEM-001', 'quantity' => 2]; - yield ['sku' => 'ITEM-002', 'quantity' => 1]; - yield ['sku' => 'ITEM-003', 'quantity' => 5]; - })(), + items: $items, createdAt: new DateTimeImmutable('2025-01-01 10:00:00', new DateTimeZone('UTC')) ); - /** @When mapping the Order to an array */ + /** @When the order is mapped to an array */ $actual = $order->toArray(); - /** @Then the mapped array should have expected values */ + /** @Then the array carries every item in iteration order alongside the id and createdAt */ + self::assertSame( + [ + 'id' => '123e4567-e89b-12d3-a456-426614174000', + 'items' => [ + ['sku' => 'ITEM-001', 'quantity' => 2], + ['sku' => 'ITEM-002', 'quantity' => 1], + ['sku' => 'ITEM-003', 'quantity' => 5] + ], + 'createdAt' => '2025-01-01T10:00:00+00:00' + ], + $actual + ); + } + + public function testOrderRoundTripsFromIterableToJson(): void + { + /** @Given an iterable representation of an order with array items */ $expected = [ 'id' => '123e4567-e89b-12d3-a456-426614174000', 'items' => [ @@ -84,13 +101,13 @@ public function testObjectWithGenerator(): void 'createdAt' => '2025-01-01T10:00:00+00:00' ]; - self::assertSame($expected, $actual); - - /** @And when mapping the Order to JSON */ + /** @And an order rebuilt from the iterable via the static factory */ $order = Order::fromIterable(iterable: $expected); + + /** @When the order is mapped to JSON */ $actual = $order->toJson(); - /** @Then the mapped JSON should have expected values */ + /** @Then the JSON payload carries every item in iteration order alongside the id and createdAt */ self::assertJsonStringEqualsJsonString((string)json_encode($expected), $actual); } @@ -115,7 +132,11 @@ public function testObjectWithoutConstructor(): void { /** @Given a Webhook with no constructor */ $webhook = new Webhook(); + + /** @And a URL assigned to the Webhook */ $webhook->url = 'https://example.com/hook'; + + /** @And the Webhook marked active */ $webhook->active = true; /** @When mapping the Webhook to an array */ @@ -138,10 +159,16 @@ public function testObjectWithoutConstructor(): void public function testObjectWithStaticProperties(): void { - /** @Given a Webhook with no constructor and static properties */ + /** @Given a Webhook with no constructor */ $webhook = new Webhook(); + + /** @And a URL assigned to the Webhook */ $webhook->url = 'https://example.com/static-test'; + + /** @And the Webhook marked active */ $webhook->active = true; + + /** @And a static timeout configured on the class */ Webhook::$timeout = 60; /** @When mapping the Webhook to an array */ @@ -195,8 +222,8 @@ public function testObjectWithNonIterableGeneratorValue(): void /** @Then the mapped array should have expected values */ $expected = [ - 'id' => [42,], - 'options' => ['single-option'], + 'id' => [42], + 'options' => ['single-option'] ]; self::assertSame($expected, $actual); @@ -306,42 +333,62 @@ public function testObjectContinuesIteratingParametersAfterNullValue(): void self::assertSame('second-value', $pair->second); } + public function testFromIterableHydratesClassWithoutConstructor(): void + { + /** @Given an iterable with values that do not correspond to constructor parameters */ + $iterable = ['url' => 'https://example.com/hook', 'active' => true]; + + /** @When the Webhook (which has no constructor) is hydrated from the iterable */ + $webhook = Webhook::fromIterable(iterable: $iterable); + + /** @Then the instance is created with its declared default property values */ + self::assertSame('', $webhook->url); + self::assertFalse($webhook->active); + } + + public function testObjectFallsBackToNullWhenKeyIsMissingAndNoDefaultExists(): void + { + /** @Given a Pair whose nullable first parameter has no default and no entry in the iterable */ + /** @When the Pair is hydrated with only the second parameter */ + $pair = Pair::fromIterable(iterable: ['second' => 'second-value']); + + /** @Then the missing parameter is populated with null and the provided one carries through */ + self::assertNull($pair->first); + self::assertSame('second-value', $pair->second); + } + public static function objectProvider(): array { return [ 'Tag object' => [ - 'class' => Tag::class, - 'iterable' => [], + 'object' => Tag::fromIterable(iterable: []), 'expected' => [ 'name' => '', 'color' => 'gray' ] ], 'Member object' => [ - 'class' => Member::class, - 'iterable' => [ + 'object' => Member::fromIterable(iterable: [ 'id' => new MemberId(value: new Uuid(value: '88f15d3f-c9b9-4855-9778-5ba7926b6736')), 'role' => 'owner', 'isOwner' => true, 'organizationId' => new OrganizationId( value: new Uuid(value: 'dc0dbdfd-9f8d-43c9-a000-19bcc989d20a23') ) - ], + ]), 'expected' => [ 'id' => '88f15d3f-c9b9-4855-9778-5ba7926b6736', 'role' => 'owner', 'isOwner' => true, 'organizationId' => 'dc0dbdfd-9f8d-43c9-a000-19bcc989d20a23' - ], + ] ], 'Service object' => [ - 'class' => Service::class, - 'iterable' => ['action' => static fn() => 'executed'], + 'object' => Service::fromIterable(iterable: ['action' => static fn() => 'executed']), 'expected' => ['action' => []] ], 'Product object' => [ - 'class' => Product::class, - 'iterable' => [ + 'object' => Product::fromIterable(iterable: [ 'id' => 1, 'amount' => Amount::from(value: 99.99, currency: Currency::USD), 'description' => new Description(text: 'A high-quality product'), @@ -353,7 +400,7 @@ public static function objectProvider(): array 'inventory' => ['stock' => 100, 'warehouse' => 'A1'], 'status' => ProductStatus::ACTIVE, 'createdAt' => new DateTimeImmutable('2026-01-01T10:00:00+00:00') - ], + ]), 'expected' => [ 'id' => 1, 'amount' => ['value' => 99.99, 'currency' => 'USD'], @@ -362,23 +409,21 @@ public static function objectProvider(): array 'inventory' => ['stock' => 100, 'warehouse' => 'A1'], 'status' => 1, 'createdAt' => '2026-01-01T10:00:00+00:00' - ], + ] ], 'Employee object' => [ - 'class' => Employee::class, - 'iterable' => [ + 'object' => Employee::fromIterable(iterable: [ 'name' => 'John', 'active' => false - ], + ]), 'expected' => [ 'name' => 'John', 'department' => 'general', 'active' => false - ], + ] ], 'Organization object' => [ - 'class' => Organization::class, - 'iterable' => [ + 'object' => Organization::fromIterable(iterable: [ 'id' => new OrganizationId( value: new Uuid(value: 'dc0dbdfd-9f8d-43c9-a000-19bcc989d20a23') ), @@ -402,7 +447,7 @@ public static function objectProvider(): array ) ]), 'invitations' => [] - ], + ]), 'expected' => [ 'id' => 'dc0dbdfd-9f8d-43c9-a000-19bcc989d20a23', 'name' => 'Tech Corp', From 1146cdb62e01f460881f5157d4a08f4ea7a43ce5 Mon Sep 17 00:00:00 2001 From: Gustavo Freze Date: Sat, 16 May 2026 13:18:16 -0300 Subject: [PATCH 10/11] chore: Update auto-assign action to version 2.1.0. --- .github/workflows/auto-assign.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/auto-assign.yml b/.github/workflows/auto-assign.yml index fe2b34c..e87e331 100644 --- a/.github/workflows/auto-assign.yml +++ b/.github/workflows/auto-assign.yml @@ -23,7 +23,7 @@ jobs: timeout-minutes: 5 steps: - name: Assign issues and pull requests - uses: gustavofreze/auto-assign@2 + uses: gustavofreze/auto-assign@2.1.0 with: assignees: '${{ vars.ASSIGNEES }}' github_token: '${{ secrets.GITHUB_TOKEN }}' From 7f71eb706cbfdaf47b7c2390fab2ded04111159e Mon Sep 17 00:00:00 2001 From: Gustavo Freze Date: Sat, 16 May 2026 13:19:39 -0300 Subject: [PATCH 11/11] chore: Add additional keywords to composer.json for improved package discovery. --- composer.json | 3 +++ 1 file changed, 3 insertions(+) diff --git a/composer.json b/composer.json index 2ce4fdf..e1ce1d8 100644 --- a/composer.json +++ b/composer.json @@ -5,6 +5,9 @@ "type": "library", "keywords": [ "dto", + "json", + "array", + "object", "mapper", "hydration", "tiny-blocks",