diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 233598b..a561aa6 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -1,31 +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` — runs PHPUnit (with coverage) and Infection (mutation testing) sequentially via `composer tests`. -- `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..465c32c 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,417 @@ 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. +- 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/`. +- 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/`** → suppress via `ignoreErrors`. Do not add PHPDoc. +- 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 anything inside `src/Internal/`: + +```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.** 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 +426,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 4791cb9..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 **license** badge. Do not include any other badges. -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/.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/.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/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. diff --git a/.github/workflows/auto-assign.yml b/.github/workflows/auto-assign.yml index d0ba49e..e87e331 100644 --- a/.github/workflows/auto-assign.yml +++ b/.github/workflows/auto-assign.yml @@ -8,12 +8,19 @@ 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 @@ -22,4 +29,4 @@ jobs: 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 20e7fbf..0ad023a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -11,8 +11,8 @@ permissions: contents: read jobs: - load-config: - name: Load config + resolve-php-version: + name: Resolve PHP version runs-on: ubuntu-latest timeout-minutes: 5 outputs: @@ -29,7 +29,7 @@ jobs: build: name: Build - needs: load-config + needs: resolve-php-version runs-on: ubuntu-latest timeout-minutes: 15 steps: @@ -40,7 +40,7 @@ jobs: uses: shivammathur/setup-php@v2 with: tools: composer:2 - php-version: ${{ needs.load-config.outputs.php-version }} + php-version: ${{ needs.resolve-php-version.outputs.php-version }} - name: Validate composer.json run: composer validate --no-interaction @@ -58,7 +58,7 @@ jobs: auto-review: name: Auto review - needs: [load-config, build] + needs: [resolve-php-version, build] runs-on: ubuntu-latest timeout-minutes: 15 steps: @@ -69,7 +69,7 @@ jobs: uses: shivammathur/setup-php@v2 with: tools: composer:2 - php-version: ${{ needs.load-config.outputs.php-version }} + php-version: ${{ needs.resolve-php-version.outputs.php-version }} - name: Download vendor artifact from build uses: actions/download-artifact@v8 @@ -82,7 +82,7 @@ jobs: tests: name: Tests - needs: [load-config, auto-review] + needs: [resolve-php-version, auto-review] runs-on: ubuntu-latest timeout-minutes: 15 env: @@ -99,7 +99,7 @@ jobs: uses: shivammathur/setup-php@v2 with: tools: composer:2 - php-version: ${{ needs.load-config.outputs.php-version }} + 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..ea6d12e 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -1,13 +1,17 @@ -name: Security checks +name: CodeQL on: push: - branches: [ "main" ] + branches: ["main"] pull_request: - branches: [ "main" ] + branches: ["main"] 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" ] - + language: ["actions"] steps: - name: Checkout repository uses: actions/checkout@v6 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 6d6ada2..fbabced 100644 --- a/Makefile +++ b/Makefile @@ -24,28 +24,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 @@ -54,18 +53,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/README.md b/README.md index c1ad7f2..cb6b146 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,6 @@ + [Producing events from an aggregate](#producing-events-from-an-aggregate) + [Customizing the table layout](#customizing-the-table-layout) + [Writing a custom payload serializer](#writing-a-custom-payload-serializer) - + [Writing a custom snapshot serializer](#writing-a-custom-snapshot-serializer) + [Event schema versioning](#event-schema-versioning) * [FAQ](#faq) * [License](#license) @@ -29,8 +28,7 @@ name, column names, and identity column storage type are all configurable. The library composes with [`tiny-blocks/building-blocks`](https://github.com/tiny-blocks/building-blocks), which contributes `DomainEvent`, `DomainEventBehavior`, `EventRecord`, `EventRecords`, `EventType`, `Revision`, -`SequenceNumber`, `SnapshotData`, and the `EventualAggregateRoot` family. This library provides the persistence step -only. +`AggregateVersion`, and the `EventualAggregateRoot` family. This library provides the persistence step only. ## Installation @@ -47,40 +45,44 @@ The library does not create or manage the outbox table. Add it in your own migra **Default schema (BINARY(16) identity columns, recommended for UUID-based aggregates):** ```sql -CREATE TABLE outbox_events ( - sequence BIGINT NOT NULL AUTO_INCREMENT UNIQUE, - id BINARY(16) NOT NULL PRIMARY KEY, - aggregate_type VARCHAR(255) NOT NULL, - aggregate_id BINARY(16) NOT NULL, - event_type VARCHAR(255) NOT NULL, - revision INT NOT NULL, - sequence_number BIGINT NOT NULL, - payload JSON NOT NULL, - snapshot JSON NOT NULL, - occurred_at DATETIME(6) NOT NULL, - created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6), - INDEX idx_aggregate (aggregate_id), - UNIQUE KEY uniq_aggregate_sequence (aggregate_type, aggregate_id, sequence_number) -); +CREATE TABLE outbox_events +( + id BINARY(16) NOT NULL COMMENT 'The event identifier in Version 4 UUID format (e.g. 123e4567-e89b-12d3-a456-426614174000).', + payload JSON NOT NULL COMMENT 'The event payload serialized as a JSON object (e.g. {"transaction_id":"..."}).', + revision INT NOT NULL COMMENT 'The positive integer indicating the payload schema revision of the event (e.g. 1).', + event_type VARCHAR(255) NOT NULL COMMENT 'The event class name in CamelCase (e.g. TransactionConfirmed).', + occurred_at TIMESTAMP(6) NOT NULL COMMENT 'The UTC date and time when the event occurred in ISO 8601 format (e.g. 2026-02-13T08:49:44.931408+00:00).', + aggregate_id BINARY(16) NOT NULL COMMENT 'The aggregate root identifier in Version 4 UUID format (e.g. 123e4567-e89b-12d3-a456-426614174000).', + aggregate_type VARCHAR(255) NOT NULL COMMENT 'The aggregate root class name that produced the event in CamelCase (e.g. Transaction).', + aggregate_version BIGINT NOT NULL COMMENT 'The version of the aggregate at the moment the event was emitted, used to detect duplicate or out-of-order events per aggregate (e.g. 1).', + created_at TIMESTAMP(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6) COMMENT 'The UTC date and time when the record was inserted in ISO 8601 format (e.g. 2026-02-13T08:49:44.931408+00:00).', + PRIMARY KEY (id), + CONSTRAINT unq_outbox_events_aggregate_type_aggregate_id_aggregate_version UNIQUE (aggregate_type, aggregate_id, aggregate_version) +) ENGINE = InnoDB + DEFAULT CHARSET = utf8mb4 + COLLATE = utf8mb4_0900_ai_ci COMMENT ='Table used to persist append-only outbox events for atomic event publication.'; ``` -The library writes to `id`, `aggregate_id`, `aggregate_type`, `event_type`, `revision`, `sequence_number`, `payload`, -`snapshot`, and `occurred_at`. It never writes to `sequence` or `created_at`. The database fills those automatically. +The library writes to `id`, `aggregate_id`, `aggregate_type`, `event_type`, `revision`, `aggregate_version`, `payload`, +and `occurred_at`. It never writes to `created_at`. The database fills it automatically. For aggregates whose identities are not UUID v4 strings, use VARCHAR columns and configure `IdentityColumnType::STRING` (see [Customizing the table layout](#customizing-the-table-layout)): ```sql --- For non-UUID identities: VARCHAR(36) or wider. -id VARCHAR(36) NOT NULL PRIMARY KEY, -aggregate_id VARCHAR(36) NOT NULL, +CREATE TABLE outbox_events +( + -- For non-UUID identities: VARCHAR(36) or wider. + id VARCHAR(36) NOT NULL, + aggregate_id VARCHAR(36) NOT NULL + -- All other columns are the same as the default schema. +) ``` ### Wiring the repository -`DoctrineOutboxRepository` requires a Doctrine DBAL `Connection` and a `PayloadSerializers` collection. The snapshot -serializer collection defaults to a `SnapshotSerializers` containing `SnapshotSerializerReflection`, and the table -layout defaults to table `outbox_events` with BINARY(16) identity columns. +`DoctrineOutboxRepository` requires a Doctrine DBAL `Connection` and a `PayloadSerializers` collection. The table layout +defaults to table `outbox_events` with BINARY(16) identity columns. ```php withTableName(tableName: 'domain_events') ->withColumns(columns: Columns::builder() ->withId(name: 'id', type: IdentityColumnType::STRING) ->withEventType(name: 'kind') ->withAggregateId(name: 'aggregate_id', type: IdentityColumnType::STRING) ->withAggregateType(name: 'entity_class') - ->withSequenceNumber(name: 'position') + ->withAggregateVersion(name: 'position') ->build()) + ->withTableName(tableName: 'my_outbox') ->build(); $repository = new DoctrineOutboxRepository( connection: $connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new PayloadSerializerReflection()]), + serializers: serializers::createFrom(elements: [new PayloadSerializerReflection()]), tableLayout: $tableLayout ); ``` -All `Columns::builder()` methods are optional. Omit any method to keep its default. -`withId` and `withAggregateId` require both `name:` and `type:`; all other methods require only `name:`. - -| Method | Default column name | Default type | Description | -|---------------------------------|---------------------|--------------|-----------------------------------------------------------------| -| `withId(name:, type:)` | `id` | `BINARY` | Renames the event id column and/or changes its storage type | -| `withAggregateId(name:, type:)` | `aggregate_id` | `BINARY` | Renames the aggregate id column and/or changes its storage type | -| `withAggregateType(name:)` | `aggregate_type` | — | Renames the aggregate type column | -| `withEventType(name:)` | `event_type` | — | Renames the event type column | -| `withRevision(name:)` | `revision` | — | Renames the schema revision column | -| `withSequenceNumber(name:)` | `sequence_number` | — | Renames the aggregate sequence number column | -| `withPayload(name:)` | `payload` | — | Renames the event payload column | -| `withSnapshot(name:)` | `snapshot` | — | Renames the aggregate snapshot column | -| `withOccurredAt(name:)` | `occurred_at` | — | Renames the event timestamp column | -| `withCreatedAt(name:)` | `created_at` | — | Renames the record creation timestamp column | +All `Columns::builder()` methods are optional. Omit any method to keep its default. `withId` and `withAggregateId` +require both `name:` and `type:`, all other methods require only `name:`. + +| Method | Default column name | Default type | Description | +|---------------------------------|---------------------|:------------:|------------------------------------------------------------------| +| `withId(name:, type:)` | `id` | `BINARY` | Renames the event id column and/or changes its storage type. | +| `withPayload(name:)` | `payload` | | Renames the event payload column. | +| `withRevision(name:)` | `revision` | | Renames the schema revision column. | +| `withEventType(name:)` | `event_type` | | Renames the event type column. | +| `withOccurredAt(name:)` | `occurred_at` | | Renames the event timestamp column. | +| `withAggregateId(name:, type:)` | `aggregate_id` | `BINARY` | Renames the aggregate id column and/or changes its storage type. | +| `withAggregateType(name:)` | `aggregate_type` | | Renames the aggregate type column. | +| `withAggregateVersion(name:)` | `aggregate_version` | | Renames the aggregate version column. | +| `withCreatedAt(name:)` | `created_at` | | Renames the record creation timestamp column. | `TableLayout::builder()` controls the table name, columns, and unique constraint name. -| Method | Default | Description | -|-------------------------------|---------------------------|--------------------------------------------------------------------| -| `withTableName(tableName:)` | `outbox_events` | Sets the outbox table name | -| `withColumns(columns:)` | Default column names | Provides a custom `Columns` configuration | -| `withUniqueConstraint(name:)` | `uniq_aggregate_sequence` | Sets the unique constraint name used to detect duplicate sequences | +| Method | Default | Description. | +|-------------------------------|-------------------------------------------------------------------|--------------------------------------------------------------------| +| `withColumns(columns:)` | Default column names. | Provides a custom `Columns` configuration. | +| `withTableName(tableName:)` | `outbox_events` | Sets the outbox table name. | +| `withUniqueConstraint(name:)` | `unq_outbox_events_aggregate_type_aggregate_id_aggregate_version` | Sets the unique constraint name used to detect duplicate versions. | -The DDL example uses `uniq_aggregate_sequence` as the unique constraint name. The library expects this name by -default; if you rename it in your DDL, configure it via +The DDL example uses `unq_outbox_events_aggregate_type_aggregate_id_aggregate_version` as the unique constraint name. +The library expects this name by default, if you rename it in your DDL, configure it via `TableLayout::builder()->withUniqueConstraint(name: 'your_name')->build()`. Constraint violation detection works with MySQL, MariaDB, PostgreSQL, and SQL Server. These DBMSs include the -constraint name in their violation messages. SQLite is not supported because it omits the constraint name. -All unique violations with SQLite fall under `DuplicateOutboxEvent`. +constraint name in their violation messages. SQLite is not supported because it omits the constraint name. All unique +violations with SQLite fall under `DuplicateOutboxEvent`. ### Writing a custom payload serializer @@ -225,7 +224,8 @@ All unique violations with SQLite fall under `DuplicateOutboxEvent`. `PayloadSerializer` explicitly for events that contain value objects or domain types that need custom JSON shaping. Both `supports()` and `serialize()` receive the full `EventRecord`, giving access to `$record->event`, -`$record->aggregateType`, `$record->snapshotData`, and all other fields when routing or shaping the payload. +`$record->aggregateType`, `$record->aggregateId`, `$record->aggregateVersion`, and all other fields when routing or +shaping the payload. Use `match (true)` in `serialize()` to handle multiple event types from the same aggregate in a single serializer: @@ -235,6 +235,7 @@ Use `match (true)` in `serialize()` to handle multiple event types from the same declare(strict_types=1); use TinyBlocks\BuildingBlocks\Event\EventRecord; +use TinyBlocks\Outbox\DoctrineOutboxRepository; use TinyBlocks\Outbox\Serialization\PayloadSerializer; use TinyBlocks\Outbox\Serialization\PayloadSerializerReflection; use TinyBlocks\Outbox\Serialization\PayloadSerializers; @@ -267,7 +268,7 @@ final readonly class OrderEventSerializer implements PayloadSerializer # PayloadSerializerReflection always returns true from supports(), so it must come last. $repository = new DoctrineOutboxRepository( connection: $connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [ + serializers: serializers::createFrom(elements: [ new OrderEventSerializer(), new PayloadSerializerReflection() ]) @@ -279,66 +280,6 @@ is malformed, before the INSERT is attempted. When building the JSON from an arr `SerializedPayload::fromArray($array)` over `SerializedPayload::from(json_encode($array, JSON_THROW_ON_ERROR))`. The library handles encoding internally. -### Writing a custom snapshot serializer - -The aggregate snapshot records the state at the time of each event. By default, `SnapshotSerializerReflection` -serializes `$record->snapshotData->toArray()` using `json_encode`. Provide a custom `SnapshotSerializer` when the -snapshot payload contains value objects or domain types that are not directly JSON-encodable. - -Both `supports()` and `serialize()` receive the full `EventRecord`, giving access to `$record->snapshotData`, -`$record->aggregateType`, `$record->event`, and all other fields when routing or shaping the snapshot. - -```php -aggregateType === 'Order'; - } - - public function serialize(EventRecord $record): SerializedSnapshot - { - $state = $record->snapshotData->toArray(); - - return SerializedSnapshot::from( - snapshot: json_encode( - ['orderId' => $state['orderId']->value, 'status' => $state['status']], - JSON_THROW_ON_ERROR - ) - ); - } -} - -# Register custom snapshot serializers before SnapshotSerializerReflection. -# SnapshotSerializerReflection always returns true from supports(), so it must come last. -$repository = new DoctrineOutboxRepository( - connection: $connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new PayloadSerializerReflection()]), - snapshotSerializers: SnapshotSerializers::createFrom(elements: [ - new OrderSnapshotSerializer(), - new SnapshotSerializerReflection() - ]) -); -``` - -`SerializedSnapshot::from()` validates the JSON string at construction time and throws `InvalidSnapshotJson` if the -JSON is malformed, before the INSERT is attempted. When building the JSON from an array, prefer -`SerializedSnapshot::fromArray($array)` over `SerializedSnapshot::from(json_encode($array, JSON_THROW_ON_ERROR))`. The -library handles encoding internally. - ### Event schema versioning Each domain event declares its schema revision via `DomainEvent::revision()`. `DomainEventBehavior` provides the @@ -358,10 +299,7 @@ final readonly class OrderPlaced implements DomainEvent { use DomainEventBehavior; - public function __construct( - public string $orderId, - public string $currency - ) { + public function __construct(public string $orderId, public string $currency) { } public function revision(): Revision @@ -372,9 +310,8 @@ final readonly class OrderPlaced implements DomainEvent ``` The `revision` column stored in the outbox lets downstream consumers detect schema changes. -`tiny-blocks/building-blocks` -provides `Upcaster`, `Upcasters`, `IntermediateEvent`, and `SingleUpcasterBehavior` to migrate events from older -revisions to the current schema on the read side. +`tiny-blocks/building-blocks` provides `Upcaster`, `Upcasters`, `IntermediateEvent`, and `SingleUpcasterBehavior` to +migrate events from older revisions to the current schema on the read side. ## FAQ @@ -382,15 +319,15 @@ revisions to the current schema on the read side. `PayloadSerializerReflection` uses PHP's `get_object_vars()` to serialize any event whose public properties are scalars or `JsonSerializable`. It always returns `true` from `supports()`, making it a universal catch-all when registered last -in `PayloadSerializers::createFrom()`. Only events with value objects or domain types that are not directly +in `serializers::createFrom()`. Only events with value objects or domain types that are not directly JSON-encodable require an explicit serializer. -### 02. What is the difference between revision and sequence_number? +### 02. What is the difference between revision and aggregate_version? `revision` is a schema version declared on the **event class** via `DomainEvent::revision()`. It starts at 1 and is -bumped when the event's payload structure changes. `sequence_number` is the **aggregate's internal position counter**, -incremented once per recorded event. They are independent: `revision` tracks event schema evolution; -`sequence_number` tracks the position of an event within a single aggregate's history. +bumped when the event's payload structure changes. `aggregate_version` is the **aggregate's internal version counter**, +incremented once per recorded event and used for optimistic offline locking. They are independent: `revision` tracks +event schema evolution, `aggregate_version` tracks the position of an event within a single aggregate's history. ### 03. Why does push require an active transaction? @@ -402,10 +339,10 @@ Calling `push()` without an active `beginTransaction()` is always a programming ### 04. When does each duplication exception fire? `DuplicateOutboxEvent` fires when an `EventRecord` with the same `id` already exists in the outbox (PRIMARY KEY -violation). `DuplicateAggregateSequence` fires when two records share the same `aggregate_type`, `aggregate_id`, and -`sequence_number` (`uniq_aggregate_sequence` unique constraint violation). The latter typically indicates concurrent -producers writing to the same aggregate position without proper locking. Both extend `RuntimeException` and can be -caught independently for precise idempotency handling. +violation). `DuplicateAggregateVersion` fires when two records share the same `aggregate_type`, `aggregate_id`, and +`aggregate_version` (`unq_outbox_events_aggregate_type_aggregate_id_aggregate_version` constraint violation). The +latter typically indicates concurrent producers writing to the same aggregate version without proper locking. Both +extend `RuntimeException` and can be caught independently for precise idempotency handling. ### 05. Why is BINARY(16) the default for identity columns? @@ -419,33 +356,30 @@ that are not UUID v4 strings, for example ULID, snowflake, integer, or opaque st No. `OutboxRepository` is a write-only interface. Reading, relaying, and processing outbox records is the responsibility of a separate relay worker, which is outside the scope of this library. -### 07. What is the authoritative ordering source for outbox records? +### 07. How are outbox records ordered? -The `sequence` column (`BIGINT AUTO_INCREMENT`) is the authoritative global ordering. The database fills it at commit -time, so it reflects the actual commit order across concurrent transactions, the only safe ordering baseline under -concurrent writes. `occurred_at` records when the domain event happened and is subject to clock skew across processes -or nodes; do not use it as a primary ordering source. `sequence_number` gives ordering within a single aggregate's -history only. +Per-aggregate ordering is guaranteed by `aggregate_version`: a monotonic counter, unique per aggregate, that advances by +one for each recorded event. Cross-aggregate ordering is the relay's responsibility. Common strategies include using a +time-ordered identifier for `id` (e.g. UUID v7), or ordering by `created_at` on the relay side. `occurred_at` records +when the domain event happened in the producing process and is subject to clock skew, do not use it as a primary +ordering source. -### 08. Why do PayloadSerializer and SnapshotSerializer both receive EventRecord instead of DomainEvent or SnapshotData? +### 08. Why does PayloadSerializer receive EventRecord instead of DomainEvent? Routing and shaping decisions often depend on context beyond the event itself. For example, a single serializer may -handle events from a specific aggregate type (`$record->aggregateType === 'Order'`), or the snapshot shaping may vary -based on which event triggered the state change (`$record->event`). Receiving the full `EventRecord` in both -`supports()` and `serialize()` gives serializers access to all available context without requiring any additional -indirection. +handle events from a specific aggregate type (`$record->aggregateType === 'Order'`), or the payload shaping may vary +based on the aggregate version (`$record->aggregateVersion`). Receiving the full `EventRecord` in both `supports()` and +`serialize()` gives serializers access to all available context without requiring any additional indirection. ### 09. How does the library handle transient database errors? -The library catches `UniqueConstraintViolationException` to differentiate -`DuplicateAggregateSequence` from `DuplicateOutboxEvent`. All other DBAL -exceptions, including transient errors like deadlocks (`DeadlockException`), -lock wait timeouts (`LockWaitTimeoutException`), and connection failures -(`ConnectionLost`), propagate unchanged to the caller. +The library catches `UniqueConstraintViolationException` to differentiate `DuplicateAggregateVersion` from +`DuplicateOutboxEvent`. All other DBAL exceptions, including transient errors like deadlocks (`DeadlockException`), +lock wait timeouts (`LockWaitTimeoutException`), and connection failures (`ConnectionLost`), propagate unchanged to the +caller. -The consumer is responsible for any retry policy. A common pattern is to wrap -the unit of work (aggregate save + outbox push) in a retry loop that catches -transient exceptions and re-executes the entire transaction. +The consumer is responsible for any retry policy. A common pattern is to wrap the unit of work (aggregate save + +outbox push) in a retry loop that catches transient exceptions and re-executes the entire transaction. ## License diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..f4a1569 --- /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/outbox/security/advisories/new). + +Please do not disclose the vulnerability publicly until it has been addressed. diff --git a/composer.json b/composer.json index 8b11ba1..50f24b5 100644 --- a/composer.json +++ b/composer.json @@ -1,6 +1,6 @@ { "name": "tiny-blocks/outbox", - "description": "Implements the Transactional Outbox pattern. Persists domain events atomically with aggregate state changes through a customizable table schema, reflection-based payload serialization, and built-in support for event schema versioning.", + "description": "Write-side adapter for the Transactional Outbox pattern that persists domain events atomically with aggregate state through Doctrine DBAL.", "license": "MIT", "type": "library", "keywords": [ @@ -29,18 +29,18 @@ }, "require": { "php": "^8.5", - "doctrine/dbal": "^4.0", + "doctrine/dbal": "^4.4", "ramsey/uuid": "^4.9", - "tiny-blocks/building-blocks": "^2.2", + "tiny-blocks/building-blocks": "^3.0", "tiny-blocks/collection": "^2.3" }, "require-dev": { - "ergebnis/composer-normalize": "^2.51", - "infection/infection": "^0.32", + "ergebnis/composer-normalize": "^2.52", + "infection/infection": "^0.33", "phpstan/phpstan": "^2.1", "phpunit/phpunit": "^13.1", "squizlabs/php_codesniffer": "^4.0", - "tiny-blocks/docker-container": "^2.0", + "tiny-blocks/docker-container": "^2.5", "tiny-blocks/environment-variable": "^1.2" }, "minimum-stability": "stable", @@ -63,22 +63,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 45c49fc..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": { 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 297c011..e68ddd5 100644 --- a/phpstan.neon.dist +++ b/phpstan.neon.dist @@ -1,9 +1,42 @@ parameters: - paths: - - src - level: 9 - tmpDir: report/phpstan - ignoreErrors: - - identifier: cast.string - - identifier: missingType.iterableValue - reportUnmatchedIgnoredErrors: true + level: max + paths: + - src + - tests + ignoreErrors: + # OutboxInsert::$parameters is an untyped iterable on an Internal collaborator; Doctrine expects array. + - identifier: argument.type + path: src/DoctrineOutboxRepository.php + + # aggregateId is intentionally typed mixed at the public exception boundary; sprintf at level max flags the mixed argument. + - identifier: argument.type + path: src/Exceptions/DuplicateAggregateVersion.php + + # Internal collaborators handle mixed identity values per design; PHPDoc is prohibited under src/Internal/. + - identifier: cast.string + path: src/Internal/BinaryIdentityColumn.php + + - identifier: cast.string + path: src/Internal/StringIdentityColumn.php + + # OutboxInsert::$parameters is a constructor parameter inside src/Internal/; PHPDoc is prohibited. + - identifier: missingType.iterableValue + path: src/Internal/OutboxInsert.php + + # Test files are excluded from typed-array PHPDoc requirements. + - identifier: missingType.iterableValue + path: tests + + # Doctrine fetchAssociative returns array|false at level max; tests assert on documented happy paths. + - identifier: offsetAccess.nonOffsetAccessible + path: tests + + - identifier: argument.type + path: tests + + - identifier: cast.int + path: tests + + - identifier: property.onlyWritten + path: tests + reportUnmatchedIgnoredErrors: true diff --git a/phpunit.xml b/phpunit.xml index 97ff87c..ce675d8 100644 --- a/phpunit.xml +++ b/phpunit.xml @@ -1,13 +1,16 @@ + failOnDeprecation="true" + failOnNotice="true" + failOnPhpunitDeprecation="true" + failOnRisky="true" + failOnWarning="true"> @@ -23,15 +26,15 @@ - - - - + + + + - + diff --git a/src/DoctrineOutboxRepository.php b/src/DoctrineOutboxRepository.php index d2260f3..7f1e7fa 100644 --- a/src/DoctrineOutboxRepository.php +++ b/src/DoctrineOutboxRepository.php @@ -8,31 +8,24 @@ use Doctrine\DBAL\Exception\UniqueConstraintViolationException; use TinyBlocks\BuildingBlocks\Event\EventRecord; use TinyBlocks\BuildingBlocks\Event\EventRecords; -use TinyBlocks\Outbox\Exceptions\DuplicateAggregateSequence; +use TinyBlocks\Outbox\Exceptions\DuplicateAggregateVersion; use TinyBlocks\Outbox\Exceptions\DuplicateOutboxEvent; use TinyBlocks\Outbox\Exceptions\OutboxRequiresActiveTransaction; use TinyBlocks\Outbox\Exceptions\PayloadSerializerNotConfigured; -use TinyBlocks\Outbox\Exceptions\SnapshotSerializerNotConfigured; use TinyBlocks\Outbox\Internal\OutboxInsert; use TinyBlocks\Outbox\Schema\TableLayout; use TinyBlocks\Outbox\Serialization\PayloadSerializers; -use TinyBlocks\Outbox\Serialization\SnapshotSerializerReflection; -use TinyBlocks\Outbox\Serialization\SnapshotSerializers; final readonly class DoctrineOutboxRepository implements OutboxRepository { private TableLayout $tableLayout; - private SnapshotSerializers $snapshotSerializers; public function __construct( private Connection $connection, - private PayloadSerializers $payloadSerializers, - ?TableLayout $tableLayout = null, - ?SnapshotSerializers $snapshotSerializers = null + private PayloadSerializers $serializers, + ?TableLayout $tableLayout = null ) { $this->tableLayout = $tableLayout ?? TableLayout::default(); - $this->snapshotSerializers = $snapshotSerializers - ?? SnapshotSerializers::createFrom(elements: [new SnapshotSerializerReflection()]); } public function push(EventRecords $records): void @@ -42,34 +35,27 @@ public function push(EventRecords $records): void } $records->each(actions: function (EventRecord $record): void { - $payloadSerializer = $this->payloadSerializers->findFor(record: $record); + $payloadSerializer = $this->serializers->findFor(record: $record); if (is_null($payloadSerializer)) { - throw new PayloadSerializerNotConfigured(eventClass: $record->event::class); - } - - $snapshotSerializer = $this->snapshotSerializers->findFor(record: $record); - - if (is_null($snapshotSerializer)) { - throw SnapshotSerializerNotConfigured::for(aggregateType: $record->aggregateType); + throw PayloadSerializerNotConfigured::forEventClass(eventClass: $record->event::class); } $insert = OutboxInsert::from( record: $record, payload: $payloadSerializer->serialize(record: $record), - snapshot: $snapshotSerializer->serialize(record: $record), tableLayout: $this->tableLayout ); try { - $this->connection->executeStatement($insert->sql, $insert->parameters); + $this->connection->executeStatement(sql: $insert->sql, params: $insert->parameters); } catch (UniqueConstraintViolationException $exception) { if ($this->tableLayout->uniqueConstraint->isViolatedBy(exception: $exception)) { - throw new DuplicateAggregateSequence( - aggregateId: (string)$record->identity->identityValue(), + throw DuplicateAggregateVersion::forRecord( + previous: $exception, + aggregateId: $record->aggregateId->identityValue(), aggregateType: $record->aggregateType, - sequenceNumber: $record->sequenceNumber->value, - previous: $exception + aggregateVersion: $record->aggregateVersion->value ); } diff --git a/src/Exceptions/DuplicateAggregateSequence.php b/src/Exceptions/DuplicateAggregateSequence.php deleted file mode 100644 index cd14141..0000000 --- a/src/Exceptions/DuplicateAggregateSequence.php +++ /dev/null @@ -1,24 +0,0 @@ - at sequence number <%d>.'; - - parent::__construct(sprintf($template, $aggregateType, $aggregateId, $sequenceNumber), self::CODE, $previous); - } -} diff --git a/src/Exceptions/DuplicateAggregateVersion.php b/src/Exceptions/DuplicateAggregateVersion.php new file mode 100644 index 0000000..4f32997 --- /dev/null +++ b/src/Exceptions/DuplicateAggregateVersion.php @@ -0,0 +1,48 @@ + at aggregate version <%d>.'; + + parent::__construct( + message: sprintf($template, $aggregateType, $aggregateId, $aggregateVersion), + previous: $previous + ); + } + + /** + * Creates a DuplicateAggregateVersion from the conflicting aggregate identity and version. + * + * @param Throwable|null $previous The driver-level violation that triggered the failure, or null. + * @param mixed $aggregateId The identifier of the aggregate whose version collided. + * @param string $aggregateType The fully-qualified type name of the aggregate. + * @param int $aggregateVersion The aggregate version that collided with an existing record. + * @return DuplicateAggregateVersion The created instance. + */ + public static function forRecord( + ?Throwable $previous, + mixed $aggregateId, + string $aggregateType, + int $aggregateVersion + ): DuplicateAggregateVersion { + return new DuplicateAggregateVersion( + previous: $previous, + aggregateId: $aggregateId, + aggregateType: $aggregateType, + aggregateVersion: $aggregateVersion + ); + } +} diff --git a/src/Exceptions/DuplicateOutboxEvent.php b/src/Exceptions/DuplicateOutboxEvent.php index 7febc2c..d6db072 100644 --- a/src/Exceptions/DuplicateOutboxEvent.php +++ b/src/Exceptions/DuplicateOutboxEvent.php @@ -10,12 +10,19 @@ final class DuplicateOutboxEvent extends RuntimeException { + /** + * Creates a DuplicateOutboxEvent from the conflicting record id. + * + * @param string|int|Stringable $eventId The id of the record that already exists in the outbox. + * @param UniqueConstraintViolationException $previous The driver-level violation that triggered the failure. + * @return DuplicateOutboxEvent The created instance. + */ public static function forRecord( string|int|Stringable $eventId, UniqueConstraintViolationException $previous ): DuplicateOutboxEvent { - $template = 'Event with id "%s" already exists in outbox.'; + $template = 'Event with id <%s> already exists in outbox.'; - return new DuplicateOutboxEvent(sprintf($template, (string)$eventId), previous: $previous); + return new DuplicateOutboxEvent(message: sprintf($template, (string)$eventId), previous: $previous); } } diff --git a/src/Exceptions/InvalidPayloadJson.php b/src/Exceptions/InvalidPayloadJson.php index c9f060b..cb7daa2 100644 --- a/src/Exceptions/InvalidPayloadJson.php +++ b/src/Exceptions/InvalidPayloadJson.php @@ -8,10 +8,16 @@ final class InvalidPayloadJson extends RuntimeException { - public static function for(string $payload): InvalidPayloadJson + /** + * Creates an InvalidPayloadJson from the payload that failed to validate. + * + * @param string $payload The raw payload string that is not valid JSON. + * @return InvalidPayloadJson The created instance. + */ + public static function forPayload(string $payload): InvalidPayloadJson { - $template = 'Payload is not valid JSON: %s'; + $template = 'Payload is not valid JSON <%s>.'; - return new InvalidPayloadJson(sprintf($template, $payload)); + return new InvalidPayloadJson(message: sprintf($template, $payload)); } } diff --git a/src/Exceptions/InvalidSnapshotJson.php b/src/Exceptions/InvalidSnapshotJson.php deleted file mode 100644 index e5438d4..0000000 --- a/src/Exceptions/InvalidSnapshotJson.php +++ /dev/null @@ -1,15 +0,0 @@ -.'; - parent::__construct(sprintf($template, $eventClass)); + return new PayloadSerializerNotConfigured(message: sprintf($template, $eventClass)); } } diff --git a/src/Exceptions/SnapshotSerializerNotConfigured.php b/src/Exceptions/SnapshotSerializerNotConfigured.php deleted file mode 100644 index 94f33a2..0000000 --- a/src/Exceptions/SnapshotSerializerNotConfigured.php +++ /dev/null @@ -1,17 +0,0 @@ -snapshot = $name; - return $this; - } - public function withEventType(string $name): ColumnsBuilder { $this->eventType = $name; @@ -74,9 +67,9 @@ public function withAggregateType(string $name): ColumnsBuilder return $this; } - public function withSequenceNumber(string $name): ColumnsBuilder + public function withAggregateVersion(string $name): ColumnsBuilder { - $this->sequenceNumber = $name; + $this->aggregateVersion = $name; return $this; } @@ -100,13 +93,12 @@ public function build(): Columns id: $this->idType->toColumn(name: $this->idName), payload: $this->payload, revision: $this->revision, - snapshot: $this->snapshot, createdAt: $this->createdAt, eventType: $this->eventType, occurredAt: $this->occurredAt, aggregateId: $this->aggregateIdType->toColumn(name: $this->aggregateIdName), aggregateType: $this->aggregateType, - sequenceNumber: $this->sequenceNumber + aggregateVersion: $this->aggregateVersion ); } } diff --git a/src/Internal/OutboxInsert.php b/src/Internal/OutboxInsert.php index 79b025f..aadc1b2 100644 --- a/src/Internal/OutboxInsert.php +++ b/src/Internal/OutboxInsert.php @@ -7,7 +7,6 @@ use TinyBlocks\BuildingBlocks\Event\EventRecord; use TinyBlocks\Outbox\Schema\TableLayout; use TinyBlocks\Outbox\Serialization\SerializedPayload; -use TinyBlocks\Outbox\Serialization\SerializedSnapshot; final readonly class OutboxInsert { @@ -18,18 +17,17 @@ private function __construct(public string $sql, public array $parameters) public static function from( EventRecord $record, SerializedPayload $payload, - SerializedSnapshot $snapshot, TableLayout $tableLayout ): OutboxInsert { $template = <<columns; $idValue = $columns->id->convert(identityValue: $record->id); - $aggregateIdValue = $columns->aggregateId->convert(identityValue: $record->identity->identityValue()); + $aggregateIdValue = $columns->aggregateId->convert(identityValue: $record->aggregateId->identityValue()); return new OutboxInsert( sql: sprintf( @@ -40,21 +38,19 @@ public static function from( $columns->aggregateType, $columns->eventType, $columns->revision, - $columns->sequenceNumber, + $columns->aggregateVersion, $columns->payload, - $columns->snapshot, $columns->occurredAt ), parameters: [ - 'id' => $idValue, - 'aggregateId' => $aggregateIdValue, - 'aggregateType' => $record->aggregateType, - 'eventType' => $record->type->value, - 'revision' => $record->revision->value, - 'sequenceNumber' => $record->sequenceNumber->value, - 'payload' => $payload->toJson(), - 'snapshot' => $snapshot->toJson(), - 'occurredAt' => $record->occurredOn->toIso8601() + 'id' => $idValue, + 'aggregateId' => $aggregateIdValue, + 'aggregateType' => $record->aggregateType, + 'eventType' => $record->eventType->value, + 'revision' => $record->revision->value, + 'aggregateVersion' => $record->aggregateVersion->value, + 'payload' => $payload->toJson(), + 'occurredAt' => $record->occurredAt->toIso8601() ] ); } diff --git a/src/OutboxRepository.php b/src/OutboxRepository.php index 54305be..1bc9160 100644 --- a/src/OutboxRepository.php +++ b/src/OutboxRepository.php @@ -5,19 +5,18 @@ namespace TinyBlocks\Outbox; use TinyBlocks\BuildingBlocks\Event\EventRecords; -use TinyBlocks\Outbox\Exceptions\DuplicateAggregateSequence; +use TinyBlocks\Outbox\Exceptions\DuplicateAggregateVersion; use TinyBlocks\Outbox\Exceptions\DuplicateOutboxEvent; use TinyBlocks\Outbox\Exceptions\InvalidPayloadJson; -use TinyBlocks\Outbox\Exceptions\InvalidSnapshotJson; use TinyBlocks\Outbox\Exceptions\OutboxRequiresActiveTransaction; use TinyBlocks\Outbox\Exceptions\PayloadSerializerNotConfigured; -use TinyBlocks\Outbox\Exceptions\SnapshotSerializerNotConfigured; /** * Producer-side contract: persists outbox records as part of the caller's open transaction. * *

    Used by aggregate repositories during the business unit of work. The implementation must not - * open or commit a transaction. Atomicity with the aggregate state change is the caller's responsibility.

    + * open or commit a transaction. Atomicity with the aggregate state change is the caller's + * responsibility.

    */ interface OutboxRepository { @@ -28,13 +27,11 @@ interface OutboxRepository * to ensure this call happens inside the same unit of work as the aggregate state change.

    * * @param EventRecords $records The records to persist. - * @throws OutboxRequiresActiveTransaction When called outside an active transaction. - * @throws PayloadSerializerNotConfigured When no serializer supports the event class. - * @throws SnapshotSerializerNotConfigured When no serializer supports the aggregate type. * @throws InvalidPayloadJson When a serializer produces an invalid JSON payload. - * @throws InvalidSnapshotJson When a serializer produces an invalid JSON snapshot. * @throws DuplicateOutboxEvent When a record with a duplicate id already exists in the outbox. - * @throws DuplicateAggregateSequence When two records share the same aggregate type, id, and sequence number. + * @throws DuplicateAggregateVersion When two records share the same aggregate type, id, and aggregate version. + * @throws PayloadSerializerNotConfigured When no serializer supports the event class. + * @throws OutboxRequiresActiveTransaction When called outside an active transaction. */ public function push(EventRecords $records): void; } diff --git a/src/Schema/Columns.php b/src/Schema/Columns.php index 42a51d5..874e38d 100644 --- a/src/Schema/Columns.php +++ b/src/Schema/Columns.php @@ -13,49 +13,70 @@ private function __construct( public IdentityColumn $id, public string $payload, public string $revision, - public string $snapshot, public string $createdAt, public string $eventType, public string $occurredAt, public IdentityColumn $aggregateId, public string $aggregateType, - public string $sequenceNumber + public string $aggregateVersion ) { } + /** + * Creates a ColumnsBuilder used to customize the outbox column names. + * + * @return ColumnsBuilder A new builder seeded with the default column names. + */ public static function builder(): ColumnsBuilder { return ColumnsBuilder::create(); } + /** + * Creates a Columns instance using the default outbox column names. + * + * @return Columns The default column configuration. + */ public static function default(): Columns { return ColumnsBuilder::create()->build(); } + /** + * Builds a Columns with the explicit column names for every outbox field. + * + * @param IdentityColumn $id The identity column for the event id. + * @param string $payload The column name for the serialized event payload. + * @param string $revision The column name for the event schema revision. + * @param string $createdAt The column name for the row insertion timestamp. + * @param string $eventType The column name for the event type identifier. + * @param string $occurredAt The column name for the event occurrence timestamp. + * @param IdentityColumn $aggregateId The identity column for the owning aggregate. + * @param string $aggregateType The column name for the aggregate type identifier. + * @param string $aggregateVersion The column name for the per-aggregate version counter. + * @return Columns The built column configuration. + */ public static function from( IdentityColumn $id, string $payload, string $revision, - string $snapshot, string $createdAt, string $eventType, string $occurredAt, IdentityColumn $aggregateId, string $aggregateType, - string $sequenceNumber + string $aggregateVersion ): Columns { return new Columns( id: $id, payload: $payload, revision: $revision, - snapshot: $snapshot, createdAt: $createdAt, eventType: $eventType, occurredAt: $occurredAt, aggregateId: $aggregateId, aggregateType: $aggregateType, - sequenceNumber: $sequenceNumber + aggregateVersion: $aggregateVersion ); } } diff --git a/src/Schema/IdentityColumnType.php b/src/Schema/IdentityColumnType.php index 8c1bd9f..0cd9017 100644 --- a/src/Schema/IdentityColumnType.php +++ b/src/Schema/IdentityColumnType.php @@ -13,6 +13,12 @@ enum IdentityColumnType: string case BINARY = 'binary'; case STRING = 'string'; + /** + * Returns the IdentityColumn implementation matching this type. + * + * @param string $name The column name to assign to the resulting IdentityColumn. + * @return IdentityColumn The identity column wired to this type and column name. + */ public function toColumn(string $name): IdentityColumn { return match ($this) { diff --git a/src/Schema/TableLayout.php b/src/Schema/TableLayout.php index f753235..8d5bb56 100644 --- a/src/Schema/TableLayout.php +++ b/src/Schema/TableLayout.php @@ -15,6 +15,34 @@ private function __construct( ) { } + /** + * Creates a TableLayoutBuilder used to customize the outbox table layout. + * + * @return TableLayoutBuilder A new builder seeded with the default table layout. + */ + public static function builder(): TableLayoutBuilder + { + return TableLayoutBuilder::create(); + } + + /** + * Creates a TableLayout using the default table name, columns, and unique constraint. + * + * @return TableLayout The default table layout. + */ + public static function default(): TableLayout + { + return TableLayoutBuilder::create()->build(); + } + + /** + * Builds a TableLayout with the explicit columns, table name, and unique constraint. + * + * @param Columns $columns The column configuration to apply to the layout. + * @param string $tableName The physical table name where outbox rows are stored. + * @param UniqueConstraint $uniqueConstraint The unique constraint guarding aggregate sequencing. + * @return TableLayout The built table layout. + */ public static function from( Columns $columns, string $tableName, @@ -26,14 +54,4 @@ public static function from( uniqueConstraint: $uniqueConstraint ); } - - public static function default(): TableLayout - { - return TableLayoutBuilder::create()->build(); - } - - public static function builder(): TableLayoutBuilder - { - return TableLayoutBuilder::create(); - } } diff --git a/src/Schema/UniqueConstraint.php b/src/Schema/UniqueConstraint.php index 96cbf61..2b15709 100644 --- a/src/Schema/UniqueConstraint.php +++ b/src/Schema/UniqueConstraint.php @@ -12,16 +12,33 @@ private function __construct(public string $name) { } + /** + * Creates a UniqueConstraint using the default constraint name. + * + * @return UniqueConstraint The default unique constraint. + */ public static function default(): UniqueConstraint { - return UniqueConstraint::named(name: 'uniq_aggregate_sequence'); + return UniqueConstraint::named(name: 'unq_outbox_events_aggregate_type_aggregate_id_aggregate_version'); } + /** + * Creates a UniqueConstraint with the explicit constraint name. + * + * @param string $name The physical name of the unique constraint in the outbox table. + * @return UniqueConstraint The created unique constraint. + */ public static function named(string $name): UniqueConstraint { return new UniqueConstraint(name: $name); } + /** + * Tells whether the given driver exception was raised by this unique constraint. + * + * @param UniqueConstraintViolationException $exception The driver exception to inspect. + * @return bool True when the exception message mentions this constraint name, false otherwise. + */ public function isViolatedBy(UniqueConstraintViolationException $exception): bool { return str_contains($exception->getMessage(), $this->name); diff --git a/src/Serialization/PayloadSerializer.php b/src/Serialization/PayloadSerializer.php index 80408b3..f4662f1 100644 --- a/src/Serialization/PayloadSerializer.php +++ b/src/Serialization/PayloadSerializer.php @@ -9,7 +9,7 @@ interface PayloadSerializer { /** - * Whether this serializer handles the event in the given record. + * Tells whether this serializer handles the event in the given record. * * @param EventRecord $record The record being serialized. * @return bool True if this serializer can produce the payload for the event. diff --git a/src/Serialization/PayloadSerializers.php b/src/Serialization/PayloadSerializers.php index 9406c86..ba6e962 100644 --- a/src/Serialization/PayloadSerializers.php +++ b/src/Serialization/PayloadSerializers.php @@ -9,6 +9,12 @@ final class PayloadSerializers extends Collection { + /** + * Returns the first payload serializer that supports the given record, or null when none matches. + * + * @param EventRecord $record The record whose payload serializer is being resolved. + * @return PayloadSerializer|null The matching serializer, or null when no element supports the record. + */ public function findFor(EventRecord $record): ?PayloadSerializer { $serializer = $this->findBy( diff --git a/src/Serialization/SerializedPayload.php b/src/Serialization/SerializedPayload.php index 2e96b56..b5211f9 100644 --- a/src/Serialization/SerializedPayload.php +++ b/src/Serialization/SerializedPayload.php @@ -12,22 +12,40 @@ private function __construct(private string $payload) { } - public static function from(string $payload): SerializedPayload + /** + * Creates a SerializedPayload from an associative array, encoding it as JSON. + * + * @param array $payload The associative array to encode as the serialized payload. + * @return SerializedPayload The serialized payload with the JSON-encoded representation. + */ + public static function fromArray(array $payload): SerializedPayload { - if (!json_validate($payload)) { - throw InvalidPayloadJson::for(payload: $payload); - } + $json = json_encode($payload, JSON_THROW_ON_ERROR); - return new SerializedPayload(payload: $payload); + return new SerializedPayload(payload: $json); } - public static function fromArray(array $payload): SerializedPayload + /** + * Creates a SerializedPayload from a raw JSON string. + * + * @param string $payload The JSON-encoded payload string. + * @return SerializedPayload The serialized payload wrapping the validated JSON string. + * @throws InvalidPayloadJson If the string is not valid JSON. + */ + public static function from(string $payload): SerializedPayload { - $json = json_encode($payload, JSON_THROW_ON_ERROR); + if (!json_validate($payload)) { + throw InvalidPayloadJson::forPayload(payload: $payload); + } - return new SerializedPayload(payload: $json); + return new SerializedPayload(payload: $payload); } + /** + * Returns the SerializedPayload as its JSON string representation. + * + * @return string The JSON-encoded payload. + */ public function toJson(): string { return $this->payload; diff --git a/src/Serialization/SerializedSnapshot.php b/src/Serialization/SerializedSnapshot.php deleted file mode 100644 index 1a0a8be..0000000 --- a/src/Serialization/SerializedSnapshot.php +++ /dev/null @@ -1,35 +0,0 @@ -snapshot; - } -} diff --git a/src/Serialization/SnapshotSerializer.php b/src/Serialization/SnapshotSerializer.php deleted file mode 100644 index 357615f..0000000 --- a/src/Serialization/SnapshotSerializer.php +++ /dev/null @@ -1,26 +0,0 @@ -snapshotData->toArray()); - } -} diff --git a/src/Serialization/SnapshotSerializers.php b/src/Serialization/SnapshotSerializers.php deleted file mode 100644 index 7eb51c0..0000000 --- a/src/Serialization/SnapshotSerializers.php +++ /dev/null @@ -1,20 +0,0 @@ -findBy( - predicates: static fn(SnapshotSerializer $serializer): bool => $serializer->supports(record: $record) - ); - - return $serializer instanceof SnapshotSerializer ? $serializer : null; - } -} diff --git a/tests/Database.php b/tests/Integration/Database.php similarity index 98% rename from tests/Database.php rename to tests/Integration/Database.php index fe6435d..7159e09 100644 --- a/tests/Database.php +++ b/tests/Integration/Database.php @@ -2,7 +2,7 @@ declare(strict_types=1); -namespace Test\TinyBlocks\Outbox; +namespace Test\TinyBlocks\Outbox\Integration; use Doctrine\DBAL\Connection; use Doctrine\DBAL\DriverManager; diff --git a/tests/DoctrineOutboxRepositoryTest.php b/tests/Integration/DoctrineOutboxRepositoryTest.php similarity index 69% rename from tests/DoctrineOutboxRepositoryTest.php rename to tests/Integration/DoctrineOutboxRepositoryTest.php index 4ed8ce7..1c61b13 100644 --- a/tests/DoctrineOutboxRepositoryTest.php +++ b/tests/Integration/DoctrineOutboxRepositoryTest.php @@ -2,40 +2,32 @@ declare(strict_types=1); -namespace Test\TinyBlocks\Outbox; +namespace Test\TinyBlocks\Outbox\Integration; use Doctrine\DBAL\Connection; use Doctrine\DBAL\Exception\UniqueConstraintViolationException; use Ramsey\Uuid\Uuid; -use Test\TinyBlocks\Outbox\Mocks\CustomOrderSnapshotSerializer; -use Test\TinyBlocks\Outbox\Mocks\DriverExceptionStub; -use Test\TinyBlocks\Outbox\Mocks\FallbackOrderPlacedSerializer; -use Test\TinyBlocks\Outbox\Mocks\InvalidPayloadSerializer; -use Test\TinyBlocks\Outbox\Mocks\InvalidSnapshotSerializer; -use Test\TinyBlocks\Outbox\Mocks\OrderPlacedSerializer; -use Test\TinyBlocks\Outbox\Mocks\RefundIssuedSerializer; use Test\TinyBlocks\Outbox\Models\EventRecordFactory; use Test\TinyBlocks\Outbox\Models\Order; use Test\TinyBlocks\Outbox\Models\OrderPlaced; use Test\TinyBlocks\Outbox\Models\RefundIssued; +use Test\TinyBlocks\Outbox\Unit\DriverExceptionStub; +use Test\TinyBlocks\Outbox\Unit\InvalidPayloadSerializer; +use Test\TinyBlocks\Outbox\Unit\OrderPlacedSerializer; +use TinyBlocks\BuildingBlocks\Aggregate\AggregateVersion; use TinyBlocks\BuildingBlocks\Event\EventRecords; use TinyBlocks\BuildingBlocks\Event\Revision; -use TinyBlocks\BuildingBlocks\Event\SequenceNumber; use TinyBlocks\Outbox\DoctrineOutboxRepository; -use TinyBlocks\Outbox\Exceptions\DuplicateAggregateSequence; +use TinyBlocks\Outbox\Exceptions\DuplicateAggregateVersion; use TinyBlocks\Outbox\Exceptions\DuplicateOutboxEvent; use TinyBlocks\Outbox\Exceptions\InvalidPayloadJson; -use TinyBlocks\Outbox\Exceptions\InvalidSnapshotJson; use TinyBlocks\Outbox\Exceptions\OutboxRequiresActiveTransaction; use TinyBlocks\Outbox\Exceptions\PayloadSerializerNotConfigured; -use TinyBlocks\Outbox\Exceptions\SnapshotSerializerNotConfigured; use TinyBlocks\Outbox\Schema\Columns; use TinyBlocks\Outbox\Schema\IdentityColumnType; use TinyBlocks\Outbox\Schema\TableLayout; use TinyBlocks\Outbox\Serialization\PayloadSerializerReflection; use TinyBlocks\Outbox\Serialization\PayloadSerializers; -use TinyBlocks\Outbox\Serialization\SnapshotSerializerReflection; -use TinyBlocks\Outbox\Serialization\SnapshotSerializers; use TinyBlocks\Time\Instant; final class DoctrineOutboxRepositoryTest extends IntegrationTestCase @@ -54,7 +46,7 @@ public function testPushWhenNoTransactionThenOutboxRequiresActiveTransaction(): /** @Given a repository */ $repository = new DoctrineOutboxRepository( connection: self::$connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) + serializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) ); /** @And a record to push */ @@ -79,14 +71,16 @@ public function testPushWhenMultipleSerializersAndFirstMatchesThenFirstIsUsed(): /** @Given a repository with two serializers supporting the same event */ $repository = new DoctrineOutboxRepository( connection: self::$connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [ + serializers: PayloadSerializers::createFrom(elements: [ new OrderPlacedSerializer(), new FallbackOrderPlacedSerializer() ]) ); - /** @When pushing an order placed event inside a transaction */ + /** @And the connection has an active transaction */ self::$connection->beginTransaction(); + + /** @When pushing an order placed event */ $repository->push(records: EventRecords::createFrom(elements: [ EventRecordFactory::create( event: new OrderPlaced(), @@ -94,6 +88,8 @@ public function testPushWhenMultipleSerializersAndFirstMatchesThenFirstIsUsed(): eventTypeName: 'OrderPlaced' ) ])); + + /** @And the transaction is committed */ self::$connection->commit(); /** @Then the payload is from the first serializer, not the fallback */ @@ -105,11 +101,13 @@ public function testPushWhenReflectionPayloadSerializerThenEventPropertiesAreEnc /** @Given a repository using ReflectionPayloadSerializer as the only serializer */ $repository = new DoctrineOutboxRepository( connection: self::$connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new PayloadSerializerReflection()]) + serializers: PayloadSerializers::createFrom(elements: [new PayloadSerializerReflection()]) ); - /** @When pushing a record inside a transaction */ + /** @And the connection has an active transaction */ self::$connection->beginTransaction(); + + /** @When pushing a record */ $repository->push(records: EventRecords::createFrom(elements: [ EventRecordFactory::create( event: new OrderPlaced(), @@ -117,6 +115,8 @@ public function testPushWhenReflectionPayloadSerializerThenEventPropertiesAreEnc eventTypeName: 'OrderPlaced' ) ])); + + /** @And the transaction is committed */ self::$connection->commit(); /** @Then the payload reflects the event's public properties */ @@ -128,7 +128,7 @@ public function testPushWhenCallerRollsBackThenNoRecordPersisted(): void /** @Given a repository */ $repository = new DoctrineOutboxRepository( connection: self::$connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) + serializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) ); /** @And the caller opens a transaction */ @@ -155,11 +155,13 @@ public function testPushWhenTwoRecordsThenBothPersisted(): void /** @Given a repository */ $repository = new DoctrineOutboxRepository( connection: self::$connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) + serializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) ); - /** @When pushing two records inside a transaction */ + /** @And the connection has an active transaction */ self::$connection->beginTransaction(); + + /** @When pushing two records */ $repository->push(records: EventRecords::createFrom(elements: [ EventRecordFactory::create( event: new OrderPlaced(), @@ -172,6 +174,8 @@ public function testPushWhenTwoRecordsThenBothPersisted(): void eventTypeName: 'OrderPlaced' ) ])); + + /** @And the transaction is committed */ self::$connection->commit(); /** @Then exactly two records are stored */ @@ -186,11 +190,13 @@ public function testPushWhenUuidWithNullBytesThenBytesPreservedInStorage(): void /** @And a repository */ $repository = new DoctrineOutboxRepository( connection: self::$connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) + serializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) ); - /** @When pushing a record with the null-byte UUID inside a transaction */ + /** @And the connection has an active transaction */ self::$connection->beginTransaction(); + + /** @When pushing a record with the null-byte UUID */ $repository->push(records: EventRecords::createFrom(elements: [ EventRecordFactory::create( event: new OrderPlaced(), @@ -199,6 +205,8 @@ public function testPushWhenUuidWithNullBytesThenBytesPreservedInStorage(): void id: $recordId ) ])); + + /** @And the transaction is committed */ self::$connection->commit(); /** @Then the retrieved bytes are identical to the original UUID bytes */ @@ -211,7 +219,7 @@ public function testPushWhenSerializerReturnsInvalidJsonThenInvalidPayloadJson() /** @Given a repository with a serializer that produces invalid JSON */ $repository = new DoctrineOutboxRepository( connection: self::$connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new InvalidPayloadSerializer()]) + serializers: PayloadSerializers::createFrom(elements: [new InvalidPayloadSerializer()]) ); /** @And the connection has an active transaction */ @@ -228,7 +236,7 @@ public function testPushWhenSerializerReturnsInvalidJsonThenInvalidPayloadJson() /** @Then an exception indicating invalid JSON payload is thrown */ $this->expectException(InvalidPayloadJson::class); - $this->expectExceptionMessage('Payload is not valid JSON: not json'); + $this->expectExceptionMessage('Payload is not valid JSON .'); /** @When pushing the record */ $repository->push(records: $records); @@ -239,14 +247,16 @@ public function testPushWhenMultipleSerializersAndSecondMatchesThenCorrectSerial /** @Given a repository with an order serializer followed by a refund serializer */ $repository = new DoctrineOutboxRepository( connection: self::$connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [ + serializers: PayloadSerializers::createFrom(elements: [ new OrderPlacedSerializer(), new RefundIssuedSerializer() ]) ); - /** @When pushing a refund event inside a transaction */ + /** @And the connection has an active transaction */ self::$connection->beginTransaction(); + + /** @When pushing a refund event */ $repository->push(records: EventRecords::createFrom(elements: [ EventRecordFactory::create( event: new RefundIssued(), @@ -254,6 +264,8 @@ public function testPushWhenMultipleSerializersAndSecondMatchesThenCorrectSerial eventTypeName: 'RefundIssued' ) ])); + + /** @And the transaction is committed */ self::$connection->commit(); /** @Then the payload is from the refund serializer */ @@ -268,7 +280,7 @@ public function testPushWhenNoSerializerSupportsThenPayloadSerializerNotConfigur /** @Given a repository with no serializers */ $repository = new DoctrineOutboxRepository( connection: self::$connection, - payloadSerializers: PayloadSerializers::createFromEmpty() + serializers: PayloadSerializers::createFromEmpty() ); /** @And the connection has an active transaction */ @@ -298,7 +310,7 @@ public function testPushWhenSerializerDoesNotSupportEventThenPayloadSerializerNo /** @Given a repository with only an order serializer */ $repository = new DoctrineOutboxRepository( connection: self::$connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) + serializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) ); /** @And the connection has an active transaction */ @@ -323,41 +335,12 @@ public function testPushWhenSerializerDoesNotSupportEventThenPayloadSerializerNo $repository->push(records: $records); } - public function testPushWhenNoSnapshotSerializerSupportsThenSnapshotSerializerNotConfigured(): void - { - /** @Given a repository with empty snapshot serializers */ - $repository = new DoctrineOutboxRepository( - connection: self::$connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]), - snapshotSerializers: SnapshotSerializers::createFromEmpty() - ); - - /** @And the connection has an active transaction */ - self::$connection->beginTransaction(); - - /** @And a record to push */ - $records = EventRecords::createFrom(elements: [ - EventRecordFactory::create( - event: new OrderPlaced(), - aggregateType: 'Order', - eventTypeName: 'OrderPlaced' - ) - ]); - - /** @Then an exception indicating no snapshot serializer is configured is thrown */ - $this->expectException(SnapshotSerializerNotConfigured::class); - $this->expectExceptionMessage('No snapshot serializer configured for aggregate type "Order".'); - - /** @When pushing the record */ - $repository->push(records: $records); - } - public function testPushWhenDuplicateEventIdThenDuplicateOutboxEvent(): void { /** @Given a repository */ $repository = new DoctrineOutboxRepository( connection: self::$connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) + serializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) ); /** @And a record with a fixed id */ @@ -382,128 +365,49 @@ public function testPushWhenDuplicateEventIdThenDuplicateOutboxEvent(): void $repository->push(records: $records); } - public function testPushWhenDuplicateAggregateSequenceThenDuplicateAggregateSequence(): void + public function testPushWhenDuplicateAggregateVersionThenDuplicateAggregateVersion(): void { /** @Given a repository */ $repository = new DoctrineOutboxRepository( connection: self::$connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) + serializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) ); - /** @And a fixed aggregate identity and sequence number */ + /** @And a fixed aggregate identity and aggregate version */ $aggregateId = Uuid::uuid4()->toString(); /** @And the connection has an active transaction */ self::$connection->beginTransaction(); - /** @And a first record is pushed with that aggregate and sequence number */ + /** @And a first record is pushed with that aggregate and aggregate version */ $repository->push(records: EventRecords::createFrom(elements: [ EventRecordFactory::create( event: new OrderPlaced(), aggregateType: 'Order', eventTypeName: 'OrderPlaced', aggregateId: $aggregateId, - sequenceNumber: SequenceNumber::of(value: 1) + aggregateVersion: AggregateVersion::of(value: 1) ) ])); - /** @Then an exception indicating a duplicate aggregate sequence is thrown */ - $this->expectException(DuplicateAggregateSequence::class); + /** @Then an exception indicating a duplicate aggregate version is thrown */ + $this->expectException(DuplicateAggregateVersion::class); $this->expectExceptionMessage( - sprintf('Duplicate aggregate sequence for at sequence number <1>.', $aggregateId) + sprintf('Duplicate aggregate version for at aggregate version <1>.', $aggregateId) ); - /** @When pushing a second record with the same aggregate and sequence number but a different id */ + /** @When pushing a second record with the same aggregate and aggregate version but a different id */ $repository->push(records: EventRecords::createFrom(elements: [ EventRecordFactory::create( event: new OrderPlaced(), aggregateType: 'Order', eventTypeName: 'OrderPlaced', aggregateId: $aggregateId, - sequenceNumber: SequenceNumber::of(value: 1) + aggregateVersion: AggregateVersion::of(value: 1) ) ])); } - public function testPushWhenNoSnapshotSerializerThenReflectionSnapshotSerializerIsUsed(): void - { - /** @Given a repository without an explicit snapshot serializer */ - $repository = new DoctrineOutboxRepository( - connection: self::$connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) - ); - - /** @When pushing a record with snapshot data inside a transaction */ - self::$connection->beginTransaction(); - $repository->push(records: EventRecords::createFrom(elements: [ - EventRecordFactory::create( - event: new OrderPlaced(), - aggregateType: 'Order', - eventTypeName: 'OrderPlaced', - snapshot: ['status' => 'placed'] - ) - ])); - self::$connection->commit(); - - /** @Then the snapshot is stored using the default reflection serializer */ - self::assertSame( - '{"status": "placed"}', - self::$connection->fetchOne('SELECT snapshot FROM outbox_events LIMIT 1') - ); - } - - public function testPushWhenCustomSnapshotSerializerThenCustomSnapshotIsUsed(): void - { - /** @Given a repository with a custom snapshot serializer */ - $repository = new DoctrineOutboxRepository( - connection: self::$connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]), - snapshotSerializers: SnapshotSerializers::createFrom(elements: [new CustomOrderSnapshotSerializer()]) - ); - - /** @When pushing a record inside a transaction */ - self::$connection->beginTransaction(); - $repository->push(records: EventRecords::createFrom(elements: [ - EventRecordFactory::create( - event: new OrderPlaced(), - aggregateType: 'Order', - eventTypeName: 'OrderPlaced' - ) - ])); - self::$connection->commit(); - - /** @Then the snapshot uses the custom serializer output */ - self::assertSame('{"custom": true}', self::$connection->fetchOne('SELECT snapshot FROM outbox_events LIMIT 1')); - } - - public function testPushWhenExplicitReflectionSnapshotSerializerThenBehaviorMatchesDefault(): void - { - /** @Given a repository with ReflectionSnapshotSerializer explicitly provided */ - $repository = new DoctrineOutboxRepository( - connection: self::$connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]), - snapshotSerializers: SnapshotSerializers::createFrom(elements: [new SnapshotSerializerReflection()]) - ); - - /** @When pushing a record with snapshot data inside a transaction */ - self::$connection->beginTransaction(); - $repository->push(records: EventRecords::createFrom(elements: [ - EventRecordFactory::create( - event: new OrderPlaced(), - aggregateType: 'Order', - eventTypeName: 'OrderPlaced', - snapshot: ['status' => 'placed'] - ) - ])); - self::$connection->commit(); - - /** @Then the snapshot is identical to the default behavior */ - self::assertSame( - '{"status": "placed"}', - self::$connection->fetchOne('SELECT snapshot FROM outbox_events LIMIT 1') - ); - } - public function testPushWhenCustomTableNameThenRecordStoredInCustomTable(): void { /** @Given a custom table layout with a different table name */ @@ -526,12 +430,14 @@ public function testPushWhenCustomTableNameThenRecordStoredInCustomTable(): void /** @And a repository using the custom layout */ $repository = new DoctrineOutboxRepository( connection: self::$connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]), + serializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]), tableLayout: $tableLayout ); - /** @When pushing a record inside a transaction */ + /** @And the connection has an active transaction */ self::$connection->beginTransaction(); + + /** @When pushing a record */ $repository->push(records: EventRecords::createFrom(elements: [ EventRecordFactory::create( event: new OrderPlaced(), @@ -539,6 +445,8 @@ public function testPushWhenCustomTableNameThenRecordStoredInCustomTable(): void eventTypeName: 'OrderPlaced' ) ])); + + /** @And the transaction is committed */ self::$connection->commit(); /** @Then the record is in the custom table */ @@ -576,12 +484,14 @@ public function testPushWhenStringIdentityTypeStoredThenIdIsUuidString(): void /** @And a repository using the string layout */ $repository = new DoctrineOutboxRepository( connection: self::$connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]), + serializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]), tableLayout: $tableLayout ); - /** @When pushing a record inside a transaction */ + /** @And the connection has an active transaction */ self::$connection->beginTransaction(); + + /** @When pushing a record */ $repository->push(records: EventRecords::createFrom(elements: [ EventRecordFactory::create( event: new OrderPlaced(), @@ -589,6 +499,8 @@ public function testPushWhenStringIdentityTypeStoredThenIdIsUuidString(): void eventTypeName: 'OrderPlaced' ) ])); + + /** @And the transaction is committed */ self::$connection->commit(); /** @Then the id is stored as a 36-character UUID string */ @@ -624,15 +536,17 @@ public function testPushWhenNonUuidAggregateIdWithStringTypeThenStoredAsOriginal /** @And a repository using the string layout */ $repository = new DoctrineOutboxRepository( connection: self::$connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]), + serializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]), tableLayout: $tableLayout ); /** @And a non-UUID aggregate identity */ $aggregateId = 'ord-1'; - /** @When pushing a record with a non-UUID aggregate id inside a transaction */ + /** @And the connection has an active transaction */ self::$connection->beginTransaction(); + + /** @When pushing a record with a non-UUID aggregate id */ $repository->push(records: EventRecords::createFrom(elements: [ EventRecordFactory::create( event: new OrderPlaced(), @@ -641,6 +555,8 @@ public function testPushWhenNonUuidAggregateIdWithStringTypeThenStoredAsOriginal aggregateId: $aggregateId ) ])); + + /** @And the transaction is committed */ self::$connection->commit(); /** @Then the aggregate_id is stored as the original string */ @@ -652,22 +568,25 @@ public function testPushWhenSingleRecordThenAllFieldsPersistedCorrectly(): void /** @Given a repository with an order placed serializer */ $repository = new DoctrineOutboxRepository( connection: self::$connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) + serializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) ); - /** @When pushing the record inside a transaction */ + /** @And the connection has an active transaction */ self::$connection->beginTransaction(); + + /** @When pushing the record */ $repository->push(records: EventRecords::createFrom(elements: [ EventRecordFactory::create( event: new OrderPlaced(), aggregateType: 'Order', eventTypeName: 'OrderPlaced', revision: Revision::of(value: 2), - snapshot: ['status' => 'placed'], - occurredOn: Instant::fromString(value: '2024-06-01 12:00:00.000000'), - sequenceNumber: SequenceNumber::of(value: 3) + occurredAt: Instant::fromString(value: '2024-06-01 12:00:00.000000'), + aggregateVersion: AggregateVersion::of(value: 3) ) ])); + + /** @And the transaction is committed */ self::$connection->commit(); /** @Then the row is retrievable from the database */ @@ -685,18 +604,12 @@ public function testPushWhenSingleRecordThenAllFieldsPersistedCorrectly(): void /** @And the revision is correct */ self::assertSame(2, (int)$row['revision']); - /** @And the sequence_number is correct */ - self::assertSame(3, (int)$row['sequence_number']); + /** @And the aggregate_version is correct */ + self::assertSame(3, (int)$row['aggregate_version']); /** @And the payload matches the serializer output */ self::assertSame('{}', $row['payload']); - /** @And the snapshot contains the aggregate state */ - self::assertSame('{"status": "placed"}', $row['snapshot']); - - /** @And the payload and snapshot store distinct JSON objects */ - self::assertNotSame($row['payload'], $row['snapshot']); - /** @And the aggregate_type is correct */ self::assertSame('Order', $row['aggregate_type']); @@ -709,14 +622,16 @@ public function testPushWhenKnownIdThenPersistedIdMatchesOriginal(): void /** @Given a repository */ $repository = new DoctrineOutboxRepository( connection: self::$connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) + serializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) ); /** @And a record with a known id */ $recordId = Uuid::uuid4(); - /** @When pushing the record inside a transaction */ + /** @And the connection has an active transaction */ self::$connection->beginTransaction(); + + /** @When pushing the record */ $repository->push(records: EventRecords::createFrom(elements: [ EventRecordFactory::create( event: new OrderPlaced(), @@ -725,6 +640,8 @@ public function testPushWhenKnownIdThenPersistedIdMatchesOriginal(): void id: $recordId ) ])); + + /** @And the transaction is committed */ self::$connection->commit(); /** @Then the persisted id bytes match the original record id */ @@ -745,13 +662,12 @@ public function testPushWhenAllColumnNamesAreCustomThenRecordStoredInCustomColum ->withId(name: 'event_id', type: IdentityColumnType::BINARY) ->withPayload(name: 'event_payload') ->withRevision(name: 'event_revision') - ->withSnapshot(name: 'event_snapshot') ->withCreatedAt(name: 'event_created_at') ->withEventType(name: 'event_event_type') ->withOccurredAt(name: 'event_occurred_at') ->withAggregateId(name: 'event_aggregate_id', type: IdentityColumnType::BINARY) ->withAggregateType(name: 'event_aggregate_type') - ->withSequenceNumber(name: 'event_sequence_number') + ->withAggregateVersion(name: 'event_aggregate_version') ->build() ) ->build(); @@ -771,20 +687,24 @@ public function testPushWhenAllColumnNamesAreCustomThenRecordStoredInCustomColum /** @And a repository using this layout */ $repository = new DoctrineOutboxRepository( connection: self::$connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]), + serializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]), tableLayout: $tableLayout ); - /** @When pushing a record inside a transaction */ + /** @And the connection has an active transaction */ self::$connection->beginTransaction(); + + /** @When pushing a record */ $repository->push(records: EventRecords::createFrom(elements: [ EventRecordFactory::create( event: new OrderPlaced(), aggregateType: 'Order', eventTypeName: 'OrderPlaced', - sequenceNumber: SequenceNumber::of(value: 5) + aggregateVersion: AggregateVersion::of(value: 5) ) ])); + + /** @And the transaction is committed */ self::$connection->commit(); /** @Then the record is retrievable from the custom table */ @@ -805,15 +725,12 @@ public function testPushWhenAllColumnNamesAreCustomThenRecordStoredInCustomColum /** @And event_revision is correct */ self::assertSame(1, (int)$row['event_revision']); - /** @And event_sequence_number is correct */ - self::assertSame(5, (int)$row['event_sequence_number']); + /** @And event_aggregate_version is correct */ + self::assertSame(5, (int)$row['event_aggregate_version']); /** @And event_payload matches the serializer output */ self::assertSame('{}', $row['event_payload']); - /** @And event_snapshot is stored */ - self::assertNotNull($row['event_snapshot']); - /** @And event_occurred_at is stored */ self::assertNotNull($row['event_occurred_at']); @@ -821,46 +738,21 @@ public function testPushWhenAllColumnNamesAreCustomThenRecordStoredInCustomColum self::assertNotNull($row['event_created_at']); } - public function testPushWhenSnapshotSerializerReturnsInvalidJsonThenInvalidSnapshotJson(): void - { - /** @Given a repository with a snapshot serializer that produces invalid JSON */ - $repository = new DoctrineOutboxRepository( - connection: self::$connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]), - snapshotSerializers: SnapshotSerializers::createFrom(elements: [new InvalidSnapshotSerializer()]) - ); - - /** @And the connection has an active transaction */ - self::$connection->beginTransaction(); - - /** @And a record to push */ - $records = EventRecords::createFrom(elements: [ - EventRecordFactory::create( - event: new OrderPlaced(), - aggregateType: 'Order', - eventTypeName: 'OrderPlaced' - ) - ]); - - /** @Then an exception indicating invalid JSON snapshot is thrown */ - $this->expectException(InvalidSnapshotJson::class); - $this->expectExceptionMessage('Snapshot is not valid JSON: not json'); - - /** @When pushing the record */ - $repository->push(records: $records); - } - public function testPushWhenEventRecordsIsEmptyThenNoInsertIsExecuted(): void { /** @Given a repository */ $repository = new DoctrineOutboxRepository( connection: self::$connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) + serializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) ); - /** @When pushing an empty EventRecords collection inside a transaction */ + /** @And the connection has an active transaction */ self::$connection->beginTransaction(); + + /** @When pushing an empty EventRecords collection */ $repository->push(records: EventRecords::createFromEmpty()); + + /** @And the transaction is committed */ self::$connection->commit(); /** @Then no records are persisted */ @@ -872,12 +764,16 @@ public function testPushWhenRealEventualAggregateRootThenEventRecordIsPersistedC /** @Given a repository with a reflection payload serializer */ $repository = new DoctrineOutboxRepository( connection: self::$connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new PayloadSerializerReflection()]) + serializers: PayloadSerializers::createFrom(elements: [new PayloadSerializerReflection()]) ); - /** @When pushing the aggregate's recorded events inside a transaction */ + /** @And the connection has an active transaction */ self::$connection->beginTransaction(); + + /** @When pushing the aggregate's recorded events */ $repository->push(records: Order::place(orderId: Uuid::uuid4()->toString())->recordedEvents()); + + /** @And the transaction is committed */ self::$connection->commit(); /** @Then one outbox record is persisted */ @@ -904,7 +800,7 @@ public function testPushWhenNullTableLayoutThenSqlUsesDefaultTableName(): void /** @When pushing a record using the default table layout */ new DoctrineOutboxRepository( connection: $connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) + serializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) )->push( records: EventRecords::createFrom(elements: [ EventRecordFactory::create( @@ -936,7 +832,7 @@ public function testPushWhenCustomTableLayoutThenSqlUsesCustomTableName(): void /** @When pushing a record using the custom table layout */ new DoctrineOutboxRepository( connection: $connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]), + serializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]), tableLayout: $tableLayout )->push( records: EventRecords::createFrom(elements: [ @@ -949,65 +845,6 @@ public function testPushWhenCustomTableLayoutThenSqlUsesCustomTableName(): void ); } - public function testPushWhenNullSnapshotSerializersThenExecuteStatementIsCalled(): void - { - /** @Given a mocked connection with an active transaction */ - $connection = $this->createMock(Connection::class); - - /** @And the connection reports an active transaction */ - $connection->method('isTransactionActive')->willReturn(true); - - /** @Then the statement is executed exactly once */ - $connection->expects(self::once())->method('executeStatement')->willReturn(1); - - /** @When pushing a record using the default snapshot serializers */ - new DoctrineOutboxRepository( - connection: $connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) - )->push( - records: EventRecords::createFrom(elements: [ - EventRecordFactory::create( - event: new OrderPlaced(), - aggregateType: 'Order', - eventTypeName: 'OrderPlaced' - ) - ]) - ); - } - - public function testPushWhenCustomSnapshotSerializersThenExecuteStatementUsesCustomSnapshot(): void - { - /** @Given a mocked connection with an active transaction */ - $connection = $this->createMock(Connection::class); - - /** @And the connection reports an active transaction */ - $connection->method('isTransactionActive')->willReturn(true); - - /** @Then the statement is executed with the custom snapshot value */ - $connection->expects(self::once()) - ->method('executeStatement') - ->with( - self::anything(), - self::callback(static fn(array $params): bool => $params['snapshot'] === '{"custom":true}') - ) - ->willReturn(1); - - /** @When pushing a record using custom snapshot serializers */ - new DoctrineOutboxRepository( - connection: $connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]), - snapshotSerializers: SnapshotSerializers::createFrom(elements: [new CustomOrderSnapshotSerializer()]) - )->push( - records: EventRecords::createFrom(elements: [ - EventRecordFactory::create( - event: new OrderPlaced(), - aggregateType: 'Order', - eventTypeName: 'OrderPlaced' - ) - ]) - ); - } - public function testPushWhenRecordHasAllFieldsThenExecuteStatementReceivesAllBindings(): void { /** @Given a mocked connection with an active transaction */ @@ -1042,7 +879,7 @@ function (string $sql, array $params) use (&$capturedParameters): int { /** @When pushing a record with all deterministic fields */ new DoctrineOutboxRepository( connection: $connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]), + serializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]), tableLayout: $tableLayout )->push( records: EventRecords::createFrom(elements: [ @@ -1051,52 +888,53 @@ function (string $sql, array $params) use (&$capturedParameters): int { aggregateType: 'Order', eventTypeName: 'OrderPlaced', id: Uuid::fromString('550e8400-e29b-41d4-a716-446655440000'), - occurredOn: Instant::fromString(value: '2021-01-01T00:00:00+00:00'), + occurredAt: Instant::fromString(value: '2021-01-01T00:00:00+00:00'), aggregateId: '6ba7b810-9dad-11d1-80b4-00c04fd430c8' ) ]) ); - /** @Then executeStatement receives all nine expected parameter bindings */ + /** @Then executeStatement receives all expected parameter bindings */ self::assertSame( [ - 'id' => '550e8400-e29b-41d4-a716-446655440000', - 'aggregateId' => '6ba7b810-9dad-11d1-80b4-00c04fd430c8', - 'aggregateType' => 'Order', - 'eventType' => 'OrderPlaced', - 'revision' => 1, - 'sequenceNumber' => 1, - 'payload' => '{}', - 'snapshot' => '[]', - 'occurredAt' => '2021-01-01T00:00:00+00:00' + 'id' => '550e8400-e29b-41d4-a716-446655440000', + 'aggregateId' => '6ba7b810-9dad-11d1-80b4-00c04fd430c8', + 'aggregateType' => 'Order', + 'eventType' => 'OrderPlaced', + 'revision' => 1, + 'aggregateVersion' => 1, + 'payload' => '{}', + 'occurredAt' => '2021-01-01T00:00:00+00:00' ], $capturedParameters ); } - public function testPushWhenUniqueConstraintOnSequenceNumberThenDuplicateAggregateSequenceIsThrown(): void + public function testPushWhenUniqueConstraintOnAggregateVersionThenDuplicateAggregateVersionIsThrown(): void { /** @Given a mocked connection with an active transaction */ $connection = self::createConfiguredStub(Connection::class, ['isTransactionActive' => true]); - /** @And the connection raises a sequence number constraint violation */ + /** @And the connection raises an aggregate version constraint violation */ $connection->method('executeStatement')->willThrowException( new UniqueConstraintViolationException( - new DriverExceptionStub('Duplicate entry for key uniq_aggregate_sequence'), + new DriverExceptionStub( + 'Duplicate entry for key unq_outbox_events_aggregate_type_aggregate_id_aggregate_version' + ), null ) ); - /** @Then a duplicate aggregate sequence exception is thrown */ - $this->expectException(DuplicateAggregateSequence::class); + /** @Then a duplicate aggregate version exception is thrown */ + $this->expectException(DuplicateAggregateVersion::class); $this->expectExceptionMessage( - 'Duplicate aggregate sequence for at sequence number <1>.' + 'Duplicate aggregate version for at aggregate version <1>.' ); /** @When pushing the record */ new DoctrineOutboxRepository( connection: $connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) + serializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) )->push( records: EventRecords::createFrom(elements: [ EventRecordFactory::create( @@ -1124,12 +962,12 @@ public function testPushWhenUniqueConstraintOnEventIdThenDuplicateOutboxEventIsT /** @Then a duplicate outbox event exception is thrown */ $this->expectException(DuplicateOutboxEvent::class); - $this->expectExceptionMessageMatches('/Event with id ".+" already exists in outbox\./'); + $this->expectExceptionMessageMatches('/Event with id <.+> already exists in outbox\./'); /** @When pushing the record */ new DoctrineOutboxRepository( connection: $connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) + serializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) )->push( records: EventRecords::createFrom(elements: [ EventRecordFactory::create( @@ -1141,31 +979,31 @@ public function testPushWhenUniqueConstraintOnEventIdThenDuplicateOutboxEventIsT ); } - public function testPushWhenUniqueConstraintWithCustomNameThenDuplicateAggregateSequenceIsThrown(): void + public function testPushWhenUniqueConstraintWithCustomNameThenDuplicateAggregateVersionIsThrown(): void { /** @Given a mocked connection with an active transaction */ $connection = self::createConfiguredStub(Connection::class, ['isTransactionActive' => true]); /** @And a custom table layout with a distinct unique constraint name */ $tableLayout = TableLayout::builder() - ->withUniqueConstraint(name: 'uniq_custom_outbox_sequence') + ->withUniqueConstraint(name: 'unq_custom_outbox_aggregate_version') ->build(); /** @And the connection raises a violation on the custom constraint name */ $connection->method('executeStatement')->willThrowException( new UniqueConstraintViolationException( - new DriverExceptionStub('Duplicate entry for key uniq_custom_outbox_sequence'), + new DriverExceptionStub('Duplicate entry for key unq_custom_outbox_aggregate_version'), null ) ); - /** @Then a duplicate aggregate sequence exception is thrown */ - $this->expectException(DuplicateAggregateSequence::class); + /** @Then a duplicate aggregate version exception is thrown */ + $this->expectException(DuplicateAggregateVersion::class); /** @When pushing a record with the custom table layout */ new DoctrineOutboxRepository( connection: $connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]), + serializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]), tableLayout: $tableLayout )->push( records: EventRecords::createFrom(elements: [ @@ -1178,12 +1016,12 @@ public function testPushWhenUniqueConstraintWithCustomNameThenDuplicateAggregate ); } - public function testPushWhenConstraintNameIsCustomThenDuplicateAggregateSequence(): void + public function testPushWhenConstraintNameIsCustomThenDuplicateAggregateVersion(): void { /** @Given a custom table layout with a distinct unique constraint name */ $tableLayout = TableLayout::builder() ->withTableName(tableName: 'custom_constraint_outbox') - ->withUniqueConstraint(name: 'uniq_custom_outbox_sequence') + ->withUniqueConstraint(name: 'unq_custom_outbox_aggregate_version') ->build(); /** @And any pre-existing table is dropped */ @@ -1201,7 +1039,7 @@ public function testPushWhenConstraintNameIsCustomThenDuplicateAggregateSequence /** @And a repository using the custom table layout */ $repository = new DoctrineOutboxRepository( connection: self::$connection, - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]), + serializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]), tableLayout: $tableLayout ); @@ -1211,28 +1049,28 @@ public function testPushWhenConstraintNameIsCustomThenDuplicateAggregateSequence /** @And the connection has an active transaction */ self::$connection->beginTransaction(); - /** @And a first record is pushed with that aggregate and sequence number */ + /** @And a first record is pushed with that aggregate and aggregate version */ $repository->push(records: EventRecords::createFrom(elements: [ EventRecordFactory::create( event: new OrderPlaced(), aggregateType: 'Order', eventTypeName: 'OrderPlaced', aggregateId: $aggregateId, - sequenceNumber: SequenceNumber::of(value: 1) + aggregateVersion: AggregateVersion::of(value: 1) ) ])); - /** @Then an exception indicating a duplicate aggregate sequence is thrown */ - $this->expectException(DuplicateAggregateSequence::class); + /** @Then an exception indicating a duplicate aggregate version is thrown */ + $this->expectException(DuplicateAggregateVersion::class); - /** @When pushing a second record with the same aggregate and sequence number */ + /** @When pushing a second record with the same aggregate and aggregate version */ $repository->push(records: EventRecords::createFrom(elements: [ EventRecordFactory::create( event: new OrderPlaced(), aggregateType: 'Order', eventTypeName: 'OrderPlaced', aggregateId: $aggregateId, - sequenceNumber: SequenceNumber::of(value: 1) + aggregateVersion: AggregateVersion::of(value: 1) ) ])); } diff --git a/tests/Mocks/FallbackOrderPlacedSerializer.php b/tests/Integration/FallbackOrderPlacedSerializer.php similarity index 92% rename from tests/Mocks/FallbackOrderPlacedSerializer.php rename to tests/Integration/FallbackOrderPlacedSerializer.php index 496c406..7d9bcbc 100644 --- a/tests/Mocks/FallbackOrderPlacedSerializer.php +++ b/tests/Integration/FallbackOrderPlacedSerializer.php @@ -2,7 +2,7 @@ declare(strict_types=1); -namespace Test\TinyBlocks\Outbox\Mocks; +namespace Test\TinyBlocks\Outbox\Integration; use Test\TinyBlocks\Outbox\Models\OrderPlaced; use TinyBlocks\BuildingBlocks\Event\EventRecord; diff --git a/tests/IntegrationTestCase.php b/tests/Integration/IntegrationTestCase.php similarity index 94% rename from tests/IntegrationTestCase.php rename to tests/Integration/IntegrationTestCase.php index cf1a8ab..5ce2ada 100644 --- a/tests/IntegrationTestCase.php +++ b/tests/Integration/IntegrationTestCase.php @@ -2,7 +2,7 @@ declare(strict_types=1); -namespace Test\TinyBlocks\Outbox; +namespace Test\TinyBlocks\Outbox\Integration; use Doctrine\DBAL\Connection; use PHPUnit\Framework\TestCase; diff --git a/tests/OutboxTableFactory.php b/tests/Integration/OutboxTableFactory.php similarity index 62% rename from tests/OutboxTableFactory.php rename to tests/Integration/OutboxTableFactory.php index ffd597d..06c60de 100644 --- a/tests/OutboxTableFactory.php +++ b/tests/Integration/OutboxTableFactory.php @@ -2,7 +2,7 @@ declare(strict_types=1); -namespace Test\TinyBlocks\Outbox; +namespace Test\TinyBlocks\Outbox\Integration; use Doctrine\DBAL\Connection; use TinyBlocks\Outbox\Schema\TableLayout; @@ -18,20 +18,20 @@ public static function createWithBinaryIdentities(Connection $connection, TableL $template = <<executeStatement( @@ -39,20 +39,19 @@ public static function createWithBinaryIdentities(Connection $connection, TableL $template, $tableLayout->tableName, $tableLayout->columns->id->name, - $tableLayout->columns->aggregateType, - $tableLayout->columns->aggregateId->name, - $tableLayout->columns->eventType, - $tableLayout->columns->revision, - $tableLayout->columns->sequenceNumber, $tableLayout->columns->payload, - $tableLayout->columns->snapshot, + $tableLayout->columns->revision, + $tableLayout->columns->eventType, $tableLayout->columns->occurredAt, - $tableLayout->columns->createdAt, $tableLayout->columns->aggregateId->name, + $tableLayout->columns->aggregateType, + $tableLayout->columns->aggregateVersion, + $tableLayout->columns->createdAt, + $tableLayout->columns->id->name, $tableLayout->uniqueConstraint->name, $tableLayout->columns->aggregateType, $tableLayout->columns->aggregateId->name, - $tableLayout->columns->sequenceNumber + $tableLayout->columns->aggregateVersion ) ); } @@ -62,20 +61,20 @@ public static function createWithStringIdentities(Connection $connection, TableL $template = <<executeStatement( @@ -83,20 +82,19 @@ public static function createWithStringIdentities(Connection $connection, TableL $template, $tableLayout->tableName, $tableLayout->columns->id->name, - $tableLayout->columns->aggregateType, - $tableLayout->columns->aggregateId->name, - $tableLayout->columns->eventType, - $tableLayout->columns->revision, - $tableLayout->columns->sequenceNumber, $tableLayout->columns->payload, - $tableLayout->columns->snapshot, + $tableLayout->columns->revision, + $tableLayout->columns->eventType, $tableLayout->columns->occurredAt, - $tableLayout->columns->createdAt, $tableLayout->columns->aggregateId->name, + $tableLayout->columns->aggregateType, + $tableLayout->columns->aggregateVersion, + $tableLayout->columns->createdAt, + $tableLayout->columns->id->name, $tableLayout->uniqueConstraint->name, $tableLayout->columns->aggregateType, $tableLayout->columns->aggregateId->name, - $tableLayout->columns->sequenceNumber + $tableLayout->columns->aggregateVersion ) ); } diff --git a/tests/Mocks/RefundIssuedSerializer.php b/tests/Integration/RefundIssuedSerializer.php similarity index 92% rename from tests/Mocks/RefundIssuedSerializer.php rename to tests/Integration/RefundIssuedSerializer.php index 525cef3..8796ae2 100644 --- a/tests/Mocks/RefundIssuedSerializer.php +++ b/tests/Integration/RefundIssuedSerializer.php @@ -2,7 +2,7 @@ declare(strict_types=1); -namespace Test\TinyBlocks\Outbox\Mocks; +namespace Test\TinyBlocks\Outbox\Integration; use Test\TinyBlocks\Outbox\Models\RefundIssued; use TinyBlocks\BuildingBlocks\Event\EventRecord; diff --git a/tests/Mocks/CustomOrderSnapshotSerializer.php b/tests/Mocks/CustomOrderSnapshotSerializer.php deleted file mode 100644 index c76b11f..0000000 --- a/tests/Mocks/CustomOrderSnapshotSerializer.php +++ /dev/null @@ -1,22 +0,0 @@ -toString()), revision: $revision ?? Revision::initial(), - occurredOn: $occurredOn ?? Instant::now(), - snapshotData: new SnapshotData(payload: $snapshot ?? []), + eventType: EventType::fromString(value: $eventTypeName), + occurredAt: $occurredAt ?? Instant::now(), + aggregateId: new OrderId(value: $aggregateId ?? Uuid::uuid4()->toString()), aggregateType: $aggregateType, - sequenceNumber: $sequenceNumber ?? SequenceNumber::first() + aggregateVersion: $aggregateVersion ?? AggregateVersion::first() ); } } diff --git a/tests/Models/Order.php b/tests/Models/Order.php index 4046e23..d677d2b 100644 --- a/tests/Models/Order.php +++ b/tests/Models/Order.php @@ -21,9 +21,4 @@ public static function place(string $orderId): Order $order->push(event: new OrderPlaced()); return $order; } - - protected function snapshotState(): array - { - return ['status' => 'placed']; - } } diff --git a/tests/Mocks/DriverExceptionStub.php b/tests/Unit/DriverExceptionStub.php similarity index 77% rename from tests/Mocks/DriverExceptionStub.php rename to tests/Unit/DriverExceptionStub.php index db0b053..d9f5c4c 100644 --- a/tests/Mocks/DriverExceptionStub.php +++ b/tests/Unit/DriverExceptionStub.php @@ -2,7 +2,7 @@ declare(strict_types=1); -namespace Test\TinyBlocks\Outbox\Mocks; +namespace Test\TinyBlocks\Outbox\Unit; use Doctrine\DBAL\Driver\AbstractException; diff --git a/tests/Mocks/InMemoryOutboxRepositoryMock.php b/tests/Unit/InMemoryOutboxRepositoryMock.php similarity index 62% rename from tests/Mocks/InMemoryOutboxRepositoryMock.php rename to tests/Unit/InMemoryOutboxRepositoryMock.php index d33f3b3..c45bf44 100644 --- a/tests/Mocks/InMemoryOutboxRepositoryMock.php +++ b/tests/Unit/InMemoryOutboxRepositoryMock.php @@ -2,30 +2,26 @@ declare(strict_types=1); -namespace Test\TinyBlocks\Outbox\Mocks; +namespace Test\TinyBlocks\Outbox\Unit; use Doctrine\DBAL\Exception\UniqueConstraintViolationException; use TinyBlocks\BuildingBlocks\Event\EventRecord; use TinyBlocks\BuildingBlocks\Event\EventRecords; -use TinyBlocks\Outbox\Exceptions\DuplicateAggregateSequence; +use TinyBlocks\Outbox\Exceptions\DuplicateAggregateVersion; use TinyBlocks\Outbox\Exceptions\DuplicateOutboxEvent; use TinyBlocks\Outbox\Exceptions\OutboxRequiresActiveTransaction; use TinyBlocks\Outbox\Exceptions\PayloadSerializerNotConfigured; -use TinyBlocks\Outbox\Exceptions\SnapshotSerializerNotConfigured; use TinyBlocks\Outbox\OutboxRepository; use TinyBlocks\Outbox\Serialization\PayloadSerializers; -use TinyBlocks\Outbox\Serialization\SnapshotSerializers; final class InMemoryOutboxRepositoryMock implements OutboxRepository { - private bool $transactionActive = false; private array $records = []; - private array $aggregateSequences = []; + private bool $transactionActive = false; + private array $aggregateVersions = []; - public function __construct( - private readonly PayloadSerializers $payloadSerializers, - private readonly SnapshotSerializers $snapshotSerializers - ) { + public function __construct(private readonly PayloadSerializers $payloadSerializers) + { } public function beginTransaction(): void @@ -47,7 +43,7 @@ public function rollback(): void { $this->transactionActive = false; $this->records = []; - $this->aggregateSequences = []; + $this->aggregateVersions = []; } public function push(EventRecords $records): void @@ -60,30 +56,24 @@ public function push(EventRecords $records): void $payloadSerializer = $this->payloadSerializers->findFor(record: $record); if (is_null($payloadSerializer)) { - throw new PayloadSerializerNotConfigured(eventClass: $record->event::class); - } - - $snapshotSerializer = $this->snapshotSerializers->findFor(record: $record); - - if (is_null($snapshotSerializer)) { - throw SnapshotSerializerNotConfigured::for(aggregateType: $record->aggregateType); + throw PayloadSerializerNotConfigured::forEventClass(eventClass: $record->event::class); } $payloadSerializer->serialize(record: $record); - $snapshotSerializer->serialize(record: $record); $aggregateKey = sprintf( '%s|%s|%d', $record->aggregateType, - $record->identity->identityValue(), - $record->sequenceNumber->value + $record->aggregateId->identityValue(), + $record->aggregateVersion->value ); - if (isset($this->aggregateSequences[$aggregateKey])) { - throw new DuplicateAggregateSequence( - aggregateId: (string)$record->identity->identityValue(), + if (isset($this->aggregateVersions[$aggregateKey])) { + throw DuplicateAggregateVersion::forRecord( + previous: null, + aggregateId: $record->aggregateId->identityValue(), aggregateType: $record->aggregateType, - sequenceNumber: $record->sequenceNumber->value + aggregateVersion: $record->aggregateVersion->value ); } @@ -99,7 +89,7 @@ public function push(EventRecords $records): void ); } - $this->aggregateSequences[$aggregateKey] = true; + $this->aggregateVersions[$aggregateKey] = true; $this->records[$eventId] = $record; }); } diff --git a/tests/InMemoryOutboxRepositoryTest.php b/tests/Unit/InMemoryOutboxRepositoryTest.php similarity index 65% rename from tests/InMemoryOutboxRepositoryTest.php rename to tests/Unit/InMemoryOutboxRepositoryTest.php index 7fa94f4..442ad23 100644 --- a/tests/InMemoryOutboxRepositoryTest.php +++ b/tests/Unit/InMemoryOutboxRepositoryTest.php @@ -2,30 +2,22 @@ declare(strict_types=1); -namespace Test\TinyBlocks\Outbox; +namespace Test\TinyBlocks\Outbox\Unit; use PHPUnit\Framework\TestCase; use Ramsey\Uuid\Uuid; -use Test\TinyBlocks\Outbox\Mocks\InMemoryOutboxRepositoryMock; -use Test\TinyBlocks\Outbox\Mocks\InvalidPayloadSerializer; -use Test\TinyBlocks\Outbox\Mocks\InvalidSnapshotSerializer; -use Test\TinyBlocks\Outbox\Mocks\OrderPlacedSerializer; use Test\TinyBlocks\Outbox\Models\EventRecordFactory; use Test\TinyBlocks\Outbox\Models\Order; use Test\TinyBlocks\Outbox\Models\OrderPlaced; +use TinyBlocks\BuildingBlocks\Aggregate\AggregateVersion; use TinyBlocks\BuildingBlocks\Event\EventRecords; -use TinyBlocks\BuildingBlocks\Event\SequenceNumber; -use TinyBlocks\Outbox\Exceptions\DuplicateAggregateSequence; +use TinyBlocks\Outbox\Exceptions\DuplicateAggregateVersion; use TinyBlocks\Outbox\Exceptions\DuplicateOutboxEvent; use TinyBlocks\Outbox\Exceptions\InvalidPayloadJson; -use TinyBlocks\Outbox\Exceptions\InvalidSnapshotJson; use TinyBlocks\Outbox\Exceptions\OutboxRequiresActiveTransaction; use TinyBlocks\Outbox\Exceptions\PayloadSerializerNotConfigured; -use TinyBlocks\Outbox\Exceptions\SnapshotSerializerNotConfigured; use TinyBlocks\Outbox\Serialization\PayloadSerializerReflection; use TinyBlocks\Outbox\Serialization\PayloadSerializers; -use TinyBlocks\Outbox\Serialization\SnapshotSerializerReflection; -use TinyBlocks\Outbox\Serialization\SnapshotSerializers; final class InMemoryOutboxRepositoryTest extends TestCase { @@ -33,8 +25,7 @@ public function testPushWhenSingleRecordThenItIsPersisted(): void { /** @Given an in-memory repository with configured serializers */ $outbox = new InMemoryOutboxRepositoryMock( - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]), - snapshotSerializers: SnapshotSerializers::createFrom(elements: [new SnapshotSerializerReflection()]) + payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) ); /** @And a transaction is started */ @@ -60,8 +51,7 @@ public function testPushWhenMultipleRecordsThenAllArePersistedInOrder(): void { /** @Given an in-memory repository with configured serializers */ $outbox = new InMemoryOutboxRepositoryMock( - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]), - snapshotSerializers: SnapshotSerializers::createFrom(elements: [new SnapshotSerializerReflection()]) + payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) ); /** @And a transaction is started */ @@ -73,13 +63,13 @@ public function testPushWhenMultipleRecordsThenAllArePersistedInOrder(): void event: new OrderPlaced(), aggregateType: 'Order', eventTypeName: 'OrderPlaced', - sequenceNumber: SequenceNumber::of(value: 1) + aggregateVersion: AggregateVersion::of(value: 1) ), EventRecordFactory::create( event: new OrderPlaced(), aggregateType: 'Order', eventTypeName: 'OrderPlaced', - sequenceNumber: SequenceNumber::of(value: 2) + aggregateVersion: AggregateVersion::of(value: 2) ) ])); @@ -94,8 +84,7 @@ public function testPushWhenNoTransactionIsActiveThenOutboxRequiresActiveTransac { /** @Given an in-memory repository without an active transaction */ $outbox = new InMemoryOutboxRepositoryMock( - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]), - snapshotSerializers: SnapshotSerializers::createFrom(elements: [new SnapshotSerializerReflection()]) + payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) ); /** @Then an exception requiring an active transaction is thrown */ @@ -115,8 +104,7 @@ public function testPushWhenNoPayloadSerializerMatchesThenPayloadSerializerNotCo { /** @Given an in-memory repository with no payload serializers configured */ $outbox = new InMemoryOutboxRepositoryMock( - payloadSerializers: PayloadSerializers::createFromEmpty(), - snapshotSerializers: SnapshotSerializers::createFrom(elements: [new SnapshotSerializerReflection()]) + payloadSerializers: PayloadSerializers::createFromEmpty() ); /** @And a transaction is started */ @@ -135,36 +123,11 @@ public function testPushWhenNoPayloadSerializerMatchesThenPayloadSerializerNotCo ])); } - public function testPushWhenNoSnapshotSerializerMatchesThenSnapshotSerializerNotConfigured(): void - { - /** @Given an in-memory repository with no snapshot serializers configured */ - $outbox = new InMemoryOutboxRepositoryMock( - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]), - snapshotSerializers: SnapshotSerializers::createFromEmpty() - ); - - /** @And a transaction is started */ - $outbox->beginTransaction(); - - /** @Then an exception indicating no configured snapshot serializer is thrown */ - $this->expectException(SnapshotSerializerNotConfigured::class); - - /** @When pushing a record whose aggregate type has no matching snapshot serializer */ - $outbox->push(records: EventRecords::createFrom(elements: [ - EventRecordFactory::create( - event: new OrderPlaced(), - aggregateType: 'Order', - eventTypeName: 'OrderPlaced' - ) - ])); - } - public function testPushWhenPayloadSerializerReturnsInvalidJsonThenInvalidPayloadJson(): void { /** @Given an in-memory repository with a serializer that produces invalid JSON */ $outbox = new InMemoryOutboxRepositoryMock( - payloadSerializers: PayloadSerializers::createFrom(elements: [new InvalidPayloadSerializer()]), - snapshotSerializers: SnapshotSerializers::createFrom(elements: [new SnapshotSerializerReflection()]) + payloadSerializers: PayloadSerializers::createFrom(elements: [new InvalidPayloadSerializer()]) ); /** @And a transaction is started */ @@ -183,36 +146,11 @@ public function testPushWhenPayloadSerializerReturnsInvalidJsonThenInvalidPayloa ])); } - public function testPushWhenSnapshotSerializerReturnsInvalidJsonThenInvalidSnapshotJson(): void - { - /** @Given an in-memory repository with a snapshot serializer that produces invalid JSON */ - $outbox = new InMemoryOutboxRepositoryMock( - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]), - snapshotSerializers: SnapshotSerializers::createFrom(elements: [new InvalidSnapshotSerializer()]) - ); - - /** @And a transaction is started */ - $outbox->beginTransaction(); - - /** @Then an exception indicating invalid snapshot JSON is thrown */ - $this->expectException(InvalidSnapshotJson::class); - - /** @When pushing a record whose snapshot serializer produces malformed JSON */ - $outbox->push(records: EventRecords::createFrom(elements: [ - EventRecordFactory::create( - event: new OrderPlaced(), - aggregateType: 'Order', - eventTypeName: 'OrderPlaced' - ) - ])); - } - public function testPushWhenTwoRecordsShareTheSameIdThenDuplicateOutboxEvent(): void { /** @Given an in-memory repository with configured serializers */ $outbox = new InMemoryOutboxRepositoryMock( - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]), - snapshotSerializers: SnapshotSerializers::createFrom(elements: [new SnapshotSerializerReflection()]) + payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) ); /** @And a transaction is started */ @@ -241,17 +179,16 @@ public function testPushWhenTwoRecordsShareTheSameIdThenDuplicateOutboxEvent(): aggregateType: 'Order', eventTypeName: 'OrderPlaced', id: $eventId, - sequenceNumber: SequenceNumber::of(value: 2) + aggregateVersion: AggregateVersion::of(value: 2) ) ])); } - public function testPushWhenTwoRecordsShareTheSameAggregateSequenceThenDuplicateAggregateSequence(): void + public function testPushWhenTwoRecordsShareTheSameAggregateVersionThenDuplicateAggregateVersion(): void { /** @Given an in-memory repository with configured serializers */ $outbox = new InMemoryOutboxRepositoryMock( - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]), - snapshotSerializers: SnapshotSerializers::createFrom(elements: [new SnapshotSerializerReflection()]) + payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) ); /** @And a transaction is started */ @@ -260,28 +197,28 @@ public function testPushWhenTwoRecordsShareTheSameAggregateSequenceThenDuplicate /** @And a fixed aggregate identity shared by both records */ $aggregateId = Uuid::uuid4()->toString(); - /** @And a first record with the fixed aggregate and sequence number 1 is pushed */ + /** @And a first record with the fixed aggregate and aggregate version 1 is pushed */ $outbox->push(records: EventRecords::createFrom(elements: [ EventRecordFactory::create( event: new OrderPlaced(), aggregateType: 'Order', eventTypeName: 'OrderPlaced', aggregateId: $aggregateId, - sequenceNumber: SequenceNumber::of(value: 1) + aggregateVersion: AggregateVersion::of(value: 1) ) ])); - /** @Then a duplicate aggregate sequence exception is thrown */ - $this->expectException(DuplicateAggregateSequence::class); + /** @Then a duplicate aggregate version exception is thrown */ + $this->expectException(DuplicateAggregateVersion::class); - /** @When a second record with the same aggregate and sequence number is pushed */ + /** @When a second record with the same aggregate and aggregate version is pushed */ $outbox->push(records: EventRecords::createFrom(elements: [ EventRecordFactory::create( event: new OrderPlaced(), aggregateType: 'Order', eventTypeName: 'OrderPlaced', aggregateId: $aggregateId, - sequenceNumber: SequenceNumber::of(value: 1) + aggregateVersion: AggregateVersion::of(value: 1) ) ])); } @@ -290,8 +227,7 @@ public function testPushWhenEventRecordsIsEmptyThenNoRecordIsPersisted(): void { /** @Given an in-memory repository with configured serializers */ $outbox = new InMemoryOutboxRepositoryMock( - payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]), - snapshotSerializers: SnapshotSerializers::createFrom(elements: [new SnapshotSerializerReflection()]) + payloadSerializers: PayloadSerializers::createFrom(elements: [new OrderPlacedSerializer()]) ); /** @And a transaction is started */ @@ -311,8 +247,7 @@ public function testPushWhenRealEventualAggregateRootThenEventRecordIsPersisted( { /** @Given an in-memory repository with a reflection payload serializer */ $outbox = new InMemoryOutboxRepositoryMock( - payloadSerializers: PayloadSerializers::createFrom(elements: [new PayloadSerializerReflection()]), - snapshotSerializers: SnapshotSerializers::createFrom(elements: [new SnapshotSerializerReflection()]) + payloadSerializers: PayloadSerializers::createFrom(elements: [new PayloadSerializerReflection()]) ); /** @And a transaction is started */ diff --git a/tests/Mocks/InvalidPayloadSerializer.php b/tests/Unit/InvalidPayloadSerializer.php similarity index 93% rename from tests/Mocks/InvalidPayloadSerializer.php rename to tests/Unit/InvalidPayloadSerializer.php index 14ca476..ac6ac21 100644 --- a/tests/Mocks/InvalidPayloadSerializer.php +++ b/tests/Unit/InvalidPayloadSerializer.php @@ -2,7 +2,7 @@ declare(strict_types=1); -namespace Test\TinyBlocks\Outbox\Mocks; +namespace Test\TinyBlocks\Outbox\Unit; use Test\TinyBlocks\Outbox\Models\OrderPlaced; use TinyBlocks\BuildingBlocks\Event\EventRecord; diff --git a/tests/Mocks/OrderPlacedSerializer.php b/tests/Unit/OrderPlacedSerializer.php similarity index 93% rename from tests/Mocks/OrderPlacedSerializer.php rename to tests/Unit/OrderPlacedSerializer.php index 721d86d..9cc81a3 100644 --- a/tests/Mocks/OrderPlacedSerializer.php +++ b/tests/Unit/OrderPlacedSerializer.php @@ -2,7 +2,7 @@ declare(strict_types=1); -namespace Test\TinyBlocks\Outbox\Mocks; +namespace Test\TinyBlocks\Outbox\Unit; use Test\TinyBlocks\Outbox\Models\OrderPlaced; use TinyBlocks\BuildingBlocks\Event\EventRecord; diff --git a/tests/bootstrap.php b/tests/bootstrap.php index 8a12f71..d4e7d2d 100644 --- a/tests/bootstrap.php +++ b/tests/bootstrap.php @@ -2,7 +2,7 @@ declare(strict_types=1); -use Test\TinyBlocks\Outbox\Database; +use Test\TinyBlocks\Outbox\Integration\Database; require __DIR__ . '/../vendor/autoload.php';