From 04a6cf8e8ed1a74a3fe3657d98861f37e103e256 Mon Sep 17 00:00:00 2001 From: Gustavo Freze Date: Sat, 6 Jun 2026 17:50:36 -0300 Subject: [PATCH 01/14] feat: Add HTTP query toolkit with RSQL filtering, sorting, and pagination. --- .claude/rules/php-library-architecture.md | 147 +++ .claude/rules/php-library-code-style.md | 960 ++++++++++++++++++ .claude/rules/php-library-documentation.md | 203 ++++ .claude/rules/php-library-github-workflows.md | 104 ++ .claude/rules/php-library-modeling.md | 314 ++++++ .claude/rules/php-library-testing.md | 372 +++++++ .claude/rules/php-library-tooling.md | 138 +++ .claude/settings.json | 232 +++++ .claude/skills/commit-message/SKILL.md | 119 +++ .claude/skills/tiny-blocks-consume/SKILL.md | 68 ++ .../tiny-blocks-consume/references/catalog.md | 32 + .../scripts/refresh-catalog.py | 102 ++ .claude/skills/tiny-blocks-create/SKILL.md | 158 +++ .../assets/config/.editorconfig | 19 + .../assets/config/.gitattributes | 19 + .../assets/config/.gitignore | 28 + .../tiny-blocks-create/assets/config/Makefile | 74 ++ .../assets/config/composer.json | 70 ++ .../assets/config/infection.json.dist | 23 + .../assets/config/phpcs.xml | 7 + .../assets/config/phpstan.neon.dist | 6 + .../assets/config/phpunit.xml | 39 + .../assets/docs/SECURITY.md | 12 + .../github/ISSUE_TEMPLATE/bug_report.md | 29 + .../github/ISSUE_TEMPLATE/feature_request.md | 17 + .../assets/github/PULL_REQUEST_TEMPLATE.md | 16 + .../assets/github/workflows/ci.yml | 105 ++ .editorconfig | 19 + .gitattributes | 19 + .github/ISSUE_TEMPLATE/bug_report.md | 29 + .github/ISSUE_TEMPLATE/feature_request.md | 17 + .github/PULL_REQUEST_TEMPLATE.md | 16 + .github/copilot-instructions.md | 12 + .github/dependabot.yml | 31 + .github/workflows/auto-assign.yml | 32 + .github/workflows/ci.yml | 105 ++ .github/workflows/codeql.yml | 39 + .gitignore | 28 + .idea/.gitignore | 10 + .idea/misc.xml | 6 + CLAUDE.md | 61 ++ Makefile | 74 ++ README.md | 344 ++++++- SECURITY.md | 12 + composer.json | 79 ++ infection.json.dist | 23 + phpcs.xml | 7 + phpstan.neon.dist | 34 + phpunit.xml | 39 + src/Comparison.php | 89 ++ src/Criteria.php | 125 +++ src/Cursor.php | 105 ++ src/CursorPage.php | 154 +++ src/CursorPagination.php | 64 ++ src/Direction.php | 27 + src/Exceptions/CursorIsInvalid.php | 38 + src/Exceptions/FilterExpressionIsInvalid.php | 36 + src/Exceptions/HttpQueryException.php | 18 + src/Exceptions/OffsetOutOfRange.php | 35 + src/Exceptions/PageNumberOutOfRange.php | 35 + src/Exceptions/PageSizeOutOfRange.php | 52 + src/Exceptions/SortExpressionIsInvalid.php | 36 + src/Exceptions/TotalIsNegative.php | 35 + src/Expression.php | 65 ++ src/Filter.php | 29 + src/Group.php | 79 ++ src/Internal/CursorCodec.php | 40 + src/Internal/PaginationResolver.php | 41 + src/Internal/Rsql/FilterParser.php | 93 ++ src/Internal/Rsql/Scanner.php | 118 +++ src/Internal/WebLink.php | 14 + src/Internal/Window.php | 48 + src/Links.php | 82 ++ src/LogicalOperator.php | 29 + src/Navigation.php | 65 ++ src/NavigationTarget.php | 49 + src/Operator.php | 32 + src/Order.php | 60 ++ src/Page.php | 203 ++++ src/Pagination.php | 153 +++ src/Paging.php | 29 + src/Schema.php | 276 +++++ src/Slice.php | 141 +++ src/Sort.php | 90 ++ tests/Models/Query.php | 20 + tests/Unit/CriteriaTest.php | 275 +++++ tests/Unit/CursorPageTest.php | 143 +++ tests/Unit/CursorPaginationTest.php | 92 ++ tests/Unit/CursorTest.php | 147 +++ tests/Unit/DirectionTest.php | 66 ++ tests/Unit/EndToEndTest.php | 102 ++ tests/Unit/ExpressionTest.php | 78 ++ tests/Unit/FilterTest.php | 375 +++++++ tests/Unit/LinksTest.php | 242 +++++ tests/Unit/LogicalOperatorTest.php | 85 ++ tests/Unit/OperatorTest.php | 78 ++ tests/Unit/OrderTest.php | 36 + tests/Unit/PageTest.php | 276 +++++ tests/Unit/PaginationTest.php | 160 +++ tests/Unit/SchemaTest.php | 292 ++++++ tests/Unit/SliceTest.php | 148 +++ tests/Unit/SortTest.php | 126 +++ 102 files changed, 9774 insertions(+), 1 deletion(-) create mode 100644 .claude/rules/php-library-architecture.md create mode 100644 .claude/rules/php-library-code-style.md create mode 100644 .claude/rules/php-library-documentation.md create mode 100644 .claude/rules/php-library-github-workflows.md create mode 100644 .claude/rules/php-library-modeling.md create mode 100644 .claude/rules/php-library-testing.md create mode 100644 .claude/rules/php-library-tooling.md create mode 100644 .claude/settings.json create mode 100644 .claude/skills/commit-message/SKILL.md create mode 100644 .claude/skills/tiny-blocks-consume/SKILL.md create mode 100644 .claude/skills/tiny-blocks-consume/references/catalog.md create mode 100644 .claude/skills/tiny-blocks-consume/scripts/refresh-catalog.py create mode 100644 .claude/skills/tiny-blocks-create/SKILL.md create mode 100644 .claude/skills/tiny-blocks-create/assets/config/.editorconfig create mode 100644 .claude/skills/tiny-blocks-create/assets/config/.gitattributes create mode 100644 .claude/skills/tiny-blocks-create/assets/config/.gitignore create mode 100644 .claude/skills/tiny-blocks-create/assets/config/Makefile create mode 100644 .claude/skills/tiny-blocks-create/assets/config/composer.json create mode 100644 .claude/skills/tiny-blocks-create/assets/config/infection.json.dist create mode 100644 .claude/skills/tiny-blocks-create/assets/config/phpcs.xml create mode 100644 .claude/skills/tiny-blocks-create/assets/config/phpstan.neon.dist create mode 100644 .claude/skills/tiny-blocks-create/assets/config/phpunit.xml create mode 100644 .claude/skills/tiny-blocks-create/assets/docs/SECURITY.md create mode 100644 .claude/skills/tiny-blocks-create/assets/github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .claude/skills/tiny-blocks-create/assets/github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .claude/skills/tiny-blocks-create/assets/github/PULL_REQUEST_TEMPLATE.md create mode 100644 .claude/skills/tiny-blocks-create/assets/github/workflows/ci.yml create mode 100644 .editorconfig create mode 100644 .gitattributes create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/copilot-instructions.md create mode 100644 .github/dependabot.yml create mode 100644 .github/workflows/auto-assign.yml create mode 100644 .github/workflows/ci.yml create mode 100644 .github/workflows/codeql.yml create mode 100644 .gitignore create mode 100644 .idea/.gitignore create mode 100644 .idea/misc.xml create mode 100644 CLAUDE.md create mode 100644 Makefile create mode 100644 SECURITY.md create mode 100644 composer.json create mode 100644 infection.json.dist create mode 100644 phpcs.xml create mode 100644 phpstan.neon.dist create mode 100644 phpunit.xml create mode 100644 src/Comparison.php create mode 100644 src/Criteria.php create mode 100644 src/Cursor.php create mode 100644 src/CursorPage.php create mode 100644 src/CursorPagination.php create mode 100644 src/Direction.php create mode 100644 src/Exceptions/CursorIsInvalid.php create mode 100644 src/Exceptions/FilterExpressionIsInvalid.php create mode 100644 src/Exceptions/HttpQueryException.php create mode 100644 src/Exceptions/OffsetOutOfRange.php create mode 100644 src/Exceptions/PageNumberOutOfRange.php create mode 100644 src/Exceptions/PageSizeOutOfRange.php create mode 100644 src/Exceptions/SortExpressionIsInvalid.php create mode 100644 src/Exceptions/TotalIsNegative.php create mode 100644 src/Expression.php create mode 100644 src/Filter.php create mode 100644 src/Group.php create mode 100644 src/Internal/CursorCodec.php create mode 100644 src/Internal/PaginationResolver.php create mode 100644 src/Internal/Rsql/FilterParser.php create mode 100644 src/Internal/Rsql/Scanner.php create mode 100644 src/Internal/WebLink.php create mode 100644 src/Internal/Window.php create mode 100644 src/Links.php create mode 100644 src/LogicalOperator.php create mode 100644 src/Navigation.php create mode 100644 src/NavigationTarget.php create mode 100644 src/Operator.php create mode 100644 src/Order.php create mode 100644 src/Page.php create mode 100644 src/Pagination.php create mode 100644 src/Paging.php create mode 100644 src/Schema.php create mode 100644 src/Slice.php create mode 100644 src/Sort.php create mode 100644 tests/Models/Query.php create mode 100644 tests/Unit/CriteriaTest.php create mode 100644 tests/Unit/CursorPageTest.php create mode 100644 tests/Unit/CursorPaginationTest.php create mode 100644 tests/Unit/CursorTest.php create mode 100644 tests/Unit/DirectionTest.php create mode 100644 tests/Unit/EndToEndTest.php create mode 100644 tests/Unit/ExpressionTest.php create mode 100644 tests/Unit/FilterTest.php create mode 100644 tests/Unit/LinksTest.php create mode 100644 tests/Unit/LogicalOperatorTest.php create mode 100644 tests/Unit/OperatorTest.php create mode 100644 tests/Unit/OrderTest.php create mode 100644 tests/Unit/PageTest.php create mode 100644 tests/Unit/PaginationTest.php create mode 100644 tests/Unit/SchemaTest.php create mode 100644 tests/Unit/SliceTest.php create mode 100644 tests/Unit/SortTest.php diff --git a/.claude/rules/php-library-architecture.md b/.claude/rules/php-library-architecture.md new file mode 100644 index 0000000..4be7fc3 --- /dev/null +++ b/.claude/rules/php-library-architecture.md @@ -0,0 +1,147 @@ +--- +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. Vendor compatibility (driver) tests, verifying the + library against specific external libraries/frameworks, are optional and have no `src/` + counterpart. They exist only as tests, under `tests/Integration/Drivers//`, + grouped by vendor. Never a top-level `Drivers/` under `tests/`. +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 + ├── Drivers/ # only present when the library exposes vendor-specific drivers + │ └── / # tests against one specific third-party implementation + └── .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 new file mode 100644 index 0000000..c44dbc1 --- /dev/null +++ b/.claude/rules/php-library-code-style.md @@ -0,0 +1,960 @@ +--- +description: Semantic code rules for all PHP files in libraries. +paths: + - "src/**/*.php" + - "tests/**/*.php" +--- + +# Code style + +Semantic rules for all PHP files in libraries. Formatting rules covered by `PSR-12` are enforced +by `phpcs.xml`. Four formatting rules outside `PSR-12` (single-line signatures within 120 +characters, no vertical alignment in parameter lists, vertical alignment of `=>` in multi-line +match arms and array literals, 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 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 static and instance methods (`DateTimeImmutable::createFromFormat`, + `DateTimeImmutable::createFromInterface`, `->setTimezone`, `->format`, and similar). Their + parameter names are an internal implementation detail, not a stable contract, exactly as + with native functions. + + 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, enum methods, and native class static and instance methods, but not native class + constructors (instantiation): those accept named arguments per rule 8. +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 **member name length ascending** (count the name only, + without parentheses, arguments, or return type). Constants, enum cases, and methods share + the same name-length-ascending rule, applied within their respective groups. This mirrors + the rule that governs constructor parameters and named arguments (rule 7). When two names + have equal length, order them alphabetically. 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 **method name + length ascending**, the same rule that governs member declarations. Boolean toggles such as + `->secure()` and `->httpOnly()` come before parameterized `with*` builders because their + names are shorter, not because the expression is narrower. When two method names have equal + length, order them alphabetically. + + **Terminal methods that change the receiver type** stay at the end of the chain regardless + of name length. 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`) stays + at its position. + + **PHPUnit test classes** follow a dedicated sub-grouping inside the instance-methods group + that overrides the name-length-ascending rule: + + 1. **Lifecycle hooks** first, in PHPUnit execution order: + `setUpBeforeClass` → `setUp` → `tearDown` → `tearDownAfterClass`. Only those actually + defined appear. Never introduce an empty hook to satisfy the rule. + 2. **Test methods** (prefix `test`) next, ordered by name length ascending (alphabetical + tiebreak). + 3. **Data providers** last, ordered by name length ascending (alphabetical tiebreak). + + A method is a data provider if and only if its name appears as the string argument of a + `#[DataProvider('')]` attribute or a `@dataProvider ` docblock annotation on a + test method in the same class. The naming convention (`*DataProvider`) is informational + only. The reference is the authoritative signal. A method named `*DataProvider` that no + test references is dead code under rule 17, not a data provider. +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. See "Polymorphism and tell-don't-ask". +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`. **Exception:** a factory or constructor parameter that + wraps a single opaque scalar the value object exists to represent may keep `$value` when no + more specific meaning applies (for example, `Seconds::from(int $value)`). Where a more + specific meaning exists, prefer it (`$iso`, `$identifier`, `$isoDay`). +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). See "Duplication" for the resolution + under the inheritance and private-method constraints. +15. No abstraction exists without real duplication or isolation need (KISS). +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, in `new self()` instantiation, and in static method calls + (`self::from(...)` → `ClassName::from(...)`). Constant access via `self::CONST_NAME` is the + only permitted `self::` form. `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, concise standard regex character classes (`\w`, `\d`, `\s`, and their negations) + over their explicit equivalents (`[A-Za-z0-9_]`, `[0-9]`), 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. +24. No method has more than three `return` statements. This bounds branching complexity and + coexists with rule 9 (no `else`): early-return guard clauses are fine, but a method that needs + more than three exit points is doing too much. Invariant violations `throw` a dedicated + exception rather than returning, so guards rarely add return points. When branching still + produces more than three returns, replace it with a `match` or map dispatch that resolves to a + single return, or extract a collaborator. When the branches turn on the runtime type of + polymorphic collaborator, the behavior belongs on that type instead. See "Return statements" + and "Polymorphism and tell-don't-ask". +25. The string concatenation operator (`.`) is never used, in any position. A string that + would be assembled by concatenation, whether it embeds a value or joins two or more + strings, is built with `sprintf` and a `$template` variable (rule 19) instead. This + covers value prefixes, value suffixes, inline fragments, and plain joins. See "Format + strings". + + **Exception:** a `const` string literal that contains no `sprintf` placeholder may + use `.` to split a message across lines when a single-line literal would exceed the + 120-character limit. In that case `sprintf` offers no benefit, since the `$template` + line would itself exceed the limit, and heredoc and nowdoc are not permitted in + constant expressions, so concatenation is the only way to honor the line length. + This exception is limited to placeholder-free constant literals. Runtime string + assembly, and any constant that interpolates a value, still uses `sprintf` with a + `$template`. +26. Behavior that varies by the concrete type of type the library owns is a polymorphic method + on that type, never an `instanceof`, `get_class`, or enum-case branch. A value or behavior an + enum case owns (a token, a flag about the case's nature, a derived value) lives on the enum as + a predicate or vocabulary method, called at the site instead of comparing the case. Behavior + that depends on a collaborator's state lives on that collaborator. See "Polymorphism and + tell-don't-ask". + +## Naming + +- 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`. +- A boolean method reads as a predicate, using an `is`/`has`/`can`/`was`/`should` prefix or a + third-person verb that reads as a yes/no question, such as `contains`, `matches`, `supports`, + `equals`, or `omits`. + +## 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, in `new self()` instantiation, + and in static method calls (`self::from(...)`). Constant access via `self::CONST_NAME` is + **permitted** and is the only allowed `self::` form. The prohibition covers the forms that + carry refactoring ambiguity when a method moves to a different class (type, instantiation, and + static-call forms): a `self::from()` call rebinds to the wrong class if the method moves, + exactly like `new self()`. 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); + } +} +``` + +**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)`. + +## American English + +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 + +### When required + +Everything exposed on the public API for consumption carries PHPDoc per these rules. + +- Every method of an interface, regardless of location. Interfaces are contracts, so they carry + PHPDoc per these rules even when declared inside `src/Internal/`. +- 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). +- Every abstract method on a public class or extension point outside `src/Internal/`. Abstract + methods are part of the public contract consumers implement or override, so each carries PHPDoc + exactly as an interface method does. +- A class-level summary docblock on every interface (including interfaces inside `src/Internal/`) + and on every public class or enum outside `src/Internal/`. The summary is a single line placed + directly above the declaration stating what the type is or does, following the same summary-line + rule as method docblocks. It is the class-level counterpart of the per-method PHPDoc. + +### 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. +- Concrete classes and collaborators inside `src/Internal/`. Internal implementation types are + detail, not contract, and carry no PHPDoc, class-level summary included. **Interfaces are the + exception**: an interface declared inside `src/Internal/` is still a contract and follows the + interface PHPDoc rules under "When required", including the class-level summary. See + `php-library-architecture.md` for the architectural meaning of `Internal/`. +- Anywhere inside `tests/`. Test methods name the scenario via the `testXxxWhenYyyThenZzz` + 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 +`tests/`, zero PHPDoc is the rule, save for the generics carve-out below. Inside `src/Internal/`, +zero PHPDoc applies to concrete classes and collaborators, but interfaces carry PHPDoc per "When +required", and the generics carve-out below still applies to those concrete classes. PHPStan +errors that result from the missing annotations on the non-interface code route through +`ignoreErrors` (see below). + +**Generics carve-out.** The prohibitions above are waived for PHPDoc that exists *purely to +express generics* the native type system cannot: `@template`, `@extends`, `@implements`, and the +`@param`/`@return`/`@var` tags whose sole purpose is to carry a type parameter (for example +`Collection`, `iterable`, `Closure(TValue): bool`, `static`). These tags +are permitted wherever they are necessary for generic typing, including on **constructors**, on +**concrete classes and collaborators inside `src/Internal/`**, and as a **bare-tag block with no +summary line** (a summary would be the prohibited descriptive form). The waiver is strict: it +covers only the type-parameter information. Descriptive or redundant PHPDoc (summaries, prose +`@param`/`@return` descriptions, anything restating what the signature already says) stays +prohibited everywhere. When the only missing annotation is non-generic (a plain iterable value +type, a mixed-origin argument), the typed-array case below still applies and routes through +`ignoreErrors`, not PHPDoc. + +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 a concrete class or collaborator inside **`src/Internal/`** → suppress via `ignoreErrors`. + Do not add PHPDoc. An interface inside `src/Internal/` is the exception: it carries PHPDoc per + "When required", so the typed-array information goes in the docblock, not `ignoreErrors`. +- On anything inside **`tests/`** → suppress via `ignoreErrors`. Do not add PHPDoc. +- On a **public method of a public (non-Internal) class** → add full PHPDoc with summary, + `@param` descriptions, and the typed-array information. The bare-tag form remains + prohibited. This is the normal case where PHPDoc is permitted by "When required" above. + +The summary requirement and the bare-tag prohibition are never waived. Use `ignoreErrors` only +when the context (constructor, `src/Internal/`, `tests/`) makes PHPDoc impossible. Every public +method of a public concrete class carries PHPDoc per "When required", whether the method +has typed-array parameters. + +### Style + +- Summary on the first line, in domain terms. **Mandatory.** PHPDoc without a summary line is + prohibited, even when it carries a single `@param` or `@return`. +- Optional detailed body in `

` paragraphs below the summary. +- Tags use the form `@param Type $name Description.`, `@return Type Description.`, + `@throws ExceptionClass If .`. +- Document `@throws` for every exception the method may raise. +- 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` 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` plus `iterator_to_array` on a `Collectible`: + +```php +$names = array_map( + static fn(Element $element): string => $element->name(), + iterator_to_array($collection) +); +``` + +**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)); +} +``` + +The `.` operator is never used to assemble a string. Value prefixes, value suffixes, inline +fragments, and plain joins all go through `sprintf` with a `$template`. This holds even when +no value is interpolated, for example when joining a directory and a file name. + +The sole exception is a placeholder-free `const` string literal that would exceed 120 +characters on a single line: it may use `.` to split across lines, since `sprintf` would +not shorten the line and heredoc is unavailable in constant expressions. + +**Prohibited.** Concatenation to inject a value: + +```php +$candidate = is_int($value) ? '@' . $value : $value; +``` + +**Correct.** `$template` plus `sprintf`: + +```php +$template = '@%d'; +$candidate = is_int($value) ? sprintf($template, $value) : $value; +``` + +**Prohibited.** Concatenation to join strings: + +```php +$location = $directory . '/' . $file; +``` + +**Correct.** A single `$template` for the join: + +```php +$template = '%s/%s'; +$location = sprintf($template, $directory, $file); +``` + +## 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(uri: 'https://api.example.com', method: 'GET')) + ->withHeader('Accept', 'application/json') + ->getBody(); +``` + +**Correct.** No parentheses: + +```php +$body = new ServerRequest(uri: 'https://api.example.com', method: 'GET') + ->withHeader('Accept', 'application/json') + ->getBody(); +``` + +## Duplication + +When two or more places share logic, extract it into a collaborator (a value object, or a class +in `src/Internal/`), or move it onto a collaborator both call sites already depend on. The type +that owns the data owns the derived behavior. + +A shared base class is not available: inheritance between concrete classes is prohibited (see +"Inheritance and constructors"). A shared private helper is not available either: private methods +on public classes are prohibited (rule 13). Composition is therefore the only mechanism, and +leaving the duplication in place is never the resolution. + +**Prohibited.** The same derivation copied byte for byte into two types: + +```php +final readonly class Exam +{ + public function __construct(public int $score) {} + + public function grade(): Grade + { + return match (true) { + $this->score >= 90 => Grade::A, + $this->score >= 80 => Grade::B, + $this->score >= 70 => Grade::C, + default => Grade::F + }; + } +} + +final readonly class Assignment +{ + public function __construct(public int $score) {} + + public function grade(): Grade + { + return match (true) { + $this->score >= 90 => Grade::A, + $this->score >= 80 => Grade::B, + $this->score >= 70 => Grade::C, + default => Grade::F + }; + } +} +``` + +**Correct.** The derivation lives once on the collaborator both types hold, and each delegates: + +```php +final readonly class Score +{ + public function __construct(public int $value) {} + + public function toGrade(): Grade + { + return match (true) { + $this->value >= 90 => Grade::A, + $this->value >= 80 => Grade::B, + $this->value >= 70 => Grade::C, + default => Grade::F + }; + } +} + +final readonly class Exam +{ + public function __construct(public Score $score) {} + + public function grade(): Grade + { + return $this->score->toGrade(); + } +} + +final readonly class Assignment +{ + public function __construct(public Score $score) {} + + public function grade(): Grade + { + return $this->score->toGrade(); + } +} +``` + +## Polymorphism and tell-don't-ask + +This refines rules 9 and 24. A `match` on an enum, on a scalar, or on a value condition stays +correct. What is prohibited is branching on the runtime type of polymorphic collaborator the +library defines: when behavior differs across the concrete implementations of an interface the +library owns, that behavior is a method on the interface, resolved by the object itself, never an +`instanceof` or `get_class` chain at the call site. + +The opening sentence holds only for control flow. When a branch on an enum case yields a value or +behavior that belongs to the case itself, a token, a flag about the case's nature, or a derived +value, that value or behavior is a method on the enum: a predicate `isXxx()`, or a vocabulary +method that returns the value, called at the site instead of comparing the case. Comparing a case +(`$direction === Order::ASCENDING`, `match ($direction)`) stays correct for control flow whose +outcome is not a property of the case. This is the enum form of tell-don't-ask, and the companion +of the modeling rule that enums carry methods only when those methods hold vocabulary meaning (see +`php-library-modeling.md`, "Enums"): a case that drives a derived value is exactly that vocabulary. + +A consumer is outside this rule. A consumer matching on a sealed type the library exposes (for +example, translating a parsed tree into its own store) cannot add methods to the library's types, +so its `instanceof` is legitimate. The rule binds the library's own code. + +A type the library owns may `instanceof` its own internal types at construction or registration +time, to invoke behavior that exists only on the concrete type and that cannot be lifted onto a +public extension interface without breaking external implementers. The minimal public interface +outweighs the local, build-time type check. + +Tell-don't-ask. Behavior that depends on a collaborator's state belongs to the collaborator. Do +not read a collaborator's fields to recompute a result the collaborator should produce. Ask it for +the result, not for its parts. A getter exposes a value the caller needs as data, it is not a +license to reimplement the collaborator's logic at the call site. Tell-don't-ask binds the types +the library owns. Reading a value off a type the library does not own (a dependency's value object, +a PSR type) and computing with it is interop, not a violation: the library cannot add a method to a +type it does not control. The rule still binds the library's own types. + +**Prohibited.** Dispatching on the concrete type of interface the library owns: + +```php +return match (true) { + $discount instanceof Percentage => $amount->multiplyBy(factor: $discount->rate()), + $discount instanceof Fixed => $amount->subtract(other: $discount->amount()) +}; +``` + +**Correct.** The behavior is a method on the interface, resolved by the object: + +```php +return $discount->applyTo(amount: $amount); +``` + +**Prohibited.** Comparing an enum case to produce a value the case owns: + +```php +$token = match ($direction) { + Order::ASCENDING => '', + Order::DESCENDING => '-' +}; +``` + +**Correct.** A vocabulary method on the enum returns the value, called at the site: + +```php +enum Order: string +{ + case ASCENDING = 'asc'; + case DESCENDING = 'desc'; + + public function token(): string + { + return match ($this) { + self::ASCENDING => '', + self::DESCENDING => '-' + }; + } +} + +$token = $direction->token(); +``` + +**Prohibited.** Reading a collaborator's parts to recompute what it already owns: + +```php +$doubled = Money::of(amount: $price->amount() * 2, currency: $price->currency()); +``` + +**Correct.** Telling the collaborator to produce the result: + +```php +$doubled = $price->multiplyBy(factor: 2); +``` + +## Return statements + +A method has at most three `return` statements. The cap keeps methods small and their control +flow scannable, and it complements rule 9: early returns are the preferred alternative to `else`, +but they stop being a simplification once a method accumulates more than three exit points. +Invariant violations are signaled with a `throw`, not a `return`, so guard clauses usually do not +add to the count. + +**Prohibited.** Four return points: + +```php +public function classify(int $score): Grade +{ + if ($score >= 90) { + return Grade::A; + } + + if ($score >= 80) { + return Grade::B; + } + + if ($score >= 70) { + return Grade::C; + } + + return Grade::F; +} +``` + +**Correct.** Single return through `match`: + +```php +public function classify(int $score): Grade +{ + return match (true) { + $score >= 90 => Grade::A, + $score >= 80 => Grade::B, + $score >= 70 => Grade::C, + default => Grade::F + }; +} +``` + +## Formatting overrides + +Four formatting rules are not covered by the canonical `phpcs.xml` (which references `PSR-12` +only). Apply them manually. + +### Single-line signatures within 120 characters + +A function or constructor signature stays on one line when the whole signature fits within the +120-character limit. Do not break the parameter list onto multiple lines unless the single-line +form would exceed 120 characters. The opening brace still goes on its own line (PSR-12). Break to +one parameter per line only when the signature genuinely overflows. + +**Prohibited.** Multiline signature that fits on one line: + +```php +private function __construct( + public ExternalReference $id, + public Money $amount, + public OrderContext $context +) { +} +``` + +**Correct.** Single line within 120 characters: + +```php +private function __construct(public ExternalReference $id, public Money $amount, public OrderContext $context) +{ +} +``` + +When the one-line form would exceed 120 characters, break to one parameter per line and apply the +no-vertical-alignment and no-trailing-comma rules below. + +### 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-documentation.md b/.claude/rules/php-library-documentation.md new file mode 100644 index 0000000..a29de61 --- /dev/null +++ b/.claude/rules/php-library-documentation.md @@ -0,0 +1,203 @@ +--- +description: Conventions for README and public-facing Markdown docs in PHP libraries. +paths: + - "README.md" + - "docs/**/*.md" +--- + +# Documentation + +Conventions for `README.md` and the public-facing Markdown a library ships. 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 **canonical bodies** of the non-README repository files (`SECURITY.md`, the issue templates, +the pull request template) are not duplicated here. They live as drop-in assets in the +`tiny-blocks-create` skill, the single source of truth for those files. This rule governs how +the README and any `docs/` Markdown are written. "Required repository files" below lists which +files must exist and points to the skill for their content. + +`CONTRIBUTING.md` 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. The repository contains the required non-README files listed in "Required repository files", + each matching its canonical asset in the `tiny-blocks-create` skill. + +## README + +### 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. The TOC mirrors the document structure +exactly. + +### Code examples + +Code examples fall into two categories. + +**Self-contained examples** include at least one of these: a `use` statement, a +`class`/`enum`/`interface`/`trait`/`function` declaration, or more than 3 lines of executable code. +They open with `value; +``` + +The criteria are mechanical: a block meeting any self-contained condition gets the prologue. A +block meeting 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 +rule 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. + +> Vaughn Vernon, *Implementing Domain-Driven Design* (Addison-Wesley, 2013), Chapter 8, +> "Domain Events". +``` + +Bibliographic citations follow `> Author, *Title* (Publisher, Year), Chapter X, "Section Name".` +The chapter and section fragments are optional when the title is precise enough. Multiple +citations stack as separate blockquote lines. + +### License and Contributing + +```markdown +## License + + is licensed under [MIT](LICENSE). +``` + +```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 + +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. + +## Required repository files + +In addition to the README, every library repository contains the files below. Their canonical +bodies are the drop-in assets in the `tiny-blocks-create` skill. This rule only asserts they +must exist and match those assets. + +- `SECURITY.md`: security policy (supported versions, private reporting via GitHub Security + Advisories). `` is substituted. +- `.github/ISSUE_TEMPLATE/bug_report.md`: bug report template (`labels: bug`). +- `.github/ISSUE_TEMPLATE/feature_request.md`: feature request template (`labels: enhancement`). +- `.github/PULL_REQUEST_TEMPLATE.md`: pull request template linking the centralized contributing + guidelines, with the standard checklist (`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..c30d364 --- /dev/null +++ b/.claude/rules/php-library-github-workflows.md @@ -0,0 +1,104 @@ +--- +description: Structure, ordering, and pinning conventions 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. + +The **canonical `ci.yml` body** is not duplicated here. It lives as a drop-in asset in the +`tiny-blocks-create` skill (`assets/github/workflows/ci.yml`), the single source of truth. This +rule defines the conventions that asset satisfies and that any edit to a workflow must preserve. + +`ci.yml` is mandatory. Additional workflow files (security scanning, automated triage, scheduled +tasks, dependency updates) may exist and follow the general rules below. 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 + +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`. Absent keys are omitted. The relative order of the rest is preserved. +2. Properties inside a job follow the canonical order `name`, `needs`, `runs-on`, + `timeout-minutes`, `outputs`, `env`, `steps`. Same omission rule. +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`). 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, prefixed by the workflow's short purpose name + (`ci`, `codeql`, `auto-assign`): + - `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 }}`. +6. `permissions` is declared at the workflow root with the minimum scope every job needs. + Job-level `permissions` 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, immutable ref: a version tag at any granularity (major, minor, or patch) or a + commit SHA. Moving refs (branch names such as @main/@master, or @v with no version) are prohibited. Do not normalize + an explicit minor or patch pin down to its major, preserve the granularity the maintainer chose. +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 + +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`. Per rule 5 + for every workflow, with purpose `ci` and a `pull_request` trigger, `concurrency.group` is + `ci-${{ github.event.pull_request.number }}`. +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`. 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 the library needs (service + containers, fixture preparation, environment variables used during testing). The other three + jobs are identical across every library in the ecosystem. +8. `timeout-minutes` is 5 for `resolve-php-version` and 15 for `build`, `auto-review`, and + `tests`. `permissions` is `contents: read`. + +## ci.yml job sequence + +`ci.yml` gates every pull request with four jobs in this exact order. The first three are +identical across every library. Only `tests` may extend. + +- **Resolve PHP version.** Reads `.require.php` from `composer.json` and exposes the minor version + as the output `php-version`. A single step uses `jq` and a short regex to extract the value. +- **Build.** Sets up PHP using the resolved version, validates `composer.json`, installs with + `--no-progress --optimize-autoloader --prefer-dist --no-interaction`, and uploads `vendor/` and + `composer.lock` as `vendor-artifact`. +- **Auto review.** Needs `resolve-php-version` and `build`. Downloads `vendor-artifact`, sets up + PHP, runs `composer review` (phpcs + phpstan). +- **Tests.** Needs `resolve-php-version` and `auto-review`. Downloads `vendor-artifact`, sets up + PHP, runs `composer tests` (phpunit + infection). Library-specific test setup lives in this job + only. + +To extend the `tests` job (external services, env vars, fixtures), the additions go inside the +`tests` job exclusively. The skill asset includes an extended example with a MySQL service +container. diff --git a/.claude/rules/php-library-modeling.md b/.claude/rules/php-library-modeling.md new file mode 100644 index 0000000..a587b54 --- /dev/null +++ b/.claude/rules/php-library-modeling.md @@ -0,0 +1,314 @@ +--- +description: Semantic modeling rules for PHP libraries (nomenclature, value objects, exceptions, enums, extension points, complexity). +paths: + - "src/**/*.php" +--- + +# 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. A value or behavior a case owns lives on the enum as that method, called instead of a + `match` on the case at the site. See "Polymorphism and tell-don't-ask" in + `php-library-code-style.md`. +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. +17. A configuration-like value object whose fields are mostly optional exposes a no-argument + baseline factory (`default()`) plus fluent immutable `with*` copies, not a single factory + whose signature lists every field. See "Value objects". + +## 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. See "Duplication" in + `php-library-code-style.md` for how to resolve it without inheritance or private helpers. +- KISS. No abstraction without real duplication or isolation need. + +## Nomenclature + +- 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()`. + +### Always banned + +These names carry zero semantic content. Never use them anywhere as class suffix, prefix, or +method name. + +- `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`). + +### Externally standardized names (exception to the banlist) + +Names that correspond to externally standardized identifiers are exempt from the banlist. The +standard reference is the meaning carrier. Renaming weakens it. Examples: + +- 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. + +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. + +### Anemic verbs + +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()`). + +- `ensure`, `validate`, `check`, `verify`, `assert`, `mark`, `enforce`, `sanitize`, `normalize`, + `compute`, `transform`, `parse`. + +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. + +### Architectural roles + +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). + +- `Manager`, `Handler`, `Processor`, `Service`. +- Verb forms: `process`, `handle`, `execute`. + +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. + +**Scope.** The architectural-role banlist and the anemic-verb banlist apply to the **public +surface**: types at the `src/` root, types in public `/` folders, and public +exception and contract names. Inside `src/Internal/` (implementation detail by definition, where +the namespace is the boundary), a collaborator may carry a mechanical role or operation name that +describes its job (`Decoder`, `Encoder`, `Parser`, `Resolver`), since consumers never see or +manipulate it. The always-banned names (`Data`, `Info`, `Utils`, `Item`, `Record`, `Entity`) +remain banned everywhere, `Internal/` included. + +## Value objects + +- 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. + +**Prohibited.** Public constructor with multiple creation paths. Semantics are unclear at the +call site: + +```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) {} + + 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); +``` + +When a value object is configuration-like and most of its fields are optional with defaults, prefer +a baseline factory that takes no required arguments (`default()`, or `from()` with every parameter +defaulted) together with fluent immutable `with*` copies, over a single factory whose signature +carries every field. Each `with*` returns a new instance. Prefer the `with*` methods on the value +object itself over a separate mutable builder class: the value object is already immutable, so it +is its own builder. The smell is a factory signature that lists every field while most are +optional. + +**Prohibited.** A single factory whose signature carries every field, most of them optional: + +```php +MoneyFormat::from(scale: 4, symbol: '€', grouping: ','); +``` + +**Correct.** A baseline `default()` plus fluent `with*` copies that override only what differs: + +```php +MoneyFormat::default()->withScale(scale: 4)->withGrouping(grouping: ','); +``` + +## Exceptions + +- 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) { + throw new InvalidArgumentException('Precision cannot be negative.'); +} +``` + +**Correct.** Dedicated class, no message (class name is sufficient): + +```php +final class PrecisionOutOfRange extends InvalidArgumentException +{ +} + +if ($value < 0) { + throw new PrecisionOutOfRange(); +} +``` + +**Correct.** Dedicated class with debugging context in the message: + +```php +if ($value < 0 || $value > 16) { + $template = 'Precision must be between 0 and 16, got %d.'; + + throw new PrecisionOutOfRange(message: sprintf($template, $value)); +} +``` + +## Enums + +- Are PHP backed enums. +- Include methods only when those methods carry vocabulary meaning. Examples are + `OrderStatus::isFinal()` and `RoundingMode::apply()`. +- A value or behavior a case owns (a token, a flag, a derived value) is one of those vocabulary + methods, a predicate `isXxx()` or a method returning the value, called at the site instead of a + `match` comparing the case. This is the enum form of tell-don't-ask. See "Polymorphism and + tell-don't-ask" in `php-library-code-style.md`. + +## Extension points + +- 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 + +- 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 new file mode 100644 index 0000000..30a329f --- /dev/null +++ b/.claude/rules/php-library-testing.md @@ -0,0 +1,372 @@ +--- +description: BDD Given/When/Then structure, PHPUnit conventions, fixture rules, and coverage discipline. +paths: + - "tests/**/*.php" +--- + +# Testing + +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 PHPUnit + lifecycle hooks (`setUp`, `setUpBeforeClass`, `tearDown`, `tearDownAfterClass`) and 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. + One narrow, last-resort exception covers irreducible internal elements. See "White-box + coverage of irreducible internals". +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 using the `testXxxWhenYyyThenZzz` shape, never after the method + under test. `Xxx` names the subject or operation, `Yyy` the condition, `Zzz` the expected + outcome (for example, `testAddMoneyWhenSameCurrencyThenAmountsAreSummed`). The `When`/`Then` + structure is mandatory. The `@Given`/`@When`/`@Then`/`@And` annotation blocks describe the + steps within. A condition-free operation may collapse to `testXxxThenZzz` when there is no + meaningful precondition to name. +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. Named arguments are never used on PHPUnit assertions and expectations. Arguments are passed + positionally. The canonical rule and its full exclusion list live in + `php-library-code-style.md` rule 4. +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". +16. Member ordering in test classes follows `php-library-code-style.md` rule 6 (PHPUnit + test-class sub-grouping). + +## Generics in test PHPDoc + +The "zero PHPDoc anywhere inside `tests/`" rule (defined in `php-library-code-style.md`) has one +narrow exception: PHPDoc that exists *purely to express generics* the native type system cannot. +A test fixture that extends a generic public type carries the type argument with `@extends` (for +example `@extends Collection` on an `Invoices` fixture), and a generics-only `@var` may +pin a type parameter at an inference point where an imprecise result feeds a typed sink (for +example `/** @var Collection $shipments */` before passing a mapped collection to +`Shipments::createFrom(...)`). These tags carry only the type-parameter information, never a +summary or prose description. Every other form of PHPDoc (summaries, `@param`/`@return` +descriptions on test methods, fixtures, data providers, or anonymous classes) stays prohibited. +This is the same carve-out stated in `php-library-code-style.md` under "When prohibited", +restated here because it most often surfaces on collection fixtures and inference points in +`tests/`. + +## Structure: Given/When/Then (BDD) + +Every test uses `/** @Given */`, `/** @And */`, `/** @When */`, `/** @Then */` doc comments +without exception. + +### Happy path example + +```php +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(1500, $total->amount()); +} +``` + +### Exception example + +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 */ + $this->expectException(CurrencyMismatch::class); + + /** @When trying to add money with different currencies */ + $brl->add(other: $usd); +} +``` + +## 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 `HttpNetworkFailed` (`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 + +Checklist items 3, 4, 5, 10, and 11 govern setup blocks: one declaration per annotation, no +single-use intermediate variables, no private or helper methods, domain-named variables, and +domain-language annotations. The examples below illustrate the rules most often violated in +practice. Double naming (the `$spy`/`$mock` banlist and the class-name suffix nuance) is detailed +in "Test doubles" below. + +**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); +``` + +**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]); +``` + +## 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 + +- 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. +- The sole exception is an irreducible internal element (a non-functional memoization + cache, or the private constructor of a static-only surface) that cannot be reached + publicly without harming the design. It is covered or killed through a reflection-based + white-box test, never through suppression. See "White-box coverage of irreducible + internals". + +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. + +## White-box coverage of irreducible internals + +Rules 6 and 15 are near-absolute: tests exercise the public API, refactoring is the response +when a line or mutation resists coverage, and code is never hidden from coverage or mutation. +They yield in one narrow case: an *irreducible* internal element that cannot be reached +through the public API without either removing a legitimate non-functional optimization or +defeating a deliberate design. Two such elements recur: + +- **Memoization caches.** A purely non-functional cache (a resolved-mapping cache, a + shared-instance cache, a reflection-descriptor cache) whose removal leaves behavior + identical. The mutant that drops the cache is an equivalent mutant: no public observation + distinguishes the cached path from the recomputed one, so no public-API test can kill it. +- **Intentionally-uncallable members.** The private constructor of a static-only surface (a + class that exists solely to expose static factories and must never be instantiated). It is + never executed through any public path, so its line stays uncovered by construction. + +For these, and only these, a white-box test is permitted as a last resort: reflecting into +`Internal/` private state to assert that memoization holds, or reflection-invoking an +uncallable constructor so its line is covered. Such a test still follows the BDD structure +and `testXxxWhenYyyThenZzz` naming, and the repeated-invocation `@When` exception (checklist +item 3) already covers the memoization case. + +This exception covers code. It never hides it. `@codeCoverageIgnore`, coverage-excluding +configuration, and mutant suppression remain prohibited without exception. The irreducible +element is killed or covered honestly through reflection, not excluded from the metric. The +burden is on demonstrating irreducibility: if the line or mutation can be reached through the +public API, or if a proportionate refactor would expose it without harming the design, this +exception does not apply and the public-API test is required. White-box access is never a +convenience and never the first resort. diff --git a/.claude/rules/php-library-tooling.md b/.claude/rules/php-library-tooling.md new file mode 100644 index 0000000..8cf50d2 --- /dev/null +++ b/.claude/rules/php-library-tooling.md @@ -0,0 +1,138 @@ +--- +description: Invariants for the canonical config files of PHP libraries in the tiny-blocks ecosystem. +paths: + - "composer.json" + - "phpcs.xml" + - "phpstan.neon" + - "phpstan.neon.dist" + - "phpunit.xml" + - "infection.json" + - "infection.json.dist" + - ".editorconfig" + - ".gitattributes" + - ".gitignore" + - "Makefile" +--- + +# Tooling + +Invariants that every config file in a tiny-blocks library must satisfy. The **canonical file +bodies** (full `composer.json`, `Makefile`, `phpunit.xml`, etc.) are not duplicated here. They +live as drop-in assets in the `tiny-blocks-create` skill, which is the single source of truth +for scaffolding a new library or restoring a file to its canonical shape. This rule defines the +invariants those files are checked against when editing an existing library. + +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 config file. If any item fails, +revise before outputting. + +1. The repository root contains all of: `composer.json`, `phpcs.xml`, `phpstan.neon.dist`, + `phpunit.xml`, `infection.json.dist`, `.editorconfig`, `.gitattributes`, `.gitignore`, + `Makefile`. (See "Config file naming" for which carry a `.dist` suffix and why.) +2. `composer.json` exposes exactly five scripts: `configure`, `configure-and-update`, `review`, + `test-file`, `tests`. No other public scripts. +3. `composer.json` fixed fields use the canonical values from the skill asset (`license`, `type`, + `minimum-stability`, `prefer-stable`, `authors`, `config`, `require.php`). The five universal + dev dependencies (`ergebnis/composer-normalize`, `infection/infection`, `phpstan/phpstan`, + `phpunit/phpunit`, `squizlabs/php_codesniffer`) are present. `require-dev` may add libraries + the tests need on top of those five. The asset's caret ranges are the canonical floor, and + the repo `composer.json` matches the asset. To bump, update the asset first, then the repo. +4. `composer.json` `description` is a single short sentence. Multi-sentence prose belongs in the + README Overview, not in Composer metadata. +5. `composer.json` includes a `keywords` array that contains `"tiny-blocks"`. Its position in + the array is not constrained. The remaining entries 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. Formatting rules outside + PSR-12 live in `php-library-code-style.md` under "Formatting overrides". +7. `phpunit.xml` sets all five `failOn*` flags to `true` (`failOnDeprecation`, `failOnNotice`, + `failOnPhpunitDeprecation`, `failOnRisky`, `failOnWarning`). +8. `phpunit.xml` sets `executionOrder="random"` and `beStrictAboutOutputDuringTests="true"`. + Non-namespace root attributes are sorted alphabetically. The `xmlns:xsi` and + `xsi:noNamespaceSchemaLocation` declarations lead the attribute list and are not part of + the alphabetical run. +9. `infection.json.dist` sets `minMsi: 100` and `minCoveredMsi: 100`. Lowering either is + prohibited. +10. `.editorconfig` sets `max_line_length = 120`, `indent_size = 4`, `indent_style = space`, + `end_of_line = lf` as the global default under `[*]`. YAML uses `indent_size = 2` and + Makefile uses `indent_style = tab` as per-extension overrides. +11. `.gitattributes` sets `* text=auto eol=lf` and lists every committed dev-only file under + `export-ignore`. The Packagist tarball contains only `src/`, `composer.json`, `README.md`, + `LICENSE`, and `SECURITY.md`. `.claude/` is listed under `export-ignore` (versioned on + GitHub for contributor parity, excluded from the published package), and `CLAUDE.md` (where + committed) is `export-ignore`d alongside it for the same reason. `.gitattributes` lists + only files that are actually committed: it never names a file the repository does not + contain (no `CONTRIBUTING.md`, which is centralized, and no phantom `.dist`/non-`.dist` + twin of a file that is committed under only one of those names). +12. `.gitignore` ignores the dependency and artifact paths, the local config overrides + (`/phpstan.neon`, `/infection.json`), and nothing tool caches the project does not produce. + The `.claude/` directory itself is **not** ignored (it is versioned on GitHub). Only + `/.claude/settings.local.json`, the per-clone settings override, is ignored. +13. `Makefile` wraps every PHP and Composer command in Docker using the canonical image + `gustavofreze/php:8.5-alpine`. No PHP command runs on the host directly. Targets that share + a name with a Composer script delegate to it. Additional non-Composer convenience targets + (`help`, `clean`, `show-*`) are permitted. +14. All test artifact paths use `reports/` (plural), consistent across `composer tests`, + `infection.json.dist`, `phpunit.xml`, and `Makefile`. `reports/` is listed under + `export-ignore` in `.gitattributes`. + +## Config file naming + +The committed config files split into two naming conventions on purpose. The split is documented +here so it reads as intentional, not accidental. + +- **Committed live, no `.dist`:** `phpcs.xml` and `phpunit.xml`. The ruleset (`PSR12` only) and + the test configuration are stable across the whole ecosystem and identical in every library. + There is no per-clone local-override story, so the live file is committed directly. +- **Committed as `.dist`:** `phpstan.neon.dist` and `infection.json.dist`. These are the two + tools a contributor may legitimately want to tune locally (a temporary `ignoreErrors` entry, a + narrower mutator set while iterating). The `.dist` baseline is committed. A contributor drops a + gitignored `phpstan.neon` or `infection.json` to override it, and the tool auto-resolves the + override over the `.dist` fallback. Those override names appear in `.gitignore`. + +Do not introduce a `.dist` twin for `phpcs.xml`/`phpunit.xml`, and do not commit a live +`phpstan.neon`/`infection.json` in place of the `.dist` baseline. + +## phpstan ignoreErrors + +`phpstan.neon.dist` runs at `level: max` on `src` and `tests`. `ignoreErrors` is permitted to +suppress legitimate false positives produced by `level: max` (third-party signatures carrying +`mixed`, PHP-FIG interfaces returning untyped arrays, trait unused-method warnings on shared +behavior, and the typed-array cases routed here by `php-library-code-style.md` instead of adding +PHPDoc). 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. + +```neon +ignoreErrors: + # Trait method intentionally unused by the consuming aggregate. Reflection wires it. + - identifier: trait.unused + path: src/Internal/EventualAggregateRootBehavior.php +``` + +## Infection mutator config + +`infection.json.dist` is configured with `"mutators": {"@default": true}`. That is the only +permitted form. No `ignore` lists, no `ignoreSourceCodeByRegex`, and no per-mutator overrides +are allowed. Every mutant the default profile produces must be killed by a test. When a mutant +escapes, the production code is refactored to make it testable rather than the configuration +relaxed. This aligns with `php-library-testing.md` rule 15 (no mutant suppression by any +mechanism) and with the MSI 100 thresholds in checklist item 9. + +## Composer scripts + +The five scripts and their purpose. Bodies live in the skill asset. + +- `composer configure` installs with `--optimize-autoloader` then normalizes. Run after cloning + or pulling. +- `composer configure-and-update` updates dependencies then normalizes. Run when intentionally + bumping dependencies. +- `composer review` runs `phpcs` then `phpstan`. Used by CI (`auto-review` job) and locally. +- `composer tests` runs `phpunit` then `infection`. Used by CI (`tests` job). +- `composer test-file ` runs a filtered subset without coverage. Local only. diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..512042f --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,232 @@ +{ + "$schema": "https://json.schemastore.org/claude-code-settings.json", + "permissions": { + "defaultMode": "default", + "allow": [ + "Read", + "Glob", + "Grep", + + "Edit(./**)", + "Write(./**)", + + "Bash(make:*)", + "Bash(docker:*)", + + "Bash(rtk gain:*)", + "Bash(rtk discover:*)", + "Bash(rtk --version)", + + "Bash(rtk git status:*)", + "Bash(rtk git diff:*)", + "Bash(rtk git log:*)", + "Bash(rtk git show:*)", + "Bash(rtk ls:*)", + "Bash(rtk cat:*)", + "Bash(rtk grep:*)", + "Bash(rtk rg:*)", + "Bash(rtk head:*)", + "Bash(rtk tail:*)", + + "Bash(rtk docker:*)", + + "Bash(rg:*)", + "Bash(grep:*)", + "Bash(jq:*)", + "Bash(cat:*)", + "Bash(ls:*)", + "Bash(head:*)", + "Bash(tail:*)", + "Bash(wc:*)", + "Bash(sort:*)", + "Bash(uniq:*)", + "Bash(diff:*)", + "Bash(echo:*)", + "Bash(mkdir:*)", + "Bash(rmdir:*)", + "Bash(rm:*)", + + "Bash(composer install:*)", + "Bash(composer validate:*)", + "Bash(composer outdated:*)", + "Bash(composer show:*)", + + "Bash(git status:*)", + "Bash(git diff:*)", + "Bash(git log:*)", + "Bash(git show:*)", + "Bash(git blame:*)", + "Bash(git ls-files:*)", + "Bash(git grep:*)", + "Bash(git merge-base:*)", + "Bash(git rev-parse:*)", + "Bash(git describe:*)", + "Bash(git shortlog:*)", + "Bash(git reflog show:*)", + "Bash(git remote -v)", + "Bash(git remote get-url:*)", + "Bash(git stash list)", + "Bash(git stash show:*)", + "Bash(git worktree list)", + "Bash(git config --get:*)", + "Bash(git config --get-all:*)", + "Bash(git config --list)", + "Bash(git config --list:*)", + + "Bash(git branch)", + "Bash(git branch -a)", + "Bash(git branch -r)", + "Bash(git branch -v)", + "Bash(git branch -vv)", + "Bash(git branch --show-current)", + "Bash(git branch --list:*)", + "Bash(git branch --contains:*)", + "Bash(git branch --merged:*)", + "Bash(git branch --no-merged:*)", + + "Bash(git tag)", + "Bash(git tag -l)", + "Bash(git tag -l:*)", + "Bash(git tag -n)", + "Bash(git tag -n:*)", + "Bash(git tag --list)", + "Bash(git tag --list:*)", + "Bash(git tag --contains:*)", + "Bash(git tag --points-at:*)", + + "Bash(git rm:*)" + ], + "ask": [ + "Edit(./.claude/**)", + "Write(./.claude/**)", + + "Bash(git add:*)", + "Bash(git commit:*)", + "Bash(git mv:*)", + + "Bash(composer require:*)", + "Bash(composer update:*)", + "Bash(composer remove:*)", + "Bash(composer normalize:*)", + + "Bash(curl:*)", + "Bash(wget:*)" + ], + "deny": [ + "Read(./.env)", + "Read(./.env.*)", + "Read(./**/.env)", + "Read(./**/.env.*)", + "Read(./secrets/**)", + "Read(./**/credentials*)", + "Read(./**/*.pem)", + "Read(./**/*.key)", + "Read(./**/id_rsa)", + "Read(./**/id_ed25519)", + "Read(~/.ssh/**)", + + "Edit(./.env)", + "Edit(./.env.*)", + "Edit(./**/.env)", + "Edit(./**/.env.*)", + "Edit(./secrets/**)", + "Edit(./.git/**)", + "Edit(~/.bashrc)", + "Edit(~/.zshrc)", + "Edit(~/.profile)", + "Edit(~/.ssh/**)", + + "Write(./.env)", + "Write(./.env.*)", + "Write(./**/.env)", + "Write(./**/.env.*)", + "Write(./secrets/**)", + "Write(./.git/**)", + "Write(~/.bashrc)", + "Write(~/.zshrc)", + "Write(~/.profile)", + "Write(~/.ssh/**)", + + "Bash(php:*)", + + "Bash(rm --no-preserve-root:*)", + "Bash(rm -rf /)", + "Bash(rm * /)", + "Bash(rm * ~)", + "Bash(rm * ~/)", + "Bash(rm * $HOME)", + "Bash(rm * $HOME/)", + + "Bash(git push:*)", + "Bash(git pull:*)", + "Bash(git fetch:*)", + "Bash(git checkout:*)", + "Bash(git switch:*)", + "Bash(git restore:*)", + "Bash(git reset:*)", + "Bash(git merge:*)", + "Bash(git rebase:*)", + "Bash(git revert:*)", + "Bash(git cherry-pick:*)", + "Bash(git apply:*)", + "Bash(git am:*)", + "Bash(git stash push:*)", + "Bash(git stash pop:*)", + "Bash(git stash apply:*)", + "Bash(git stash drop:*)", + "Bash(git stash clear)", + "Bash(git stash save:*)", + "Bash(git branch -d:*)", + "Bash(git branch -D:*)", + "Bash(git branch -m:*)", + "Bash(git branch -M:*)", + "Bash(git branch -c:*)", + "Bash(git branch -C:*)", + "Bash(git tag -a:*)", + "Bash(git tag -s:*)", + "Bash(git tag -d:*)", + "Bash(git tag -f:*)", + "Bash(git tag --delete:*)", + "Bash(git tag --force:*)", + "Bash(git remote add:*)", + "Bash(git remote remove:*)", + "Bash(git remote rm:*)", + "Bash(git remote rename:*)", + "Bash(git remote set-url:*)", + "Bash(git submodule:*)", + "Bash(git worktree add:*)", + "Bash(git worktree remove:*)", + "Bash(git worktree prune:*)", + "Bash(git filter-branch:*)", + "Bash(git filter-repo:*)", + "Bash(git replace:*)", + "Bash(git notes:*)", + "Bash(git clean:*)", + "Bash(git gc:*)", + "Bash(git prune:*)", + "Bash(git reflog delete:*)", + "Bash(git reflog expire:*)", + "Bash(git config --add:*)", + "Bash(git config --unset:*)", + "Bash(git config --unset-all:*)", + "Bash(git config --replace-all:*)", + "Bash(git config --global:*)", + + "Bash(eval:*)", + + "Bash(sudo:*)", + "Bash(mysql:*)", + "Bash(dropdb:*)", + "Bash(dd:*)", + "Bash(chmod:*)", + "Bash(chown:*)", + + "Bash(curl * | sh)", + "Bash(curl * | bash)", + "Bash(curl * | sudo:*)", + "Bash(wget * | sh)", + "Bash(wget * | bash)", + "Bash(wget * | sudo:*)" + ] + } +} diff --git a/.claude/skills/commit-message/SKILL.md b/.claude/skills/commit-message/SKILL.md new file mode 100644 index 0000000..de37fcd --- /dev/null +++ b/.claude/skills/commit-message/SKILL.md @@ -0,0 +1,119 @@ +--- +name: commit-message +description: Generate a git commit message in the tiny-blocks Conventional Commits format (type-prefixed, imperative, capitalized, period-terminated, no scopes). Use this skill whenever the user asks you to write, draft, suggest, or fix a commit message, or whenever you are about to propose commit text for staged changes, even if they do not say the words "conventional commits". Commit messages are produced on request only and are never generated automatically as part of another task. +--- + +# Commit message + +Produce a single commit message in the tiny-blocks format. This skill formats the message only. +It never stages, commits, or runs any Git command. That happens only when the user explicitly +asks for it. + +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. Keep the 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. + +## Trailers + +Commit messages carry no trailers, regardless of any default to the contrary. Never append a +`Co-Authored-By` line or any other trailer. The message is the type-prefixed subject and, when +justified, a body. Nothing follows the body. + +## Allowed types + +- `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 + +**Example 1:** +Input: handled the case where a transaction has a zero amount +Output: `fix: Handle zero-amount transactions.` + +**Example 2:** +Input: added an endpoint to cancel an order +Output: `feat: Add order cancellation endpoint.` + +**Example 3:** +Input: pulled OrderStatus out into its own enum, no behavior change +Output: `refactor: Extract OrderStatus into its own enum.` + +Reject these shapes: + +- `Added order cancellation`: past tense, missing type, missing period. +- `feat: Adds order cancellation.`: 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, so split them. +- `feat(orders): Add cancellation.`: uses a scope, which is 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. + +When bullets are used, every bullet starts with a capital letter and ends with a period, with an +imperative present-tense verb, same as the subject line. + +### Body example with prose (preferred) + +``` +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. +``` + +### 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. +``` + +## Commit splitting + +Prefer one logical change per commit. Refactor commits never modify behavior. When a task needs +multiple types of change, produce multiple commits in order: `refactor` first, then `feat` or +`fix` on top. When the staged diff mixes types, say so and propose the split rather than forcing +one message over an incoherent change set. diff --git a/.claude/skills/tiny-blocks-consume/SKILL.md b/.claude/skills/tiny-blocks-consume/SKILL.md new file mode 100644 index 0000000..c318df8 --- /dev/null +++ b/.claude/skills/tiny-blocks-consume/SKILL.md @@ -0,0 +1,68 @@ +--- +name: tiny-blocks-consume +description: + Discover and reuse an existing tiny-blocks library as a dependency instead of writing or keeping hand-written code. Use this skill in two moments: before implementing a capability from scratch or adding a dependency from outside the ecosystem, and when reviewing or refactoring existing code, to catch where a tiny-blocks package now covers something already written by hand. It checks the catalog of published tiny-blocks packages for a candidate, adds the match with composer, and reads the installed library's own README and public API to use it correctly. Trigger on any request to implement, add, build, review, simplify, or refactor where an existing building block (collections, value objects, money, time, http, mapping, logging, identifiers, and similar) might apply. +--- + +# tiny-blocks consume + +Reuse the ecosystem before building anew. Inside any library, when a capability is needed, the +first move is to check whether a tiny-blocks package already provides it, adopt that package, and +use its documented API. This is the consuming counterpart of `tiny-blocks-create`. + +The source of truth for how to use a package is the package itself. After adding a dependency, its +README and public PHPDoc under `vendor/tiny-blocks//` are authoritative. This skill does not +copy any package API. It only points to the catalog for discovery and to the installed package for +usage. + +## When to use + +Use this before writing new code for a capability that is plausibly generic: collections, value +objects, money or currency, time, country codes, http primitives, object mapping, logging, +identifiers, encoding, environment variables, and similar. Also use it before reaching for any +dependency from outside the ecosystem. + +Use it also when reviewing or refactoring existing code. A package may have been published after +that code was written, so check whether hand-rolled logic can now be replaced by a tiny-blocks +package. The catalog is what surfaces newly published packages, so refresh it (see below) before +concluding that nothing applies. + +Do not use it for logic that is specific to the library being built and has no general building +block. In that case, write the code following the rules. + +## Consume steps + +1. Name the capability in one phrase, whether it is something you are about to write or something + the existing code already does by hand (for example, "type-safe ordered collection" or "ISO + currency with fraction digits"). +2. Check `references/catalog.md` for a tiny-blocks candidate. If nothing matches and the need is + generic, refresh the catalog (see below) and look again, since a newer package may exist. +3. If a candidate fits, add it with `composer require tiny-blocks/`. Packages from the + ecosystem are exempt from the freshness cooldown, and `composer require` prompts once before + adding. +4. Learn the API from the installed package, not from memory. Read + `vendor/tiny-blocks//README.md` and the public classes, interfaces, and enums under + `vendor/tiny-blocks//src/`. Their PHPDoc and the README examples are the contract. +5. Use the package following its documented API. Transitive dependencies are resolved by composer, + so depend on and use only the package that solves the capability directly. +6. If no candidate fits, only then write the code from scratch, or consider a dependency from + outside the ecosystem, subject to the freshness cooldown and the `composer require` prompt. + +## Catalog + +`references/catalog.md` is the committed index of published tiny-blocks packages, with a one-line +purpose for each. It exists for fast, offline discovery. It is generated from Packagist, not hand +maintained. Each entry points to a package whose full API lives in its own README and PHPDoc once +installed. + +## Refresh the catalog + +Run `python3 scripts/refresh-catalog.py` to rebuild `references/catalog.md` from the `tiny-blocks` +vendor on Packagist. The script uses only the Python standard library, with no curl or jq, pulls +the package list plus each description, skips abandoned packages, and rewrites the list. Refresh +when a new package shipped, or when the catalog looks stale and a needed capability is not listed. + +## Validate + +After adding a dependency and wiring it in, run `make review` and `make tests`. Both must be green +before the work is complete. A new dependency that breaks either gate is not done. diff --git a/.claude/skills/tiny-blocks-consume/references/catalog.md b/.claude/skills/tiny-blocks-consume/references/catalog.md new file mode 100644 index 0000000..778be52 --- /dev/null +++ b/.claude/skills/tiny-blocks-consume/references/catalog.md @@ -0,0 +1,32 @@ +# tiny-blocks catalog + +Index of published tiny-blocks packages and their one-line purpose. Generated from Packagist by +scripts/refresh-catalog.py, not hand-maintained. For the full API of a package, read its README +and public PHPDoc under vendor/tiny-blocks//. + +- `tiny-blocks/building-blocks`: Implements tactical DDD building blocks for PHP: entities, aggregate roots, domain + events, snapshots, and upcasters. +- `tiny-blocks/collection`: Models a type-safe, fluent collection API for PHP with eager and lazy pipelines over arrays, + iterators, and generators. +- `tiny-blocks/country`: Provides an ISO 3166-1 country value object for PHP, with Alpha-2, Alpha-3, numeric, and IANA + timezone resolution. +- `tiny-blocks/currency`: Models ISO-4217 currencies as a PHP enum, with per-currency fraction digit resolution. +- `tiny-blocks/docker-container`: Manages Docker containers programmatically for PHP, aimed at integration tests and + disposable infrastructure. +- `tiny-blocks/encoder`: Encoder and decoder for arbitrary data. +- `tiny-blocks/environment-variable`: Provides a type-safe environment variable reader for PHP, with strict integer and + boolean conversion. +- `tiny-blocks/http`: Implements PSR-7, PSR-15, PSR-17 and PSR-18 HTTP primitives for PHP, with a fluent response + builder, cookies, cache control, and a PSR-18 client facade. +- `tiny-blocks/immutable-object`: Provides immutable behavior for objects. +- `tiny-blocks/ksuid`: K-Sortable Unique Identifier. +- `tiny-blocks/logger`: Emits PSR-3 structured logs for PHP, with correlation tracking and configurable sensitive data + redaction. +- `tiny-blocks/mapper`: Maps PHP objects to and from arrays, JSON, and iterables through reflection and pluggable + strategies. +- `tiny-blocks/math`: Value Objects for handling arbitrary precision numbers. +- `tiny-blocks/outbox`: Write-side adapter for the Transactional Outbox pattern that persists domain events atomically + with aggregate state through Doctrine DBAL. +- `tiny-blocks/time`: Models time as immutable value objects for PHP: instants, durations, periods, timezones, and + time-of-day, all UTC-normalized. +- `tiny-blocks/value-object`: Defines the default behavior contract for PHP value objects with structural equality. diff --git a/.claude/skills/tiny-blocks-consume/scripts/refresh-catalog.py b/.claude/skills/tiny-blocks-consume/scripts/refresh-catalog.py new file mode 100644 index 0000000..b6fa359 --- /dev/null +++ b/.claude/skills/tiny-blocks-consume/scripts/refresh-catalog.py @@ -0,0 +1,102 @@ +#!/usr/bin/env python3 +"""Rebuild references/catalog.md from the tiny-blocks vendor on Packagist. + +Usage: + python3 scripts/refresh-catalog.py + +Depends only on the Python standard library. No curl, no jq, no shell. +""" + +from __future__ import annotations + +import json +import sys +import textwrap +import urllib.error +import urllib.request +from pathlib import Path +from typing import List, Optional + +VENDOR = "tiny-blocks" +LIST_URL = f"https://packagist.org/packages/list.json?vendor={VENDOR}" +CATALOG_PATH = Path(__file__).resolve().parent.parent / "references" / "catalog.md" +LINE_WIDTH = 120 +REQUEST_TIMEOUT_SECONDS = 30 + +CATALOG_HEADER = """\ +# tiny-blocks catalog + +Index of published tiny-blocks packages and their one-line purpose. Generated from Packagist by +scripts/refresh-catalog.py, not hand-maintained. For the full API of a package, read its README +and public PHPDoc under vendor/tiny-blocks//. + +""" + + +def report(message: str) -> None: + print(message, file=sys.stderr) + + +def fetch_json(url: str) -> dict: + request = urllib.request.Request(url=url, headers={"User-Agent": "tiny-blocks-catalog"}) + + with urllib.request.urlopen(url=request, timeout=REQUEST_TIMEOUT_SECONDS) as response: + payload = json.load(fp=response) + return payload + + +def sanitize(description: str) -> str: + collapsed = " ".join(description.split()) + + for character in (";", "—", "–"): + collapsed = collapsed.replace(character, ",") + return collapsed + + +def catalog_line(name: str) -> Optional[str]: + try: + metadata = fetch_json(url=f"https://packagist.org/packages/{name}.json").get("package", {}) + except (urllib.error.URLError, json.JSONDecodeError): + report(message=f"Skipping {name}, metadata fetch failed.") + return None + + if metadata.get("abandoned"): + return None + + description = sanitize(description=metadata.get("description") or "") + + return textwrap.fill( + text=f"- `{name}`: {description}", + width=LINE_WIDTH, + subsequent_indent=" ", + break_long_words=False, + break_on_hyphens=False, + ) + + +def build_catalog() -> str: + names = sorted(fetch_json(url=LIST_URL).get("packageNames", [])) + lines: List[str] = [] + + for name in names: + line = catalog_line(name=name) + + if line is not None: + lines.append(line) + return CATALOG_HEADER + "\n".join(lines) + "\n" + + +def main() -> int: + try: + catalog = build_catalog() + except (urllib.error.URLError, json.JSONDecodeError) as error: + report(message=f"Failed to build the catalog: {error}") + return 1 + + CATALOG_PATH.write_text(data=catalog, encoding="utf-8") + print(f"Wrote {CATALOG_PATH}") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/.claude/skills/tiny-blocks-create/SKILL.md b/.claude/skills/tiny-blocks-create/SKILL.md new file mode 100644 index 0000000..efcc62b --- /dev/null +++ b/.claude/skills/tiny-blocks-create/SKILL.md @@ -0,0 +1,158 @@ +--- +name: tiny-blocks-create +description: Scaffold a new PHP library for the tiny-blocks ecosystem, or restore a single canonical config/repository file (composer.json, phpcs.xml, phpunit.xml, phpstan.neon.dist, infection.json.dist, .editorconfig, .gitattributes, .gitignore, Makefile, the CI workflow, SECURITY.md, the issue templates, the PR template) to its standard shape. Use this skill whenever the user asks to create, bootstrap, set up, or initialize a new tiny-blocks library, to add the standard config/tooling files to a repository, or to fix/regenerate any of those files to match the ecosystem standard, even if they only mention one file by name. This skill owns the canonical bodies of those files. Do not hand-write them from memory. +--- + +# tiny-blocks library scaffolding + +This skill is the single source of truth for the boilerplate every tiny-blocks PHP library +shares: the config files, the CI workflow, and the repository templates. The canonical bodies +live in `assets/` as drop-in files. Copy them and substitute the placeholders rather than +regenerating them from memory. The assets already encode the ecosystem's decisions (PSR-12 only, +`level: max`, MSI 100, Docker-wrapped Makefile, the `.dist` naming split, the export-ignore set). + +The semantic conventions (how to name classes, how to structure `src/`, how to write tests) are +**not** in this skill. They live in `.claude/rules/`. This skill produces the skeleton. The rules +govern the code you then write into it. + +## When to use which mode + +- **Full scaffold**: the user is starting a new library. Create the directory skeleton and copy + every asset, substituting placeholders. +- **Single-file restore**: the user wants one file brought back to standard (for example, "fix + my Makefile" or "regenerate the CI workflow"). Copy only that asset. Do not touch the rest. + +## Asset map + +Copy each asset to the path on the right, relative to the repository root. + +| Asset (`assets/…`) | Destination | Placeholders | +|--------------------------------------------|---------------------------------------------|--------------| +| `config/composer.json` | `composer.json` | yes | +| `config/phpcs.xml` | `phpcs.xml` | no | +| `config/phpstan.neon.dist` | `phpstan.neon.dist` | no | +| `config/phpunit.xml` | `phpunit.xml` | no | +| `config/infection.json.dist` | `infection.json.dist` | no | +| `config/.editorconfig` | `.editorconfig` | no | +| `config/.gitattributes` | `.gitattributes` | no | +| `config/.gitignore` | `.gitignore` | no | +| `config/Makefile` | `Makefile` | no | +| `github/workflows/ci.yml` | `.github/workflows/ci.yml` | no | +| `github/ISSUE_TEMPLATE/bug_report.md` | `.github/ISSUE_TEMPLATE/bug_report.md` | no | +| `github/ISSUE_TEMPLATE/feature_request.md` | `.github/ISSUE_TEMPLATE/feature_request.md` | no | +| `github/PULL_REQUEST_TEMPLATE.md` | `.github/PULL_REQUEST_TEMPLATE.md` | no | +| `docs/SECURITY.md` | `SECURITY.md` | yes | + +## Placeholders + +Two assets carry placeholders. Substitute every occurrence. + +| Placeholder | Meaning | Example | +|---------------------------------------------------------|----------------------------------------------|---------------------------| +| `` | Repository name, kebab-case | `event-sourcing` | +| `` | PSR-4 namespace segment, PascalCase | `EventSourcing` | +| `` | `composer.json` `description` (one sentence) | n/a | +| ``, `` | `composer.json` `keywords` topic tokens | `psr-7`, `event-sourcing` | + +`` appears in `composer.json` (`name`, `homepage`, `support`) and in `SECURITY.md` +(advisory URL). `` appears only in `composer.json` (`autoload` / `autoload-dev` PSR-4 +prefixes). The first `keywords` entry is always `tiny-blocks`. The topic tokens follow. + +## Full scaffold steps + +1. Confirm ``, ``, the one-sentence description, and the keyword topics with + the user if not already known. +2. Create the directory skeleton: + ``` + src/ + tests/ + .github/workflows/ + .github/ISSUE_TEMPLATE/ + ``` +3. Copy every asset to its destination (table above), substituting placeholders. +4. Author the files this skill does **not** carry, following the rules: + - `README.md`: follow `php-library-documentation.md` (title, license badge, TOC, the fixed + section order, code-example rules). + - `LICENSE`: MIT, attributed to the author in `composer.json`. + - Initial `src/` and `tests/`: follow `php-library-architecture.md`, + `php-library-code-style.md`, `php-library-modeling.md`, and `php-library-testing.md`. +5. Validate (see below) before reporting the scaffold complete. + +## The .dist naming split + +The assets deliberately commit `phpcs.xml` and `phpunit.xml` as live files, but +`phpstan.neon.dist` and `infection.json.dist` with the `.dist` suffix. This is intentional and +documented in `php-library-tooling.md`: the ruleset and the test config are stable and committed +live. PHPStan and Infection are the two tools a contributor may tune locally, so a gitignored +`phpstan.neon` / `infection.json` overrides the committed `.dist` baseline. Do not add a `.dist` +twin for `phpcs.xml`/`phpunit.xml`, and do not commit a live `phpstan.neon`/`infection.json`. + +## Extending the CI tests job + +`ci.yml` is the minimal canonical workflow. Only the `tests` job may be extended, and only when +the library's tests need external services, environment variables, or fixture preparation. Add +them inside the `tests` job. Leave `resolve-php-version`, `build`, and `auto-review` untouched. +Example with a MySQL service container: + +```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 +``` + +## Pinned action versions + +The action versions pinned in `ci.yml` (`actions/checkout@v6`, `shivammathur/setup-php@v2`, +`actions/upload-artifact@v7`, `actions/download-artifact@v8`) may be outdated. Before adopting the +workflow, verify the current major version of each action and update the pin while preserving the +`@vN` prefix style, as required by `php-library-github-workflows.md` rule 8. + +## Validate + +After scaffolding (or restoring `composer.json`/the test config), run the toolchain through the +Makefile and confirm both pass before reporting done: + +- `make review`: phpcs (PSR-12) and phpstan (`level: max`) must pass clean. +- `make tests`: phpunit and infection must pass with MSI 100 / covered MSI 100. + +If `make` targets are missing, `make help` lists them. Do not claim the scaffold is complete on +the strength of file creation alone. The definition of done is a clean `review` and `tests`. diff --git a/.claude/skills/tiny-blocks-create/assets/config/.editorconfig b/.claude/skills/tiny-blocks-create/assets/config/.editorconfig new file mode 100644 index 0000000..be5640e --- /dev/null +++ b/.claude/skills/tiny-blocks-create/assets/config/.editorconfig @@ -0,0 +1,19 @@ +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 diff --git a/.claude/skills/tiny-blocks-create/assets/config/.gitattributes b/.claude/skills/tiny-blocks-create/assets/config/.gitattributes new file mode 100644 index 0000000..2bd9baa --- /dev/null +++ b/.claude/skills/tiny-blocks-create/assets/config/.gitattributes @@ -0,0 +1,19 @@ +* text=auto eol=lf + +*.php text diff=php + +# Dev-only, excluded from the Packagist tarball +/.github export-ignore +/tests export-ignore +/.claude export-ignore +/CLAUDE.md export-ignore +/.editorconfig export-ignore +/.gitattributes export-ignore +/.gitignore export-ignore +/phpcs.xml export-ignore +/phpunit.xml export-ignore +/phpstan.neon.dist export-ignore +/infection.json.dist export-ignore +/Makefile export-ignore +/reports export-ignore +/.phpunit.cache export-ignore diff --git a/.claude/skills/tiny-blocks-create/assets/config/.gitignore b/.claude/skills/tiny-blocks-create/assets/config/.gitignore new file mode 100644 index 0000000..c8f4364 --- /dev/null +++ b/.claude/skills/tiny-blocks-create/assets/config/.gitignore @@ -0,0 +1,28 @@ +# PHP dependencies +/vendor/ +composer.lock + +# Local config overrides (committed baselines are the .dist files) +/phpstan.neon +/infection.json + +# Tooling cache +.phpunit.cache/ +.phpunit.result.cache + +# Coverage and reports +build/ +reports/ +coverage/ +infection.log + +# Editors and agents +.idea/ +.cursor/ +.vscode/ +/.claude/settings.local.json + +# OS +Thumbs.db +.DS_Store +Desktop.ini diff --git a/.claude/skills/tiny-blocks-create/assets/config/Makefile b/.claude/skills/tiny-blocks-create/assets/config/Makefile new file mode 100644 index 0000000..90ab50d --- /dev/null +++ b/.claude/skills/tiny-blocks-create/assets/config/Makefile @@ -0,0 +1,74 @@ +PWD := $(CURDIR) +ARCH := $(shell uname -m) +PLATFORM := + +ifeq ($(ARCH),arm64) + PLATFORM := --platform=linux/amd64 +endif + +TTY := $(shell [ -t 0 ] && echo -it) + +DOCKER_RUN = docker run ${PLATFORM} --rm ${TTY} --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/.claude/skills/tiny-blocks-create/assets/config/composer.json b/.claude/skills/tiny-blocks-create/assets/config/composer.json new file mode 100644 index 0000000..e10a520 --- /dev/null +++ b/.claude/skills/tiny-blocks-create/assets/config/composer.json @@ -0,0 +1,70 @@ +{ + "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.52", + "infection/infection": "^0.33", + "phpstan/phpstan": "^2.2", + "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" + ] + } +} diff --git a/.claude/skills/tiny-blocks-create/assets/config/infection.json.dist b/.claude/skills/tiny-blocks-create/assets/config/infection.json.dist new file mode 100644 index 0000000..aab8c7e --- /dev/null +++ b/.claude/skills/tiny-blocks-create/assets/config/infection.json.dist @@ -0,0 +1,23 @@ +{ + "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" +} diff --git a/.claude/skills/tiny-blocks-create/assets/config/phpcs.xml b/.claude/skills/tiny-blocks-create/assets/config/phpcs.xml new file mode 100644 index 0000000..a52372c --- /dev/null +++ b/.claude/skills/tiny-blocks-create/assets/config/phpcs.xml @@ -0,0 +1,7 @@ + + + Code style for the tiny-blocks library. + + src + tests + diff --git a/.claude/skills/tiny-blocks-create/assets/config/phpstan.neon.dist b/.claude/skills/tiny-blocks-create/assets/config/phpstan.neon.dist new file mode 100644 index 0000000..0df69df --- /dev/null +++ b/.claude/skills/tiny-blocks-create/assets/config/phpstan.neon.dist @@ -0,0 +1,6 @@ +parameters: + level: max + paths: + - src + - tests + reportUnmatchedIgnoredErrors: true diff --git a/.claude/skills/tiny-blocks-create/assets/config/phpunit.xml b/.claude/skills/tiny-blocks-create/assets/config/phpunit.xml new file mode 100644 index 0000000..9cc6d13 --- /dev/null +++ b/.claude/skills/tiny-blocks-create/assets/config/phpunit.xml @@ -0,0 +1,39 @@ + + + + + + src + + + + + + tests + + + + + + + + + + + + + + + + + diff --git a/.claude/skills/tiny-blocks-create/assets/docs/SECURITY.md b/.claude/skills/tiny-blocks-create/assets/docs/SECURITY.md new file mode 100644 index 0000000..a892afe --- /dev/null +++ b/.claude/skills/tiny-blocks-create/assets/docs/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//security/advisories/new). + +Please do not disclose the vulnerability publicly until it has been addressed. diff --git a/.claude/skills/tiny-blocks-create/assets/github/ISSUE_TEMPLATE/bug_report.md b/.claude/skills/tiny-blocks-create/assets/github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..8ddd1db --- /dev/null +++ b/.claude/skills/tiny-blocks-create/assets/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/.claude/skills/tiny-blocks-create/assets/github/ISSUE_TEMPLATE/feature_request.md b/.claude/skills/tiny-blocks-create/assets/github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..b344d9e --- /dev/null +++ b/.claude/skills/tiny-blocks-create/assets/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/.claude/skills/tiny-blocks-create/assets/github/PULL_REQUEST_TEMPLATE.md b/.claude/skills/tiny-blocks-create/assets/github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..7a2c836 --- /dev/null +++ b/.claude/skills/tiny-blocks-create/assets/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/.claude/skills/tiny-blocks-create/assets/github/workflows/ci.yml b/.claude/skills/tiny-blocks-create/assets/github/workflows/ci.yml new file mode 100644 index 0000000..728bb3b --- /dev/null +++ b/.claude/skills/tiny-blocks-create/assets/github/workflows/ci.yml @@ -0,0 +1,105 @@ +name: CI + +on: + pull_request: + +concurrency: + group: ci-${{ 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 diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..be5640e --- /dev/null +++ b/.editorconfig @@ -0,0 +1,19 @@ +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 diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..2bd9baa --- /dev/null +++ b/.gitattributes @@ -0,0 +1,19 @@ +* text=auto eol=lf + +*.php text diff=php + +# Dev-only, excluded from the Packagist tarball +/.github export-ignore +/tests export-ignore +/.claude export-ignore +/CLAUDE.md export-ignore +/.editorconfig export-ignore +/.gitattributes export-ignore +/.gitignore export-ignore +/phpcs.xml export-ignore +/phpunit.xml export-ignore +/phpstan.neon.dist export-ignore +/infection.json.dist export-ignore +/Makefile 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 new file mode 100644 index 0000000..de1576d --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,12 @@ +# Copilot instructions + +## Context + +PHP library in the tiny-blocks ecosystem. + +## Mandatory pre-task step + +Before starting any task, read and strictly follow `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/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..f0ce8fc --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,31 @@ +version: 2 + +updates: + - package-ecosystem: "composer" + directory: "/" + schedule: + interval: "weekly" + open-pull-requests-limit: 0 + labels: + - "php" + - "security" + - "dependencies" + groups: + php-security: + applies-to: security-updates + patterns: + - "*" + + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + commit-message: + prefix: "build" + labels: + - "dependencies" + - "github-actions" + groups: + github-actions: + patterns: + - "*" diff --git a/.github/workflows/auto-assign.yml b/.github/workflows/auto-assign.yml new file mode 100644 index 0000000..e87e331 --- /dev/null +++ b/.github/workflows/auto-assign.yml @@ -0,0 +1,32 @@ +name: Auto assign issues and pull requests + +on: + issues: + types: + - opened + pull_request: + 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: + auto-assign: + name: Auto assign + runs-on: ubuntu-latest + timeout-minutes: 5 + steps: + - name: Assign issues and pull requests + uses: gustavofreze/auto-assign@2.1.0 + with: + assignees: '${{ vars.ASSIGNEES }}' + github_token: '${{ secrets.GITHUB_TOKEN }}' + allow_self_assign: 'true' + allow_no_assignees: 'true' + assignment_options: 'ISSUE,PULL_REQUEST' diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..728bb3b --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,105 @@ +name: CI + +on: + pull_request: + +concurrency: + group: ci-${{ 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 diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml new file mode 100644 index 0000000..0634bbf --- /dev/null +++ b/.github/workflows/codeql.yml @@ -0,0 +1,39 @@ +name: Security checks + +on: + push: + branches: [ "main" ] + pull_request: + branches: [ "main" ] + schedule: + - cron: "0 0 * * *" + +concurrency: + group: codeql-${{ github.ref }} + cancel-in-progress: true + +permissions: + actions: read + contents: read + security-events: write + +jobs: + analyze: + name: Analyze + runs-on: ubuntu-latest + timeout-minutes: 30 + strategy: + fail-fast: false + matrix: + language: [ "actions" ] + steps: + - name: Checkout repository + uses: actions/checkout@v6 + + - name: Initialize CodeQL + uses: github/codeql-action/init@v4 + with: + languages: ${{ matrix.language }} + + - name: Perform CodeQL analysis + uses: github/codeql-action/analyze@v4 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c8f4364 --- /dev/null +++ b/.gitignore @@ -0,0 +1,28 @@ +# PHP dependencies +/vendor/ +composer.lock + +# Local config overrides (committed baselines are the .dist files) +/phpstan.neon +/infection.json + +# Tooling cache +.phpunit.cache/ +.phpunit.result.cache + +# Coverage and reports +build/ +reports/ +coverage/ +infection.log + +# Editors and agents +.idea/ +.cursor/ +.vscode/ +/.claude/settings.local.json + +# OS +Thumbs.db +.DS_Store +Desktop.ini diff --git a/.idea/.gitignore b/.idea/.gitignore new file mode 100644 index 0000000..30cf57e --- /dev/null +++ b/.idea/.gitignore @@ -0,0 +1,10 @@ +# Default ignored files +/shelf/ +/workspace.xml +# Editor-based HTTP Client requests +/httpRequests/ +# Ignored default folder with query files +/queries/ +# Datasource local storage ignored files +/dataSources/ +/dataSources.local.xml diff --git a/.idea/misc.xml b/.idea/misc.xml new file mode 100644 index 0000000..13515d1 --- /dev/null +++ b/.idea/misc.xml @@ -0,0 +1,6 @@ + + + + + \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..d7efbcf --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,61 @@ +# tiny-blocks PHP library + +A library in the [tiny-blocks](https://github.com/tiny-blocks) ecosystem: small, focused, +framework-agnostic PHP building blocks published to Packagist. Target runtime is **PHP 8.5**. + +This file is the index. The detailed conventions live in `.claude/rules/` (loaded automatically +when you touch matching files) and in three skills under `.claude/skills/`. Keep this file short: +when a convention needs explaining, it belongs in a rule or a skill, not here. + +## Validate + +Every PHP and Composer command runs inside Docker via the `Makefile` (image +`gustavofreze/php:8.5-alpine`). Never run PHP on the host directly. + +- `make review`: phpcs (PSR-12) + phpstan (`level: max`). Run before claiming code is clean. +- `make tests`: phpunit + infection. Mutation thresholds are `minMsi: 100` / `minCoveredMsi: 100`. +- `make test-file FILE=`: one filtered test file, no coverage. +- `make help`: discover all targets if any of the above is missing or has changed. + +Treat `make review` and `make tests` as the definition of done. Both gate every pull request in +CI. Passing them locally is the bar before any "complete" / "fixed" / "passing" claim. + +## Conventions (`.claude/rules/`) + +Path-scoped. Each loads only when you edit matching files. + +- `php-library-architecture.md`: folder layout, public API boundary, `Internal/` semantics (`src/`). +- `php-library-code-style.md`: semantic code rules, naming, PHPDoc, `self`/`static` (`src/`, `tests/`). +- `php-library-modeling.md`: value objects, exceptions, enums, complexity (`src/`). +- `php-library-testing.md`: BDD Given/When/Then, PHPUnit, fixtures, coverage discipline (`tests/`). +- `php-library-tooling.md`: invariants for `composer.json`, `phpcs.xml`, `phpunit.xml`, etc. +- `php-library-documentation.md`: README and `docs/` conventions. +- `php-library-github-workflows.md`: GitHub Actions conventions. + +## Skills (`.claude/skills/`) + +- `tiny-blocks-create`: scaffold a new library or restore a canonical config/repo file. Holds + the drop-in bodies of every config file, the CI workflow, and the issue/PR/security templates. +- `tiny-blocks-consume`: discover and reuse a published tiny-blocks package as a dependency + instead of writing the capability by hand. Checks the catalog, adds the match with Composer, + and uses the installed package's own README and public API. The consuming counterpart of + `tiny-blocks-create`. +- `commit-message`: generate a Conventional Commits message in the ecosystem's format. Invoke + when writing a commit. Commit messages are never generated automatically. + +## Global defaults + +- All identifiers, comments, documentation, and commit messages use American English. +- In prose and headings, do not use semicolons or em-dashes. This applies to PHPDoc descriptions + and to every Markdown file (README, docs). Use a period or a comma in place of a semicolon, and + a colon, a comma, or parentheses in place of an em-dash. Hyphens in compound words and + identifiers (`tiny-blocks`, `name-length`) are not affected, and semicolons that terminate PHP + statements in code are not affected. +- Prefer dependencies from the tiny-blocks ecosystem before reaching outside it. +- Do not install or update any dependency to a version published less than 7 days ago. Freshly + released versions can be yanked or compromised. Let them age past the cooldown first. Packages + from the tiny-blocks ecosystem (`tiny-blocks/*`) are exempt, they are first-party. When a + dependency bump is needed but the target version is too recent, report it and wait rather than + pinning the new version. +- Do not run any history-altering Git operation (branch, commit, push, merge, rebase, tag) unless + explicitly asked. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..90ab50d --- /dev/null +++ b/Makefile @@ -0,0 +1,74 @@ +PWD := $(CURDIR) +ARCH := $(shell uname -m) +PLATFORM := + +ifeq ($(ARCH),arm64) + PLATFORM := --platform=linux/amd64 +endif + +TTY := $(shell [ -t 0 ] && echo -it) + +DOCKER_RUN = docker run ${PLATFORM} --rm ${TTY} --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/README.md b/README.md index c0211ab..6b78b2e 100644 --- a/README.md +++ b/README.md @@ -1 +1,343 @@ -# http-query \ No newline at end of file +# Http Query + +[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/tiny-blocks/http-query/blob/main/LICENSE) + +* [Overview](#overview) +* [Installation](#installation) +* [How to use](#how-to-use) + + [Filtering with RSQL](#filtering-with-rsql) + + [Sorting](#sorting) + + [Offset pagination](#offset-pagination) + + [Cursor pagination](#cursor-pagination) + + [Rendering navigation links](#rendering-navigation-links) + + [Configuring the schema](#configuring-the-schema) +* [FAQ](#faq) +* [License](#license) +* [Contributing](#contributing) + +## Overview + +A typed, framework- and database-agnostic toolkit for the query of an HTTP collection endpoint. It parses an incoming +request query string into typed specifications for filtering (RSQL), sorting, and pagination (offset and cursor), and it +renders the result navigation as an RFC 8288 `Link` header and as a JSON:API-style body `links` object. + +The library never touches a data store. It turns the query string into value objects the consumer applies to its own +store, and it renders the navigation the consumer attaches to the response. Every computation is O(1) value-object math +over the inputs the consumer supplies. + +It builds on the [tiny-blocks](https://github.com/tiny-blocks) ecosystem: it reads a `QueryParameters` from +[`tiny-blocks/http`](https://github.com/tiny-blocks/http), carries items in a +[`tiny-blocks/collection`](https://github.com/tiny-blocks/collection) `Collection`, encodes cursors through +[`tiny-blocks/encoder`](https://github.com/tiny-blocks/encoder), and renders the `Link` header with the `Link` and +`LinkRelation` types from `tiny-blocks/http`. + +## Installation + +```bash +composer require tiny-blocks/http-query +``` + +## How to use + +The entry point is `Criteria::fromQuery`, which reads the request query parameters and produces a `Criteria` carrying +the filter, the sort, and the pagination. + +```php +query()); +``` + +### Filtering with RSQL + +The `filter` parameter is an RSQL expression. `Criteria::filtering()` returns the parsed expression tree as a `Filter`, +which is either a `Comparison` leaf or a `Group` composite. The consumer matches on the node type to translate the tree +to its own store. + +```php + sprintf( + '%s %s %s', + $filter->field(), + $filter->operator()->value, + implode(',', $filter->values()) + ), + $filter instanceof Group => implode( + $filter->operator()->value, + array_map(describe(...), $filter->filters()) + ) + }; +} + +# filter=status==paid;total=ge=100 parses to a Group(AND) of two Comparison leaves. +``` + +The supported operators map to their RSQL tokens through the `Operator` enum (`==`, `!=`, `=lt=`, `=gt=`, `=le=`, +`=ge=`, `=in=`, `=out=`). The logical connectives map through the `LogicalOperator` enum, where `;` (AND) binds tighter +than `,` (OR), and parentheses group. A malformed expression raises `FilterExpressionIsInvalid`. + +### Sorting + +The `sort` parameter is a comma-separated list of fields, where a leading minus marks descending order, following the +JSON:API convention. `Criteria::sorting()` returns a `Sort` whose `Order` list preserves the request order. + +```php +orders() as $order) { + $order->field(); # 'created_at' then 'id' + $order->direction() === Direction::DESCENDING; # true then false +} +``` + +A malformed expression raises `SortExpressionIsInvalid`. + +### Offset pagination + +When no cursor is present, `Criteria::pagination()` returns an offset-based `Pagination`. Its canonical state is an +offset and a limit, and the page-based factory derives the offset from the one-based page number. + +```php +offset(); # 40 +$pagination->limit(); # 20 + +/** @var Collection $items */ +$page = Page::from(items: $items, total: 480, pagination: $pagination); + +$page->hasNext(); # true +$page->totalPages(); # 24 +$page->metadata(); # the JSON:API meta contents +``` + +Use a `Slice` instead of a `Page` when the total is unknown. The consumer fetches one element beyond the page size, and +the `Slice` trims it and reads its presence as the next-page hint. + +```php + $items */ +$slice = Slice::from(items: $items, pagination: Pagination::fromPage(page: 2, perPage: 20)); + +$slice->hasNext(); # inferred from the extra fetched element +``` + +### Cursor pagination + +When the `cursor` parameter is present, `Criteria::pagination()` returns a keyset `CursorPagination`. A `Cursor` is an +opaque, URI-safe token wrapping the last-seen ordering key values, encoded through `tiny-blocks/encoder`. + +```php + $items */ +$cursorPage = CursorPage::from( + items: $items, + keysOf: static fn(array $order): array => [$order['created_at'], $order['id']], + pagination: $pagination +); + +$cursorPage->hasNext(); # inferred from the extra fetched element +$cursorPage->nextCursor()->toString(); # the opaque token for the next page +$cursorPage->previousCursor()->toArray(); # the decoded key values for the previous page +``` + +An invalid cursor token raises `CursorIsInvalid` when it is decoded. + +### Rendering navigation links + +`Links::from` reads the navigation a result exposes through `result->navigation()`, swaps the criteria's pagination for +each target, and serializes it back through `Criteria::toUri`, so the filter and the sort are preserved in every URI. +`toArray()` returns the JSON:API body `links` object and `toHeader()` returns an RFC 8288 `Link`. + +```php +query()); + +/** @var Collection $items */ +$page = Page::from(items: $items, total: 480, pagination: $criteria->pagination()); +$links = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $page->navigation()); + +$response = Response::ok([ + 'data' => $page->items()->toArray(), + 'meta' => $page->metadata(), + 'links' => $links->toArray() +], $links->toHeader()); +``` + +The body carries the navigation with the filter and the sort preserved in every URI. + +```json +{ + "data": [], + "meta": { + "total": 480, + "has_next": true, + "per_page": 20, + "total_pages": 24, + "current_page": 3, + "has_previous": true + }, + "links": { + "self": "/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page=3&per_page=20", + "first": "/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page=1&per_page=20", + "prev": "/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page=2&per_page=20", + "next": "/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page=4&per_page=20", + "last": "/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page=24&per_page=20" + } +} +``` + +The header folds the same relations into one RFC 8288 `Link` line. + +```text +Link: ; rel="self", + ; rel="first", + ; rel="prev", + ; rel="next", + ; rel="last" +``` + +The `links` keys are the canonical JSON:API relations, in the semantic order below. Unavailable relations are omitted, +so the first page carries no `prev` and the last page carries no `next`. A `Slice` and a `CursorPage` expose only +`self`, `prev`, and `next`. + +| Relation | Meaning | +|----------|--------------------| +| `self` | The current page. | +| `first` | The first page. | +| `prev` | The previous page. | +| `next` | The next page. | +| `last` | The last page. | + +### Configuring the schema + +`Schema` maps the query parameter names and the page-size bounds. `Schema::default()` is applied when +`Criteria::fromQuery` receives no schema, and the fluent `with*` copies override any subset. + +| Setting | Default | Meaning | +|------------------|------------|-------------------------------------------------| +| `filterKey` | `filter` | The query key carrying the RSQL filter. | +| `sortKey` | `sort` | The query key carrying the sort expression. | +| `pageKey` | `page` | The query key carrying the page number. | +| `perPageKey` | `per_page` | The query key carrying the page size. | +| `cursorKey` | `cursor` | The query key carrying the cursor token. | +| `defaultPerPage` | `20` | The page size applied when the query omits one. | +| `maxPerPage` | `100` | The maximum allowed page size. | + +```php +withFilterKey(filterKey: 'q') + ->withMaxPerPage(maxPerPage: 200) + ->withPerPageKey(perPageKey: 'size'); + +# GET /v1/orders?q=status==paid&size=50 +$criteria = Criteria::fromQuery(query: $query, schema: $schema); +``` + +A page size above `maxPerPage` raises `PageSizeOutOfRange`. + +## FAQ + +### 01. Why does the library never touch a data store? + +The query of a collection has two halves: deciding what to fetch, and fetching it. This library owns only the first +half. It parses the request into typed specifications and renders the response navigation, leaving the consumer free to +apply the specifications to any store, SQL, a document database, or an in-memory list. Keeping the store out makes every +operation pure value-object math and keeps the library framework- and database-agnostic. + +### 02. Why RSQL for filtering instead of ad-hoc query parameters? + +RSQL is a small, URI-safe grammar with a published reference, so the filter survives a query string without encoding and +the same expression reads the same on the client and the server. The parser produces an immutable expression tree the +consumer walks, rather than a flat map of parameters that cannot express grouping or disjunction. + +> Zdenek Jirutka, *RSQL / FIQL parser* (https://github.com/jirutka/rsql-parser). + +### 03. Why are both offset and cursor pagination supported? + +Offset pagination answers "how many pages are there" and "jump to page N", which a `Page` with a total provides. Cursor +pagination answers "give me the next slice after this point" without a total, which scales to large collections and +avoids the drift of offset pagination under concurrent writes. The library models both, plus a `Slice` for offset +navigation without a total. + +### 04. How are the `meta` keys ordered? + +The keys are snake_case and ordered by key length ascending, with an alphabetical tiebreak. The order is fixed so the +serialized response is deterministic across requests. + +## License + +Http Query is licensed under [MIT](LICENSE). + +## Contributing + +Please follow the [contributing guidelines](https://github.com/tiny-blocks/tiny-blocks/blob/main/CONTRIBUTING.md) to +contribute to the project. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..fb9fbc4 --- /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/http-query/security/advisories/new). + +Please do not disclose the vulnerability publicly until it has been addressed. diff --git a/composer.json b/composer.json new file mode 100644 index 0000000..b36ca5d --- /dev/null +++ b/composer.json @@ -0,0 +1,79 @@ +{ + "name": "tiny-blocks/http-query", + "description": "Typed, framework and database-agnostic toolkit for HTTP collection queries with RSQL filtering, sorting, and offset and cursor pagination.", + "license": "MIT", + "type": "library", + "keywords": [ + "rsql", + "json-api", + "http-query", + "pagination", + "link-header", + "query-string", + "tiny-blocks", + "cursor-pagination" + ], + "authors": [ + { + "name": "Gustavo Freze de Araujo Santos", + "homepage": "https://github.com/gustavofreze" + } + ], + "homepage": "https://github.com/tiny-blocks/http-query", + "support": { + "issues": "https://github.com/tiny-blocks/http-query/issues", + "source": "https://github.com/tiny-blocks/http-query" + }, + "require": { + "php": "^8.5", + "tiny-blocks/collection": "^2.4", + "tiny-blocks/encoder": "^3.2", + "tiny-blocks/http": "^6.1" + }, + "require-dev": { + "ergebnis/composer-normalize": "^2.52", + "infection/infection": "^0.33", + "nyholm/psr7": "^1.8", + "phpstan/phpstan": "^2.2", + "phpunit/phpunit": "^13.1", + "squizlabs/php_codesniffer": "^4.0" + }, + "minimum-stability": "stable", + "prefer-stable": true, + "autoload": { + "psr-4": { + "TinyBlocks\\HttpQuery\\": "src/" + } + }, + "autoload-dev": { + "psr-4": { + "Test\\TinyBlocks\\HttpQuery\\": "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" + ] + } +} diff --git a/infection.json.dist b/infection.json.dist new file mode 100644 index 0000000..aab8c7e --- /dev/null +++ b/infection.json.dist @@ -0,0 +1,23 @@ +{ + "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" +} 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 new file mode 100644 index 0000000..dc7a292 --- /dev/null +++ b/phpstan.neon.dist @@ -0,0 +1,34 @@ +parameters: + level: max + paths: + - src + - tests + reportUnmatchedIgnoredErrors: true + ignoreErrors: + # The compared values are a list of strings carried on a value-object constructor. + - identifier: missingType.iterableValue + path: src/Comparison.php + - identifier: return.type + path: src/Comparison.php + # The child filters are a list of nodes carried on a value-object constructor. + - identifier: missingType.iterableValue + path: src/Group.php + - identifier: return.type + path: src/Group.php + # The orders are a list of nodes carried on a value-object constructor. + - identifier: missingType.iterableValue + path: src/Sort.php + - identifier: return.type + path: src/Sort.php + # reduce() folds the links into the associative body; phpstan widens the carry to array. + - identifier: return.type + path: src/Links.php + # Cursor key values are opaque, decoded scalars carried on a constructor parameter. + - identifier: missingType.iterableValue + path: src/Cursor.php + # The cursor codec encodes and decodes opaque key values whose types are not known. + - identifier: missingType.iterableValue + path: src/Internal/CursorCodec.php + # Test fixtures and data providers carry raw arrays at the test boundary. + - identifier: missingType.iterableValue + path: tests diff --git a/phpunit.xml b/phpunit.xml new file mode 100644 index 0000000..9cc6d13 --- /dev/null +++ b/phpunit.xml @@ -0,0 +1,39 @@ + + + + + + src + + + + + + tests + + + + + + + + + + + + + + + + + diff --git a/src/Comparison.php b/src/Comparison.php new file mode 100644 index 0000000..924045f --- /dev/null +++ b/src/Comparison.php @@ -0,0 +1,89 @@ + $values The compared values, a single element except for IN and NOT_IN. + * @param Operator $operator The comparison operator. + * @return Comparison The composed comparison leaf. + */ + public static function of(string $field, array $values, Operator $operator): Comparison + { + return new Comparison(field: $field, values: $values, operator: $operator); + } + + /** + * Returns the field being compared. + * + * @return string The field being compared. + */ + public function field(): string + { + return $this->field; + } + + /** + * Returns the values compared against the field. + * + * @return list The compared values, a single element except for IN and NOT_IN. + */ + public function values(): array + { + return $this->values; + } + + public function isEmpty(): bool + { + return false; + } + + /** + * Returns the comparison operator. + * + * @return Operator The comparison operator. + */ + public function operator(): Operator + { + return $this->operator; + } + + public function toExpression(): Expression + { + /** @var Collection $values */ + $values = Collection::createFrom(elements: $this->values); + + $arguments = $values + ->map(transformations: static function (string $value): string { + if ($value !== '' && preg_match('/[\s"\'();,=!~<>]/', $value) !== 1) { + return $value; + } + + $escaped = str_replace(['\\', '"'], ['\\\\', '\\"'], $value); + $template = '"%s"'; + + return sprintf($template, $escaped); + }) + ->joinToString(separator: ','); + + $wrapped = $this->operator->isMultiValued(); + $template = $wrapped ? '%s%s(%s)' : '%s%s%s'; + + return Expression::atomic(value: sprintf($template, $this->field, $this->operator->value, $arguments)); + } +} diff --git a/src/Criteria.php b/src/Criteria.php new file mode 100644 index 0000000..fa2fd78 --- /dev/null +++ b/src/Criteria.php @@ -0,0 +1,125 @@ +It parses from the request query string and serializes back to a URI, so the navigation links + * built from it preserve the filter and the sort.

    + */ +final readonly class Criteria +{ + private function __construct( + private Sort $sort, + private Filter $filter, + private Schema $schema, + private Paging $pagination + ) { + } + + /** + * Creates a Criteria from the request query parameters and an optional schema. + * + *

    When the schema is omitted, the canonical default key names and bounds apply. The + * pagination is a {@see CursorPagination} when the cursor key is present, otherwise an + * offset-based {@see Pagination}.

    + * + * @param QueryParameters $query The decoded request query parameters. + * @param Schema|null $schema The schema mapping the query keys and bounds, or null for the default. + * @return Criteria The criteria carrying the parsed filter, sort, and pagination. + * @throws FilterExpressionIsInvalid If the filter expression cannot be parsed. + * @throws SortExpressionIsInvalid If the sort expression cannot be parsed. + * @throws PageNumberOutOfRange If the page number is less than 1. + * @throws PageSizeOutOfRange If the page size falls outside the valid range. + * @throws OffsetOutOfRange If the offset is less than 0. + */ + public static function fromQuery(QueryParameters $query, ?Schema $schema = null): Criteria + { + $schema = $schema ?? Schema::default(); + $expression = $query->get(key: $schema->filterKey())->toString(); + $filter = $expression === '' ? Group::none() : FilterParser::from(input: $expression)->parse(); + + $sort = Sort::fromExpression(expression: $query->get(key: $schema->sortKey())->toString()); + $pagination = PaginationResolver::from(query: $query, schema: $schema)->resolve(); + + return new Criteria(sort: $sort, filter: $filter, schema: $schema, pagination: $pagination); + } + + /** + * Returns the criteria as a URI built on the given base. + * + * @param string $baseUri The base URI the query string is appended to. + * @return string The URI carrying the filter, sort, and pagination. + */ + public function toUri(string $baseUri): string + { + $parameters = []; + $template = '%s=%s'; + + if (!$this->filter->isEmpty()) { + $parameters[] = sprintf($template, $this->schema->filterKey(), $this->filter->toExpression()->value()); + } + + if (!$this->sort->isEmpty()) { + $parameters[] = sprintf($template, $this->schema->sortKey(), $this->sort->toExpression()); + } + + $parameters[] = $this->pagination->toQueryString(schema: $this->schema); + $template = '%s?%s'; + + return sprintf($template, $baseUri, implode('&', $parameters)); + } + + /** + * Returns the sorting specification. + * + * @return Sort The sorting specification. + */ + public function sorting(): Sort + { + return $this->sort; + } + + /** + * Returns the filtering specification as the root of the filter tree. + * + * @return Filter The filter tree root, an empty {@see Group} when no filter is present. + */ + public function filtering(): Filter + { + return $this->filter; + } + + /** + * Returns the pagination specification. + * + * @return Paging The pagination, cursor-based when a cursor is present. + */ + public function pagination(): Paging + { + return $this->pagination; + } + + /** + * Returns a copy of the criteria with the pagination replaced. + * + * @param Paging $pagination The pagination to apply. + * @return Criteria A new criteria carrying the given pagination with the filter and sort preserved. + */ + public function withPagination(Paging $pagination): Criteria + { + return new Criteria(sort: $this->sort, filter: $this->filter, schema: $this->schema, pagination: $pagination); + } +} diff --git a/src/Cursor.php b/src/Cursor.php new file mode 100644 index 0000000..8d299e8 --- /dev/null +++ b/src/Cursor.php @@ -0,0 +1,105 @@ +A cursor is built either from an incoming token (decoded on demand) or from the last-seen + * ordering key values (encoded on demand). The token is the only form that travels in the query + * string, the key values are the form the consumer feeds back to the store.

    + */ +final readonly class Cursor +{ + private function __construct(private ?array $keys, private ?string $token) + { + } + + /** + * Creates a Cursor wrapping an incoming opaque token, decoded on demand. + * + * @param string $token The opaque token received in the query string. + * @return Cursor A Cursor backed by the incoming token. + */ + public static function from(string $token): Cursor + { + return new Cursor(keys: null, token: $token); + } + + /** + * Creates an absent Cursor that carries neither a token nor key values. + * + * @return Cursor The absent cursor. + */ + public static function none(): Cursor + { + return new Cursor(keys: null, token: null); + } + + /** + * Creates a Cursor from the last-seen ordering key values, encoded on demand. + * + * @param array $keys The last-seen ordering key values. + * @return Cursor A Cursor backed by the given key values. + */ + public static function fromKeys(array $keys): Cursor + { + return new Cursor(keys: $keys, token: null); + } + + /** + * Returns the decoded ordering key values. + * + * @return array The decoded key values, empty when the cursor is absent. + * @throws CursorIsInvalid If the wrapped token cannot be decoded. + */ + public function toArray(): array + { + if (!is_null($this->keys)) { + return array_values($this->keys); + } + + if (is_null($this->token) || $this->token === '') { + return []; + } + + return CursorCodec::decode(token: $this->token); + } + + /** + * Tells whether the cursor carries neither a token nor key values. + * + * @return bool True when the cursor is absent. + */ + public function isAbsent(): bool + { + return match (true) { + !is_null($this->keys) => false, + is_null($this->token) => true, + default => $this->token === '' + }; + } + + /** + * Returns the opaque, URI-safe token. + * + * @return string The opaque token, empty when the cursor is absent. + */ + public function toString(): string + { + if (!is_null($this->token)) { + return $this->token; + } + + if (is_null($this->keys)) { + return ''; + } + + return CursorCodec::encode(keys: $this->keys); + } +} diff --git a/src/CursorPage.php b/src/CursorPage.php new file mode 100644 index 0000000..b472ca8 --- /dev/null +++ b/src/CursorPage.php @@ -0,0 +1,154 @@ + $items + */ + private function __construct( + private Collection $items, + private bool $hasNext, + private int $perPage, + private Cursor $nextCursor, + private bool $hasPrevious, + private Cursor $previousCursor + ) { + } + + /** + * Creates a CursorPage from the items, the key extractor, and the pagination. + * + *

    The consumer fetches one element beyond the page size via keyset. The extra element is + * trimmed and its presence is read as the next-page hint. The forward cursor anchors on the + * last retained element, the backward cursor on the first.

    + * + * @param Collection $items The items fetched for the page size plus one. + * @param Closure(TValue): list $keysOf Extracts the ordering key values from an element. + * @param CursorPagination $pagination The pagination describing the current page. + * @return CursorPage The cursor page carrying the trimmed items and the cursors. + */ + public static function from(Collection $items, Closure $keysOf, CursorPagination $pagination): CursorPage + { + $limit = $pagination->limit(); + $window = Window::from(items: $items, limit: $limit); + $hasNext = $window->hasNext(); + $hasPrevious = !$pagination->cursor()->isAbsent(); + + /** @var Collection $trimmed */ + $trimmed = $window->items(); + + $lastItem = $hasNext ? $trimmed->last() : null; + $firstItem = $hasPrevious ? $trimmed->first() : null; + + $nextCursor = is_null($lastItem) ? Cursor::none() : Cursor::fromKeys(keys: $keysOf($lastItem)); + $previousCursor = is_null($firstItem) ? Cursor::none() : Cursor::fromKeys(keys: $keysOf($firstItem)); + + return new CursorPage( + items: $trimmed, + hasNext: $hasNext, + perPage: $limit, + nextCursor: $nextCursor, + hasPrevious: $hasPrevious, + previousCursor: $previousCursor + ); + } + + /** + * Returns the items on the current page. + * + * @return Collection The items on the current page. + */ + public function items(): Collection + { + return $this->items; + } + + /** + * Tells whether a next page exists. + * + * @return bool True when a next page exists. + */ + public function hasNext(): bool + { + return $this->hasNext; + } + + /** + * Returns the cursor page as the JSON:API meta contents. + * + * @return array The meta contents keyed in length-ascending order. + */ + public function metadata(): array + { + return [ + 'has_next' => $this->hasNext, + 'per_page' => $this->perPage, + 'next_cursor' => $this->nextCursor->isAbsent() ? null : $this->nextCursor->toString(), + 'has_previous' => $this->hasPrevious, + 'previous_cursor' => $this->previousCursor->isAbsent() ? null : $this->previousCursor->toString() + ]; + } + + /** + * Returns the navigation exposing the previous and next targets. + * + * @return Navigation The navigation listing the keyset pages present for this page. + */ + public function navigation(): Navigation + { + $next = $this->nextCursor->isAbsent() + ? null + : CursorPagination::from(cursor: $this->nextCursor, perPage: $this->perPage); + $previous = $this->previousCursor->isAbsent() + ? null + : CursorPagination::from(cursor: $this->previousCursor, perPage: $this->perPage); + + return Navigation::empty() + ->with(target: $previous, relation: LinkRelation::PREVIOUS) + ->with(target: $next, relation: LinkRelation::NEXT); + } + + /** + * Returns the forward cursor, absent when there is no next page. + * + * @return Cursor The forward cursor. + */ + public function nextCursor(): Cursor + { + return $this->nextCursor; + } + + /** + * Tells whether a previous page exists. + * + * @return bool True when a previous page exists. + */ + public function hasPrevious(): bool + { + return $this->hasPrevious; + } + + /** + * Returns the backward cursor, absent when there is no previous page. + * + * @return Cursor The backward cursor. + */ + public function previousCursor(): Cursor + { + return $this->previousCursor; + } +} diff --git a/src/CursorPagination.php b/src/CursorPagination.php new file mode 100644 index 0000000..2219858 --- /dev/null +++ b/src/CursorPagination.php @@ -0,0 +1,64 @@ +limit; + } + + /** + * Returns the incoming cursor. + * + * @return Cursor The cursor. + */ + public function cursor(): Cursor + { + return $this->cursor; + } + + public function toQueryString(Schema $schema): string + { + $template = '%s=%d'; + $perPage = sprintf($template, $schema->perPageKey(), $this->limit); + $token = $this->cursor->toString(); + + if ($token === '') { + return $perPage; + } + + $template = '%s=%s&%s'; + + return sprintf($template, $schema->cursorKey(), $token, $perPage); + } +} diff --git a/src/Direction.php b/src/Direction.php new file mode 100644 index 0000000..22f3f28 --- /dev/null +++ b/src/Direction.php @@ -0,0 +1,27 @@ + '', + Direction::DESCENDING => '-' + }; + } +} diff --git a/src/Exceptions/CursorIsInvalid.php b/src/Exceptions/CursorIsInvalid.php new file mode 100644 index 0000000..e4a6bbc --- /dev/null +++ b/src/Exceptions/CursorIsInvalid.php @@ -0,0 +1,38 @@ + is invalid and could not be decoded.'; + + private function __construct(string $token, ?Throwable $previous) + { + $template = CursorIsInvalid::REASON_TEMPLATE; + + parent::__construct(message: sprintf($template, $token), previous: $previous); + } + + /** + * Creates a CursorIsInvalid from the offending token and the optional underlying cause. + * + * @param string $token The opaque cursor token that could not be decoded. + * @param Throwable|null $previous The underlying decoding failure preserved in the chain, if any. + * @return CursorIsInvalid The composed exception describing the invalid cursor token. + */ + public static function from(string $token, ?Throwable $previous = null): CursorIsInvalid + { + return new CursorIsInvalid(token: $token, previous: $previous); + } +} diff --git a/src/Exceptions/FilterExpressionIsInvalid.php b/src/Exceptions/FilterExpressionIsInvalid.php new file mode 100644 index 0000000..e13533b --- /dev/null +++ b/src/Exceptions/FilterExpressionIsInvalid.php @@ -0,0 +1,36 @@ + is invalid and could not be parsed.'; + + private function __construct(string $expression) + { + $template = FilterExpressionIsInvalid::REASON_TEMPLATE; + + parent::__construct(message: sprintf($template, $expression)); + } + + /** + * Creates a FilterExpressionIsInvalid from the offending expression. + * + * @param string $expression The RSQL filter expression that failed to parse. + * @return FilterExpressionIsInvalid The composed exception describing the invalid expression. + */ + public static function from(string $expression): FilterExpressionIsInvalid + { + return new FilterExpressionIsInvalid(expression: $expression); + } +} diff --git a/src/Exceptions/HttpQueryException.php b/src/Exceptions/HttpQueryException.php new file mode 100644 index 0000000..ca94d14 --- /dev/null +++ b/src/Exceptions/HttpQueryException.php @@ -0,0 +1,18 @@ + must be greater than or equal to 0.'; + + private function __construct(int $offset) + { + $template = OffsetOutOfRange::REASON_TEMPLATE; + + parent::__construct(message: sprintf($template, $offset)); + } + + /** + * Creates an OffsetOutOfRange from the offending offset. + * + * @param int $offset The offset that fell outside the valid range. + * @return OffsetOutOfRange The composed exception describing the invalid offset. + */ + public static function from(int $offset): OffsetOutOfRange + { + return new OffsetOutOfRange(offset: $offset); + } +} diff --git a/src/Exceptions/PageNumberOutOfRange.php b/src/Exceptions/PageNumberOutOfRange.php new file mode 100644 index 0000000..5802083 --- /dev/null +++ b/src/Exceptions/PageNumberOutOfRange.php @@ -0,0 +1,35 @@ + must be greater than or equal to 1.'; + + private function __construct(int $page) + { + $template = PageNumberOutOfRange::REASON_TEMPLATE; + + parent::__construct(message: sprintf($template, $page)); + } + + /** + * Creates a PageNumberOutOfRange from the offending page number. + * + * @param int $page The page number that fell outside the valid range. + * @return PageNumberOutOfRange The composed exception describing the invalid page number. + */ + public static function from(int $page): PageNumberOutOfRange + { + return new PageNumberOutOfRange(page: $page); + } +} diff --git a/src/Exceptions/PageSizeOutOfRange.php b/src/Exceptions/PageSizeOutOfRange.php new file mode 100644 index 0000000..a05d5bb --- /dev/null +++ b/src/Exceptions/PageSizeOutOfRange.php @@ -0,0 +1,52 @@ + must be less than or equal to %d.'; + private const string BELOW_MINIMUM = 'Page size <%d> must be greater than or equal to 1.'; + + private function __construct(string $reason) + { + parent::__construct(message: $reason); + } + + /** + * Creates a PageSizeOutOfRange signaling that the page size exceeds the allowed maximum. + * + * @param int $maximum The maximum page size allowed by the schema. + * @param int $perPage The page size that exceeded the maximum. + * @return PageSizeOutOfRange The composed exception describing the oversized page size. + */ + public static function aboveMaximum(int $maximum, int $perPage): PageSizeOutOfRange + { + $template = PageSizeOutOfRange::ABOVE_MAXIMUM; + + return new PageSizeOutOfRange(reason: sprintf($template, $perPage, $maximum)); + } + + /** + * Creates a PageSizeOutOfRange signaling that the page size is below the minimum of 1. + * + * @param int $perPage The page size that fell below the minimum. + * @return PageSizeOutOfRange The composed exception describing the undersized page size. + */ + public static function belowMinimum(int $perPage): PageSizeOutOfRange + { + $template = PageSizeOutOfRange::BELOW_MINIMUM; + + return new PageSizeOutOfRange(reason: sprintf($template, $perPage)); + } +} diff --git a/src/Exceptions/SortExpressionIsInvalid.php b/src/Exceptions/SortExpressionIsInvalid.php new file mode 100644 index 0000000..83f6594 --- /dev/null +++ b/src/Exceptions/SortExpressionIsInvalid.php @@ -0,0 +1,36 @@ + is invalid and could not be parsed.'; + + private function __construct(string $expression) + { + $template = SortExpressionIsInvalid::REASON_TEMPLATE; + + parent::__construct(message: sprintf($template, $expression)); + } + + /** + * Creates a SortExpressionIsInvalid from the offending expression. + * + * @param string $expression The sort expression that failed to parse. + * @return SortExpressionIsInvalid The composed exception describing the invalid expression. + */ + public static function from(string $expression): SortExpressionIsInvalid + { + return new SortExpressionIsInvalid(expression: $expression); + } +} diff --git a/src/Exceptions/TotalIsNegative.php b/src/Exceptions/TotalIsNegative.php new file mode 100644 index 0000000..80ba5ad --- /dev/null +++ b/src/Exceptions/TotalIsNegative.php @@ -0,0 +1,35 @@ + must be greater than or equal to 0.'; + + private function __construct(int $total) + { + $template = TotalIsNegative::REASON_TEMPLATE; + + parent::__construct(message: sprintf($template, $total)); + } + + /** + * Creates a TotalIsNegative from the offending total. + * + * @param int $total The total element count that fell below 0. + * @return TotalIsNegative The composed exception describing the negative total. + */ + public static function from(int $total): TotalIsNegative + { + return new TotalIsNegative(total: $total); + } +} diff --git a/src/Expression.php b/src/Expression.php new file mode 100644 index 0000000..8efc260 --- /dev/null +++ b/src/Expression.php @@ -0,0 +1,65 @@ +value; + } + + /** + * Returns the expression parenthesized when it binds looser than the given connective. + * + * @param LogicalOperator $parent The connective the expression is nested within. + * @return string The expression, parenthesized when required. + */ + public function nestedWithin(LogicalOperator $parent): string + { + if (!is_null($this->connective) && $parent->bindsTighterThan(other: $this->connective)) { + $template = '(%s)'; + + return sprintf($template, $this->value); + } + + return $this->value; + } +} diff --git a/src/Filter.php b/src/Filter.php new file mode 100644 index 0000000..bc29331 --- /dev/null +++ b/src/Filter.php @@ -0,0 +1,29 @@ +A node is either a {@see Comparison} leaf or a {@see Group} composite. The marker is sealed + * by the two implementations the library ships, so consumers match on the concrete type when they + * translate the tree to their own store.

    + */ +interface Filter +{ + /** + * Tells whether the filter carries no constraint. + * + * @return bool True when the filter is empty. + */ + public function isEmpty(): bool; + + /** + * Returns the filter as its RSQL expression. + * + * @return Expression The RSQL expression. + */ + public function toExpression(): Expression; +} diff --git a/src/Group.php b/src/Group.php new file mode 100644 index 0000000..cbd11cf --- /dev/null +++ b/src/Group.php @@ -0,0 +1,79 @@ + $filters The child filters joined by the connective. + * @param LogicalOperator $operator The logical connective joining the children. + * @return Group The composed group. + */ + public static function of(array $filters, LogicalOperator $operator): Group + { + return new Group(filters: $filters, operator: $operator); + } + + /** + * Creates an empty Group that carries no child filters. + * + * @return Group The empty group standing for the absence of a filter. + */ + public static function none(): Group + { + return new Group(filters: [], operator: LogicalOperator::AND); + } + + /** + * Returns the child filters joined by the connective. + * + * @return list The child filters. + */ + public function filters(): array + { + return $this->filters; + } + + public function isEmpty(): bool + { + return $this->filters === []; + } + + /** + * Returns the logical connective joining the child filters. + * + * @return LogicalOperator The logical connective. + */ + public function operator(): LogicalOperator + { + return $this->operator; + } + + public function toExpression(): Expression + { + $operator = $this->operator; + + /** @var Collection $filters */ + $filters = Collection::createFrom(elements: $this->filters); + + $value = $filters + ->map(transformations: static fn(Filter $filter): string => $filter->toExpression() + ->nestedWithin(parent: $operator)) + ->joinToString(separator: $operator->value); + + return Expression::grouped(value: $value, connective: $operator); + } +} diff --git a/src/Internal/CursorCodec.php b/src/Internal/CursorCodec.php new file mode 100644 index 0000000..6eca4be --- /dev/null +++ b/src/Internal/CursorCodec.php @@ -0,0 +1,40 @@ +decode(); + } catch (InvalidDecoding $exception) { + throw CursorIsInvalid::from(token: $token, previous: $exception); + } + + $keys = json_decode($payload); + + if (!is_array($keys)) { + throw CursorIsInvalid::from(token: $token); + } + + return $keys; + } + + public static function encode(array $keys): string + { + $payload = json_encode($keys, JSON_THROW_ON_ERROR); + + return Base62::from(value: $payload)->encode(); + } +} diff --git a/src/Internal/PaginationResolver.php b/src/Internal/PaginationResolver.php new file mode 100644 index 0000000..9fd5e7b --- /dev/null +++ b/src/Internal/PaginationResolver.php @@ -0,0 +1,41 @@ +query->get(key: $this->schema->perPageKey()); + $requested = $attribute->toString() === '' ? $this->schema->defaultPerPage() : $attribute->toInteger(); + $perPage = $this->schema->pageSizeFor(requested: $requested); + + $cursorToken = $this->query->get(key: $this->schema->cursorKey())->toString(); + + if ($cursorToken !== '') { + return CursorPagination::from(cursor: Cursor::from(token: $cursorToken), perPage: $perPage); + } + + $page = $this->query->get(key: $this->schema->pageKey()); + + return Pagination::fromPage(page: $page->toString() === '' ? 1 : $page->toInteger(), perPage: $perPage); + } +} diff --git a/src/Internal/Rsql/FilterParser.php b/src/Internal/Rsql/FilterParser.php new file mode 100644 index 0000000..7cdaa8c --- /dev/null +++ b/src/Internal/Rsql/FilterParser.php @@ -0,0 +1,93 @@ +disjunction(); + + if (!$this->scanner->isAtEnd()) { + throw FilterExpressionIsInvalid::from(expression: $this->input); + } + + return $filter; + } + + private function disjunction(): Filter + { + $filters = [$this->conjunction()]; + + while ($this->scanner->peek() === LogicalOperator::OR->value) { + $this->scanner->expect(character: LogicalOperator::OR->value); + $filters[] = $this->conjunction(); + } + + return count($filters) === 1 ? $filters[0] : Group::of(filters: $filters, operator: LogicalOperator::OR); + } + + private function conjunction(): Filter + { + $filters = [$this->constraint()]; + + while ($this->scanner->peek() === LogicalOperator::AND->value) { + $this->scanner->expect(character: LogicalOperator::AND->value); + $filters[] = $this->constraint(); + } + + return count($filters) === 1 ? $filters[0] : Group::of(filters: $filters, operator: LogicalOperator::AND); + } + + private function constraint(): Filter + { + if ($this->scanner->peek() === '(') { + $this->scanner->expect(character: '('); + $group = $this->disjunction(); + $this->scanner->expect(character: ')'); + + return $group; + } + + return $this->comparison(); + } + + private function comparison(): Comparison + { + $field = $this->scanner->unreserved(); + $operator = $this->scanner->operator(); + + if ($this->scanner->peek() !== '(') { + return Comparison::of(field: $field, values: [$this->scanner->value()], operator: $operator); + } + + $this->scanner->expect(character: '('); + $values = [$this->scanner->value()]; + + while ($this->scanner->peek() === ',') { + $this->scanner->expect(character: ','); + $values[] = $this->scanner->value(); + } + + $this->scanner->expect(character: ')'); + + return Comparison::of(field: $field, values: $values, operator: $operator); + } +} diff --git a/src/Internal/Rsql/Scanner.php b/src/Internal/Rsql/Scanner.php new file mode 100644 index 0000000..c9dfba8 --- /dev/null +++ b/src/Internal/Rsql/Scanner.php @@ -0,0 +1,118 @@ +'; + + private int $position = 0; + + private function __construct(private readonly string $input) + { + } + + public static function from(string $input): Scanner + { + return new Scanner(input: $input); + } + + public function peek(): string + { + return $this->input[$this->position] ?? ''; + } + + public function value(): string + { + if ($this->peek() === '"') { + return $this->quoted(quote: '"'); + } + + if ($this->peek() === "'") { + return $this->quoted(quote: "'"); + } + + return $this->unreserved(); + } + + public function expect(string $character): void + { + if ($this->peek() !== $character) { + throw FilterExpressionIsInvalid::from(expression: $this->input); + } + + $this->position++; + } + + private function quoted(string $quote): string + { + $this->position++; + $characters = []; + + while ($this->position < strlen($this->input)) { + $character = $this->input[$this->position]; + + if ($character === '\\') { + $characters[] = $this->input[$this->position + 1] ?? ''; + $this->position += 2; + continue; + } + + if ($character === $quote) { + $this->position++; + return implode('', $characters); + } + + $characters[] = $character; + $this->position++; + } + + throw FilterExpressionIsInvalid::from(expression: $this->input); + } + + public function isAtEnd(): bool + { + return $this->position === strlen($this->input); + } + + public function operator(): Operator + { + foreach (Operator::cases() as $operator) { + $token = $operator->value; + + if (substr($this->input, $this->position, strlen($token)) === $token) { + $this->position += strlen($token); + return $operator; + } + } + + throw FilterExpressionIsInvalid::from(expression: $this->input); + } + + private function isReserved(string $character): bool + { + return $character === ' ' || str_contains(self::RESERVED, $character); + } + + public function unreserved(): string + { + $start = $this->position; + + while ($this->position < strlen($this->input) && !$this->isReserved(character: $this->input[$this->position])) { + $this->position++; + } + + $token = substr($this->input, $start, $this->position - $start); + + if ($token === '') { + throw FilterExpressionIsInvalid::from(expression: $this->input); + } + + return $token; + } +} diff --git a/src/Internal/WebLink.php b/src/Internal/WebLink.php new file mode 100644 index 0000000..51e55ac --- /dev/null +++ b/src/Internal/WebLink.php @@ -0,0 +1,14 @@ + $items + */ + private function __construct(private Collection $items, private bool $hasNext) + { + } + + /** + * @param Collection $items + * @return Window + */ + public static function from(Collection $items, int $limit): Window + { + $elements = [...$items]; + $hasNext = count($elements) > $limit; + + /** @var Collection $trimmed */ + $trimmed = Collection::createFrom(elements: array_slice($elements, 0, $limit)); + + return new Window(items: $trimmed, hasNext: $hasNext); + } + + /** + * @return Collection + */ + public function items(): Collection + { + return $this->items; + } + + public function hasNext(): bool + { + return $this->hasNext; + } +} diff --git a/src/Links.php b/src/Links.php new file mode 100644 index 0000000..2661f4a --- /dev/null +++ b/src/Links.php @@ -0,0 +1,82 @@ +It renders uniformly over a {@see Navigation}, building the self link from the criteria and + * each navigation target by swapping the criteria's pagination, so the filter and the sort are + * preserved in every URI.

    + */ +final readonly class Links +{ + /** + * @param Collection $links + */ + private function __construct(private WebLink $self, private Collection $links) + { + } + + /** + * Creates a Links from the base URI, the criteria, and the navigation of a result. + * + * @param string $baseUri The base URI the navigation URIs are built on. + * @param Criteria $criteria The criteria that produced the result. + * @param Navigation $navigation The navigation the result exposes. + * @return Links The navigation for the result. + */ + public static function from(string $baseUri, Criteria $criteria, Navigation $navigation): Links + { + $self = new WebLink(uri: $criteria->toUri(baseUri: $baseUri), relation: LinkRelation::SELF); + + /** @var Collection $links */ + $links = $navigation->targets()->map( + transformations: static fn(NavigationTarget $target): WebLink => new WebLink( + uri: $criteria->withPagination(pagination: $target->target())->toUri(baseUri: $baseUri), + relation: $target->relation() + ) + ); + + return new Links(self: $self, links: $links); + } + + /** + * Returns the navigation as the JSON:API body links object. + * + * @return array The present relations mapped to their URIs, self first. + */ + public function toArray(): array + { + return $this->links->reduce( + accumulator: static fn(array $body, WebLink $link): array => [ + ...$body, + $link->relation->value => $link->uri + ], + initial: [$this->self->relation->value => $this->self->uri] + ); + } + + /** + * Returns the navigation as an RFC 8288 Link header. + * + * @return Link The Link folding self plus every navigation target. + */ + public function toHeader(): Link + { + return $this->links->reduce( + accumulator: static fn(Link $carry, WebLink $link): Link => $carry->and( + uri: $link->uri, + relation: $link->relation + ), + initial: Link::to(uri: $this->self->uri, relation: $this->self->relation) + ); + } +} diff --git a/src/LogicalOperator.php b/src/LogicalOperator.php new file mode 100644 index 0000000..9703104 --- /dev/null +++ b/src/LogicalOperator.php @@ -0,0 +1,29 @@ +The AND token (;) binds tighter than the OR token (,).

    + * + * @see https://github.com/jirutka/rsql-parser + */ +enum LogicalOperator: string +{ + case OR = ','; + case AND = ';'; + + /** + * Tells whether this connective binds tighter than the given one. + * + * @param LogicalOperator $other The connective to compare against. + * @return bool True when this connective binds tighter. + */ + public function bindsTighterThan(LogicalOperator $other): bool + { + return $this === LogicalOperator::AND && $other === LogicalOperator::OR; + } +} diff --git a/src/Navigation.php b/src/Navigation.php new file mode 100644 index 0000000..2502c04 --- /dev/null +++ b/src/Navigation.php @@ -0,0 +1,65 @@ +A result lists its own targets, so {@see Links} renders every result uniformly without + * branching on the concrete result type. The insertion order is preserved.

    + */ +final readonly class Navigation +{ + /** + * @param Collection $targets + */ + private function __construct(private Collection $targets) + { + } + + /** + * Creates an empty Navigation that carries no target. + * + * @return Navigation The empty navigation. + */ + public static function empty(): Navigation + { + /** @var Collection $targets */ + $targets = Collection::createFromEmpty(); + + return new Navigation(targets: $targets); + } + + /** + * Returns a copy of the Navigation with the target added under the relation. + * + *

    A null target is ignored, so the copy carries the same targets as the original.

    + * + * @param Paging|null $target The paging the target points to, or null to ignore. + * @param LinkRelation $relation The relation the target is reached through. + * @return Navigation A copy carrying the original targets plus the added target. + */ + public function with(?Paging $target, LinkRelation $relation): Navigation + { + if (is_null($target)) { + return $this; + } + + return new Navigation(targets: $this->targets->add(NavigationTarget::to(target: $target, relation: $relation))); + } + + /** + * Returns the navigation targets in insertion order. + * + * @return Collection The navigation targets. + */ + public function targets(): Collection + { + return $this->targets; + } +} diff --git a/src/NavigationTarget.php b/src/NavigationTarget.php new file mode 100644 index 0000000..f3b5155 --- /dev/null +++ b/src/NavigationTarget.php @@ -0,0 +1,49 @@ +target; + } + + /** + * Returns the relation the target is reached through. + * + * @return LinkRelation The link relation. + */ + public function relation(): LinkRelation + { + return $this->relation; + } +} diff --git a/src/Operator.php b/src/Operator.php new file mode 100644 index 0000000..650bfb5 --- /dev/null +++ b/src/Operator.php @@ -0,0 +1,32 @@ +field; + } + + /** + * Returns the direction applied to the field. + * + * @return Direction The direction applied to the field. + */ + public function direction(): Direction + { + return $this->direction; + } + + /** + * Returns the Order as its sort token. + * + * @return string The field with a leading minus when the direction is descending. + */ + public function toExpression(): string + { + $prefix = $this->direction->prefix(); + $template = '%s%s'; + + return sprintf($template, $prefix, $this->field); + } +} diff --git a/src/Page.php b/src/Page.php new file mode 100644 index 0000000..94bfe5c --- /dev/null +++ b/src/Page.php @@ -0,0 +1,203 @@ + $items + */ + private function __construct(private Collection $items, private int $total, private Pagination $pagination) + { + } + + /** + * Creates a Page from the items, the total element count, and the pagination. + * + * @param Collection $items The items on the current page. + * @param int $total The total element count across every page. + * @param Pagination $pagination The pagination describing the current page. + * @return Page The page carrying the items, the total, and the navigation. + * @throws TotalIsNegative If the total is less than 0. + */ + public static function from(Collection $items, int $total, Pagination $pagination): Page + { + if ($total < 0) { + throw TotalIsNegative::from(total: $total); + } + + return new Page(items: $items, total: $total, pagination: $pagination); + } + + /** + * Returns the pagination for the last page, or null when there is no page. + * + * @return Pagination|null The pagination for the last page, or null. + */ + public function last(): ?Pagination + { + return $this->totalPages() === 0 ? null : $this->pagination->atPage(page: $this->totalPages()); + } + + /** + * Returns the pagination for the next page, or null when there is none. + * + * @return Pagination|null The pagination for the next page, or null. + */ + public function next(): ?Pagination + { + return $this->hasNext() ? $this->pagination->next() : null; + } + + /** + * Returns the pagination for the first page, or null when there is no page. + * + * @return Pagination|null The pagination for the first page, or null. + */ + public function first(): ?Pagination + { + return $this->totalPages() === 0 ? null : $this->pagination->first(); + } + + /** + * Returns the items on the current page. + * + * @return Collection The items on the current page. + */ + public function items(): Collection + { + return $this->items; + } + + /** + * Returns the total element count across every page. + * + * @return int The total element count. + */ + public function total(): int + { + return $this->total; + } + + /** + * Tells whether the current page is the last page. + * + * @return bool True when the current page is the last page. + */ + public function isLast(): bool + { + return $this->currentPage() >= $this->totalPages(); + } + + /** + * Returns the zero-based offset of the current page. + * + * @return int The offset of the current page. + */ + public function offset(): int + { + return $this->pagination->offset(); + } + + /** + * Tells whether a next page exists. + * + * @return bool True when a next page exists. + */ + public function hasNext(): bool + { + return $this->currentPage() < $this->totalPages(); + } + + /** + * Tells whether the current page is the first page. + * + * @return bool True when the current page is the first page. + */ + public function isFirst(): bool + { + return !$this->pagination->hasPrevious(); + } + + /** + * Returns the page as the JSON:API meta contents. + * + * @return array The meta contents keyed in length-ascending order. + */ + public function metadata(): array + { + return [ + 'total' => $this->total, + 'has_next' => $this->hasNext(), + 'per_page' => $this->pagination->limit(), + 'total_pages' => $this->totalPages(), + 'current_page' => $this->currentPage(), + 'has_previous' => $this->hasPrevious() + ]; + } + + /** + * Returns the pagination for the previous page, or null when there is none. + * + * @return Pagination|null The pagination for the previous page, or null. + */ + public function previous(): ?Pagination + { + return $this->pagination->previous(); + } + + /** + * Returns the navigation exposing the first, previous, next, and last targets. + * + * @return Navigation The navigation listing the surrounding pages present for this page. + */ + public function navigation(): Navigation + { + return Navigation::empty() + ->with(target: $this->first(), relation: LinkRelation::FIRST) + ->with(target: $this->previous(), relation: LinkRelation::PREVIOUS) + ->with(target: $this->next(), relation: LinkRelation::NEXT) + ->with(target: $this->last(), relation: LinkRelation::LAST); + } + + /** + * Returns the total number of pages. + * + * @return int The total number of pages. + */ + public function totalPages(): int + { + return (int)ceil($this->total / $this->pagination->limit()); + } + + /** + * Returns the one-based current page number. + * + * @return int The current page number. + */ + public function currentPage(): int + { + return $this->pagination->page(); + } + + /** + * Tells whether a previous page exists. + * + * @return bool True when a previous page exists. + */ + public function hasPrevious(): bool + { + return $this->pagination->hasPrevious(); + } +} diff --git a/src/Pagination.php b/src/Pagination.php new file mode 100644 index 0000000..25c05f0 --- /dev/null +++ b/src/Pagination.php @@ -0,0 +1,153 @@ +The page-based factory derives the offset from the one-based page number and the page size.

    + */ +final readonly class Pagination implements Paging +{ + private function __construct(private int $offset, private int $limit) + { + } + + /** + * Creates a Pagination from a one-based page number and a page size. + * + * @param int $page The one-based page number. + * @param int $perPage The page size. + * @return Pagination The pagination whose offset is derived from the page and the page size. + * @throws PageNumberOutOfRange If the page number is less than 1. + * @throws PageSizeOutOfRange If the page size is less than 1. + */ + public static function fromPage(int $page, int $perPage): Pagination + { + if ($page < 1) { + throw PageNumberOutOfRange::from(page: $page); + } + + if ($perPage < 1) { + throw PageSizeOutOfRange::belowMinimum(perPage: $perPage); + } + + return new Pagination(offset: ($page - 1) * $perPage, limit: $perPage); + } + + /** + * Creates a Pagination from a zero-based offset and a limit. + * + * @param int $offset The zero-based offset. + * @param int $limit The maximum number of elements per page. + * @return Pagination The pagination carrying the offset and the limit. + * @throws OffsetOutOfRange If the offset is less than 0. + * @throws PageSizeOutOfRange If the limit is less than 1. + */ + public static function fromOffset(int $offset, int $limit): Pagination + { + if ($offset < 0) { + throw OffsetOutOfRange::from(offset: $offset); + } + + if ($limit < 1) { + throw PageSizeOutOfRange::belowMinimum(perPage: $limit); + } + + return new Pagination(offset: $offset, limit: $limit); + } + + /** + * Returns the pagination for the next page. + * + * @return Pagination The pagination for the next page. + */ + public function next(): Pagination + { + return Pagination::fromPage(page: $this->page() + 1, perPage: $this->limit); + } + + /** + * Returns the one-based page number derived from the offset and the limit. + * + * @return int The one-based page number. + */ + public function page(): int + { + return intdiv($this->offset, $this->limit) + 1; + } + + /** + * Returns the pagination for the first page. + * + * @return Pagination The pagination for the first page. + */ + public function first(): Pagination + { + return Pagination::fromPage(page: 1, perPage: $this->limit); + } + + public function limit(): int + { + return $this->limit; + } + + /** + * Returns the pagination for the given page. + * + * @param int $page The one-based page number. + * @return Pagination The pagination for the given page. + * @throws PageNumberOutOfRange If the page number is less than 1. + */ + public function atPage(int $page): Pagination + { + return Pagination::fromPage(page: $page, perPage: $this->limit); + } + + /** + * Returns the zero-based offset. + * + * @return int The offset. + */ + public function offset(): int + { + return $this->offset; + } + + /** + * Returns the pagination for the previous page, or null when there is none. + * + * @return Pagination|null The pagination for the previous page, or null. + */ + public function previous(): ?Pagination + { + if (!$this->hasPrevious()) { + return null; + } + + return Pagination::fromPage(page: $this->page() - 1, perPage: $this->limit); + } + + /** + * Tells whether a previous page exists. + * + * @return bool True when a previous page exists. + */ + public function hasPrevious(): bool + { + return $this->page() > 1; + } + + public function toQueryString(Schema $schema): string + { + $template = '%s=%d&%s=%d'; + + return sprintf($template, $schema->pageKey(), $this->page(), $schema->perPageKey(), $this->limit); + } +} diff --git a/src/Paging.php b/src/Paging.php new file mode 100644 index 0000000..be6bf90 --- /dev/null +++ b/src/Paging.php @@ -0,0 +1,29 @@ +It is implemented by the offset-based {@see Pagination} and the keyset {@see CursorPagination}, + * so a {@see Criteria} carries either one without branching on the concrete type.

    + */ +interface Paging +{ + /** + * Returns the maximum number of elements per page. + * + * @return int The limit. + */ + public function limit(): int; + + /** + * Returns the pagination as a query string fragment built against the schema keys. + * + * @param Schema $schema The schema mapping the query key names. + * @return string The query string fragment carrying the pagination. + */ + public function toQueryString(Schema $schema): string; +} diff --git a/src/Schema.php b/src/Schema.php new file mode 100644 index 0000000..b479bdc --- /dev/null +++ b/src/Schema.php @@ -0,0 +1,276 @@ +The defaults follow the canonical conventions: filter, sort, + * page, per_page, and cursor, with a default page size of + * 20 and a maximum of 100.

    + */ +final readonly class Schema +{ + private function __construct( + private string $pageKey, + private string $sortKey, + private string $cursorKey, + private string $filterKey, + private int $maxPerPage, + private string $perPageKey, + private int $defaultPerPage + ) { + if ($maxPerPage < 1) { + throw PageSizeOutOfRange::belowMinimum(perPage: $maxPerPage); + } + + if ($defaultPerPage < 1) { + throw PageSizeOutOfRange::belowMinimum(perPage: $defaultPerPage); + } + + if ($defaultPerPage > $maxPerPage) { + throw PageSizeOutOfRange::aboveMaximum(maximum: $maxPerPage, perPage: $defaultPerPage); + } + } + + /** + * Creates a Schema carrying the canonical default key names and bounds. + * + * @return Schema The default schema. + */ + public static function default(): Schema + { + return new Schema( + pageKey: 'page', + sortKey: 'sort', + cursorKey: 'cursor', + filterKey: 'filter', + maxPerPage: 100, + perPageKey: 'per_page', + defaultPerPage: 20 + ); + } + + /** + * Returns the query key carrying the page number. + * + * @return string The page key. + */ + public function pageKey(): string + { + return $this->pageKey; + } + + /** + * Returns the query key carrying the sort expression. + * + * @return string The sort key. + */ + public function sortKey(): string + { + return $this->sortKey; + } + + /** + * Returns the query key carrying the cursor token. + * + * @return string The cursor key. + */ + public function cursorKey(): string + { + return $this->cursorKey; + } + + /** + * Returns the query key carrying the RSQL filter. + * + * @return string The filter key. + */ + public function filterKey(): string + { + return $this->filterKey; + } + + /** + * Returns the maximum allowed page size. + * + * @return int The maximum page size. + */ + public function maxPerPage(): int + { + return $this->maxPerPage; + } + + /** + * Returns the query key carrying the page size. + * + * @return string The page-size key. + */ + public function perPageKey(): string + { + return $this->perPageKey; + } + + /** + * Returns the requested page size bounded by the maximum allowed. + * + * @param int $requested The requested page size. + * @return int The requested page size when it is within the maximum. + * @throws PageSizeOutOfRange If the requested size exceeds the maximum. + */ + public function pageSizeFor(int $requested): int + { + if ($requested > $this->maxPerPage) { + throw PageSizeOutOfRange::aboveMaximum(maximum: $this->maxPerPage, perPage: $requested); + } + + return $requested; + } + + /** + * Returns a copy of the Schema with the page key replaced. + * + * @param string $pageKey The query key carrying the page number. + * @return Schema A copy of the schema carrying the new page key. + */ + public function withPageKey(string $pageKey): Schema + { + return new Schema( + pageKey: $pageKey, + sortKey: $this->sortKey, + cursorKey: $this->cursorKey, + filterKey: $this->filterKey, + maxPerPage: $this->maxPerPage, + perPageKey: $this->perPageKey, + defaultPerPage: $this->defaultPerPage + ); + } + + /** + * Returns a copy of the Schema with the sort key replaced. + * + * @param string $sortKey The query key carrying the sort expression. + * @return Schema A copy of the schema carrying the new sort key. + */ + public function withSortKey(string $sortKey): Schema + { + return new Schema( + pageKey: $this->pageKey, + sortKey: $sortKey, + cursorKey: $this->cursorKey, + filterKey: $this->filterKey, + maxPerPage: $this->maxPerPage, + perPageKey: $this->perPageKey, + defaultPerPage: $this->defaultPerPage + ); + } + + /** + * Returns a copy of the Schema with the cursor key replaced. + * + * @param string $cursorKey The query key carrying the cursor token. + * @return Schema A copy of the schema carrying the new cursor key. + */ + public function withCursorKey(string $cursorKey): Schema + { + return new Schema( + pageKey: $this->pageKey, + sortKey: $this->sortKey, + cursorKey: $cursorKey, + filterKey: $this->filterKey, + maxPerPage: $this->maxPerPage, + perPageKey: $this->perPageKey, + defaultPerPage: $this->defaultPerPage + ); + } + + /** + * Returns a copy of the Schema with the filter key replaced. + * + * @param string $filterKey The query key carrying the RSQL filter. + * @return Schema A copy of the schema carrying the new filter key. + */ + public function withFilterKey(string $filterKey): Schema + { + return new Schema( + pageKey: $this->pageKey, + sortKey: $this->sortKey, + cursorKey: $this->cursorKey, + filterKey: $filterKey, + maxPerPage: $this->maxPerPage, + perPageKey: $this->perPageKey, + defaultPerPage: $this->defaultPerPage + ); + } + + /** + * Returns the page size applied when the query omits one. + * + * @return int The default page size. + */ + public function defaultPerPage(): int + { + return $this->defaultPerPage; + } + + /** + * Returns a copy of the Schema with the maximum page size replaced. + * + * @param int $maxPerPage The maximum allowed page size. + * @return Schema A copy of the schema carrying the new maximum page size. + */ + public function withMaxPerPage(int $maxPerPage): Schema + { + return new Schema( + pageKey: $this->pageKey, + sortKey: $this->sortKey, + cursorKey: $this->cursorKey, + filterKey: $this->filterKey, + maxPerPage: $maxPerPage, + perPageKey: $this->perPageKey, + defaultPerPage: $this->defaultPerPage + ); + } + + /** + * Returns a copy of the Schema with the page-size key replaced. + * + * @param string $perPageKey The query key carrying the page size. + * @return Schema A copy of the schema carrying the new page-size key. + */ + public function withPerPageKey(string $perPageKey): Schema + { + return new Schema( + pageKey: $this->pageKey, + sortKey: $this->sortKey, + cursorKey: $this->cursorKey, + filterKey: $this->filterKey, + maxPerPage: $this->maxPerPage, + perPageKey: $perPageKey, + defaultPerPage: $this->defaultPerPage + ); + } + + /** + * Returns a copy of the Schema with the default page size replaced. + * + * @param int $defaultPerPage The page size applied when the query omits one. + * @return Schema A copy of the schema carrying the new default page size. + */ + public function withDefaultPerPage(int $defaultPerPage): Schema + { + return new Schema( + pageKey: $this->pageKey, + sortKey: $this->sortKey, + cursorKey: $this->cursorKey, + filterKey: $this->filterKey, + maxPerPage: $this->maxPerPage, + perPageKey: $this->perPageKey, + defaultPerPage: $defaultPerPage + ); + } +} diff --git a/src/Slice.php b/src/Slice.php new file mode 100644 index 0000000..d072b2b --- /dev/null +++ b/src/Slice.php @@ -0,0 +1,141 @@ + $items + */ + private function __construct(private Collection $items, private bool $hasNext, private Pagination $pagination) + { + } + + /** + * Creates a Slice from the items and the pagination. + * + *

    The consumer fetches one element beyond the page size. The extra element is trimmed and + * its presence is read as the next-page hint.

    + * + * @param Collection $items The items fetched for the page size plus one. + * @param Pagination $pagination The pagination describing the current page. + * @return Slice The slice carrying the trimmed items and the next-page hint. + */ + public static function from(Collection $items, Pagination $pagination): Slice + { + $window = Window::from(items: $items, limit: $pagination->limit()); + + /** @var Collection $trimmed */ + $trimmed = $window->items(); + + return new Slice(items: $trimmed, hasNext: $window->hasNext(), pagination: $pagination); + } + + /** + * Returns the pagination for the next page, or null when there is none. + * + * @return Pagination|null The pagination for the next page, or null. + */ + public function next(): ?Pagination + { + return $this->hasNext ? $this->pagination->next() : null; + } + + /** + * Returns the items on the current page. + * + * @return Collection The items on the current page. + */ + public function items(): Collection + { + return $this->items; + } + + /** + * Returns the zero-based offset of the current page. + * + * @return int The offset of the current page. + */ + public function offset(): int + { + return $this->pagination->offset(); + } + + /** + * Tells whether a next page exists. + * + * @return bool True when a next page exists. + */ + public function hasNext(): bool + { + return $this->hasNext; + } + + /** + * Returns the slice as the JSON:API meta contents. + * + * @return array The meta contents keyed in length-ascending order. + */ + public function metadata(): array + { + return [ + 'has_next' => $this->hasNext, + 'per_page' => $this->pagination->limit(), + 'current_page' => $this->currentPage(), + 'has_previous' => $this->hasPrevious() + ]; + } + + /** + * Returns the pagination for the previous page, or null when there is none. + * + * @return Pagination|null The pagination for the previous page, or null. + */ + public function previous(): ?Pagination + { + return $this->pagination->previous(); + } + + /** + * Returns the navigation exposing the previous and next targets. + * + * @return Navigation The navigation listing the surrounding pages present for this slice. + */ + public function navigation(): Navigation + { + return Navigation::empty() + ->with(target: $this->previous(), relation: LinkRelation::PREVIOUS) + ->with(target: $this->next(), relation: LinkRelation::NEXT); + } + + /** + * Returns the one-based current page number. + * + * @return int The current page number. + */ + public function currentPage(): int + { + return $this->pagination->page(); + } + + /** + * Tells whether a previous page exists. + * + * @return bool True when a previous page exists. + */ + public function hasPrevious(): bool + { + return $this->pagination->hasPrevious(); + } +} diff --git a/src/Sort.php b/src/Sort.php new file mode 100644 index 0000000..06a4729 --- /dev/null +++ b/src/Sort.php @@ -0,0 +1,90 @@ +Fields are comma-separated and a leading minus marks descending order, for example + * -created_at,id. The request order is preserved.

    + */ +final readonly class Sort +{ + private function __construct(private array $orders) + { + } + + /** + * Creates a Sort from a comma-separated sort expression. + * + *

    An empty expression yields an empty Sort. A leading minus on a field marks descending + * order, every other field is ascending.

    + * + * @param string $expression The comma-separated sort expression. + * @return Sort The parsed ordering with the request order preserved. + * @throws SortExpressionIsInvalid If a field is empty or carries reserved characters. + */ + public static function fromExpression(string $expression): Sort + { + $trimmed = trim($expression); + + if ($trimmed === '') { + return new Sort(orders: []); + } + + $orders = array_map(static function (string $token) use ($expression): Order { + $descending = str_starts_with($token, '-'); + $field = $descending ? substr($token, 1) : $token; + + if (preg_match('/^\w[\w.-]*$/', $field) !== 1) { + throw SortExpressionIsInvalid::from(expression: $expression); + } + + $direction = $descending ? Direction::DESCENDING : Direction::ASCENDING; + + return Order::from(field: $field, direction: $direction); + }, explode(',', $trimmed)); + + return new Sort(orders: $orders); + } + + /** + * Returns the orders in the request order. + * + * @return list The orders in the request order. + */ + public function orders(): array + { + return $this->orders; + } + + /** + * Tells whether no sort field is present. + * + * @return bool True when the Sort carries no order. + */ + public function isEmpty(): bool + { + return $this->orders === []; + } + + /** + * Returns the Sort as a comma-separated sort expression. + * + * @return string The sort expression with a leading minus marking each descending field. + */ + public function toExpression(): string + { + /** @var Collection $orders */ + $orders = Collection::createFrom(elements: $this->orders); + + return $orders + ->map(transformations: static fn(Order $order): string => $order->toExpression()) + ->joinToString(separator: ','); + } +} diff --git a/tests/Models/Query.php b/tests/Models/Query.php new file mode 100644 index 0000000..323da3c --- /dev/null +++ b/tests/Models/Query.php @@ -0,0 +1,20 @@ +withQueryParams($parameters)); + } +} diff --git a/tests/Unit/CriteriaTest.php b/tests/Unit/CriteriaTest.php new file mode 100644 index 0000000..a6512b6 --- /dev/null +++ b/tests/Unit/CriteriaTest.php @@ -0,0 +1,275 @@ +sorting()->isEmpty()); + } + + public function testFromQueryWhenEmptyThenFilteringIsAnEmptyGroup(): void + { + /** @Given empty query parameters */ + $query = Query::from(parameters: []); + + /** @When building the criteria from the query */ + $criteria = Criteria::fromQuery(query: $query); + + /** @Then the filtering is an empty group */ + self::assertInstanceOf(Group::class, $criteria->filtering()); + + /** @And the group carries no child filter */ + self::assertSame([], $criteria->filtering()->filters()); + } + + public function testFromQueryWhenNoCursorThenPaginationIsOffsetBased(): void + { + /** @Given query parameters without a cursor */ + $query = Query::from(parameters: ['page' => '2', 'per_page' => '15']); + + /** @When building the criteria from the query */ + $criteria = Criteria::fromQuery(query: $query); + + /** @Then the pagination is offset-based */ + self::assertInstanceOf(Pagination::class, $criteria->pagination()); + } + + public function testToUriWhenAndGroupNestedInOrThenLeavesItUnwrapped(): void + { + /** @Given a criteria whose filter nests an AND group inside an OR group */ + $criteria = Criteria::fromQuery(query: Query::from(parameters: ['filter' => 'a==1;b==2,c==3'])); + + /** @When serializing the criteria back to a URI */ + $actual = $criteria->toUri(baseUri: '/v1/orders'); + + /** @Then the tighter-binding AND group is left unwrapped */ + self::assertSame('/v1/orders?filter=a==1;b==2,c==3&page=1&per_page=20', $actual); + } + + public function testFromQueryWhenPerPageIsAtTheMaximumThenItIsAccepted(): void + { + /** @Given query parameters carrying a page size at the default maximum */ + $query = Query::from(parameters: ['per_page' => '100']); + + /** @When building the criteria from the query */ + $criteria = Criteria::fromQuery(query: $query); + + /** @Then the pagination is offset-based */ + self::assertInstanceOf(Pagination::class, $criteria->pagination()); + + /** @And it carries the maximum page size */ + self::assertSame(100, $criteria->pagination()->limit()); + } + + public function testToUriWhenOrGroupNestedInAndThenWrapsItInParentheses(): void + { + /** @Given a criteria whose filter nests an OR group inside an AND group */ + $criteria = Criteria::fromQuery(query: Query::from(parameters: ['filter' => '(a==1,b==2);c==3'])); + + /** @When serializing the criteria back to a URI */ + $actual = $criteria->toUri(baseUri: '/v1/orders'); + + /** @Then the nested OR group is wrapped in parentheses */ + self::assertSame('/v1/orders?filter=(a==1,b==2);c==3&page=1&per_page=20', $actual); + } + + public function testToUriWhenValueCarriesReservedCharactersThenItIsQuoted(): void + { + /** @Given a criteria whose filter value carries a space */ + $criteria = Criteria::fromQuery(query: Query::from(parameters: ['filter' => 'name=="John Doe"'])); + + /** @When serializing the criteria back to a URI */ + $actual = $criteria->toUri(baseUri: '/v1/orders'); + + /** @Then the value is rendered with surrounding double quotes */ + self::assertSame('/v1/orders?filter=name=="John Doe"&page=1&per_page=20', $actual); + } + + public function testFromQueryWhenCursorIsPresentThenPaginationIsCursorBased(): void + { + /** @Given query parameters carrying a cursor */ + $query = Query::from(parameters: ['cursor' => 'abc', 'per_page' => '10']); + + /** @When building the criteria from the query */ + $criteria = Criteria::fromQuery(query: $query); + + /** @Then the pagination is cursor-based */ + self::assertInstanceOf(CursorPagination::class, $criteria->pagination()); + + /** @And it carries the requested page size */ + self::assertSame(10, $criteria->pagination()->limit()); + + /** @And it carries the incoming cursor token */ + self::assertSame('abc', $criteria->pagination()->cursor()->toString()); + } + + public function testToUriWhenValueCarriesQuoteAndBackslashThenBothAreEscaped(): void + { + /** @Given a criteria whose filter value carries a double quote and a backslash */ + $criteria = Criteria::fromQuery(query: Query::from(parameters: ['filter' => 'name=="a\"b\\\\c"'])); + + /** @When serializing the criteria back to a URI */ + $actual = $criteria->toUri(baseUri: '/v1/orders'); + + /** @Then the quote and the backslash are escaped within the double-quoted value */ + self::assertSame('/v1/orders?filter=name=="a\"b\\\\c"&page=1&per_page=20', $actual); + } + + public function testFromQueryWhenEmptyThenPaginationCarriesDefaultPageAndLimit(): void + { + /** @Given empty query parameters */ + $query = Query::from(parameters: []); + + /** @When building the criteria from the query */ + $criteria = Criteria::fromQuery(query: $query); + + /** @Then the pagination is offset-based */ + self::assertInstanceOf(Pagination::class, $criteria->pagination()); + + /** @And it starts at the first page */ + self::assertSame(1, $criteria->pagination()->page()); + + /** @And it carries the default page size */ + self::assertSame(20, $criteria->pagination()->limit()); + } + + public function testWithPaginationWhenPageReplacedThenFilterAndSortArePreserved(): void + { + /** @Given a criteria parsed from a filter, a sort, a page, and a page size */ + $criteria = Criteria::fromQuery(query: Query::from(parameters: [ + 'sort' => '-created_at,id', + 'page' => '3', + 'filter' => 'status==paid', + 'per_page' => '20' + ])); + + /** @And a replacement pagination pointing at a new page */ + $pagination = Pagination::fromPage(page: 5, perPage: 20); + + /** @When replacing the pagination and serializing back to a URI */ + $actual = $criteria->withPagination(pagination: $pagination)->toUri(baseUri: '/v1/orders'); + + /** @Then the URI keeps the filter and the sort while pointing at the new page */ + self::assertSame('/v1/orders?filter=status==paid&sort=-created_at,id&page=5&per_page=20', $actual); + } + + public function testFromQueryWhenCustomSchemaGivenThenParsesAgainstTheCustomKeys(): void + { + /** @Given query parameters using custom key names */ + $query = Query::from(parameters: ['q' => 'name==bob', 'size' => '5', 'p' => '2']); + + /** @And a schema mapping those custom key names */ + $schema = Schema::default() + ->withPageKey(pageKey: 'p') + ->withFilterKey(filterKey: 'q') + ->withPerPageKey(perPageKey: 'size'); + + /** @When building the criteria from the query and the schema */ + $criteria = Criteria::fromQuery(query: $query, schema: $schema); + + /** @Then the pagination is offset-based */ + self::assertInstanceOf(Pagination::class, $criteria->pagination()); + + /** @And the pagination points at the requested page */ + self::assertSame(2, $criteria->pagination()->page()); + + /** @And the pagination carries the requested page size */ + self::assertSame(5, $criteria->pagination()->limit()); + + /** @And the filtering is a comparison */ + self::assertInstanceOf(Comparison::class, $criteria->filtering()); + + /** @And the comparison targets the filtered field */ + self::assertSame('name', $criteria->filtering()->field()); + } + + public function testFromQueryWhenPerPageAboveMaximumThenThrowsPageSizeOutOfRange(): void + { + /** @Given query parameters carrying a page size above the default maximum */ + $query = Query::from(parameters: ['per_page' => '500']); + + /** @Then an exception indicating the page size is out of range is raised */ + $this->expectException(PageSizeOutOfRange::class); + $this->expectExceptionMessage('Page size'); + + /** @When building the criteria from the query */ + Criteria::fromQuery(query: $query); + } + + public function testToUriWhenFilterSortAndPageGivenThenRoundTripsToTheCanonicalUri(): void + { + /** @Given a criteria parsed from a filter, a sort, a page, and a page size */ + $criteria = Criteria::fromQuery(query: Query::from(parameters: [ + 'sort' => '-created_at,id', + 'page' => '3', + 'filter' => 'status==paid;total=ge=100', + 'per_page' => '20' + ])); + + /** @When serializing the criteria back to a URI */ + $actual = $criteria->toUri(baseUri: '/v1/orders'); + + /** @Then the URI preserves the filter, the sort, and the pagination */ + self::assertSame('/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page=3&per_page=20', $actual); + } + + public function testFromQueryWhenFilterSortAndPageGivenThenEachSpecificationIsParsed(): void + { + /** @Given query parameters carrying a filter, a sort, a page, and a page size */ + $query = Query::from(parameters: [ + 'sort' => '-created_at', + 'page' => '2', + 'filter' => 'status==paid', + 'per_page' => '15' + ]); + + /** @When building the criteria from the query */ + $criteria = Criteria::fromQuery(query: $query); + + /** @Then the filtering is a comparison */ + self::assertInstanceOf(Comparison::class, $criteria->filtering()); + + /** @And the comparison targets the filtered field */ + self::assertSame('status', $criteria->filtering()->field()); + + /** @And the sorting carries exactly one order */ + self::assertCount(1, $criteria->sorting()->orders()); + + /** @And the single order sorts by the descending field */ + self::assertSame('created_at', $criteria->sorting()->orders()[0]->field()); + + /** @And the single order applies descending direction */ + self::assertSame(Direction::DESCENDING, $criteria->sorting()->orders()[0]->direction()); + + /** @And the pagination is offset-based */ + self::assertInstanceOf(Pagination::class, $criteria->pagination()); + + /** @And it points at the requested page */ + self::assertSame(2, $criteria->pagination()->page()); + + /** @And it carries the requested page size */ + self::assertSame(15, $criteria->pagination()->limit()); + } +} diff --git a/tests/Unit/CursorPageTest.php b/tests/Unit/CursorPageTest.php new file mode 100644 index 0000000..f71bc80 --- /dev/null +++ b/tests/Unit/CursorPageTest.php @@ -0,0 +1,143 @@ + [$element], + pagination: CursorPagination::from(cursor: Cursor::none(), perPage: 2) + ); + + /** @When reading the navigation targets */ + $targets = $page->navigation()->targets(); + + /** @Then it lists a single navigation target */ + self::assertCount(1, $targets->toArray()); + + /** @And the only target is the next target anchored on the forward cursor */ + self::assertEquals( + NavigationTarget::to( + target: CursorPagination::from(cursor: Cursor::fromKeys(keys: [20]), perPage: 2), + relation: LinkRelation::NEXT + ), + $targets->first() + ); + } + + public function testNavigationWhenExtraElementFetchedThenHasNextAndForwardCursorAnchorsLastItem(): void + { + /** @Given a keyset pagination with an absent incoming cursor and a page size of two */ + $pagination = CursorPagination::from(cursor: Cursor::none(), perPage: 2); + + /** @And items fetched for the page size plus one */ + $items = Collection::createFrom(elements: [10, 20, 30]); + + /** @When building the cursor page from the items, the key extractor, and the pagination */ + $page = CursorPage::from( + items: $items, + keysOf: static fn(mixed $element): array => [$element], + pagination: $pagination + ); + + /** @Then the page reports a next page */ + self::assertTrue($page->hasNext()); + + /** @And the items are trimmed to the page size */ + self::assertSame([10, 20], $page->items()->toArray()); + + /** @And the page has no previous page */ + self::assertFalse($page->hasPrevious()); + + /** @And the forward cursor anchors on the last retained element */ + self::assertSame([20], $page->nextCursor()->toArray()); + + /** @And the forward cursor is present */ + self::assertFalse($page->nextCursor()->isAbsent()); + + /** @And the backward cursor is absent */ + self::assertTrue($page->previousCursor()->isAbsent()); + + /** @And the metadata carries every navigation flag and cursor in declared key order */ + self::assertSame([ + 'has_next' => true, + 'per_page' => 2, + 'next_cursor' => Cursor::fromKeys(keys: [20])->toString(), + 'has_previous' => false, + 'previous_cursor' => null + ], $page->metadata()); + } + + public function testNavigationWhenIncomingCursorAndNoExtraElementThenListsOnlyThePreviousTarget(): void + { + /** @Given the opaque token produced from ordering key values */ + $token = Cursor::fromKeys(keys: [5])->toString(); + + /** @And a keyset page fetched within the page size reached through that incoming cursor */ + $page = CursorPage::from( + items: Collection::createFrom(elements: [10, 20]), + keysOf: static fn(mixed $element): array => [$element], + pagination: CursorPagination::from(cursor: Cursor::from(token: $token), perPage: 2) + ); + + /** @When reading the navigation targets */ + $targets = $page->navigation()->targets(); + + /** @Then it lists a single navigation target */ + self::assertCount(1, $targets->toArray()); + + /** @And the only target is the previous target anchored on the backward cursor */ + self::assertEquals( + NavigationTarget::to( + target: CursorPagination::from(cursor: Cursor::fromKeys(keys: [10]), perPage: 2), + relation: LinkRelation::PREVIOUS + ), + $targets->first() + ); + } + + public function testNavigationWhenNoExtraElementAndIncomingCursorThenNoNextAndBackwardCursorAnchorsFirstItem(): void + { + /** @Given the opaque token produced from ordering key values */ + $existingToken = Cursor::fromKeys(keys: [5])->toString(); + + /** @And a keyset pagination with a present incoming cursor and a page size of two */ + $pagination = CursorPagination::from(cursor: Cursor::from(token: $existingToken), perPage: 2); + + /** @And items fetched within the page size */ + $items = Collection::createFrom(elements: [10, 20]); + + /** @When building the cursor page from the items, the key extractor, and the pagination */ + $page = CursorPage::from( + items: $items, + keysOf: static fn(mixed $element): array => [$element], + pagination: $pagination + ); + + /** @Then the page reports no next page */ + self::assertFalse($page->hasNext()); + + /** @And the page has a previous page */ + self::assertTrue($page->hasPrevious()); + + /** @And the forward cursor is absent */ + self::assertTrue($page->nextCursor()->isAbsent()); + + /** @And the backward cursor anchors on the first retained element */ + self::assertSame([10], $page->previousCursor()->toArray()); + } +} diff --git a/tests/Unit/CursorPaginationTest.php b/tests/Unit/CursorPaginationTest.php new file mode 100644 index 0000000..7dd6ae4 --- /dev/null +++ b/tests/Unit/CursorPaginationTest.php @@ -0,0 +1,92 @@ +limit(); + + /** @Then it carries the minimum page size */ + self::assertSame(1, $limit); + } + + public function testToQueryStringWhenCursorAbsentThenRendersOnlyPerPage(): void + { + /** @Given a cursor pagination carrying an absent cursor and a page size */ + $pagination = CursorPagination::from(cursor: Cursor::none(), perPage: 10); + + /** @When rendering it as a query string against the default schema */ + $queryString = $pagination->toQueryString(schema: Schema::default()); + + /** @Then it renders only the page size */ + self::assertSame('per_page=10', $queryString); + } + + public function testFromWhenAbsentCursorGivenThenCarriesLimitAndAbsentCursor(): void + { + /** @Given a cursor pagination built from an absent cursor and a page size of 20 */ + $pagination = CursorPagination::from(cursor: Cursor::none(), perPage: 20); + + /** @When reading the page size limit */ + $limit = $pagination->limit(); + + /** @Then it carries the requested page size */ + self::assertSame(20, $limit); + + /** @And its cursor is absent */ + self::assertTrue($pagination->cursor()->isAbsent()); + } + + public function testFromWhenPageSizeBelowMinimumThenThrowsPageSizeOutOfRange(): void + { + /** @Given an absent cursor */ + $cursor = Cursor::none(); + + /** @Then an exception indicating the page size is out of range is raised */ + $this->expectException(PageSizeOutOfRange::class); + + /** @When building a cursor pagination with a page size below the minimum */ + CursorPagination::from(cursor: $cursor, perPage: 0); + } + + public function testToQueryStringWhenCursorPresentThenRendersCursorAndPerPage(): void + { + /** @Given a cursor pagination carrying an incoming cursor and a page size */ + $pagination = CursorPagination::from(cursor: Cursor::from(token: 'abc'), perPage: 10); + + /** @When rendering it as a query string against the default schema */ + $queryString = $pagination->toQueryString(schema: Schema::default()); + + /** @Then it renders the cursor token followed by the page size */ + self::assertSame('cursor=abc&per_page=10', $queryString); + } + + public function testFromWhenIncomingCursorGivenThenCarriesLimitAndTheCursorToken(): void + { + /** @Given a cursor pagination built from an incoming cursor and a page size of 50 */ + $pagination = CursorPagination::from(cursor: Cursor::from(token: 'abc'), perPage: 50); + + /** @When reading the page size limit */ + $limit = $pagination->limit(); + + /** @Then it carries the requested page size */ + self::assertSame(50, $limit); + + /** @And its cursor renders the incoming token */ + self::assertSame('abc', $pagination->cursor()->toString()); + } +} diff --git a/tests/Unit/CursorTest.php b/tests/Unit/CursorTest.php new file mode 100644 index 0000000..51a30ad --- /dev/null +++ b/tests/Unit/CursorTest.php @@ -0,0 +1,147 @@ +isAbsent(); + + /** @Then it reports itself as present */ + self::assertFalse($isAbsent); + } + + public function testFromWhenEmptyTokenGivenThenIsAbsent(): void + { + /** @Given a cursor backed by an empty incoming token */ + $cursor = Cursor::from(token: ''); + + /** @When inspecting whether the cursor is absent */ + $isAbsent = $cursor->isAbsent(); + + /** @Then it reports itself as absent */ + self::assertTrue($isAbsent); + } + + public function testFromWhenNonEmptyTokenGivenThenIsPresent(): void + { + /** @Given a cursor backed by a non-empty incoming token */ + $cursor = Cursor::from(token: 'abc'); + + /** @When inspecting whether the cursor is absent */ + $isAbsent = $cursor->isAbsent(); + + /** @Then it reports itself as present */ + self::assertFalse($isAbsent); + } + + public function testNoneThenAbsentWithEmptyKeysAndEmptyToken(): void + { + /** @Given an absent cursor */ + $cursor = Cursor::none(); + + /** @When inspecting the absent cursor */ + $isAbsent = $cursor->isAbsent(); + + /** @Then it reports itself as absent */ + self::assertTrue($isAbsent); + + /** @And it decodes to no key values */ + self::assertSame([], $cursor->toArray()); + + /** @And it renders an empty token */ + self::assertSame('', $cursor->toString()); + } + + public function testFromKeysWhenKeysGivenThenDecodesToTheSameKeys(): void + { + /** @Given a cursor backed by ordering key values */ + $cursor = Cursor::fromKeys(keys: ['2024-01-01', 42]); + + /** @When decoding the cursor into key values */ + $keys = $cursor->toArray(); + + /** @Then it yields the original key values */ + self::assertSame(['2024-01-01', 42], $keys); + } + + public function testFromKeysWhenKeysAreGappedThenDecodesToAReindexedList(): void + { + /** @Given a cursor backed by ordering key values held under gapped integer keys */ + $cursor = Cursor::fromKeys(keys: [5 => 'x', 9 => 'y']); + + /** @When decoding the cursor into key values */ + $keys = $cursor->toArray(); + + /** @Then it yields the values as a zero-based list */ + self::assertSame(['x', 'y'], $keys); + } + + public function testToArrayWhenTokenIsNotBase62ThenThrowsCursorIsInvalid(): void + { + /** @Given a cursor backed by a token carrying characters outside the base62 alphabet */ + $cursor = Cursor::from(token: 'not valid base62 !!!'); + + /** @Then an exception indicating the cursor token is invalid is raised */ + $this->expectException(CursorIsInvalid::class); + $this->expectExceptionMessage('could not be decoded'); + + /** @When decoding the cursor into key values */ + $cursor->toArray(); + } + + public function testToArrayWhenTokenDecodesToScalarThenThrowsCursorIsInvalid(): void + { + /** @Given a base62 token whose decoded payload is the JSON scalar 5 */ + $cursor = Cursor::from(token: Base62::from(value: '5')->encode()); + + /** @Then an exception indicating the cursor token is invalid is raised */ + $this->expectException(CursorIsInvalid::class); + $this->expectExceptionMessage('could not be decoded'); + + /** @When decoding the cursor into key values */ + $cursor->toArray(); + } + + public function testFromKeysWhenRoundTrippedThroughTokenThenYieldsTheOriginalKeys(): void + { + /** @Given the opaque token produced from ordering key values */ + $token = Cursor::fromKeys(keys: ['2024-01-01', 42])->toString(); + + /** @And the token is not empty */ + self::assertNotSame('', $token); + + /** @When rebuilding a cursor from that token and decoding it */ + $keys = Cursor::from(token: $token)->toArray(); + + /** @Then it yields the original key values */ + self::assertSame(['2024-01-01', 42], $keys); + } + + public function testConstructorWhenInvokedThroughReflectionThenInstantiatesTheStaticOnlyCodec(): void + { + /** @Given an uninitialized instance of the static-only cursor codec */ + $codec = new ReflectionClass(CursorCodec::class)->newInstanceWithoutConstructor(); + + /** @When invoking its otherwise-uncallable private constructor */ + new ReflectionMethod(CursorCodec::class, '__construct')->invoke($codec); + + /** @Then the static-only cursor codec is instantiated */ + self::assertInstanceOf(CursorCodec::class, $codec); + } +} diff --git a/tests/Unit/DirectionTest.php b/tests/Unit/DirectionTest.php new file mode 100644 index 0000000..a75d95c --- /dev/null +++ b/tests/Unit/DirectionTest.php @@ -0,0 +1,66 @@ +value; + + /** @Then the value equals the canonical token */ + self::assertSame($token, $actual); + } + + #[DataProvider('prefixCases')] + public function testPrefixWhenCaseGivenThenReturnsTheSortExpressionPrefix( + Direction $direction, + string $prefix + ): void { + /** @Given a sort direction and its sort-expression prefix */ + + /** @When reading the prefix */ + $actual = $direction->prefix(); + + /** @Then the prefix matches the expected token */ + self::assertSame($prefix, $actual); + } + + public static function prefixCases(): array + { + return [ + 'ASCENDING' => ['direction' => Direction::ASCENDING, 'prefix' => ''], + 'DESCENDING' => ['direction' => Direction::DESCENDING, 'prefix' => '-'] + ]; + } + + public static function directionCases(): array + { + return [ + 'ASCENDING' => ['direction' => Direction::ASCENDING, 'token' => 'asc'], + 'DESCENDING' => ['direction' => Direction::DESCENDING, 'token' => 'desc'] + ]; + } +} diff --git a/tests/Unit/EndToEndTest.php b/tests/Unit/EndToEndTest.php new file mode 100644 index 0000000..84524f3 --- /dev/null +++ b/tests/Unit/EndToEndTest.php @@ -0,0 +1,102 @@ + 'status==paid;total=ge=100', + 'sort' => '-created_at,id', + 'page' => '3', + 'per_page' => '20' + ]); + + /** @And the criteria parsed from those parameters */ + $criteria = Criteria::fromQuery(query: $query); + + /** @And the offset pagination pointing at the third page */ + $pagination = Pagination::fromPage(page: 3, perPage: 20); + + /** @And the third page of a 480-element result */ + $page = Page::from(items: Collection::createFromEmpty(), total: 480, pagination: $pagination); + + /** @And the navigation for that page over the orders base URI */ + $links = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $page->navigation()); + + /** @When rendering the RFC 8288 Link header line */ + $header = $links->toHeader()->toArray()['Link'][0]; + + /** @Then the line folds the five relations in navigation order */ + self::assertSame(implode(', ', [ + '; rel="self"', + '; rel="first"', + '; rel="prev"', + '; rel="next"', + '; rel="last"' + ]), $header); + } + + public function testPipelineWhenCanonicalRequestGivenThenJsonBodyCarriesDataMetaAndLinks(): void + { + /** @Given the canonical request query parameters */ + $query = Query::from(parameters: [ + 'filter' => 'status==paid;total=ge=100', + 'sort' => '-created_at,id', + 'page' => '3', + 'per_page' => '20' + ]); + + /** @And the criteria parsed from those parameters */ + $criteria = Criteria::fromQuery(query: $query); + + /** @And the offset pagination pointing at the third page */ + $pagination = Pagination::fromPage(page: 3, perPage: 20); + + /** @And the third page of a 480-element result */ + $page = Page::from(items: Collection::createFromEmpty(), total: 480, pagination: $pagination); + + /** @And the navigation for that page over the orders base URI */ + $links = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $page->navigation()); + + /** @When assembling the JSON:API body from the data, the meta, and the links */ + $body = [ + 'data' => $page->items()->toArray(keyPreservation: KeyPreservation::DISCARD), + 'meta' => $page->metadata(), + 'links' => $links->toArray() + ]; + + /** @Then the body carries the empty data, the meta, and the five navigation links in order */ + self::assertSame([ + 'data' => [], + 'meta' => [ + 'total' => 480, + 'has_next' => true, + 'per_page' => 20, + 'total_pages' => 24, + 'current_page' => 3, + 'has_previous' => true + ], + 'links' => [ + 'self' => '/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page=3&per_page=20', + 'first' => '/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page=1&per_page=20', + 'prev' => '/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page=2&per_page=20', + 'next' => '/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page=4&per_page=20', + 'last' => '/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page=24&per_page=20' + ] + ], $body); + } +} diff --git a/tests/Unit/ExpressionTest.php b/tests/Unit/ExpressionTest.php new file mode 100644 index 0000000..26d4b8c --- /dev/null +++ b/tests/Unit/ExpressionTest.php @@ -0,0 +1,78 @@ +value(); + + /** @Then it returns the rendered leaf */ + self::assertSame('status==paid', $actual); + } + + public function testValueWhenGroupedGivenThenReturnsJoinedChildren(): void + { + /** @Given a grouped expression rendered from children joined by a connective */ + $expression = Expression::grouped(value: 'a==1;b==2', connective: LogicalOperator::AND); + + /** @When reading the RSQL expression */ + $actual = $expression->value(); + + /** @Then it returns the joined children */ + self::assertSame('a==1;b==2', $actual); + } + + #[DataProvider('nestingCases')] + public function testNestedWithinWhenNestedThenParenthesizesByPrecedence( + Expression $expression, + LogicalOperator $parent, + string $expected + ): void { + /** @Given a rendered expression and the connective it is nested within */ + + /** @When rendering it nested within the parent connective */ + $actual = $expression->nestedWithin(parent: $parent); + + /** @Then it is parenthesized only when it binds looser than the parent */ + self::assertSame($expected, $actual); + } + + public static function nestingCases(): array + { + return [ + 'OR grouped within AND' => [ + 'expression' => Expression::grouped(value: 'a==1,b==2', connective: LogicalOperator::OR), + 'parent' => LogicalOperator::AND, + 'expected' => '(a==1,b==2)' + ], + 'AND grouped within OR' => [ + 'expression' => Expression::grouped(value: 'a==1;b==2', connective: LogicalOperator::AND), + 'parent' => LogicalOperator::OR, + 'expected' => 'a==1;b==2' + ], + 'OR grouped within OR' => [ + 'expression' => Expression::grouped(value: 'a==1,b==2', connective: LogicalOperator::OR), + 'parent' => LogicalOperator::OR, + 'expected' => 'a==1,b==2' + ], + 'atomic within AND' => [ + 'expression' => Expression::atomic(value: 'a==1'), + 'parent' => LogicalOperator::AND, + 'expected' => 'a==1' + ] + ]; + } +} diff --git a/tests/Unit/FilterTest.php b/tests/Unit/FilterTest.php new file mode 100644 index 0000000..8f24150 --- /dev/null +++ b/tests/Unit/FilterTest.php @@ -0,0 +1,375 @@ +isEmpty(); + + /** @Then it reports itself as empty */ + self::assertTrue($isEmpty); + } + + public function testIsEmptyWhenGroupHasChildThenIsNotEmpty(): void + { + /** @Given a group joining a single comparison */ + $group = Group::of(filters: [ + Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL) + ], operator: LogicalOperator::AND); + + /** @When checking whether it is empty */ + $isEmpty = $group->isEmpty(); + + /** @Then it reports itself as not empty */ + self::assertFalse($isEmpty); + } + + public function testIsEmptyWhenComparisonGivenThenIsNotEmpty(): void + { + /** @Given an equality comparison */ + $comparison = Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL); + + /** @When checking whether it is empty */ + $isEmpty = $comparison->isEmpty(); + + /** @Then it reports itself as not empty */ + self::assertFalse($isEmpty); + } + + public function testFilteringWhenNoFilterGivenThenReturnsEmptyGroup(): void + { + /** @Given a query carrying no filter parameter at all */ + $query = Query::from(parameters: []); + + /** @When reading the filtering specification */ + $filter = Criteria::fromQuery(query: $query)->filtering(); + + /** @Then the filter is an empty group joined by the AND connective */ + self::assertEquals(Group::of(filters: [], operator: LogicalOperator::AND), $filter); + } + + public function testFilteringWhenOrGivenThenGroupJoinsTwoComparisons(): void + { + /** @Given a query carrying an OR expression of two comparisons */ + $query = Query::from(parameters: ['filter' => 'a==1,b==2']); + + /** @When reading the filtering specification */ + $filter = Criteria::fromQuery(query: $query)->filtering(); + + /** @Then the filter is an OR group joining the two comparison children in order */ + self::assertEquals(Group::of(filters: [ + Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), + Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) + ], operator: LogicalOperator::OR), $filter); + } + + public function testFilteringWhenAndGivenThenGroupJoinsTwoComparisons(): void + { + /** @Given a query carrying an AND expression of two comparisons */ + $query = Query::from(parameters: ['filter' => 'a==1;b==2']); + + /** @When reading the filtering specification */ + $filter = Criteria::fromQuery(query: $query)->filtering(); + + /** @Then the filter is an AND group joining the two comparison children in order */ + self::assertEquals(Group::of(filters: [ + Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), + Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) + ], operator: LogicalOperator::AND), $filter); + } + + public function testFilteringWhenInListGivenThenComparisonCarriesEveryValue(): void + { + /** @Given a query carrying an IN list comparison */ + $query = Query::from(parameters: ['filter' => 'role=in=(admin,user)']); + + /** @When reading the filtering specification */ + $filter = Criteria::fromQuery(query: $query)->filtering(); + + /** @Then the filter is an IN comparison carrying every listed value in order */ + self::assertEquals(Comparison::of(field: 'role', values: ['admin', 'user'], operator: Operator::IN), $filter); + } + + public function testToExpressionWhenAndGroupNestedInOrThenLeavesItUnwrapped(): void + { + /** @Given an OR group whose first child is an AND group */ + $group = Group::of(filters: [ + Group::of(filters: [ + Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), + Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) + ], operator: LogicalOperator::AND), + Comparison::of(field: 'c', values: ['3'], operator: Operator::EQUAL) + ], operator: LogicalOperator::OR); + + /** @When rendering it as an RSQL expression */ + $expression = $group->toExpression()->value(); + + /** @Then the tighter-binding AND group is left unwrapped */ + self::assertSame('a==1;b==2,c==3', $expression); + } + + public function testToExpressionWhenInListGivenThenWrapsValuesInParentheses(): void + { + /** @Given an IN comparison carrying several values */ + $comparison = Comparison::of(field: 'role', values: ['admin', 'user'], operator: Operator::IN); + + /** @When rendering it as an RSQL expression */ + $expression = $comparison->toExpression()->value(); + + /** @Then it wraps the comma-joined values in parentheses */ + self::assertSame('role=in=(admin,user)', $expression); + } + + public function testToExpressionWhenValueCarriesReservedCharacterThenQuotesIt(): void + { + /** @Given a comparison whose value carries a space */ + $comparison = Comparison::of(field: 'name', values: ['John Doe'], operator: Operator::EQUAL); + + /** @When rendering it as an RSQL expression */ + $expression = $comparison->toExpression()->value(); + + /** @Then it renders the value within double quotes */ + self::assertSame('name=="John Doe"', $expression); + } + + public function testFilteringWhenMixedPrecedenceGivenThenAndBindsTighterThanOr(): void + { + /** @Given a query mixing AND and OR connectives without explicit grouping */ + $query = Query::from(parameters: ['filter' => 'a==1;b==2,c==3']); + + /** @When reading the filtering specification */ + $filter = Criteria::fromQuery(query: $query)->filtering(); + + /** @Then the top filter is an OR group whose first child is the tighter AND group */ + self::assertEquals(Group::of(filters: [ + Group::of(filters: [ + Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), + Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) + ], operator: LogicalOperator::AND), + Comparison::of(field: 'c', values: ['3'], operator: Operator::EQUAL) + ], operator: LogicalOperator::OR), $filter); + } + + public function testFilteringWhenNotInListGivenThenComparisonCarriesEveryValue(): void + { + /** @Given a query carrying a NOT_IN list comparison */ + $query = Query::from(parameters: ['filter' => 'role=out=(a,b)']); + + /** @When reading the filtering specification */ + $filter = Criteria::fromQuery(query: $query)->filtering(); + + /** @Then the filter is a NOT_IN comparison carrying every listed value in order */ + self::assertEquals(Comparison::of(field: 'role', values: ['a', 'b'], operator: Operator::NOT_IN), $filter); + } + + public function testToExpressionWhenAndGroupGivenThenJoinsChildrenWithAndToken(): void + { + /** @Given an AND group of two comparisons */ + $group = Group::of(filters: [ + Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), + Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) + ], operator: LogicalOperator::AND); + + /** @When rendering it as an RSQL expression */ + $expression = $group->toExpression()->value(); + + /** @Then it joins the children with the AND token */ + self::assertSame('a==1;b==2', $expression); + } + + public function testToExpressionWhenOrGroupNestedInAndThenWrapsItInParentheses(): void + { + /** @Given an AND group whose first child is an OR group */ + $group = Group::of(filters: [ + Group::of(filters: [ + Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), + Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) + ], operator: LogicalOperator::OR), + Comparison::of(field: 'c', values: ['3'], operator: Operator::EQUAL) + ], operator: LogicalOperator::AND); + + /** @When rendering it as an RSQL expression */ + $expression = $group->toExpression()->value(); + + /** @Then the nested OR group is wrapped in parentheses */ + self::assertSame('(a==1,b==2);c==3', $expression); + } + + public function testFilteringWhenDoubleQuotedValueGivenThenComparisonStripsQuotes(): void + { + /** @Given a query carrying a double-quoted value with whitespace */ + $query = Query::from(parameters: ['filter' => 'name=="John Doe"']); + + /** @When reading the filtering specification */ + $filter = Criteria::fromQuery(query: $query)->filtering(); + + /** @Then the comparison carries the value with the surrounding quotes stripped */ + self::assertEquals(Comparison::of(field: 'name', values: ['John Doe'], operator: Operator::EQUAL), $filter); + } + + public function testFilteringWhenSingleQuotedValueGivenThenComparisonStripsQuotes(): void + { + /** @Given a query carrying a single-quoted value with whitespace */ + $query = Query::from(parameters: ['filter' => "name=='John Doe'"]); + + /** @When reading the filtering specification */ + $filter = Criteria::fromQuery(query: $query)->filtering(); + + /** @Then the comparison carries the value with the surrounding quotes stripped */ + self::assertEquals(Comparison::of(field: 'name', values: ['John Doe'], operator: Operator::EQUAL), $filter); + } + + public function testToExpressionWhenComparisonGivenThenRendersFieldOperatorAndValue(): void + { + /** @Given an equality comparison on a field */ + $comparison = Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL); + + /** @When rendering it as an RSQL expression */ + $expression = $comparison->toExpression()->value(); + + /** @Then it renders the field, the operator token, and the value */ + self::assertSame('status==paid', $expression); + } + + public function testFilteringWhenExplicitGroupingGivenThenParenthesesOverridePrecedence(): void + { + /** @Given a query whose parentheses force the OR group to bind first */ + $query = Query::from(parameters: ['filter' => '(a==1,b==2);c==3']); + + /** @When reading the filtering specification */ + $filter = Criteria::fromQuery(query: $query)->filtering(); + + /** @Then the top filter is an AND group whose first child is the parenthesized OR group */ + self::assertEquals(Group::of(filters: [ + Group::of(filters: [ + Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), + Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) + ], operator: LogicalOperator::OR), + Comparison::of(field: 'c', values: ['3'], operator: Operator::EQUAL) + ], operator: LogicalOperator::AND), $filter); + } + + public function testFilteringWhenSingleComparisonGivenThenComparisonCarriesFieldAndValue(): void + { + /** @Given a query carrying a single equality comparison */ + $query = Query::from(parameters: ['filter' => 'status==paid']); + + /** @When reading the filtering specification */ + $filter = Criteria::fromQuery(query: $query)->filtering(); + + /** @Then the filter is an equality comparison on the named field with its value */ + self::assertEquals(Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL), $filter); + } + + #[DataProvider('comparisonOperatorCases')] + public function testFilteringWhenComparisonOperatorGivenThenComparisonCarriesThatOperator( + string $expression, + Operator $expected + ): void { + /** @Given a query carrying a binary comparison using one RSQL operator */ + $query = Query::from(parameters: ['filter' => $expression]); + + /** @When reading the filtering specification */ + $filter = Criteria::fromQuery(query: $query)->filtering(); + + /** @Then the filter is a comparison on the left field carrying the expected operator */ + self::assertEquals(Comparison::of(field: 'a', values: ['b'], operator: $expected), $filter); + } + + #[DataProvider('malformedExpressionCases')] + public function testFilteringWhenMalformedExpressionGivenThenThrowsFilterExpressionIsInvalid( + string $expression + ): void { + /** @Given a query carrying a filter expression that breaks the RSQL grammar */ + $query = Query::from(parameters: ['filter' => $expression]); + + /** @Then an exception indicating the filter expression is invalid is raised */ + $this->expectException(FilterExpressionIsInvalid::class); + $this->expectExceptionMessage('could not be parsed'); + + /** @When building the criteria from the query */ + Criteria::fromQuery(query: $query); + } + + public function testValuesWhenComparisonGivenThenReturnsTheComparedValues(): void + { + /** @Given an IN comparison carrying several values */ + $comparison = Comparison::of(field: 'role', values: ['admin', 'user'], operator: Operator::IN); + + /** @When reading the compared values */ + $values = $comparison->values(); + + /** @Then it returns the values compared against the field in order */ + self::assertSame(['admin', 'user'], $values); + } + + public function testOperatorWhenComparisonGivenThenReturnsTheComparisonOperator(): void + { + /** @Given an equality comparison */ + $comparison = Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL); + + /** @When reading the comparison operator */ + $operator = $comparison->operator(); + + /** @Then it returns the operator the comparison carries */ + self::assertSame(Operator::EQUAL, $operator); + } + + public function testOperatorWhenGroupGivenThenReturnsTheLogicalConnective(): void + { + /** @Given an AND group joining two comparisons */ + $group = Group::of(filters: [ + Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), + Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) + ], operator: LogicalOperator::AND); + + /** @When reading the logical connective */ + $operator = $group->operator(); + + /** @Then it returns the connective joining the children */ + self::assertSame(LogicalOperator::AND, $operator); + } + + public static function comparisonOperatorCases(): array + { + return [ + 'NOT_EQUAL' => ['expression' => 'a!=b', 'expected' => Operator::NOT_EQUAL], + 'LESS_THAN' => ['expression' => 'a=lt=b', 'expected' => Operator::LESS_THAN], + 'GREATER_THAN' => ['expression' => 'a=gt=b', 'expected' => Operator::GREATER_THAN], + 'LESS_THAN_OR_EQUAL' => ['expression' => 'a=le=b', 'expected' => Operator::LESS_THAN_OR_EQUAL], + 'GREATER_THAN_OR_EQUAL' => ['expression' => 'a=ge=b', 'expected' => Operator::GREATER_THAN_OR_EQUAL] + ]; + } + + public static function malformedExpressionCases(): array + { + return [ + 'No operator' => ['expression' => 'status'], + 'Empty value' => ['expression' => 'status=='], + 'Unclosed group' => ['expression' => '(status==paid'], + 'Trailing semicolon' => ['expression' => 'status==paid;'], + 'Unknown operator' => ['expression' => 'status=zz=paid'], + 'Group missing close mark' => ['expression' => '(a==1 '], + 'Trailing close mark' => ['expression' => 'a==1)'], + 'Unclosed quoted value' => ['expression' => 'name=="x'] + ]; + } +} diff --git a/tests/Unit/LinksTest.php b/tests/Unit/LinksTest.php new file mode 100644 index 0000000..6962eed --- /dev/null +++ b/tests/Unit/LinksTest.php @@ -0,0 +1,242 @@ +withPagination(pagination: $pagination); + + /** @And a page carrying a total spanning twenty-four pages */ + $result = Page::from( + items: Collection::createFrom(elements: range(1, 20)), + total: 480, + pagination: $pagination + ); + + /** @When rendering the navigation for the last page */ + $links = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $result->navigation()); + + /** @Then the navigation exposes the self, first, previous, and last relations in that order */ + self::assertSame([ + 'self' => '/v1/orders?page=24&per_page=20', + 'first' => '/v1/orders?page=1&per_page=20', + 'prev' => '/v1/orders?page=23&per_page=20', + 'last' => '/v1/orders?page=24&per_page=20' + ], $links->toArray()); + + /** @And the navigation carries no next relation */ + self::assertArrayNotHasKey('next', $links->toArray()); + } + + public function testToArrayWhenSliceMiddleThenExposesSelfPrevAndNext(): void + { + /** @Given an offset pagination pointing at a middle page */ + $pagination = Pagination::fromPage(page: 3, perPage: 20); + + /** @And a criteria carrying a filter and a sort over that pagination */ + $criteria = Criteria::fromQuery(query: Query::from(parameters: [ + 'sort' => '-created_at,id', + 'filter' => 'status==paid' + ]))->withPagination(pagination: $pagination); + + /** @And a slice fetched for the page size plus one so a next page exists */ + $result = Slice::from(items: Collection::createFrom(elements: range(1, 21)), pagination: $pagination); + + /** @When rendering the navigation for the slice */ + $links = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $result->navigation()); + + /** @Then the navigation exposes the self, previous, and next relations preserving filter and sort */ + self::assertSame([ + 'self' => '/v1/orders?filter=status==paid&sort=-created_at,id&page=3&per_page=20', + 'prev' => '/v1/orders?filter=status==paid&sort=-created_at,id&page=2&per_page=20', + 'next' => '/v1/orders?filter=status==paid&sort=-created_at,id&page=4&per_page=20' + ], $links->toArray()); + } + + public function testToArrayWhenCursorResultThenExposesOnlySelfAndNext(): void + { + /** @Given a cursor criteria carrying an incoming cursor token and a page size of two */ + $criteria = Criteria::fromQuery(query: Query::from(parameters: [ + 'cursor' => Cursor::fromKeys(keys: [5])->toString(), + 'per_page' => '2' + ])); + + /** @And a cursor page fetched for the page size plus one with no incoming cursor */ + $result = CursorPage::from( + items: Collection::createFrom(elements: [10, 20, 30]), + keysOf: static fn(mixed $element): array => [$element], + pagination: CursorPagination::from(cursor: Cursor::none(), perPage: 2) + ); + + /** @When rendering the navigation for the cursor page */ + $links = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $result->navigation()); + + /** @Then the navigation exposes only the self and next relations */ + self::assertSame([ + 'self' => sprintf('/v1/orders?cursor=%s&per_page=2', Cursor::fromKeys(keys: [5])->toString()), + 'next' => sprintf('/v1/orders?cursor=%s&per_page=2', Cursor::fromKeys(keys: [20])->toString()) + ], $links->toArray()); + } + + public function testToArrayWhenPageIsTheFirstThenOmitsThePreviousRelation(): void + { + /** @Given an offset pagination pointing at the first page */ + $pagination = Pagination::fromPage(page: 1, perPage: 20); + + /** @And a criteria over that pagination */ + $criteria = Criteria::fromQuery(query: Query::from(parameters: []))->withPagination(pagination: $pagination); + + /** @And a page carrying a total spanning twenty-four pages */ + $result = Page::from( + items: Collection::createFrom(elements: range(1, 20)), + total: 480, + pagination: $pagination + ); + + /** @When rendering the navigation for the first page */ + $links = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $result->navigation()); + + /** @Then the navigation exposes the self, first, next, and last relations in that order */ + self::assertSame([ + 'self' => '/v1/orders?page=1&per_page=20', + 'first' => '/v1/orders?page=1&per_page=20', + 'next' => '/v1/orders?page=2&per_page=20', + 'last' => '/v1/orders?page=24&per_page=20' + ], $links->toArray()); + + /** @And the navigation carries no previous relation */ + self::assertArrayNotHasKey('prev', $links->toArray()); + } + + public function testToArrayWhenSliceMiddleThenCarriesNoFirstOrLastRelation(): void + { + /** @Given an offset pagination pointing at a middle page */ + $pagination = Pagination::fromPage(page: 3, perPage: 20); + + /** @And a criteria over that pagination */ + $criteria = Criteria::fromQuery(query: Query::from(parameters: []))->withPagination(pagination: $pagination); + + /** @And a slice fetched for the page size plus one so a next page exists */ + $result = Slice::from(items: Collection::createFrom(elements: range(1, 21)), pagination: $pagination); + + /** @When rendering the navigation for the slice */ + $links = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $result->navigation()); + + /** @Then the navigation carries no first relation */ + self::assertArrayNotHasKey('first', $links->toArray()); + + /** @And the navigation carries no last relation */ + self::assertArrayNotHasKey('last', $links->toArray()); + } + + public function testToArrayWhenCursorResultThenCarriesNoFirstOrLastOrPreviousRelation(): void + { + /** @Given a cursor criteria carrying an incoming cursor token and a page size of two */ + $criteria = Criteria::fromQuery(query: Query::from(parameters: [ + 'cursor' => Cursor::fromKeys(keys: [5])->toString(), + 'per_page' => '2' + ])); + + /** @And a cursor page fetched for the page size plus one with no incoming cursor */ + $result = CursorPage::from( + items: Collection::createFrom(elements: [10, 20, 30]), + keysOf: static fn(mixed $element): array => [$element], + pagination: CursorPagination::from(cursor: Cursor::none(), perPage: 2) + ); + + /** @When rendering the navigation for the cursor page */ + $links = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $result->navigation()); + + /** @Then the navigation carries no first relation */ + self::assertArrayNotHasKey('first', $links->toArray()); + + /** @And the navigation carries no last relation */ + self::assertArrayNotHasKey('last', $links->toArray()); + + /** @And the navigation carries no previous relation */ + self::assertArrayNotHasKey('prev', $links->toArray()); + } + + public function testToHeaderWhenPageInTheMiddleThenFoldsEveryRelationIntoOneCommaJoinedValue(): void + { + /** @Given an offset pagination pointing at a middle page */ + $pagination = Pagination::fromPage(page: 3, perPage: 20); + + /** @And a criteria carrying a filter and a sort over that pagination */ + $criteria = Criteria::fromQuery(query: Query::from(parameters: [ + 'sort' => '-created_at,id', + 'filter' => 'status==paid' + ]))->withPagination(pagination: $pagination); + + /** @And a page carrying a total spanning twenty-four pages */ + $result = Page::from( + items: Collection::createFrom(elements: range(1, 20)), + total: 480, + pagination: $pagination + ); + + /** @When rendering the navigation as an RFC 8288 Link header */ + $header = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $result->navigation()) + ->toHeader(); + + /** @Then every present relation is folded into one comma-joined Link header value */ + self::assertSame(['Link' => [implode(', ', [ + '; rel="self"', + '; rel="first"', + '; rel="prev"', + '; rel="next"', + '; rel="last"' + ])]], $header->toArray()); + } + + public function testToArrayWhenPageInTheMiddleThenExposesEveryRelationPreservingFilterAndSort(): void + { + /** @Given an offset pagination pointing at a middle page */ + $pagination = Pagination::fromPage(page: 3, perPage: 20); + + /** @And a criteria carrying a filter and a sort over that pagination */ + $criteria = Criteria::fromQuery(query: Query::from(parameters: [ + 'sort' => '-created_at,id', + 'filter' => 'status==paid' + ]))->withPagination(pagination: $pagination); + + /** @And a page carrying a total spanning twenty-four pages */ + $result = Page::from( + items: Collection::createFrom(elements: range(1, 20)), + total: 480, + pagination: $pagination + ); + + /** @When rendering the navigation for the page */ + $links = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $result->navigation()); + + /** @Then the navigation exposes every relation in semantic order preserving filter and sort */ + self::assertSame([ + 'self' => '/v1/orders?filter=status==paid&sort=-created_at,id&page=3&per_page=20', + 'first' => '/v1/orders?filter=status==paid&sort=-created_at,id&page=1&per_page=20', + 'prev' => '/v1/orders?filter=status==paid&sort=-created_at,id&page=2&per_page=20', + 'next' => '/v1/orders?filter=status==paid&sort=-created_at,id&page=4&per_page=20', + 'last' => '/v1/orders?filter=status==paid&sort=-created_at,id&page=24&per_page=20' + ], $links->toArray()); + } +} diff --git a/tests/Unit/LogicalOperatorTest.php b/tests/Unit/LogicalOperatorTest.php new file mode 100644 index 0000000..9c846e5 --- /dev/null +++ b/tests/Unit/LogicalOperatorTest.php @@ -0,0 +1,85 @@ +value; + + /** @Then the value equals the canonical token */ + self::assertSame($token, $actual); + } + + #[DataProvider('precedenceCases')] + public function testBindsTighterThanWhenComparedToOtherThenReflectsPrecedence( + LogicalOperator $operator, + LogicalOperator $other, + bool $expected + ): void { + /** @Given a connective and another connective to compare against */ + + /** @When asking whether the connective binds tighter than the other */ + $actual = $operator->bindsTighterThan(other: $other); + + /** @Then the answer reflects that AND binds tighter than OR */ + self::assertSame($expected, $actual); + } + + public static function precedenceCases(): array + { + return [ + 'AND over OR' => [ + 'operator' => LogicalOperator::AND, + 'other' => LogicalOperator::OR, + 'expected' => true + ], + 'OR over AND' => [ + 'operator' => LogicalOperator::OR, + 'other' => LogicalOperator::AND, + 'expected' => false + ], + 'AND over AND' => [ + 'operator' => LogicalOperator::AND, + 'other' => LogicalOperator::AND, + 'expected' => false + ], + 'OR over OR' => [ + 'operator' => LogicalOperator::OR, + 'other' => LogicalOperator::OR, + 'expected' => false + ] + ]; + } + + public static function logicalOperatorCases(): array + { + return [ + 'OR' => ['operator' => LogicalOperator::OR, 'token' => ','], + 'AND' => ['operator' => LogicalOperator::AND, 'token' => ';'] + ]; + } +} diff --git a/tests/Unit/OperatorTest.php b/tests/Unit/OperatorTest.php new file mode 100644 index 0000000..0259842 --- /dev/null +++ b/tests/Unit/OperatorTest.php @@ -0,0 +1,78 @@ +value; + + /** @Then the value equals the canonical token */ + self::assertSame($token, $actual); + } + + #[DataProvider('multiValuedCases')] + public function testIsMultiValuedWhenOperatorGivenThenTellsWhetherItComparesAgainstAList( + Operator $operator, + bool $multiValued + ): void { + /** @Given a comparison operator and whether it compares against a value list */ + + /** @When asking whether the operator is multi-valued */ + $actual = $operator->isMultiValued(); + + /** @Then the answer matches the expected outcome */ + self::assertSame($multiValued, $actual); + } + + public static function operatorCases(): array + { + return [ + 'IN' => ['operator' => Operator::IN, 'token' => '=in='], + 'EQUAL' => ['operator' => Operator::EQUAL, 'token' => '=='], + 'NOT_IN' => ['operator' => Operator::NOT_IN, 'token' => '=out='], + 'LESS_THAN' => ['operator' => Operator::LESS_THAN, 'token' => '=lt='], + 'NOT_EQUAL' => ['operator' => Operator::NOT_EQUAL, 'token' => '!='], + 'GREATER_THAN' => ['operator' => Operator::GREATER_THAN, 'token' => '=gt='], + 'LESS_THAN_OR_EQUAL' => ['operator' => Operator::LESS_THAN_OR_EQUAL, 'token' => '=le='], + 'GREATER_THAN_OR_EQUAL' => ['operator' => Operator::GREATER_THAN_OR_EQUAL, 'token' => '=ge='] + ]; + } + + public static function multiValuedCases(): array + { + return [ + 'IN' => ['operator' => Operator::IN, 'multiValued' => true], + 'EQUAL' => ['operator' => Operator::EQUAL, 'multiValued' => false], + 'NOT_IN' => ['operator' => Operator::NOT_IN, 'multiValued' => true], + 'LESS_THAN' => ['operator' => Operator::LESS_THAN, 'multiValued' => false], + 'NOT_EQUAL' => ['operator' => Operator::NOT_EQUAL, 'multiValued' => false], + 'GREATER_THAN' => ['operator' => Operator::GREATER_THAN, 'multiValued' => false], + 'LESS_THAN_OR_EQUAL' => ['operator' => Operator::LESS_THAN_OR_EQUAL, 'multiValued' => false], + 'GREATER_THAN_OR_EQUAL' => ['operator' => Operator::GREATER_THAN_OR_EQUAL, 'multiValued' => false] + ]; + } +} diff --git a/tests/Unit/OrderTest.php b/tests/Unit/OrderTest.php new file mode 100644 index 0000000..2cfb7fd --- /dev/null +++ b/tests/Unit/OrderTest.php @@ -0,0 +1,36 @@ +toExpression(); + + /** @Then it renders the field without a leading minus */ + self::assertSame('name', $expression); + } + + public function testToExpressionWhenDescendingThenRendersTheFieldWithALeadingMinus(): void + { + /** @Given an order sorting a field in descending direction */ + $order = Order::from(field: 'created_at', direction: Direction::DESCENDING); + + /** @When rendering it as a sort token */ + $expression = $order->toExpression(); + + /** @Then it renders the field with a leading minus */ + self::assertSame('-created_at', $expression); + } +} diff --git a/tests/Unit/PageTest.php b/tests/Unit/PageTest.php new file mode 100644 index 0000000..de0122c --- /dev/null +++ b/tests/Unit/PageTest.php @@ -0,0 +1,276 @@ +totalPages()); + + /** @And the page reports no next page */ + self::assertFalse($page->hasNext()); + + /** @And the first pagination is null */ + self::assertNull($page->first()); + + /** @And the last pagination is null */ + self::assertNull($page->last()); + + /** @And the metadata carries a zero total and zero total pages */ + self::assertSame([ + 'total' => 0, + 'has_next' => false, + 'per_page' => 20, + 'total_pages' => 0, + 'current_page' => 1, + 'has_previous' => false + ], $page->metadata()); + } + + public function testNavigationWhenLastPageGivenThenHasNoNextPage(): void + { + /** @Given a pagination on the last page */ + $pagination = Pagination::fromPage(page: 24, perPage: 20); + + /** @When building the page from the total element count */ + $page = Page::from(items: Collection::createFrom(elements: ['a', 'b']), total: 480, pagination: $pagination); + + /** @Then the page reports no next page */ + self::assertFalse($page->hasNext()); + + /** @And the page is the last page */ + self::assertTrue($page->isLast()); + + /** @And the page has a previous page */ + self::assertTrue($page->hasPrevious()); + + /** @And the next pagination is null */ + self::assertNull($page->next()); + + /** @And the last pagination points at the last page */ + self::assertSame(24, $page->last()?->page()); + } + + public function testItemsWhenPageGivenThenReturnsTheSameCollection(): void + { + /** @Given a collection of items */ + $items = Collection::createFrom(elements: ['a', 'b']); + + /** @And a pagination on the third page */ + $pagination = Pagination::fromPage(page: 3, perPage: 20); + + /** @When building the page and reading its items */ + $page = Page::from(items: $items, total: 480, pagination: $pagination); + + /** @Then the items are the same collection that was provided */ + self::assertSame($items, $page->items()); + } + + public function testTotalWhenPageGivenThenReturnsTheTotalElementCount(): void + { + /** @Given a collection of items */ + $items = Collection::createFrom(elements: ['a', 'b']); + + /** @And a pagination on the first page */ + $pagination = Pagination::fromPage(page: 1, perPage: 20); + + /** @When building the page from the total element count */ + $page = Page::from(items: $items, total: 480, pagination: $pagination); + + /** @Then the total is the count provided across every page */ + self::assertSame(480, $page->total()); + } + + public function testFromWhenTotalIsNegativeThenThrowsTotalIsNegative(): void + { + /** @Given an empty collection of items */ + $items = Collection::createFromEmpty(); + + /** @And a pagination on the first page */ + $pagination = Pagination::fromPage(page: 1, perPage: 20); + + /** @Then an exception indicating the total is negative is raised */ + $this->expectException(TotalIsNegative::class); + $this->expectExceptionMessage('Total'); + + /** @When building a page from a negative total */ + Page::from(items: $items, total: -1, pagination: $pagination); + } + + public function testNavigationWhenFirstPageGivenThenHasNoPreviousPage(): void + { + /** @Given a pagination on the first page */ + $pagination = Pagination::fromPage(page: 1, perPage: 20); + + /** @When building the page from the total element count */ + $page = Page::from(items: Collection::createFrom(elements: ['a', 'b']), total: 480, pagination: $pagination); + + /** @Then the page reports no previous page */ + self::assertFalse($page->hasPrevious()); + + /** @And the page is the first page */ + self::assertTrue($page->isFirst()); + + /** @And the page has a next page */ + self::assertTrue($page->hasNext()); + + /** @And the previous pagination is null */ + self::assertNull($page->previous()); + + /** @And the first pagination points at the first page */ + self::assertSame(1, $page->first()?->page()); + + /** @And the next pagination points at the second page */ + self::assertSame(2, $page->next()?->page()); + + /** @And the last pagination points at the last page */ + self::assertSame(24, $page->last()?->page()); + } + + public function testTotalPagesWhenTotalIsNotAMultipleOfPerPageThenRoundsUp(): void + { + /** @Given a pagination on the first page */ + $pagination = Pagination::fromPage(page: 1, perPage: 20); + + /** @When building the page from a total that is not a multiple of the page size */ + $page = Page::from(items: Collection::createFrom(elements: ['a', 'b']), total: 21, pagination: $pagination); + + /** @Then the total number of pages rounds the division up */ + self::assertSame(2, $page->totalPages()); + } + + public function testMetadataWhenMiddlePageGivenThenCarriesEveryFlagAndCount(): void + { + /** @Given a pagination on a middle page */ + $pagination = Pagination::fromPage(page: 3, perPage: 20); + + /** @When building the page from the total element count */ + $page = Page::from(items: Collection::createFrom(elements: ['a', 'b']), total: 480, pagination: $pagination); + + /** @Then the metadata carries every navigation flag and count in length-ascending key order */ + self::assertSame([ + 'total' => 480, + 'has_next' => true, + 'per_page' => 20, + 'total_pages' => 24, + 'current_page' => 3, + 'has_previous' => true + ], $page->metadata()); + } + + public function testNavigationWhenFirstPageGivenThenOmitsThePreviousRelation(): void + { + /** @Given a page on the first page of a multi-page result */ + $page = Page::from( + items: Collection::createFromEmpty(), + total: 480, + pagination: Pagination::fromPage(page: 1, perPage: 20) + ); + + /** @When reading the relations of the navigation targets */ + $relations = $page->navigation()->targets() + ->map(transformations: static fn(NavigationTarget $target): string => $target->relation()->value) + ->toArray(keyPreservation: KeyPreservation::DISCARD); + + /** @Then it lists the first, next, and last relations while omitting the previous relation */ + self::assertSame(['first', 'next', 'last'], $relations); + } + + public function testNavigationWhenMiddlePageGivenThenExposesEverySurroundingPage(): void + { + /** @Given a pagination on a middle page */ + $pagination = Pagination::fromPage(page: 3, perPage: 20); + + /** @When building the page from the total element count */ + $page = Page::from(items: Collection::createFrom(elements: ['a', 'b']), total: 480, pagination: $pagination); + + /** @Then the current page number is preserved */ + self::assertSame(3, $page->currentPage()); + + /** @And the total number of pages is derived from the total and the page size */ + self::assertSame(24, $page->totalPages()); + + /** @And the offset is derived from the page and the page size */ + self::assertSame(40, $page->offset()); + + /** @And the page has a next page */ + self::assertTrue($page->hasNext()); + + /** @And the page has a previous page */ + self::assertTrue($page->hasPrevious()); + + /** @And the page is not the first page */ + self::assertFalse($page->isFirst()); + + /** @And the page is not the last page */ + self::assertFalse($page->isLast()); + + /** @And the next pagination points at the fourth page */ + self::assertSame(4, $page->next()?->page()); + + /** @And the previous pagination points at the second page */ + self::assertSame(2, $page->previous()?->page()); + + /** @And the first pagination points at the first page */ + self::assertSame(1, $page->first()?->page()); + + /** @And the last pagination points at the last page */ + self::assertSame(24, $page->last()?->page()); + } + + public function testNavigationWhenMiddlePageGivenThenListsFirstPreviousNextAndLastTargets(): void + { + /** @Given a page on a middle page of a multi-page result */ + $page = Page::from( + items: Collection::createFromEmpty(), + total: 480, + pagination: Pagination::fromPage(page: 3, perPage: 20) + ); + + /** @When reading the relations of the navigation targets */ + $relations = $page->navigation()->targets() + ->map(transformations: static fn(NavigationTarget $target): string => $target->relation()->value) + ->toArray(keyPreservation: KeyPreservation::DISCARD); + + /** @Then it lists the first, previous, next, and last relations in semantic order */ + self::assertSame(['first', 'prev', 'next', 'last'], $relations); + } + + public function testNavigationWhenMiddlePageGivenThenTheNextTargetPointsAtTheFollowingPage(): void + { + /** @Given a page on a middle page of a multi-page result */ + $page = Page::from( + items: Collection::createFromEmpty(), + total: 480, + pagination: Pagination::fromPage(page: 3, perPage: 20) + ); + + /** @When reading the first navigation target */ + $target = $page->navigation()->targets()->first(); + + /** @Then the first target is the first page reached through the first relation */ + self::assertEquals( + NavigationTarget::to(target: Pagination::fromPage(page: 1, perPage: 20), relation: LinkRelation::FIRST), + $target + ); + } +} diff --git a/tests/Unit/PaginationTest.php b/tests/Unit/PaginationTest.php new file mode 100644 index 0000000..db4fa77 --- /dev/null +++ b/tests/Unit/PaginationTest.php @@ -0,0 +1,160 @@ +limit()); + } + + public function testFromPageWhenPerPageIsOneThenLimitIsOne(): void + { + /** @When building a pagination from the minimum page size */ + $pagination = Pagination::fromPage(page: 1, perPage: 1); + + /** @Then the limit equals the minimum page size */ + self::assertSame(1, $pagination->limit()); + } + + public function testFromOffsetWhenZeroOffsetGivenThenPageIsOne(): void + { + /** @When building a pagination from a zero offset */ + $pagination = Pagination::fromOffset(offset: 0, limit: 20); + + /** @Then the page number is one */ + self::assertSame(1, $pagination->page()); + + /** @And the offset is zero */ + self::assertSame(0, $pagination->offset()); + + /** @And the limit is preserved */ + self::assertSame(20, $pagination->limit()); + } + + public function testFromPageWhenFirstPageGivenThenOffsetIsZero(): void + { + /** @When building a pagination from the first page */ + $pagination = Pagination::fromPage(page: 1, perPage: 20); + + /** @Then the page number is one */ + self::assertSame(1, $pagination->page()); + + /** @And the offset is zero */ + self::assertSame(0, $pagination->offset()); + + /** @And the limit equals the page size */ + self::assertSame(20, $pagination->limit()); + } + + public function testFromPageWhenThirdPageGivenThenOffsetIsDerived(): void + { + /** @When building a pagination from the third page */ + $pagination = Pagination::fromPage(page: 3, perPage: 20); + + /** @Then the page number is three */ + self::assertSame(3, $pagination->page()); + + /** @And the offset is derived from the page and the page size */ + self::assertSame(40, $pagination->offset()); + + /** @And the limit equals the page size */ + self::assertSame(20, $pagination->limit()); + } + + public function testFromOffsetWhenAlignedOffsetGivenThenPageIsDerived(): void + { + /** @When building a pagination from an offset aligned to the limit */ + $pagination = Pagination::fromOffset(offset: 40, limit: 20); + + /** @Then the page number is derived from the offset and the limit */ + self::assertSame(3, $pagination->page()); + + /** @And the offset is preserved */ + self::assertSame(40, $pagination->offset()); + + /** @And the limit is preserved */ + self::assertSame(20, $pagination->limit()); + } + + public function testFromOffsetWhenUnalignedOffsetGivenThenPageIsFloored(): void + { + /** @When building a pagination from an offset that is not aligned to the limit */ + $pagination = Pagination::fromOffset(offset: 45, limit: 20); + + /** @Then the page number floors the offset division and adds one */ + self::assertSame(3, $pagination->page()); + + /** @And the offset is preserved */ + self::assertSame(45, $pagination->offset()); + + /** @And the limit is preserved */ + self::assertSame(20, $pagination->limit()); + } + + public function testToQueryStringWhenPageGivenThenRendersPageAndPerPage(): void + { + /** @Given an offset pagination on the third page */ + $pagination = Pagination::fromPage(page: 3, perPage: 20); + + /** @When rendering it as a query string against the default schema */ + $queryString = $pagination->toQueryString(schema: Schema::default()); + + /** @Then it renders the page number and the page size */ + self::assertSame('page=3&per_page=20', $queryString); + } + + public function testFromPageWhenPageBelowOneGivenThenPageNumberOutOfRange(): void + { + /** @Then an exception indicating the page number is out of range is raised */ + $this->expectException(PageNumberOutOfRange::class); + $this->expectExceptionMessage('Page number'); + + /** @When building a pagination from a page number below one */ + Pagination::fromPage(page: 0, perPage: 20); + } + + public function testFromOffsetWhenLimitBelowOneGivenThenPageSizeOutOfRange(): void + { + /** @Then an exception indicating the page size is out of range is raised */ + $this->expectException(PageSizeOutOfRange::class); + $this->expectExceptionMessage('Page size'); + + /** @When building a pagination from a limit below one */ + Pagination::fromOffset(offset: 0, limit: 0); + } + + public function testFromOffsetWhenOffsetBelowZeroGivenThenOffsetOutOfRange(): void + { + /** @Then an exception indicating the offset is out of range is raised */ + $this->expectException(OffsetOutOfRange::class); + $this->expectExceptionMessage('Offset'); + + /** @When building a pagination from an offset below zero */ + Pagination::fromOffset(offset: -1, limit: 20); + } + + public function testFromPageWhenPerPageBelowOneGivenThenPageSizeOutOfRange(): void + { + /** @Then an exception indicating the page size is out of range is raised */ + $this->expectException(PageSizeOutOfRange::class); + $this->expectExceptionMessage('Page size'); + + /** @When building a pagination from a page size below one */ + Pagination::fromPage(page: 1, perPage: 0); + } +} diff --git a/tests/Unit/SchemaTest.php b/tests/Unit/SchemaTest.php new file mode 100644 index 0000000..d41a554 --- /dev/null +++ b/tests/Unit/SchemaTest.php @@ -0,0 +1,292 @@ +pageKey(); + + /** @Then it is the canonical page key */ + self::assertSame('page', $actual); + } + + public function testDefaultThenCarriesTheCanonicalSortKey(): void + { + /** @Given the default schema */ + $schema = Schema::default(); + + /** @When reading the sort key */ + $actual = $schema->sortKey(); + + /** @Then it is the canonical sort key */ + self::assertSame('sort', $actual); + } + + public function testDefaultThenCarriesTheCanonicalCursorKey(): void + { + /** @Given the default schema */ + $schema = Schema::default(); + + /** @When reading the cursor key */ + $actual = $schema->cursorKey(); + + /** @Then it is the canonical cursor key */ + self::assertSame('cursor', $actual); + } + + public function testDefaultThenCarriesTheCanonicalFilterKey(): void + { + /** @Given the default schema */ + $schema = Schema::default(); + + /** @When reading the filter key */ + $actual = $schema->filterKey(); + + /** @Then it is the canonical filter key */ + self::assertSame('filter', $actual); + } + + public function testDefaultThenCarriesTheCanonicalMaxPerPage(): void + { + /** @Given the default schema */ + $schema = Schema::default(); + + /** @When reading the maximum page size */ + $actual = $schema->maxPerPage(); + + /** @Then it is the canonical maximum page size */ + self::assertSame(100, $actual); + } + + public function testDefaultThenCarriesTheCanonicalPerPageKey(): void + { + /** @Given the default schema */ + $schema = Schema::default(); + + /** @When reading the per-page key */ + $actual = $schema->perPageKey(); + + /** @Then it is the canonical per-page key */ + self::assertSame('per_page', $actual); + } + + public function testDefaultThenCarriesTheCanonicalDefaultPerPage(): void + { + /** @Given the default schema */ + $schema = Schema::default(); + + /** @When reading the default page size */ + $actual = $schema->defaultPerPage(); + + /** @Then it is the canonical default page size */ + self::assertSame(20, $actual); + } + + public function testWithBoundsWhenBothAtMinimumThenSchemaCarriesThem(): void + { + /** @Given a schema with the default and maximum page sizes lowered to the minimum */ + $schema = Schema::default()->withDefaultPerPage(defaultPerPage: 1)->withMaxPerPage(maxPerPage: 1); + + /** @When reading the maximum page size */ + $actual = $schema->maxPerPage(); + + /** @Then it is the minimum page size */ + self::assertSame(1, $actual); + + /** @And the default page size is the minimum too */ + self::assertSame(1, $schema->defaultPerPage()); + } + + public function testPageSizeForWhenAtMaximumThenReturnsTheMaximumSize(): void + { + /** @Given the default schema */ + $schema = Schema::default(); + + /** @When asking for a page size equal to the maximum */ + $actual = $schema->pageSizeFor(requested: 100); + + /** @Then it returns the maximum page size */ + self::assertSame(100, $actual); + } + + public function testPageSizeForWhenAboveMaximumThenThrowsPageSizeOutOfRange(): void + { + /** @Given the default schema */ + $schema = Schema::default(); + + /** @Then an exception indicating the page size is out of range is raised */ + $this->expectException(PageSizeOutOfRange::class); + $this->expectExceptionMessage('Page size'); + + /** @When asking for a page size above the maximum */ + $schema->pageSizeFor(requested: 101); + } + + public function testPageSizeForWhenWithinMaximumThenReturnsTheRequestedSize(): void + { + /** @Given the default schema */ + $schema = Schema::default(); + + /** @When asking for a page size within the maximum */ + $actual = $schema->pageSizeFor(requested: 50); + + /** @Then it returns the requested page size */ + self::assertSame(50, $actual); + } + + public function testWithMaxPerPageWhenBelowMinimumThenThrowsPageSizeOutOfRange(): void + { + /** @Given the default schema */ + $schema = Schema::default(); + + /** @Then an exception indicating the page size is out of range is raised */ + $this->expectException(PageSizeOutOfRange::class); + $this->expectExceptionMessage('Page size <0> must be greater than or equal to 1.'); + + /** @When lowering the maximum page size below the minimum */ + $schema->withMaxPerPage(maxPerPage: 0); + } + + public function testWithDefaultPerPageWhenAboveMaximumThenThrowsPageSizeOutOfRange(): void + { + /** @Given the default schema */ + $schema = Schema::default(); + + /** @Then an exception indicating the page size is out of range is raised */ + $this->expectException(PageSizeOutOfRange::class); + $this->expectExceptionMessage('Page size <150> must be less than or equal to 100.'); + + /** @When raising the default page size above the maximum */ + $schema->withDefaultPerPage(defaultPerPage: 150); + } + + public function testWithDefaultPerPageWhenBelowMinimumThenThrowsPageSizeOutOfRange(): void + { + /** @Given the default schema */ + $schema = Schema::default(); + + /** @Then an exception indicating the page size is out of range is raised */ + $this->expectException(PageSizeOutOfRange::class); + $this->expectExceptionMessage('Page size <0> must be greater than or equal to 1.'); + + /** @When lowering the default page size below the minimum */ + $schema->withDefaultPerPage(defaultPerPage: 0); + } + + public function testWithPageKeyWhenReplacedThenCopyCarriesItAndOriginalIsUnchanged(): void + { + /** @Given the default schema */ + $schema = Schema::default(); + + /** @When replacing the page key */ + $copy = $schema->withPageKey(pageKey: 'p'); + + /** @Then the copy carries the new page key */ + self::assertSame('p', $copy->pageKey()); + + /** @And the original schema keeps the canonical page key */ + self::assertSame('page', $schema->pageKey()); + } + + public function testWithSortKeyWhenReplacedThenCopyCarriesItAndOriginalIsUnchanged(): void + { + /** @Given the default schema */ + $schema = Schema::default(); + + /** @When replacing the sort key */ + $copy = $schema->withSortKey(sortKey: 'order'); + + /** @Then the copy carries the new sort key */ + self::assertSame('order', $copy->sortKey()); + + /** @And the original schema keeps the canonical sort key */ + self::assertSame('sort', $schema->sortKey()); + } + + public function testWithCursorKeyWhenReplacedThenCopyCarriesItAndOriginalIsUnchanged(): void + { + /** @Given the default schema */ + $schema = Schema::default(); + + /** @When replacing the cursor key */ + $copy = $schema->withCursorKey(cursorKey: 'after'); + + /** @Then the copy carries the new cursor key */ + self::assertSame('after', $copy->cursorKey()); + + /** @And the original schema keeps the canonical cursor key */ + self::assertSame('cursor', $schema->cursorKey()); + } + + public function testWithFilterKeyWhenReplacedThenCopyCarriesItAndOriginalIsUnchanged(): void + { + /** @Given the default schema */ + $schema = Schema::default(); + + /** @When replacing the filter key */ + $copy = $schema->withFilterKey(filterKey: 'q'); + + /** @Then the copy carries the new filter key */ + self::assertSame('q', $copy->filterKey()); + + /** @And the original schema keeps the canonical filter key */ + self::assertSame('filter', $schema->filterKey()); + } + + public function testWithMaxPerPageWhenReplacedThenCopyCarriesItAndOriginalIsUnchanged(): void + { + /** @Given the default schema */ + $schema = Schema::default(); + + /** @When replacing the maximum page size */ + $copy = $schema->withMaxPerPage(maxPerPage: 250); + + /** @Then the copy carries the new maximum page size */ + self::assertSame(250, $copy->maxPerPage()); + + /** @And the original schema keeps the canonical maximum page size */ + self::assertSame(100, $schema->maxPerPage()); + } + + public function testWithPerPageKeyWhenReplacedThenCopyCarriesItAndOriginalIsUnchanged(): void + { + /** @Given the default schema */ + $schema = Schema::default(); + + /** @When replacing the per-page key */ + $copy = $schema->withPerPageKey(perPageKey: 'size'); + + /** @Then the copy carries the new per-page key */ + self::assertSame('size', $copy->perPageKey()); + + /** @And the original schema keeps the canonical per-page key */ + self::assertSame('per_page', $schema->perPageKey()); + } + + public function testWithDefaultPerPageWhenReplacedThenCopyCarriesItAndOriginalIsUnchanged(): void + { + /** @Given the default schema */ + $schema = Schema::default(); + + /** @When replacing the default page size */ + $copy = $schema->withDefaultPerPage(defaultPerPage: 50); + + /** @Then the copy carries the new default page size */ + self::assertSame(50, $copy->defaultPerPage()); + + /** @And the original schema keeps the canonical default page size */ + self::assertSame(20, $schema->defaultPerPage()); + } +} diff --git a/tests/Unit/SliceTest.php b/tests/Unit/SliceTest.php new file mode 100644 index 0000000..32ca8db --- /dev/null +++ b/tests/Unit/SliceTest.php @@ -0,0 +1,148 @@ +hasNext()); + + /** @And the items are trimmed to the page size */ + self::assertSame(['a', 'b', 'c'], $slice->items()->toArray(keyPreservation: KeyPreservation::DISCARD)); + + /** @And the current page number is preserved */ + self::assertSame(2, $slice->currentPage()); + + /** @And the slice has a previous page */ + self::assertTrue($slice->hasPrevious()); + + /** @And the next pagination points at the third page */ + self::assertSame(3, $slice->next()?->page()); + + /** @And the previous pagination points at the first page */ + self::assertSame(1, $slice->previous()?->page()); + + /** @And the metadata carries every navigation flag and count in length-ascending key order */ + self::assertSame([ + 'has_next' => true, + 'per_page' => 3, + 'current_page' => 2, + 'has_previous' => true + ], $slice->metadata()); + } + + public function testOffsetWhenSecondPageGivenThenReturnsTheZeroBasedOffset(): void + { + /** @Given a pagination on the second page with a page size of three */ + $pagination = Pagination::fromPage(page: 2, perPage: 3); + + /** @And items fetched for the page size plus one */ + $items = Collection::createFrom(elements: ['a', 'b', 'c', 'd']); + + /** @When building the slice from the items and the pagination */ + $slice = Slice::from(items: $items, pagination: $pagination); + + /** @Then the offset is derived from the page and the page size */ + self::assertSame(3, $slice->offset()); + } + + public function testNavigationWhenFirstPageWithoutExtraElementThenListsNoRelation(): void + { + /** @Given a slice on the first page fetched within the page size */ + $slice = Slice::from( + items: Collection::createFrom(elements: ['a', 'b', 'c']), + pagination: Pagination::fromPage(page: 1, perPage: 3) + ); + + /** @When reading the relations of the navigation targets */ + $relations = $slice->navigation()->targets() + ->map(transformations: static fn(NavigationTarget $target): string => $target->relation()->value) + ->toArray(keyPreservation: KeyPreservation::DISCARD); + + /** @Then it lists no relation */ + self::assertSame([], $relations); + } + + public function testNavigationWhenMiddlePageGivenThenListsPreviousAndNextRelations(): void + { + /** @Given a slice on a middle page fetched for the page size plus one */ + $slice = Slice::from( + items: Collection::createFrom(elements: ['a', 'b', 'c', 'd']), + pagination: Pagination::fromPage(page: 2, perPage: 3) + ); + + /** @When reading the relations of the navigation targets */ + $relations = $slice->navigation()->targets() + ->map(transformations: static fn(NavigationTarget $target): string => $target->relation()->value) + ->toArray(keyPreservation: KeyPreservation::DISCARD); + + /** @Then it lists the previous and next relations in that order */ + self::assertSame(['prev', 'next'], $relations); + } + + public function testNavigationWhenNoExtraElementOnFirstPageThenNoNextAndNoPrevious(): void + { + /** @Given a pagination on the first page with a page size of three */ + $pagination = Pagination::fromPage(page: 1, perPage: 3); + + /** @And items fetched within the page size */ + $items = Collection::createFrom(elements: ['a', 'b', 'c']); + + /** @When building the slice from the items and the pagination */ + $slice = Slice::from(items: $items, pagination: $pagination); + + /** @Then the slice reports no next page */ + self::assertFalse($slice->hasNext()); + + /** @And the items keep every fetched element */ + self::assertSame(['a', 'b', 'c'], $slice->items()->toArray(keyPreservation: KeyPreservation::DISCARD)); + + /** @And the next pagination is null */ + self::assertNull($slice->next()); + + /** @And the slice has no previous page */ + self::assertFalse($slice->hasPrevious()); + + /** @And the previous pagination is null */ + self::assertNull($slice->previous()); + } + + public function testNavigationWhenMiddlePageGivenThenTheNextTargetPointsAtTheFollowingPage(): void + { + /** @Given a slice on a middle page fetched for the page size plus one */ + $slice = Slice::from( + items: Collection::createFrom(elements: ['a', 'b', 'c', 'd']), + pagination: Pagination::fromPage(page: 2, perPage: 3) + ); + + /** @When reading the last navigation target */ + $target = $slice->navigation()->targets()->last(); + + /** @Then the last target is the third page reached through the next relation */ + self::assertEquals( + NavigationTarget::to(target: Pagination::fromPage(page: 3, perPage: 3), relation: LinkRelation::NEXT), + $target + ); + } +} diff --git a/tests/Unit/SortTest.php b/tests/Unit/SortTest.php new file mode 100644 index 0000000..de79520 --- /dev/null +++ b/tests/Unit/SortTest.php @@ -0,0 +1,126 @@ +isEmpty()); + + /** @And the orders are an empty list */ + self::assertSame([], $sort->orders()); + } + + public function testFromExpressionWhenWhitespaceOnlyThenIsEmpty(): void + { + /** @Given a whitespace-only sort expression */ + $expression = ' '; + + /** @When parsing the sort expression */ + $sort = Sort::fromExpression(expression: $expression); + + /** @Then the sort carries no order */ + self::assertTrue($sort->isEmpty()); + + /** @And the orders are an empty list */ + self::assertSame([], $sort->orders()); + } + + public function testFromExpressionWhenSingleFieldThenSingleAscendingOrder(): void + { + /** @Given a single ascending field */ + $expression = 'name'; + + /** @When parsing the sort expression */ + $sort = Sort::fromExpression(expression: $expression); + + /** @Then the sort is not empty */ + self::assertFalse($sort->isEmpty()); + + /** @And the orders carry exactly one order */ + self::assertCount(1, $sort->orders()); + + /** @And the single order sorts by the given field */ + self::assertSame('name', $sort->orders()[0]->field()); + + /** @And the single order applies ascending direction */ + self::assertSame(Direction::ASCENDING, $sort->orders()[0]->direction()); + } + + #[DataProvider('invalidExpressionsProvider')] + public function testFromExpressionWhenMalformedThenThrowsSortExpressionIsInvalid(string $expression): void + { + /** @Given a malformed sort expression */ + + /** @Then an exception indicating the sort expression is invalid is raised */ + $this->expectException(SortExpressionIsInvalid::class); + $this->expectExceptionMessage('Sort expression'); + + /** @When parsing the sort expression */ + Sort::fromExpression(expression: $expression); + } + + public function testToExpressionWhenDescendingAndAscendingFieldsThenRendersTheSortExpression(): void + { + /** @Given a sort parsed from a descending field followed by an ascending field */ + $sort = Sort::fromExpression(expression: '-created_at,id'); + + /** @When rendering it back to a sort expression */ + $expression = $sort->toExpression(); + + /** @Then the descending field carries a leading minus and the ascending field does not */ + self::assertSame('-created_at,id', $expression); + } + + public function testFromExpressionWhenLeadingMinusAndPlainFieldThenPreservesOrderAndDirection(): void + { + /** @Given a descending field followed by an ascending field */ + $expression = '-created_at,id'; + + /** @When parsing the sort expression */ + $sort = Sort::fromExpression(expression: $expression); + + /** @Then the sort is not empty */ + self::assertFalse($sort->isEmpty()); + + /** @And the orders carry exactly two orders */ + self::assertCount(2, $sort->orders()); + + /** @And the first order sorts by the descending field */ + self::assertSame('created_at', $sort->orders()[0]->field()); + + /** @And the first order applies descending direction */ + self::assertSame(Direction::DESCENDING, $sort->orders()[0]->direction()); + + /** @And the second order sorts by the ascending field */ + self::assertSame('id', $sort->orders()[1]->field()); + + /** @And the second order applies ascending direction */ + self::assertSame(Direction::ASCENDING, $sort->orders()[1]->direction()); + } + + public static function invalidExpressionsProvider(): array + { + return [ + 'Trailing comma' => ['expression' => 'id,'], + 'Just minus sign' => ['expression' => '-'], + 'Field with space' => ['expression' => 'a b'] + ]; + } +} From b66de942cda0b51c6805e024dd57faa2b31d6fef Mon Sep 17 00:00:00 2001 From: Gustavo Freze Date: Mon, 8 Jun 2026 13:48:07 -0300 Subject: [PATCH 02/14] feat: Build result pages in Criteria and keep the pagination style internal. Pagination is now an interface implemented by OffsetPagination and the keyset CursorPagination, so a Criteria carries either without the consumer branching on a concrete type. The Criteria builds the result page itself through offsetPage, offsetSlice, and cursorPage, which replace the free-standing Page and Slice. Criteria::fromQuery reads a PSR-7 request and the page parameters follow the JSON:API page family, so Schema drops its configurable key names and keeps only the page-size bounds. --- README.md | 189 +++++++------ src/Criteria.php | 99 +++++-- src/CursorPage.php | 125 +++++---- src/CursorPagination.php | 25 +- src/Internal/Keyset.php | 71 +++++ src/Internal/Limit.php | 28 ++ src/Internal/Offset.php | 33 +++ src/Internal/OffsetNavigator.php | 58 ++++ src/Internal/PageCount.php | 32 +++ src/Internal/PageNumber.php | 48 ++++ src/Internal/PageParameters.php | 52 ++++ src/Internal/PaginationResolver.php | 41 --- src/Internal/Total.php | 33 +++ src/Navigation.php | 4 +- src/NavigationTarget.php | 10 +- src/OffsetPage.php | 252 ++++++++++++++++++ src/OffsetPagination.php | 87 ++++++ src/OffsetSlice.php | 195 ++++++++++++++ src/Page.php | 203 -------------- src/Pagination.php | 145 +--------- src/Paging.php | 29 -- src/Schema.php | 195 +------------- src/Slice.php | 141 ---------- tests/Models/Query.php | 6 +- tests/Unit/CriteriaTest.php | 157 +++++++---- tests/Unit/CursorPageTest.php | 95 +++++-- tests/Unit/CursorPaginationTest.php | 21 +- tests/Unit/EndToEndTest.php | 148 ++++++++-- tests/Unit/FilterTest.php | 24 +- tests/Unit/LinksTest.php | 123 +++++---- .../Unit/{PageTest.php => OffsetPageTest.php} | 170 +++++++----- ...ationTest.php => OffsetPaginationTest.php} | 39 ++- tests/Unit/OffsetSliceTest.php | 231 ++++++++++++++++ tests/Unit/SchemaTest.php | 135 ---------- tests/Unit/SliceTest.php | 148 ---------- 35 files changed, 1924 insertions(+), 1468 deletions(-) create mode 100644 src/Internal/Keyset.php create mode 100644 src/Internal/Limit.php create mode 100644 src/Internal/Offset.php create mode 100644 src/Internal/OffsetNavigator.php create mode 100644 src/Internal/PageCount.php create mode 100644 src/Internal/PageNumber.php create mode 100644 src/Internal/PageParameters.php delete mode 100644 src/Internal/PaginationResolver.php create mode 100644 src/Internal/Total.php create mode 100644 src/OffsetPage.php create mode 100644 src/OffsetPagination.php create mode 100644 src/OffsetSlice.php delete mode 100644 src/Page.php delete mode 100644 src/Paging.php delete mode 100644 src/Slice.php rename tests/Unit/{PageTest.php => OffsetPageTest.php} (58%) rename tests/Unit/{PaginationTest.php => OffsetPaginationTest.php} (79%) create mode 100644 tests/Unit/OffsetSliceTest.php delete mode 100644 tests/Unit/SliceTest.php diff --git a/README.md b/README.md index 6b78b2e..2c279ba 100644 --- a/README.md +++ b/README.md @@ -19,17 +19,18 @@ A typed, framework- and database-agnostic toolkit for the query of an HTTP collection endpoint. It parses an incoming request query string into typed specifications for filtering (RSQL), sorting, and pagination (offset and cursor), and it -renders the result navigation as an RFC 8288 `Link` header and as a JSON:API-style body `links` object. +renders the result as a JSON:API response carrying an RFC 8288 `Link` header and a body `links` object. The library never touches a data store. It turns the query string into value objects the consumer applies to its own -store, and it renders the navigation the consumer attaches to the response. Every computation is O(1) value-object math -over the inputs the consumer supplies. +store, and it renders the response the consumer returns. Every computation is O(1) value-object math over the inputs the +consumer supplies. The pagination style stays internal: the `Criteria` builds the result page, so the public API never +exposes a concrete pagination type. -It builds on the [tiny-blocks](https://github.com/tiny-blocks) ecosystem: it reads a `QueryParameters` from -[`tiny-blocks/http`](https://github.com/tiny-blocks/http), carries items in a +It builds on the [tiny-blocks](https://github.com/tiny-blocks) ecosystem: it reads the query parameters of a PSR-7 +request through [`tiny-blocks/http`](https://github.com/tiny-blocks/http), carries items in a [`tiny-blocks/collection`](https://github.com/tiny-blocks/collection) `Collection`, encodes cursors through -[`tiny-blocks/encoder`](https://github.com/tiny-blocks/encoder), and renders the `Link` header with the `Link` and -`LinkRelation` types from `tiny-blocks/http`. +[`tiny-blocks/encoder`](https://github.com/tiny-blocks/encoder), and renders the response and its `Link` header with the +`Response`, `Link`, and `LinkRelation` types from `tiny-blocks/http`. ## Installation @@ -39,8 +40,9 @@ composer require tiny-blocks/http-query ## How to use -The entry point is `Criteria::fromQuery`, which reads the request query parameters and produces a `Criteria` carrying -the filter, the sort, and the pagination. +The entry point is `Criteria::fromQuery`, which reads the request query parameters from a PSR-7 request and produces a +`Criteria` carrying the filter, the sort, and the pagination. The `Criteria` then builds the result page and renders it, +so the pagination style stays internal. ```php query()); +$criteria = Criteria::fromQuery(request: $request); ``` ### Filtering with RSQL @@ -110,7 +111,7 @@ use TinyBlocks\HttpQuery\Sort; $sort = Sort::fromExpression(expression: '-created_at,id'); foreach ($sort->orders() as $order) { - $order->field(); # 'created_at' then 'id' + $order->field(); # 'created_at' then 'id' $order->direction() === Direction::DESCENDING; # true then false } ``` @@ -119,83 +120,107 @@ A malformed expression raises `SortExpressionIsInvalid`. ### Offset pagination -When no cursor is present, `Criteria::pagination()` returns an offset-based `Pagination`. Its canonical state is an -offset and a limit, and the page-based factory derives the offset from the one-based page number. +When no cursor is present, `Criteria::offsetPage` builds an `OffsetPage` from the items of the current page and the total +element count. The page derives the offset and the total pages from the request, so the consumer never builds the +pagination itself. The items are any `iterable`, and `items()` returns them as a `Collection`. ```php offset(); # 40 -$pagination->limit(); # 20 +# GET /v1/orders?page[number]=3&page[size]=20 +/** @var ServerRequestInterface $request */ +$criteria = Criteria::fromQuery(request: $request); -/** @var Collection $items */ -$page = Page::from(items: $items, total: 480, pagination: $pagination); +/** @var iterable $items */ +$page = $criteria->offsetPage(items: $items, total: 480); $page->hasNext(); # true $page->totalPages(); # 24 $page->metadata(); # the JSON:API meta contents ``` -Use a `Slice` instead of a `Page` when the total is unknown. The consumer fetches one element beyond the page size, and -the `Slice` trims it and reads its presence as the next-page hint. +Use `Criteria::offsetSlice` instead of `Criteria::offsetPage` when the total is unknown. The consumer fetches one element +beyond the page size, and the `OffsetSlice` trims it and reads its presence as the next-page hint. ```php $items */ -$slice = Slice::from(items: $items, pagination: Pagination::fromPage(page: 2, perPage: 20)); +/** @var iterable $items */ +$slice = $criteria->offsetSlice(items: $items); $slice->hasNext(); # inferred from the extra fetched element ``` ### Cursor pagination -When the `cursor` parameter is present, `Criteria::pagination()` returns a keyset `CursorPagination`. A `Cursor` is an -opaque, URI-safe token wrapping the last-seen ordering key values, encoded through `tiny-blocks/encoder`. +When the `cursor` parameter is present, `Criteria::cursorPage` builds a keyset `CursorPage`. A `Cursor` is an opaque, +URI-safe token wrapping the last-seen ordering key values, encoded through `tiny-blocks/encoder`. The `keysOf` closure +extracts the ordering key values from an element, and the page derives the forward and backward cursors from them. ```php $items */ -$cursorPage = CursorPage::from( +/** @var iterable $items */ +$cursorPage = $criteria->cursorPage( items: $items, - keysOf: static fn(array $order): array => [$order['created_at'], $order['id']], - pagination: $pagination + keysOf: static fn(array $order): array => [$order['created_at'], $order['id']] ); -$cursorPage->hasNext(); # inferred from the extra fetched element -$cursorPage->nextCursor()->toString(); # the opaque token for the next page -$cursorPage->previousCursor()->toArray(); # the decoded key values for the previous page +$cursorPage->hasNext(); # Inferred from the extra fetched element +$cursorPage->next(); # The CursorPagination for the next page, or null +$cursorPage->previous(); # The CursorPagination for the previous page, or null ``` An invalid cursor token raises `CursorIsInvalid` when it is decoded. ### Rendering navigation links -`Links::from` reads the navigation a result exposes through `result->navigation()`, swaps the criteria's pagination for -each target, and serializes it back through `Criteria::toUri`, so the filter and the sort are preserved in every URI. -`toArray()` returns the JSON:API body `links` object and `toHeader()` returns an RFC 8288 `Link`. +`toResponse` renders a result as a JSON:API response in one call. It builds the body from the data, the meta, and the +navigation links, and folds the same relations into an RFC 8288 `Link` header. It returns a PSR-7 `ResponseInterface`. + +```php + $items */ +$response = $criteria->offsetPage(items: $items, total: 480)->toResponse(baseUri: '/v1/orders'); +``` + +For full control over the body, assemble it from the parts. `Links::from` reads the navigation a result exposes through +`result->navigation()`, swaps the criteria's pagination for each target, and serializes it back through `Criteria::toUri`, +so the filter and the sort are preserved in every URI. `toArray()` returns the JSON:API body `links` object and +`toHeader()` returns an RFC 8288 `Link`. ```php query()); +$criteria = Criteria::fromQuery(request: $request); -/** @var Collection $items */ -$page = Page::from(items: $items, total: 480, pagination: $criteria->pagination()); +/** @var iterable $items */ +$page = $criteria->offsetPage(items: $items, total: 480); $links = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $page->navigation()); $response = Response::ok([ @@ -239,11 +261,11 @@ The body carries the navigation with the filter and the sort preserved in every "has_previous": true }, "links": { - "self": "/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page=3&per_page=20", - "first": "/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page=1&per_page=20", - "prev": "/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page=2&per_page=20", - "next": "/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page=4&per_page=20", - "last": "/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page=24&per_page=20" + "self": "/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page[number]=3&page[size]=20", + "first": "/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page[number]=1&page[size]=20", + "prev": "/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page[number]=2&page[size]=20", + "next": "/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page[number]=4&page[size]=20", + "last": "/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page[number]=24&page[size]=20" } } ``` @@ -251,16 +273,16 @@ The body carries the navigation with the filter and the sort preserved in every The header folds the same relations into one RFC 8288 `Link` line. ```text -Link: ; rel="self", - ; rel="first", - ; rel="prev", - ; rel="next", - ; rel="last" +Link: ; rel="self", + ; rel="first", + ; rel="prev", + ; rel="next", + ; rel="last" ``` The `links` keys are the canonical JSON:API relations, in the semantic order below. Unavailable relations are omitted, -so the first page carries no `prev` and the last page carries no `next`. A `Slice` and a `CursorPage` expose only -`self`, `prev`, and `next`. +so the first page carries no `prev` and the last page carries no `next`. An `OffsetSlice` exposes `self`, `first`, +`prev`, and `next` (no `last`), and a `CursorPage` exposes only `self`, `prev`, and `next`. | Relation | Meaning | |----------|--------------------| @@ -272,34 +294,31 @@ so the first page carries no `prev` and the last page carries no `next`. A `Slic ### Configuring the schema -`Schema` maps the query parameter names and the page-size bounds. `Schema::default()` is applied when -`Criteria::fromQuery` receives no schema, and the fluent `with*` copies override any subset. +The query parameter names follow JSON:API and are fixed: `filter`, `sort`, and the `page` family (`page[number]`, +`page[size]`, `page[cursor]`). `Schema` carries only the page-size bounds. `Schema::default()` is applied when +`Criteria::fromQuery` receives no schema, and the fluent `with*` copies override either bound. -| Setting | Default | Meaning | -|------------------|------------|-------------------------------------------------| -| `filterKey` | `filter` | The query key carrying the RSQL filter. | -| `sortKey` | `sort` | The query key carrying the sort expression. | -| `pageKey` | `page` | The query key carrying the page number. | -| `perPageKey` | `per_page` | The query key carrying the page size. | -| `cursorKey` | `cursor` | The query key carrying the cursor token. | -| `defaultPerPage` | `20` | The page size applied when the query omits one. | -| `maxPerPage` | `100` | The maximum allowed page size. | +| Setting | Default | Meaning | +|------------------|---------|-------------------------------------------------| +| `defaultPerPage` | `20` | The page size applied when the query omits one. | +| `maxPerPage` | `100` | The maximum allowed page size. | ```php withFilterKey(filterKey: 'q') ->withMaxPerPage(maxPerPage: 200) - ->withPerPageKey(perPageKey: 'size'); + ->withDefaultPerPage(defaultPerPage: 50); -# GET /v1/orders?q=status==paid&size=50 -$criteria = Criteria::fromQuery(query: $query, schema: $schema); +# GET /v1/orders?filter=status==paid&page[size]=50 +/** @var ServerRequestInterface $request */ +$criteria = Criteria::fromQuery(request: $request, schema: $schema); ``` A page size above `maxPerPage` raises `PageSizeOutOfRange`. @@ -323,10 +342,10 @@ consumer walks, rather than a flat map of parameters that cannot express groupin ### 03. Why are both offset and cursor pagination supported? -Offset pagination answers "how many pages are there" and "jump to page N", which a `Page` with a total provides. Cursor -pagination answers "give me the next slice after this point" without a total, which scales to large collections and -avoids the drift of offset pagination under concurrent writes. The library models both, plus a `Slice` for offset -navigation without a total. +Offset pagination answers "how many pages are there" and "jump to page N", which an `OffsetPage` with a total provides. +Cursor pagination answers "give me the next slice after this point" without a total, which scales to large collections +and avoids the drift of offset pagination under concurrent writes. The library models both, plus an `OffsetSlice` for +offset navigation without a total. ### 04. How are the `meta` keys ordered? diff --git a/src/Criteria.php b/src/Criteria.php index fa2fd78..a94e816 100644 --- a/src/Criteria.php +++ b/src/Criteria.php @@ -4,40 +4,43 @@ namespace TinyBlocks\HttpQuery; +use Closure; +use Psr\Http\Message\ServerRequestInterface; use TinyBlocks\Http\Server\Decoded\QueryParameters; use TinyBlocks\HttpQuery\Exceptions\FilterExpressionIsInvalid; use TinyBlocks\HttpQuery\Exceptions\OffsetOutOfRange; use TinyBlocks\HttpQuery\Exceptions\PageNumberOutOfRange; use TinyBlocks\HttpQuery\Exceptions\PageSizeOutOfRange; use TinyBlocks\HttpQuery\Exceptions\SortExpressionIsInvalid; -use TinyBlocks\HttpQuery\Internal\PaginationResolver; +use TinyBlocks\HttpQuery\Exceptions\TotalIsNegative; +use TinyBlocks\HttpQuery\Internal\PageParameters; use TinyBlocks\HttpQuery\Internal\Rsql\FilterParser; /** * Umbrella specification of a collection query, pairing filtering, sorting, and pagination. * *

    It parses from the request query string and serializes back to a URI, so the navigation links - * built from it preserve the filter and the sort.

    + * built from it preserve the filter and the sort. It also builds the result page for the items the + * store returns, keeping the pagination style internal.

    */ final readonly class Criteria { private function __construct( + private PageParameters $page, private Sort $sort, private Filter $filter, - private Schema $schema, - private Paging $pagination + private Pagination $pagination ) { } /** - * Creates a Criteria from the request query parameters and an optional schema. + * Creates a Criteria from the request and an optional schema. * - *

    When the schema is omitted, the canonical default key names and bounds apply. The - * pagination is a {@see CursorPagination} when the cursor key is present, otherwise an - * offset-based {@see Pagination}.

    + *

    When the schema is omitted, the default page-size bounds apply. The pagination is a + * {@see CursorPagination} when the cursor is present, otherwise an {@see OffsetPagination}.

    * - * @param QueryParameters $query The decoded request query parameters. - * @param Schema|null $schema The schema mapping the query keys and bounds, or null for the default. + * @param ServerRequestInterface $request The incoming PSR-7 server request. + * @param Schema|null $schema The schema carrying the page-size bounds, or null for the default. * @return Criteria The criteria carrying the parsed filter, sort, and pagination. * @throws FilterExpressionIsInvalid If the filter expression cannot be parsed. * @throws SortExpressionIsInvalid If the sort expression cannot be parsed. @@ -45,16 +48,17 @@ private function __construct( * @throws PageSizeOutOfRange If the page size falls outside the valid range. * @throws OffsetOutOfRange If the offset is less than 0. */ - public static function fromQuery(QueryParameters $query, ?Schema $schema = null): Criteria + public static function fromQuery(ServerRequestInterface $request, ?Schema $schema = null): Criteria { $schema = $schema ?? Schema::default(); - $expression = $query->get(key: $schema->filterKey())->toString(); - $filter = $expression === '' ? Group::none() : FilterParser::from(input: $expression)->parse(); + $query = QueryParameters::from(request: $request); + $page = PageParameters::from(query: $query, schema: $schema); - $sort = Sort::fromExpression(expression: $query->get(key: $schema->sortKey())->toString()); - $pagination = PaginationResolver::from(query: $query, schema: $schema)->resolve(); + $expression = $query->get(key: 'filter')->toString(); + $filter = $expression === '' ? Group::none() : FilterParser::from(input: $expression)->parse(); + $sort = Sort::fromExpression(expression: $query->get(key: 'sort')->toString()); - return new Criteria(sort: $sort, filter: $filter, schema: $schema, pagination: $pagination); + return new Criteria(page: $page, sort: $sort, filter: $filter, pagination: $page->resolve()); } /** @@ -66,17 +70,18 @@ public static function fromQuery(QueryParameters $query, ?Schema $schema = null) public function toUri(string $baseUri): string { $parameters = []; - $template = '%s=%s'; if (!$this->filter->isEmpty()) { - $parameters[] = sprintf($template, $this->schema->filterKey(), $this->filter->toExpression()->value()); + $template = 'filter=%s'; + $parameters[] = sprintf($template, $this->filter->toExpression()->value()); } if (!$this->sort->isEmpty()) { - $parameters[] = sprintf($template, $this->schema->sortKey(), $this->sort->toExpression()); + $template = 'sort=%s'; + $parameters[] = sprintf($template, $this->sort->toExpression()); } - $parameters[] = $this->pagination->toQueryString(schema: $this->schema); + $parameters[] = $this->pagination->toQueryString(); $template = '%s?%s'; return sprintf($template, $baseUri, implode('&', $parameters)); @@ -102,24 +107,68 @@ public function filtering(): Filter return $this->filter; } + /** + * Creates a CursorPage from the items and the ordering-key extractor. + * + * @template TValue + * @param iterable $items The items fetched for the page size plus one. + * @param Closure(TValue): list $keysOf Extracts the ordering key values from an element. + * @return CursorPage The cursor page carrying the trimmed items and the cursors. + * @throws PageSizeOutOfRange If the page size is less than 1. + */ + public function cursorPage(iterable $items, Closure $keysOf): CursorPage + { + return CursorPage::from(items: $items, keysOf: $keysOf, criteria: $this, pagination: $this->page->toCursor()); + } + + /** + * Creates an OffsetPage from the items and the total element count. + * + * @template TValue + * @param iterable $items The items on the current page. + * @param int $total The total element count across every page. + * @return OffsetPage The offset page carrying the items, the total, and the navigation. + * @throws TotalIsNegative If the total is less than 0. + * @throws PageNumberOutOfRange If the page number is less than 1. + * @throws PageSizeOutOfRange If the page size falls outside the valid range. + */ + public function offsetPage(iterable $items, int $total): OffsetPage + { + return OffsetPage::from(items: $items, total: $total, criteria: $this, pagination: $this->page->toOffset()); + } + /** * Returns the pagination specification. * - * @return Paging The pagination, cursor-based when a cursor is present. + * @return Pagination The pagination, cursor-based when a cursor is present. */ - public function pagination(): Paging + public function pagination(): Pagination { return $this->pagination; } + /** + * Creates an OffsetSlice from the items, without a total element count. + * + * @template TValue + * @param iterable $items The items fetched for the page size plus one. + * @return OffsetSlice The offset slice carrying the trimmed items and the next-page hint. + * @throws PageNumberOutOfRange If the page number is less than 1. + * @throws PageSizeOutOfRange If the page size falls outside the valid range. + */ + public function offsetSlice(iterable $items): OffsetSlice + { + return OffsetSlice::from(items: $items, criteria: $this, pagination: $this->page->toOffset()); + } + /** * Returns a copy of the criteria with the pagination replaced. * - * @param Paging $pagination The pagination to apply. + * @param Pagination $pagination The pagination to apply. * @return Criteria A new criteria carrying the given pagination with the filter and sort preserved. */ - public function withPagination(Paging $pagination): Criteria + public function withPagination(Pagination $pagination): Criteria { - return new Criteria(sort: $this->sort, filter: $this->filter, schema: $this->schema, pagination: $pagination); + return new Criteria(page: $this->page, sort: $this->sort, filter: $this->filter, pagination: $pagination); } } diff --git a/src/CursorPage.php b/src/CursorPage.php index b472ca8..2f6f0c2 100644 --- a/src/CursorPage.php +++ b/src/CursorPage.php @@ -5,9 +5,12 @@ namespace TinyBlocks\HttpQuery; use Closure; +use Psr\Http\Message\ResponseInterface; use TinyBlocks\Collection\Collection; use TinyBlocks\Http\LinkRelation; -use TinyBlocks\HttpQuery\Internal\Window; +use TinyBlocks\Http\Server\Response; +use TinyBlocks\HttpQuery\Internal\Keyset; +use TinyBlocks\HttpQuery\Internal\Limit; /** * Keyset (cursor) page carrying its items and the forward and backward cursors, without a total. @@ -21,8 +24,9 @@ */ private function __construct( private Collection $items, + private Limit $limit, private bool $hasNext, - private int $perPage, + private Criteria $criteria, private Cursor $nextCursor, private bool $hasPrevious, private Cursor $previousCursor @@ -30,43 +34,52 @@ private function __construct( } /** - * Creates a CursorPage from the items, the key extractor, and the pagination. + * Creates a CursorPage from the items, the key extractor, the criteria, and the pagination. * *

    The consumer fetches one element beyond the page size via keyset. The extra element is * trimmed and its presence is read as the next-page hint. The forward cursor anchors on the * last retained element, the backward cursor on the first.

    * - * @param Collection $items The items fetched for the page size plus one. - * @param Closure(TValue): list $keysOf Extracts the ordering key values from an element. + * @template TElement + * @param iterable $items The items fetched for the page size plus one. + * @param Closure(TElement): list $keysOf Extracts the ordering key values from an element. + * @param Criteria $criteria The criteria that produced the result. * @param CursorPagination $pagination The pagination describing the current page. - * @return CursorPage The cursor page carrying the trimmed items and the cursors. + * @return CursorPage The cursor page carrying the trimmed items and the cursors. */ - public static function from(Collection $items, Closure $keysOf, CursorPagination $pagination): CursorPage - { - $limit = $pagination->limit(); - $window = Window::from(items: $items, limit: $limit); - $hasNext = $window->hasNext(); - $hasPrevious = !$pagination->cursor()->isAbsent(); - - /** @var Collection $trimmed */ - $trimmed = $window->items(); - - $lastItem = $hasNext ? $trimmed->last() : null; - $firstItem = $hasPrevious ? $trimmed->first() : null; - - $nextCursor = is_null($lastItem) ? Cursor::none() : Cursor::fromKeys(keys: $keysOf($lastItem)); - $previousCursor = is_null($firstItem) ? Cursor::none() : Cursor::fromKeys(keys: $keysOf($firstItem)); + public static function from( + iterable $items, + Closure $keysOf, + Criteria $criteria, + CursorPagination $pagination + ): CursorPage { + /** @var Collection $collection */ + $collection = Collection::createFrom(elements: $items); + $keyset = Keyset::from(items: $collection, keysOf: $keysOf, pagination: $pagination); return new CursorPage( - items: $trimmed, - hasNext: $hasNext, - perPage: $limit, - nextCursor: $nextCursor, - hasPrevious: $hasPrevious, - previousCursor: $previousCursor + items: $keyset->items(), + limit: Limit::from(value: $pagination->limit()), + hasNext: $keyset->hasNext(), + criteria: $criteria, + nextCursor: $keyset->next(), + hasPrevious: $keyset->hasPrevious(), + previousCursor: $keyset->previous() ); } + /** + * Returns the pagination for the next page, or null when there is none. + * + * @return CursorPagination|null The pagination for the next page, or null. + */ + public function next(): ?CursorPagination + { + return $this->nextCursor->isAbsent() + ? null + : CursorPagination::from(cursor: $this->nextCursor, perPage: $this->limit->value()); + } + /** * Returns the items on the current page. * @@ -90,19 +103,29 @@ public function hasNext(): bool /** * Returns the cursor page as the JSON:API meta contents. * - * @return array The meta contents keyed in length-ascending order. + * @return array The meta contents keyed in length-ascending order. */ public function metadata(): array { return [ - 'has_next' => $this->hasNext, - 'per_page' => $this->perPage, - 'next_cursor' => $this->nextCursor->isAbsent() ? null : $this->nextCursor->toString(), - 'has_previous' => $this->hasPrevious, - 'previous_cursor' => $this->previousCursor->isAbsent() ? null : $this->previousCursor->toString() + 'has_next' => $this->hasNext, + 'per_page' => $this->limit->value(), + 'has_previous' => $this->hasPrevious ]; } + /** + * Returns the pagination for the previous page, or null when there is none. + * + * @return CursorPagination|null The pagination for the previous page, or null. + */ + public function previous(): ?CursorPagination + { + return $this->previousCursor->isAbsent() + ? null + : CursorPagination::from(cursor: $this->previousCursor, perPage: $this->limit->value()); + } + /** * Returns the navigation exposing the previous and next targets. * @@ -110,26 +133,26 @@ public function metadata(): array */ public function navigation(): Navigation { - $next = $this->nextCursor->isAbsent() - ? null - : CursorPagination::from(cursor: $this->nextCursor, perPage: $this->perPage); - $previous = $this->previousCursor->isAbsent() - ? null - : CursorPagination::from(cursor: $this->previousCursor, perPage: $this->perPage); - return Navigation::empty() - ->with(target: $previous, relation: LinkRelation::PREVIOUS) - ->with(target: $next, relation: LinkRelation::NEXT); + ->with(target: $this->previous(), relation: LinkRelation::PREVIOUS) + ->with(target: $this->next(), relation: LinkRelation::NEXT); } /** - * Returns the forward cursor, absent when there is no next page. + * Returns the cursor page as a JSON:API response carrying the body and the RFC 8288 Link header. * - * @return Cursor The forward cursor. + * @param string $baseUri The base URI the navigation URIs are built on. + * @return ResponseInterface The response with the data, meta, and links, plus the Link header. */ - public function nextCursor(): Cursor + public function toResponse(string $baseUri): ResponseInterface { - return $this->nextCursor; + $links = Links::from(baseUri: $baseUri, criteria: $this->criteria, navigation: $this->navigation()); + + return Response::ok([ + 'data' => $this->items->toArray(), + 'meta' => $this->metadata(), + 'links' => $links->toArray() + ], $links->toHeader()); } /** @@ -141,14 +164,4 @@ public function hasPrevious(): bool { return $this->hasPrevious; } - - /** - * Returns the backward cursor, absent when there is no previous page. - * - * @return Cursor The backward cursor. - */ - public function previousCursor(): Cursor - { - return $this->previousCursor; - } } diff --git a/src/CursorPagination.php b/src/CursorPagination.php index 2219858..76600e7 100644 --- a/src/CursorPagination.php +++ b/src/CursorPagination.php @@ -5,13 +5,14 @@ namespace TinyBlocks\HttpQuery; use TinyBlocks\HttpQuery\Exceptions\PageSizeOutOfRange; +use TinyBlocks\HttpQuery\Internal\Limit; /** * Keyset (cursor) pagination request carrying the incoming cursor and the page size. */ -final readonly class CursorPagination implements Paging +final readonly class CursorPagination implements Pagination { - private function __construct(private int $limit, private Cursor $cursor) + private function __construct(private Limit $limit, private Cursor $cursor) { } @@ -25,16 +26,12 @@ private function __construct(private int $limit, private Cursor $cursor) */ public static function from(Cursor $cursor, int $perPage): CursorPagination { - if ($perPage < 1) { - throw PageSizeOutOfRange::belowMinimum(perPage: $perPage); - } - - return new CursorPagination(limit: $perPage, cursor: $cursor); + return new CursorPagination(limit: Limit::from(value: $perPage), cursor: $cursor); } public function limit(): int { - return $this->limit; + return $this->limit->value(); } /** @@ -47,18 +44,18 @@ public function cursor(): Cursor return $this->cursor; } - public function toQueryString(Schema $schema): string + public function toQueryString(): string { - $template = '%s=%d'; - $perPage = sprintf($template, $schema->perPageKey(), $this->limit); + $template = 'page[size]=%d'; + $size = sprintf($template, $this->limit->value()); $token = $this->cursor->toString(); if ($token === '') { - return $perPage; + return $size; } - $template = '%s=%s&%s'; + $template = 'page[cursor]=%s&%s'; - return sprintf($template, $schema->cursorKey(), $token, $perPage); + return sprintf($template, $token, $size); } } diff --git a/src/Internal/Keyset.php b/src/Internal/Keyset.php new file mode 100644 index 0000000..ff06495 --- /dev/null +++ b/src/Internal/Keyset.php @@ -0,0 +1,71 @@ + $keysOf + * @param Window $window + */ + private function __construct(private Cursor $cursor, private Closure $keysOf, private Window $window) + { + } + + /** + * @template TElement + * @param Collection $items + * @param Closure(TElement): list $keysOf + * @return Keyset + */ + public static function from(Collection $items, Closure $keysOf, CursorPagination $pagination): Keyset + { + /** @var Window $window */ + $window = Window::from(items: $items, limit: $pagination->limit()); + + return new Keyset(cursor: $pagination->cursor(), keysOf: $keysOf, window: $window); + } + + public function next(): Cursor + { + return $this->cursorFor(element: $this->hasNext() ? $this->window->items()->last() : null); + } + + /** + * @return Collection + */ + public function items(): Collection + { + return $this->window->items(); + } + + public function hasNext(): bool + { + return $this->window->hasNext(); + } + + public function previous(): Cursor + { + return $this->cursorFor(element: $this->hasPrevious() ? $this->window->items()->first() : null); + } + + private function cursorFor(mixed $element): Cursor + { + return is_null($element) ? Cursor::none() : Cursor::fromKeys(keys: ($this->keysOf)($element)); + } + + public function hasPrevious(): bool + { + return !$this->cursor->isAbsent(); + } +} diff --git a/src/Internal/Limit.php b/src/Internal/Limit.php new file mode 100644 index 0000000..1c27e8d --- /dev/null +++ b/src/Internal/Limit.php @@ -0,0 +1,28 @@ +value; + } +} diff --git a/src/Internal/Offset.php b/src/Internal/Offset.php new file mode 100644 index 0000000..6558590 --- /dev/null +++ b/src/Internal/Offset.php @@ -0,0 +1,33 @@ +value() - 1) * $limit->value()); + } + + public function value(): int + { + return $this->value; + } +} diff --git a/src/Internal/OffsetNavigator.php b/src/Internal/OffsetNavigator.php new file mode 100644 index 0000000..63e7b02 --- /dev/null +++ b/src/Internal/OffsetNavigator.php @@ -0,0 +1,58 @@ +pageNumber()->next(); + + return OffsetPagination::fromPage(page: $next->value(), perPage: $this->pagination->limit()); + } + + public function first(): OffsetPagination + { + return OffsetPagination::fromPage(page: 1, perPage: $this->pagination->limit()); + } + + public function atPage(int $page): OffsetPagination + { + return OffsetPagination::fromPage(page: $page, perPage: $this->pagination->limit()); + } + + public function isFirst(): bool + { + return $this->pageNumber()->isFirst(); + } + + public function previous(): ?OffsetPagination + { + $previous = $this->pageNumber()->previous(); + + return is_null($previous) + ? null + : OffsetPagination::fromPage(page: $previous->value(), perPage: $this->pagination->limit()); + } + + private function pageNumber(): PageNumber + { + return PageNumber::fromOffset( + offset: Offset::from(value: $this->pagination->offset()), + limit: Limit::from(value: $this->pagination->limit()) + ); + } +} diff --git a/src/Internal/PageCount.php b/src/Internal/PageCount.php new file mode 100644 index 0000000..e5f9636 --- /dev/null +++ b/src/Internal/PageCount.php @@ -0,0 +1,32 @@ +value() / $limit->value())); + } + + public function value(): int + { + return $this->value; + } + + public function isEmpty(): bool + { + return $this->value === 0; + } + + public function hasPageAfter(PageNumber $page): bool + { + return $page->value() < $this->value; + } +} diff --git a/src/Internal/PageNumber.php b/src/Internal/PageNumber.php new file mode 100644 index 0000000..abe6a6f --- /dev/null +++ b/src/Internal/PageNumber.php @@ -0,0 +1,48 @@ +value(), $limit->value()) + 1); + } + + public function next(): PageNumber + { + return new PageNumber(value: $this->value + 1); + } + + public function value(): int + { + return $this->value; + } + + public function isFirst(): bool + { + return $this->value === 1; + } + + public function previous(): ?PageNumber + { + return $this->isFirst() ? null : new PageNumber(value: $this->value - 1); + } +} diff --git a/src/Internal/PageParameters.php b/src/Internal/PageParameters.php new file mode 100644 index 0000000..f15c361 --- /dev/null +++ b/src/Internal/PageParameters.php @@ -0,0 +1,52 @@ +get(key: 'page')->toArray(); + + $size = Attribute::from(value: $page['size'] ?? null); + $cursor = Attribute::from(value: $page['cursor'] ?? null); + $number = Attribute::from(value: $page['number'] ?? null); + + $requested = $size->toString() === '' ? $schema->defaultPerPage() : $size->toInteger(); + + return new PageParameters( + cursor: Cursor::from(token: $cursor->toString()), + perPage: $schema->pageSizeFor(requested: $requested), + pageNumber: $number->toString() === '' ? 1 : $number->toInteger() + ); + } + + public function resolve(): Pagination + { + return $this->cursor->isAbsent() ? $this->toOffset() : $this->toCursor(); + } + + public function toCursor(): CursorPagination + { + return CursorPagination::from(cursor: $this->cursor, perPage: $this->perPage); + } + + public function toOffset(): OffsetPagination + { + return OffsetPagination::fromPage(page: $this->pageNumber, perPage: $this->perPage); + } +} diff --git a/src/Internal/PaginationResolver.php b/src/Internal/PaginationResolver.php deleted file mode 100644 index 9fd5e7b..0000000 --- a/src/Internal/PaginationResolver.php +++ /dev/null @@ -1,41 +0,0 @@ -query->get(key: $this->schema->perPageKey()); - $requested = $attribute->toString() === '' ? $this->schema->defaultPerPage() : $attribute->toInteger(); - $perPage = $this->schema->pageSizeFor(requested: $requested); - - $cursorToken = $this->query->get(key: $this->schema->cursorKey())->toString(); - - if ($cursorToken !== '') { - return CursorPagination::from(cursor: Cursor::from(token: $cursorToken), perPage: $perPage); - } - - $page = $this->query->get(key: $this->schema->pageKey()); - - return Pagination::fromPage(page: $page->toString() === '' ? 1 : $page->toInteger(), perPage: $perPage); - } -} diff --git a/src/Internal/Total.php b/src/Internal/Total.php new file mode 100644 index 0000000..8b70bb8 --- /dev/null +++ b/src/Internal/Total.php @@ -0,0 +1,33 @@ +value; + } + + public function pageCount(Limit $limit): PageCount + { + return PageCount::from(total: $this, limit: $limit); + } +} diff --git a/src/Navigation.php b/src/Navigation.php index 2502c04..f7e42bc 100644 --- a/src/Navigation.php +++ b/src/Navigation.php @@ -40,11 +40,11 @@ public static function empty(): Navigation * *

    A null target is ignored, so the copy carries the same targets as the original.

    * - * @param Paging|null $target The paging the target points to, or null to ignore. + * @param Pagination|null $target The paging the target points to, or null to ignore. * @param LinkRelation $relation The relation the target is reached through. * @return Navigation A copy carrying the original targets plus the added target. */ - public function with(?Paging $target, LinkRelation $relation): Navigation + public function with(?Pagination $target, LinkRelation $relation): Navigation { if (is_null($target)) { return $this; diff --git a/src/NavigationTarget.php b/src/NavigationTarget.php index f3b5155..5bac6c8 100644 --- a/src/NavigationTarget.php +++ b/src/NavigationTarget.php @@ -11,18 +11,18 @@ */ final readonly class NavigationTarget { - private function __construct(private Paging $target, private LinkRelation $relation) + private function __construct(private Pagination $target, private LinkRelation $relation) { } /** * Creates a NavigationTarget from a paging target and the relation it carries. * - * @param Paging $target The paging the target points to. + * @param Pagination $target The paging the target points to. * @param LinkRelation $relation The relation the target is reached through. * @return NavigationTarget The composed navigation target. */ - public static function to(Paging $target, LinkRelation $relation): NavigationTarget + public static function to(Pagination $target, LinkRelation $relation): NavigationTarget { return new NavigationTarget(target: $target, relation: $relation); } @@ -30,9 +30,9 @@ public static function to(Paging $target, LinkRelation $relation): NavigationTar /** * Returns the paging the target points to. * - * @return Paging The paging target. + * @return Pagination The paging target. */ - public function target(): Paging + public function target(): Pagination { return $this->target; } diff --git a/src/OffsetPage.php b/src/OffsetPage.php new file mode 100644 index 0000000..caa519e --- /dev/null +++ b/src/OffsetPage.php @@ -0,0 +1,252 @@ + $items + */ + private function __construct( + private Collection $items, + private Total $total, + private Criteria $criteria, + private OffsetNavigator $navigator, + private PageCount $pageCount, + private PageNumber $pageNumber, + private OffsetPagination $pagination + ) { + } + + /** + * Creates an OffsetPage from the items, the total element count, the criteria, and the pagination. + * + * @template TElement + * @param iterable $items The items on the current page. + * @param int $total The total element count across every page. + * @param Criteria $criteria The criteria that produced the result. + * @param OffsetPagination $pagination The pagination describing the current page. + * @return OffsetPage The page carrying the items, the total, and the navigation. + * @throws TotalIsNegative If the total is less than 0. + */ + public static function from( + iterable $items, + int $total, + Criteria $criteria, + OffsetPagination $pagination + ): OffsetPage { + $count = Total::from(value: $total); + $limit = Limit::from(value: $pagination->limit()); + $offset = Offset::from(value: $pagination->offset()); + + /** @var Collection $collection */ + $collection = Collection::createFrom(elements: [...$items]); + + return new OffsetPage( + items: $collection, + total: $count, + criteria: $criteria, + navigator: OffsetNavigator::from(pagination: $pagination), + pageCount: $count->pageCount(limit: $limit), + pageNumber: PageNumber::fromOffset(offset: $offset, limit: $limit), + pagination: $pagination + ); + } + + /** + * Returns the pagination for the last page, or null when there is no page. + * + * @return OffsetPagination|null The pagination for the last page, or null. + */ + public function last(): ?OffsetPagination + { + return $this->pageCount->isEmpty() ? null : $this->navigator->atPage(page: $this->pageCount->value()); + } + + /** + * Returns the pagination for the next page, or null when there is none. + * + * @return OffsetPagination|null The pagination for the next page, or null. + */ + public function next(): ?OffsetPagination + { + return $this->hasNext() ? $this->navigator->next() : null; + } + + /** + * Returns the pagination for the first page, or null when there is no page. + * + * @return OffsetPagination|null The pagination for the first page, or null. + */ + public function first(): ?OffsetPagination + { + return $this->pageCount->isEmpty() ? null : $this->navigator->first(); + } + + /** + * Returns the items on the current page. + * + * @return Collection The items on the current page. + */ + public function items(): Collection + { + return $this->items; + } + + /** + * Returns the total element count across every page. + * + * @return int The total element count. + */ + public function total(): int + { + return $this->total->value(); + } + + /** + * Tells whether the current page is the last page. + * + * @return bool True when the current page is the last page. + */ + public function isLast(): bool + { + return !$this->hasNext(); + } + + /** + * Returns the zero-based offset of the current page. + * + * @return int The offset of the current page. + */ + public function offset(): int + { + return $this->pagination->offset(); + } + + /** + * Tells whether a next page exists. + * + * @return bool True when a next page exists. + */ + public function hasNext(): bool + { + return $this->pageCount->hasPageAfter(page: $this->pageNumber); + } + + /** + * Tells whether the current page is the first page. + * + * @return bool True when the current page is the first page. + */ + public function isFirst(): bool + { + return $this->navigator->isFirst(); + } + + /** + * Returns the page as the JSON:API meta contents. + * + * @return array The meta contents keyed in length-ascending order. + */ + public function metadata(): array + { + return [ + 'total' => $this->total->value(), + 'has_next' => $this->hasNext(), + 'per_page' => $this->pagination->limit(), + 'total_pages' => $this->pageCount->value(), + 'current_page' => $this->pageNumber->value(), + 'has_previous' => $this->hasPrevious() + ]; + } + + /** + * Returns the pagination for the previous page, or null when there is none. + * + * @return OffsetPagination|null The pagination for the previous page, or null. + */ + public function previous(): ?OffsetPagination + { + return $this->navigator->previous(); + } + + /** + * Returns the navigation exposing the first, previous, next, and last targets. + * + * @return Navigation The navigation listing the surrounding pages present for this page. + */ + public function navigation(): Navigation + { + return Navigation::empty() + ->with(target: $this->first(), relation: LinkRelation::FIRST) + ->with(target: $this->previous(), relation: LinkRelation::PREVIOUS) + ->with(target: $this->next(), relation: LinkRelation::NEXT) + ->with(target: $this->last(), relation: LinkRelation::LAST); + } + + /** + * Returns the page as a JSON:API response carrying the body and the RFC 8288 Link header. + * + * @param string $baseUri The base URI the navigation URIs are built on. + * @return ResponseInterface The response with the data, meta, and links, plus the Link header. + */ + public function toResponse(string $baseUri): ResponseInterface + { + $links = Links::from(baseUri: $baseUri, criteria: $this->criteria, navigation: $this->navigation()); + + return Response::ok([ + 'data' => $this->items->toArray(), + 'meta' => $this->metadata(), + 'links' => $links->toArray() + ], $links->toHeader()); + } + + /** + * Returns the total number of pages. + * + * @return int The total number of pages. + */ + public function totalPages(): int + { + return $this->pageCount->value(); + } + + /** + * Returns the one-based current page number. + * + * @return int The current page number. + */ + public function currentPage(): int + { + return $this->pageNumber->value(); + } + + /** + * Tells whether a previous page exists. + * + * @return bool True when a previous page exists. + */ + public function hasPrevious(): bool + { + return !$this->navigator->isFirst(); + } +} diff --git a/src/OffsetPagination.php b/src/OffsetPagination.php new file mode 100644 index 0000000..5a952f0 --- /dev/null +++ b/src/OffsetPagination.php @@ -0,0 +1,87 @@ +The page-based factory derives the offset from the one-based page number and the page size.

    + */ +final readonly class OffsetPagination implements Pagination +{ + private function __construct(private Limit $limit, private Offset $offset) + { + } + + /** + * Creates an OffsetPagination from a one-based page number and a page size. + * + * @param int $page The one-based page number. + * @param int $perPage The page size. + * @return OffsetPagination The pagination whose offset is derived from the page and the page size. + * @throws PageNumberOutOfRange If the page number is less than 1. + * @throws PageSizeOutOfRange If the page size is less than 1. + */ + public static function fromPage(int $page, int $perPage): OffsetPagination + { + $limit = Limit::from(value: $perPage); + $number = PageNumber::from(value: $page); + + return new OffsetPagination(limit: $limit, offset: Offset::fromPage(page: $number, limit: $limit)); + } + + /** + * Creates an OffsetPagination from a zero-based offset and a limit. + * + * @param int $offset The zero-based offset. + * @param int $limit The maximum number of elements per page. + * @return OffsetPagination The pagination carrying the offset and the limit. + * @throws OffsetOutOfRange If the offset is less than 0. + * @throws PageSizeOutOfRange If the limit is less than 1. + */ + public static function fromOffset(int $offset, int $limit): OffsetPagination + { + return new OffsetPagination(limit: Limit::from(value: $limit), offset: Offset::from(value: $offset)); + } + + /** + * Returns the one-based page number derived from the offset and the limit. + * + * @return int The one-based page number. + */ + public function page(): int + { + return PageNumber::fromOffset(offset: $this->offset, limit: $this->limit)->value(); + } + + public function limit(): int + { + return $this->limit->value(); + } + + /** + * Returns the zero-based offset. + * + * @return int The offset. + */ + public function offset(): int + { + return $this->offset->value(); + } + + public function toQueryString(): string + { + $template = 'page[number]=%d&page[size]=%d'; + + return sprintf($template, $this->page(), $this->limit->value()); + } +} diff --git a/src/OffsetSlice.php b/src/OffsetSlice.php new file mode 100644 index 0000000..054f218 --- /dev/null +++ b/src/OffsetSlice.php @@ -0,0 +1,195 @@ + $items + */ + private function __construct( + private Collection $items, + private bool $hasNext, + private Criteria $criteria, + private OffsetNavigator $navigator, + private PageNumber $pageNumber, + private OffsetPagination $pagination + ) { + } + + /** + * Creates an OffsetSlice from the items, the criteria, and the pagination. + * + *

    The consumer fetches one element beyond the page size. The extra element is trimmed and + * its presence is read as the next-page hint.

    + * + * @template TElement + * @param iterable $items The items fetched for the page size plus one. + * @param Criteria $criteria The criteria that produced the result. + * @param OffsetPagination $pagination The pagination describing the current page. + * @return OffsetSlice The slice carrying the trimmed items and the next-page hint. + */ + public static function from(iterable $items, Criteria $criteria, OffsetPagination $pagination): OffsetSlice + { + $limit = Limit::from(value: $pagination->limit()); + $offset = Offset::from(value: $pagination->offset()); + + /** @var Collection $collection */ + $collection = Collection::createFrom(elements: $items); + $window = Window::from(items: $collection, limit: $pagination->limit()); + + /** @var Collection $trimmed */ + $trimmed = $window->items(); + + return new OffsetSlice( + items: $trimmed, + hasNext: $window->hasNext(), + criteria: $criteria, + navigator: OffsetNavigator::from(pagination: $pagination), + pageNumber: PageNumber::fromOffset(offset: $offset, limit: $limit), + pagination: $pagination + ); + } + + /** + * Returns the pagination for the next page, or null when there is none. + * + * @return OffsetPagination|null The pagination for the next page, or null. + */ + public function next(): ?OffsetPagination + { + return $this->hasNext ? $this->navigator->next() : null; + } + + /** + * Returns the pagination for the first page. + * + * @return OffsetPagination The pagination for the first page. + */ + public function first(): OffsetPagination + { + return $this->navigator->first(); + } + + /** + * Returns the items on the current page. + * + * @return Collection The items on the current page. + */ + public function items(): Collection + { + return $this->items; + } + + /** + * Returns the zero-based offset of the current page. + * + * @return int The offset of the current page. + */ + public function offset(): int + { + return $this->pagination->offset(); + } + + /** + * Tells whether a next page exists. + * + * @return bool True when a next page exists. + */ + public function hasNext(): bool + { + return $this->hasNext; + } + + /** + * Returns the slice as the JSON:API meta contents. + * + * @return array The meta contents keyed in length-ascending order. + */ + public function metadata(): array + { + return [ + 'has_next' => $this->hasNext, + 'per_page' => $this->pagination->limit(), + 'current_page' => $this->pageNumber->value(), + 'has_previous' => $this->hasPrevious() + ]; + } + + /** + * Returns the pagination for the previous page, or null when there is none. + * + * @return OffsetPagination|null The pagination for the previous page, or null. + */ + public function previous(): ?OffsetPagination + { + return $this->navigator->previous(); + } + + /** + * Returns the navigation exposing the first, previous, and next targets. + * + * @return Navigation The navigation listing the surrounding pages present for this slice. + */ + public function navigation(): Navigation + { + return Navigation::empty() + ->with(target: $this->first(), relation: LinkRelation::FIRST) + ->with(target: $this->previous(), relation: LinkRelation::PREVIOUS) + ->with(target: $this->next(), relation: LinkRelation::NEXT); + } + + /** + * Returns the slice as a JSON:API response carrying the body and the RFC 8288 Link header. + * + * @param string $baseUri The base URI the navigation URIs are built on. + * @return ResponseInterface The response with the data, meta, and links, plus the Link header. + */ + public function toResponse(string $baseUri): ResponseInterface + { + $links = Links::from(baseUri: $baseUri, criteria: $this->criteria, navigation: $this->navigation()); + + return Response::ok([ + 'data' => $this->items->toArray(), + 'meta' => $this->metadata(), + 'links' => $links->toArray() + ], $links->toHeader()); + } + + /** + * Returns the one-based current page number. + * + * @return int The current page number. + */ + public function currentPage(): int + { + return $this->pageNumber->value(); + } + + /** + * Tells whether a previous page exists. + * + * @return bool True when a previous page exists. + */ + public function hasPrevious(): bool + { + return !$this->navigator->isFirst(); + } +} diff --git a/src/Page.php b/src/Page.php deleted file mode 100644 index 94bfe5c..0000000 --- a/src/Page.php +++ /dev/null @@ -1,203 +0,0 @@ - $items - */ - private function __construct(private Collection $items, private int $total, private Pagination $pagination) - { - } - - /** - * Creates a Page from the items, the total element count, and the pagination. - * - * @param Collection $items The items on the current page. - * @param int $total The total element count across every page. - * @param Pagination $pagination The pagination describing the current page. - * @return Page The page carrying the items, the total, and the navigation. - * @throws TotalIsNegative If the total is less than 0. - */ - public static function from(Collection $items, int $total, Pagination $pagination): Page - { - if ($total < 0) { - throw TotalIsNegative::from(total: $total); - } - - return new Page(items: $items, total: $total, pagination: $pagination); - } - - /** - * Returns the pagination for the last page, or null when there is no page. - * - * @return Pagination|null The pagination for the last page, or null. - */ - public function last(): ?Pagination - { - return $this->totalPages() === 0 ? null : $this->pagination->atPage(page: $this->totalPages()); - } - - /** - * Returns the pagination for the next page, or null when there is none. - * - * @return Pagination|null The pagination for the next page, or null. - */ - public function next(): ?Pagination - { - return $this->hasNext() ? $this->pagination->next() : null; - } - - /** - * Returns the pagination for the first page, or null when there is no page. - * - * @return Pagination|null The pagination for the first page, or null. - */ - public function first(): ?Pagination - { - return $this->totalPages() === 0 ? null : $this->pagination->first(); - } - - /** - * Returns the items on the current page. - * - * @return Collection The items on the current page. - */ - public function items(): Collection - { - return $this->items; - } - - /** - * Returns the total element count across every page. - * - * @return int The total element count. - */ - public function total(): int - { - return $this->total; - } - - /** - * Tells whether the current page is the last page. - * - * @return bool True when the current page is the last page. - */ - public function isLast(): bool - { - return $this->currentPage() >= $this->totalPages(); - } - - /** - * Returns the zero-based offset of the current page. - * - * @return int The offset of the current page. - */ - public function offset(): int - { - return $this->pagination->offset(); - } - - /** - * Tells whether a next page exists. - * - * @return bool True when a next page exists. - */ - public function hasNext(): bool - { - return $this->currentPage() < $this->totalPages(); - } - - /** - * Tells whether the current page is the first page. - * - * @return bool True when the current page is the first page. - */ - public function isFirst(): bool - { - return !$this->pagination->hasPrevious(); - } - - /** - * Returns the page as the JSON:API meta contents. - * - * @return array The meta contents keyed in length-ascending order. - */ - public function metadata(): array - { - return [ - 'total' => $this->total, - 'has_next' => $this->hasNext(), - 'per_page' => $this->pagination->limit(), - 'total_pages' => $this->totalPages(), - 'current_page' => $this->currentPage(), - 'has_previous' => $this->hasPrevious() - ]; - } - - /** - * Returns the pagination for the previous page, or null when there is none. - * - * @return Pagination|null The pagination for the previous page, or null. - */ - public function previous(): ?Pagination - { - return $this->pagination->previous(); - } - - /** - * Returns the navigation exposing the first, previous, next, and last targets. - * - * @return Navigation The navigation listing the surrounding pages present for this page. - */ - public function navigation(): Navigation - { - return Navigation::empty() - ->with(target: $this->first(), relation: LinkRelation::FIRST) - ->with(target: $this->previous(), relation: LinkRelation::PREVIOUS) - ->with(target: $this->next(), relation: LinkRelation::NEXT) - ->with(target: $this->last(), relation: LinkRelation::LAST); - } - - /** - * Returns the total number of pages. - * - * @return int The total number of pages. - */ - public function totalPages(): int - { - return (int)ceil($this->total / $this->pagination->limit()); - } - - /** - * Returns the one-based current page number. - * - * @return int The current page number. - */ - public function currentPage(): int - { - return $this->pagination->page(); - } - - /** - * Tells whether a previous page exists. - * - * @return bool True when a previous page exists. - */ - public function hasPrevious(): bool - { - return $this->pagination->hasPrevious(); - } -} diff --git a/src/Pagination.php b/src/Pagination.php index 25c05f0..91c244d 100644 --- a/src/Pagination.php +++ b/src/Pagination.php @@ -4,150 +4,25 @@ namespace TinyBlocks\HttpQuery; -use TinyBlocks\HttpQuery\Exceptions\OffsetOutOfRange; -use TinyBlocks\HttpQuery\Exceptions\PageNumberOutOfRange; -use TinyBlocks\HttpQuery\Exceptions\PageSizeOutOfRange; - /** - * Offset-based pagination request whose canonical state is an offset and a limit. + * Pagination request that knows its page size and how to serialize itself into a query string. * - *

    The page-based factory derives the offset from the one-based page number and the page size.

    + *

    It is implemented by the offset-based {@see OffsetPagination} and the keyset {@see CursorPagination}, + * so a {@see Criteria} carries either one without branching on the concrete type.

    */ -final readonly class Pagination implements Paging +interface Pagination { - private function __construct(private int $offset, private int $limit) - { - } - - /** - * Creates a Pagination from a one-based page number and a page size. - * - * @param int $page The one-based page number. - * @param int $perPage The page size. - * @return Pagination The pagination whose offset is derived from the page and the page size. - * @throws PageNumberOutOfRange If the page number is less than 1. - * @throws PageSizeOutOfRange If the page size is less than 1. - */ - public static function fromPage(int $page, int $perPage): Pagination - { - if ($page < 1) { - throw PageNumberOutOfRange::from(page: $page); - } - - if ($perPage < 1) { - throw PageSizeOutOfRange::belowMinimum(perPage: $perPage); - } - - return new Pagination(offset: ($page - 1) * $perPage, limit: $perPage); - } - - /** - * Creates a Pagination from a zero-based offset and a limit. - * - * @param int $offset The zero-based offset. - * @param int $limit The maximum number of elements per page. - * @return Pagination The pagination carrying the offset and the limit. - * @throws OffsetOutOfRange If the offset is less than 0. - * @throws PageSizeOutOfRange If the limit is less than 1. - */ - public static function fromOffset(int $offset, int $limit): Pagination - { - if ($offset < 0) { - throw OffsetOutOfRange::from(offset: $offset); - } - - if ($limit < 1) { - throw PageSizeOutOfRange::belowMinimum(perPage: $limit); - } - - return new Pagination(offset: $offset, limit: $limit); - } - - /** - * Returns the pagination for the next page. - * - * @return Pagination The pagination for the next page. - */ - public function next(): Pagination - { - return Pagination::fromPage(page: $this->page() + 1, perPage: $this->limit); - } - - /** - * Returns the one-based page number derived from the offset and the limit. - * - * @return int The one-based page number. - */ - public function page(): int - { - return intdiv($this->offset, $this->limit) + 1; - } - - /** - * Returns the pagination for the first page. - * - * @return Pagination The pagination for the first page. - */ - public function first(): Pagination - { - return Pagination::fromPage(page: 1, perPage: $this->limit); - } - - public function limit(): int - { - return $this->limit; - } - /** - * Returns the pagination for the given page. + * Returns the maximum number of elements per page. * - * @param int $page The one-based page number. - * @return Pagination The pagination for the given page. - * @throws PageNumberOutOfRange If the page number is less than 1. + * @return int The limit. */ - public function atPage(int $page): Pagination - { - return Pagination::fromPage(page: $page, perPage: $this->limit); - } + public function limit(): int; /** - * Returns the zero-based offset. + * Returns the pagination as a JSON:API query string fragment. * - * @return int The offset. + * @return string The query string fragment carrying the pagination. */ - public function offset(): int - { - return $this->offset; - } - - /** - * Returns the pagination for the previous page, or null when there is none. - * - * @return Pagination|null The pagination for the previous page, or null. - */ - public function previous(): ?Pagination - { - if (!$this->hasPrevious()) { - return null; - } - - return Pagination::fromPage(page: $this->page() - 1, perPage: $this->limit); - } - - /** - * Tells whether a previous page exists. - * - * @return bool True when a previous page exists. - */ - public function hasPrevious(): bool - { - return $this->page() > 1; - } - - public function toQueryString(Schema $schema): string - { - $template = '%s=%d&%s=%d'; - - return sprintf($template, $schema->pageKey(), $this->page(), $schema->perPageKey(), $this->limit); - } + public function toQueryString(): string; } diff --git a/src/Paging.php b/src/Paging.php deleted file mode 100644 index be6bf90..0000000 --- a/src/Paging.php +++ /dev/null @@ -1,29 +0,0 @@ -It is implemented by the offset-based {@see Pagination} and the keyset {@see CursorPagination}, - * so a {@see Criteria} carries either one without branching on the concrete type.

    - */ -interface Paging -{ - /** - * Returns the maximum number of elements per page. - * - * @return int The limit. - */ - public function limit(): int; - - /** - * Returns the pagination as a query string fragment built against the schema keys. - * - * @param Schema $schema The schema mapping the query key names. - * @return string The query string fragment carrying the pagination. - */ - public function toQueryString(Schema $schema): string; -} diff --git a/src/Schema.php b/src/Schema.php index b479bdc..a7dd2d1 100644 --- a/src/Schema.php +++ b/src/Schema.php @@ -7,23 +7,15 @@ use TinyBlocks\HttpQuery\Exceptions\PageSizeOutOfRange; /** - * Configurable mapping of query parameter names and page-size bounds used to read and write a Criteria. + * Page-size bounds used to read and write a Criteria. * - *

    The defaults follow the canonical conventions: filter, sort, - * page, per_page, and cursor, with a default page size of - * 20 and a maximum of 100.

    + *

    The query parameter names follow JSON:API and are fixed: filter, sort, + * and the page family. The default page size is 20 and the maximum is 100.

    */ final readonly class Schema { - private function __construct( - private string $pageKey, - private string $sortKey, - private string $cursorKey, - private string $filterKey, - private int $maxPerPage, - private string $perPageKey, - private int $defaultPerPage - ) { + private function __construct(private int $maxPerPage, private int $defaultPerPage) + { if ($maxPerPage < 1) { throw PageSizeOutOfRange::belowMinimum(perPage: $maxPerPage); } @@ -38,61 +30,13 @@ private function __construct( } /** - * Creates a Schema carrying the canonical default key names and bounds. + * Creates a Schema carrying the default page-size bounds. * * @return Schema The default schema. */ public static function default(): Schema { - return new Schema( - pageKey: 'page', - sortKey: 'sort', - cursorKey: 'cursor', - filterKey: 'filter', - maxPerPage: 100, - perPageKey: 'per_page', - defaultPerPage: 20 - ); - } - - /** - * Returns the query key carrying the page number. - * - * @return string The page key. - */ - public function pageKey(): string - { - return $this->pageKey; - } - - /** - * Returns the query key carrying the sort expression. - * - * @return string The sort key. - */ - public function sortKey(): string - { - return $this->sortKey; - } - - /** - * Returns the query key carrying the cursor token. - * - * @return string The cursor key. - */ - public function cursorKey(): string - { - return $this->cursorKey; - } - - /** - * Returns the query key carrying the RSQL filter. - * - * @return string The filter key. - */ - public function filterKey(): string - { - return $this->filterKey; + return new Schema(maxPerPage: 100, defaultPerPage: 20); } /** @@ -105,16 +49,6 @@ public function maxPerPage(): int return $this->maxPerPage; } - /** - * Returns the query key carrying the page size. - * - * @return string The page-size key. - */ - public function perPageKey(): string - { - return $this->perPageKey; - } - /** * Returns the requested page size bounded by the maximum allowed. * @@ -131,82 +65,6 @@ public function pageSizeFor(int $requested): int return $requested; } - /** - * Returns a copy of the Schema with the page key replaced. - * - * @param string $pageKey The query key carrying the page number. - * @return Schema A copy of the schema carrying the new page key. - */ - public function withPageKey(string $pageKey): Schema - { - return new Schema( - pageKey: $pageKey, - sortKey: $this->sortKey, - cursorKey: $this->cursorKey, - filterKey: $this->filterKey, - maxPerPage: $this->maxPerPage, - perPageKey: $this->perPageKey, - defaultPerPage: $this->defaultPerPage - ); - } - - /** - * Returns a copy of the Schema with the sort key replaced. - * - * @param string $sortKey The query key carrying the sort expression. - * @return Schema A copy of the schema carrying the new sort key. - */ - public function withSortKey(string $sortKey): Schema - { - return new Schema( - pageKey: $this->pageKey, - sortKey: $sortKey, - cursorKey: $this->cursorKey, - filterKey: $this->filterKey, - maxPerPage: $this->maxPerPage, - perPageKey: $this->perPageKey, - defaultPerPage: $this->defaultPerPage - ); - } - - /** - * Returns a copy of the Schema with the cursor key replaced. - * - * @param string $cursorKey The query key carrying the cursor token. - * @return Schema A copy of the schema carrying the new cursor key. - */ - public function withCursorKey(string $cursorKey): Schema - { - return new Schema( - pageKey: $this->pageKey, - sortKey: $this->sortKey, - cursorKey: $cursorKey, - filterKey: $this->filterKey, - maxPerPage: $this->maxPerPage, - perPageKey: $this->perPageKey, - defaultPerPage: $this->defaultPerPage - ); - } - - /** - * Returns a copy of the Schema with the filter key replaced. - * - * @param string $filterKey The query key carrying the RSQL filter. - * @return Schema A copy of the schema carrying the new filter key. - */ - public function withFilterKey(string $filterKey): Schema - { - return new Schema( - pageKey: $this->pageKey, - sortKey: $this->sortKey, - cursorKey: $this->cursorKey, - filterKey: $filterKey, - maxPerPage: $this->maxPerPage, - perPageKey: $this->perPageKey, - defaultPerPage: $this->defaultPerPage - ); - } - /** * Returns the page size applied when the query omits one. * @@ -225,34 +83,7 @@ public function defaultPerPage(): int */ public function withMaxPerPage(int $maxPerPage): Schema { - return new Schema( - pageKey: $this->pageKey, - sortKey: $this->sortKey, - cursorKey: $this->cursorKey, - filterKey: $this->filterKey, - maxPerPage: $maxPerPage, - perPageKey: $this->perPageKey, - defaultPerPage: $this->defaultPerPage - ); - } - - /** - * Returns a copy of the Schema with the page-size key replaced. - * - * @param string $perPageKey The query key carrying the page size. - * @return Schema A copy of the schema carrying the new page-size key. - */ - public function withPerPageKey(string $perPageKey): Schema - { - return new Schema( - pageKey: $this->pageKey, - sortKey: $this->sortKey, - cursorKey: $this->cursorKey, - filterKey: $this->filterKey, - maxPerPage: $this->maxPerPage, - perPageKey: $perPageKey, - defaultPerPage: $this->defaultPerPage - ); + return new Schema(maxPerPage: $maxPerPage, defaultPerPage: $this->defaultPerPage); } /** @@ -263,14 +94,6 @@ public function withPerPageKey(string $perPageKey): Schema */ public function withDefaultPerPage(int $defaultPerPage): Schema { - return new Schema( - pageKey: $this->pageKey, - sortKey: $this->sortKey, - cursorKey: $this->cursorKey, - filterKey: $this->filterKey, - maxPerPage: $this->maxPerPage, - perPageKey: $this->perPageKey, - defaultPerPage: $defaultPerPage - ); + return new Schema(maxPerPage: $this->maxPerPage, defaultPerPage: $defaultPerPage); } } diff --git a/src/Slice.php b/src/Slice.php deleted file mode 100644 index d072b2b..0000000 --- a/src/Slice.php +++ /dev/null @@ -1,141 +0,0 @@ - $items - */ - private function __construct(private Collection $items, private bool $hasNext, private Pagination $pagination) - { - } - - /** - * Creates a Slice from the items and the pagination. - * - *

    The consumer fetches one element beyond the page size. The extra element is trimmed and - * its presence is read as the next-page hint.

    - * - * @param Collection $items The items fetched for the page size plus one. - * @param Pagination $pagination The pagination describing the current page. - * @return Slice The slice carrying the trimmed items and the next-page hint. - */ - public static function from(Collection $items, Pagination $pagination): Slice - { - $window = Window::from(items: $items, limit: $pagination->limit()); - - /** @var Collection $trimmed */ - $trimmed = $window->items(); - - return new Slice(items: $trimmed, hasNext: $window->hasNext(), pagination: $pagination); - } - - /** - * Returns the pagination for the next page, or null when there is none. - * - * @return Pagination|null The pagination for the next page, or null. - */ - public function next(): ?Pagination - { - return $this->hasNext ? $this->pagination->next() : null; - } - - /** - * Returns the items on the current page. - * - * @return Collection The items on the current page. - */ - public function items(): Collection - { - return $this->items; - } - - /** - * Returns the zero-based offset of the current page. - * - * @return int The offset of the current page. - */ - public function offset(): int - { - return $this->pagination->offset(); - } - - /** - * Tells whether a next page exists. - * - * @return bool True when a next page exists. - */ - public function hasNext(): bool - { - return $this->hasNext; - } - - /** - * Returns the slice as the JSON:API meta contents. - * - * @return array The meta contents keyed in length-ascending order. - */ - public function metadata(): array - { - return [ - 'has_next' => $this->hasNext, - 'per_page' => $this->pagination->limit(), - 'current_page' => $this->currentPage(), - 'has_previous' => $this->hasPrevious() - ]; - } - - /** - * Returns the pagination for the previous page, or null when there is none. - * - * @return Pagination|null The pagination for the previous page, or null. - */ - public function previous(): ?Pagination - { - return $this->pagination->previous(); - } - - /** - * Returns the navigation exposing the previous and next targets. - * - * @return Navigation The navigation listing the surrounding pages present for this slice. - */ - public function navigation(): Navigation - { - return Navigation::empty() - ->with(target: $this->previous(), relation: LinkRelation::PREVIOUS) - ->with(target: $this->next(), relation: LinkRelation::NEXT); - } - - /** - * Returns the one-based current page number. - * - * @return int The current page number. - */ - public function currentPage(): int - { - return $this->pagination->page(); - } - - /** - * Tells whether a previous page exists. - * - * @return bool True when a previous page exists. - */ - public function hasPrevious(): bool - { - return $this->pagination->hasPrevious(); - } -} diff --git a/tests/Models/Query.php b/tests/Models/Query.php index 323da3c..6abb2af 100644 --- a/tests/Models/Query.php +++ b/tests/Models/Query.php @@ -5,7 +5,7 @@ namespace Test\TinyBlocks\HttpQuery\Models; use Nyholm\Psr7\ServerRequest; -use TinyBlocks\Http\Server\Decoded\QueryParameters; +use Psr\Http\Message\ServerRequestInterface; final class Query { @@ -13,8 +13,8 @@ private function __construct() { } - public static function from(array $parameters): QueryParameters + public static function from(array $parameters): ServerRequestInterface { - return QueryParameters::from(request: new ServerRequest(method: 'GET', uri: '/')->withQueryParams($parameters)); + return new ServerRequest(method: 'GET', uri: '/')->withQueryParams($parameters); } } diff --git a/tests/Unit/CriteriaTest.php b/tests/Unit/CriteriaTest.php index a6512b6..b03177f 100644 --- a/tests/Unit/CriteriaTest.php +++ b/tests/Unit/CriteriaTest.php @@ -8,11 +8,14 @@ use Test\TinyBlocks\HttpQuery\Models\Query; use TinyBlocks\HttpQuery\Comparison; use TinyBlocks\HttpQuery\Criteria; +use TinyBlocks\HttpQuery\CursorPage; use TinyBlocks\HttpQuery\CursorPagination; use TinyBlocks\HttpQuery\Direction; use TinyBlocks\HttpQuery\Exceptions\PageSizeOutOfRange; use TinyBlocks\HttpQuery\Group; -use TinyBlocks\HttpQuery\Pagination; +use TinyBlocks\HttpQuery\OffsetPage; +use TinyBlocks\HttpQuery\OffsetPagination; +use TinyBlocks\HttpQuery\OffsetSlice; use TinyBlocks\HttpQuery\Schema; final class CriteriaTest extends TestCase @@ -23,7 +26,7 @@ public function testFromQueryWhenEmptyThenSortingIsEmpty(): void $query = Query::from(parameters: []); /** @When building the criteria from the query */ - $criteria = Criteria::fromQuery(query: $query); + $criteria = Criteria::fromQuery(request: $query); /** @Then the sorting is empty */ self::assertTrue($criteria->sorting()->isEmpty()); @@ -35,7 +38,7 @@ public function testFromQueryWhenEmptyThenFilteringIsAnEmptyGroup(): void $query = Query::from(parameters: []); /** @When building the criteria from the query */ - $criteria = Criteria::fromQuery(query: $query); + $criteria = Criteria::fromQuery(request: $query); /** @Then the filtering is an empty group */ self::assertInstanceOf(Group::class, $criteria->filtering()); @@ -47,73 +50,118 @@ public function testFromQueryWhenEmptyThenFilteringIsAnEmptyGroup(): void public function testFromQueryWhenNoCursorThenPaginationIsOffsetBased(): void { /** @Given query parameters without a cursor */ - $query = Query::from(parameters: ['page' => '2', 'per_page' => '15']); + $query = Query::from(parameters: ['page' => ['number' => '2', 'size' => '15']]); /** @When building the criteria from the query */ - $criteria = Criteria::fromQuery(query: $query); + $criteria = Criteria::fromQuery(request: $query); /** @Then the pagination is offset-based */ - self::assertInstanceOf(Pagination::class, $criteria->pagination()); + self::assertInstanceOf(OffsetPagination::class, $criteria->pagination()); } public function testToUriWhenAndGroupNestedInOrThenLeavesItUnwrapped(): void { /** @Given a criteria whose filter nests an AND group inside an OR group */ - $criteria = Criteria::fromQuery(query: Query::from(parameters: ['filter' => 'a==1;b==2,c==3'])); + $criteria = Criteria::fromQuery(request: Query::from(parameters: ['filter' => 'a==1;b==2,c==3'])); /** @When serializing the criteria back to a URI */ $actual = $criteria->toUri(baseUri: '/v1/orders'); /** @Then the tighter-binding AND group is left unwrapped */ - self::assertSame('/v1/orders?filter=a==1;b==2,c==3&page=1&per_page=20', $actual); + self::assertSame('/v1/orders?filter=a==1;b==2,c==3&page[number]=1&page[size]=20', $actual); } public function testFromQueryWhenPerPageIsAtTheMaximumThenItIsAccepted(): void { /** @Given query parameters carrying a page size at the default maximum */ - $query = Query::from(parameters: ['per_page' => '100']); + $query = Query::from(parameters: ['page' => ['size' => '100']]); /** @When building the criteria from the query */ - $criteria = Criteria::fromQuery(query: $query); + $criteria = Criteria::fromQuery(request: $query); /** @Then the pagination is offset-based */ - self::assertInstanceOf(Pagination::class, $criteria->pagination()); + self::assertInstanceOf(OffsetPagination::class, $criteria->pagination()); /** @And it carries the maximum page size */ self::assertSame(100, $criteria->pagination()->limit()); } + public function testCursorPageWhenBuiltFromRequestThenReturnsCursorPage(): void + { + /** @Given a criteria parsed from a request carrying a page size of two */ + $criteria = Criteria::fromQuery(request: Query::from(parameters: ['page' => ['size' => '2']])); + + /** @When building a cursor page from the items fetched for the page size plus one */ + $page = $criteria->cursorPage(items: [10, 20, 30], keysOf: static fn(mixed $element): array => [$element]); + + /** @Then the result is a cursor page */ + self::assertInstanceOf(CursorPage::class, $page); + + /** @And the items are trimmed to the page size */ + self::assertSame([10, 20], $page->items()->toArray()); + } + + public function testOffsetPageWhenBuiltFromRequestThenReturnsOffsetPage(): void + { + /** @Given a criteria parsed from a request carrying a page size of three */ + $criteria = Criteria::fromQuery(request: Query::from(parameters: ['page' => ['size' => '3']])); + + /** @When building an offset page from the items and the total element count */ + $page = $criteria->offsetPage(items: ['a', 'b', 'c'], total: 30); + + /** @Then the result is an offset page */ + self::assertInstanceOf(OffsetPage::class, $page); + + /** @And it carries the total element count */ + self::assertSame(30, $page->total()); + } + public function testToUriWhenOrGroupNestedInAndThenWrapsItInParentheses(): void { /** @Given a criteria whose filter nests an OR group inside an AND group */ - $criteria = Criteria::fromQuery(query: Query::from(parameters: ['filter' => '(a==1,b==2);c==3'])); + $criteria = Criteria::fromQuery(request: Query::from(parameters: ['filter' => '(a==1,b==2);c==3'])); /** @When serializing the criteria back to a URI */ $actual = $criteria->toUri(baseUri: '/v1/orders'); /** @Then the nested OR group is wrapped in parentheses */ - self::assertSame('/v1/orders?filter=(a==1,b==2);c==3&page=1&per_page=20', $actual); + self::assertSame('/v1/orders?filter=(a==1,b==2);c==3&page[number]=1&page[size]=20', $actual); + } + + public function testOffsetSliceWhenBuiltFromRequestThenReturnsOffsetSlice(): void + { + /** @Given a criteria parsed from a request carrying a page size of three */ + $criteria = Criteria::fromQuery(request: Query::from(parameters: ['page' => ['size' => '3']])); + + /** @When building an offset slice from the items fetched for the page size plus one */ + $slice = $criteria->offsetSlice(items: ['a', 'b', 'c', 'd']); + + /** @Then the result is an offset slice */ + self::assertInstanceOf(OffsetSlice::class, $slice); + + /** @And it reports a next page from the trimmed extra element */ + self::assertTrue($slice->hasNext()); } public function testToUriWhenValueCarriesReservedCharactersThenItIsQuoted(): void { /** @Given a criteria whose filter value carries a space */ - $criteria = Criteria::fromQuery(query: Query::from(parameters: ['filter' => 'name=="John Doe"'])); + $criteria = Criteria::fromQuery(request: Query::from(parameters: ['filter' => 'name=="John Doe"'])); /** @When serializing the criteria back to a URI */ $actual = $criteria->toUri(baseUri: '/v1/orders'); /** @Then the value is rendered with surrounding double quotes */ - self::assertSame('/v1/orders?filter=name=="John Doe"&page=1&per_page=20', $actual); + self::assertSame('/v1/orders?filter=name=="John Doe"&page[number]=1&page[size]=20', $actual); } public function testFromQueryWhenCursorIsPresentThenPaginationIsCursorBased(): void { /** @Given query parameters carrying a cursor */ - $query = Query::from(parameters: ['cursor' => 'abc', 'per_page' => '10']); + $query = Query::from(parameters: ['page' => ['cursor' => 'abc', 'size' => '10']]); /** @When building the criteria from the query */ - $criteria = Criteria::fromQuery(query: $query); + $criteria = Criteria::fromQuery(request: $query); /** @Then the pagination is cursor-based */ self::assertInstanceOf(CursorPagination::class, $criteria->pagination()); @@ -128,13 +176,13 @@ public function testFromQueryWhenCursorIsPresentThenPaginationIsCursorBased(): v public function testToUriWhenValueCarriesQuoteAndBackslashThenBothAreEscaped(): void { /** @Given a criteria whose filter value carries a double quote and a backslash */ - $criteria = Criteria::fromQuery(query: Query::from(parameters: ['filter' => 'name=="a\"b\\\\c"'])); + $criteria = Criteria::fromQuery(request: Query::from(parameters: ['filter' => 'name=="a\"b\\\\c"'])); /** @When serializing the criteria back to a URI */ $actual = $criteria->toUri(baseUri: '/v1/orders'); /** @Then the quote and the backslash are escaped within the double-quoted value */ - self::assertSame('/v1/orders?filter=name=="a\"b\\\\c"&page=1&per_page=20', $actual); + self::assertSame('/v1/orders?filter=name=="a\"b\\\\c"&page[number]=1&page[size]=20', $actual); } public function testFromQueryWhenEmptyThenPaginationCarriesDefaultPageAndLimit(): void @@ -143,10 +191,10 @@ public function testFromQueryWhenEmptyThenPaginationCarriesDefaultPageAndLimit() $query = Query::from(parameters: []); /** @When building the criteria from the query */ - $criteria = Criteria::fromQuery(query: $query); + $criteria = Criteria::fromQuery(request: $query); /** @Then the pagination is offset-based */ - self::assertInstanceOf(Pagination::class, $criteria->pagination()); + self::assertInstanceOf(OffsetPagination::class, $criteria->pagination()); /** @And it starts at the first page */ self::assertSame(1, $criteria->pagination()->page()); @@ -158,95 +206,86 @@ public function testFromQueryWhenEmptyThenPaginationCarriesDefaultPageAndLimit() public function testWithPaginationWhenPageReplacedThenFilterAndSortArePreserved(): void { /** @Given a criteria parsed from a filter, a sort, a page, and a page size */ - $criteria = Criteria::fromQuery(query: Query::from(parameters: [ - 'sort' => '-created_at,id', - 'page' => '3', - 'filter' => 'status==paid', - 'per_page' => '20' + $criteria = Criteria::fromQuery(request: Query::from(parameters: [ + 'sort' => '-created_at,id', + 'page' => ['number' => '3', 'size' => '20'], + 'filter' => 'status==paid' ])); /** @And a replacement pagination pointing at a new page */ - $pagination = Pagination::fromPage(page: 5, perPage: 20); + $pagination = OffsetPagination::fromPage(page: 5, perPage: 20); /** @When replacing the pagination and serializing back to a URI */ $actual = $criteria->withPagination(pagination: $pagination)->toUri(baseUri: '/v1/orders'); /** @Then the URI keeps the filter and the sort while pointing at the new page */ - self::assertSame('/v1/orders?filter=status==paid&sort=-created_at,id&page=5&per_page=20', $actual); + self::assertSame('/v1/orders?filter=status==paid&sort=-created_at,id&page[number]=5&page[size]=20', $actual); } - public function testFromQueryWhenCustomSchemaGivenThenParsesAgainstTheCustomKeys(): void + public function testFromQueryWhenCustomSchemaGivenThenAppliesItsDefaultPageSize(): void { - /** @Given query parameters using custom key names */ - $query = Query::from(parameters: ['q' => 'name==bob', 'size' => '5', 'p' => '2']); + /** @Given query parameters carrying a page number without a page size */ + $query = Query::from(parameters: ['page' => ['number' => '2']]); - /** @And a schema mapping those custom key names */ - $schema = Schema::default() - ->withPageKey(pageKey: 'p') - ->withFilterKey(filterKey: 'q') - ->withPerPageKey(perPageKey: 'size'); + /** @And a schema lowering the default page size */ + $schema = Schema::default()->withDefaultPerPage(defaultPerPage: 5); /** @When building the criteria from the query and the schema */ - $criteria = Criteria::fromQuery(query: $query, schema: $schema); + $criteria = Criteria::fromQuery(request: $query, schema: $schema); /** @Then the pagination is offset-based */ - self::assertInstanceOf(Pagination::class, $criteria->pagination()); + self::assertInstanceOf(OffsetPagination::class, $criteria->pagination()); /** @And the pagination points at the requested page */ self::assertSame(2, $criteria->pagination()->page()); - /** @And the pagination carries the requested page size */ + /** @And the pagination carries the schema default page size */ self::assertSame(5, $criteria->pagination()->limit()); - - /** @And the filtering is a comparison */ - self::assertInstanceOf(Comparison::class, $criteria->filtering()); - - /** @And the comparison targets the filtered field */ - self::assertSame('name', $criteria->filtering()->field()); } public function testFromQueryWhenPerPageAboveMaximumThenThrowsPageSizeOutOfRange(): void { /** @Given query parameters carrying a page size above the default maximum */ - $query = Query::from(parameters: ['per_page' => '500']); + $query = Query::from(parameters: ['page' => ['size' => '500']]); /** @Then an exception indicating the page size is out of range is raised */ $this->expectException(PageSizeOutOfRange::class); $this->expectExceptionMessage('Page size'); /** @When building the criteria from the query */ - Criteria::fromQuery(query: $query); + Criteria::fromQuery(request: $query); } public function testToUriWhenFilterSortAndPageGivenThenRoundTripsToTheCanonicalUri(): void { /** @Given a criteria parsed from a filter, a sort, a page, and a page size */ - $criteria = Criteria::fromQuery(query: Query::from(parameters: [ - 'sort' => '-created_at,id', - 'page' => '3', - 'filter' => 'status==paid;total=ge=100', - 'per_page' => '20' + $criteria = Criteria::fromQuery(request: Query::from(parameters: [ + 'sort' => '-created_at,id', + 'page' => ['number' => '3', 'size' => '20'], + 'filter' => 'status==paid;total=ge=100' ])); /** @When serializing the criteria back to a URI */ $actual = $criteria->toUri(baseUri: '/v1/orders'); /** @Then the URI preserves the filter, the sort, and the pagination */ - self::assertSame('/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page=3&per_page=20', $actual); + self::assertSame( + '/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page[number]=3&page[size]=20', + $actual + ); } public function testFromQueryWhenFilterSortAndPageGivenThenEachSpecificationIsParsed(): void { /** @Given query parameters carrying a filter, a sort, a page, and a page size */ $query = Query::from(parameters: [ - 'sort' => '-created_at', - 'page' => '2', - 'filter' => 'status==paid', - 'per_page' => '15' + 'sort' => '-created_at', + 'page' => ['number' => '2', 'size' => '15'], + 'filter' => 'status==paid' ]); /** @When building the criteria from the query */ - $criteria = Criteria::fromQuery(query: $query); + $criteria = Criteria::fromQuery(request: $query); /** @Then the filtering is a comparison */ self::assertInstanceOf(Comparison::class, $criteria->filtering()); @@ -264,7 +303,7 @@ public function testFromQueryWhenFilterSortAndPageGivenThenEachSpecificationIsPa self::assertSame(Direction::DESCENDING, $criteria->sorting()->orders()[0]->direction()); /** @And the pagination is offset-based */ - self::assertInstanceOf(Pagination::class, $criteria->pagination()); + self::assertInstanceOf(OffsetPagination::class, $criteria->pagination()); /** @And it points at the requested page */ self::assertSame(2, $criteria->pagination()->page()); diff --git a/tests/Unit/CursorPageTest.php b/tests/Unit/CursorPageTest.php index f71bc80..8d1cafa 100644 --- a/tests/Unit/CursorPageTest.php +++ b/tests/Unit/CursorPageTest.php @@ -5,8 +5,10 @@ namespace Test\TinyBlocks\HttpQuery\Unit; use PHPUnit\Framework\TestCase; +use Test\TinyBlocks\HttpQuery\Models\Query; use TinyBlocks\Collection\Collection; use TinyBlocks\Http\LinkRelation; +use TinyBlocks\HttpQuery\Criteria; use TinyBlocks\HttpQuery\Cursor; use TinyBlocks\HttpQuery\CursorPage; use TinyBlocks\HttpQuery\CursorPagination; @@ -14,12 +16,60 @@ final class CursorPageTest extends TestCase { + private Criteria $criteria; + + protected function setUp(): void + { + $this->criteria = Criteria::fromQuery(request: Query::from(parameters: [])); + } + + public function testToResponseWhenCursorPageGivenThenRendersBodyAndLinkHeader(): void + { + /** @Given an opaque token produced from ordering key values */ + $token = Cursor::fromKeys(keys: [5])->toString(); + + /** @And query parameters carrying that cursor and a page size of two */ + $query = Query::from(parameters: ['page' => ['cursor' => $token, 'size' => '2']]); + + /** @And the criteria parsed from those parameters */ + $criteria = Criteria::fromQuery(request: $query); + + /** @And a cursor page built from the criteria over items fetched for the page size plus one */ + $page = $criteria->cursorPage(items: [10, 20, 30], keysOf: static fn(mixed $element): array => [$element]); + + /** @When rendering the cursor page as a JSON:API response over the orders base URI */ + $response = $page->toResponse(baseUri: '/v1/orders'); + + /** @Then the response body carries the trimmed data, the meta, and the keyset links */ + self::assertSame([ + 'data' => [10, 20], + 'meta' => [ + 'has_next' => true, + 'per_page' => 2, + 'has_previous' => true + ], + 'links' => [ + 'self' => sprintf('/v1/orders?page[cursor]=%s&page[size]=2', $token), + 'prev' => sprintf('/v1/orders?page[cursor]=%s&page[size]=2', Cursor::fromKeys(keys: [10])->toString()), + 'next' => sprintf('/v1/orders?page[cursor]=%s&page[size]=2', Cursor::fromKeys(keys: [20])->toString()) + ] + ], json_decode($response->getBody()->getContents(), true)); + + /** @And the Link header folds the self, previous, and next relations */ + self::assertSame(implode(', ', [ + sprintf('; rel="self"', $token), + sprintf('; rel="prev"', Cursor::fromKeys(keys: [10])->toString()), + sprintf('; rel="next"', Cursor::fromKeys(keys: [20])->toString()) + ]), $response->getHeaderLine('Link')); + } + public function testNavigationWhenExtraElementFetchedThenListsOnlyTheNextTarget(): void { /** @Given a keyset page fetched for the page size plus one with an absent incoming cursor */ $page = CursorPage::from( items: Collection::createFrom(elements: [10, 20, 30]), keysOf: static fn(mixed $element): array => [$element], + criteria: $this->criteria, pagination: CursorPagination::from(cursor: Cursor::none(), perPage: 2) ); @@ -51,6 +101,7 @@ public function testNavigationWhenExtraElementFetchedThenHasNextAndForwardCursor $page = CursorPage::from( items: $items, keysOf: static fn(mixed $element): array => [$element], + criteria: $this->criteria, pagination: $pagination ); @@ -63,22 +114,20 @@ public function testNavigationWhenExtraElementFetchedThenHasNextAndForwardCursor /** @And the page has no previous page */ self::assertFalse($page->hasPrevious()); - /** @And the forward cursor anchors on the last retained element */ - self::assertSame([20], $page->nextCursor()->toArray()); - - /** @And the forward cursor is present */ - self::assertFalse($page->nextCursor()->isAbsent()); + /** @And the next pagination anchors on the last retained element with the page size */ + self::assertEquals( + CursorPagination::from(cursor: Cursor::fromKeys(keys: [20]), perPage: 2), + $page->next() + ); - /** @And the backward cursor is absent */ - self::assertTrue($page->previousCursor()->isAbsent()); + /** @And there is no previous pagination */ + self::assertNull($page->previous()); - /** @And the metadata carries every navigation flag and cursor in declared key order */ + /** @And the metadata carries every navigation flag in length-ascending key order */ self::assertSame([ - 'has_next' => true, - 'per_page' => 2, - 'next_cursor' => Cursor::fromKeys(keys: [20])->toString(), - 'has_previous' => false, - 'previous_cursor' => null + 'has_next' => true, + 'per_page' => 2, + 'has_previous' => false ], $page->metadata()); } @@ -91,6 +140,7 @@ public function testNavigationWhenIncomingCursorAndNoExtraElementThenListsOnlyTh $page = CursorPage::from( items: Collection::createFrom(elements: [10, 20]), keysOf: static fn(mixed $element): array => [$element], + criteria: $this->criteria, pagination: CursorPagination::from(cursor: Cursor::from(token: $token), perPage: 2) ); @@ -125,6 +175,7 @@ public function testNavigationWhenNoExtraElementAndIncomingCursorThenNoNextAndBa $page = CursorPage::from( items: $items, keysOf: static fn(mixed $element): array => [$element], + criteria: $this->criteria, pagination: $pagination ); @@ -134,10 +185,20 @@ public function testNavigationWhenNoExtraElementAndIncomingCursorThenNoNextAndBa /** @And the page has a previous page */ self::assertTrue($page->hasPrevious()); - /** @And the forward cursor is absent */ - self::assertTrue($page->nextCursor()->isAbsent()); + /** @And there is no next pagination */ + self::assertNull($page->next()); - /** @And the backward cursor anchors on the first retained element */ - self::assertSame([10], $page->previousCursor()->toArray()); + /** @And the previous pagination anchors on the first retained element with the page size */ + self::assertEquals( + CursorPagination::from(cursor: Cursor::fromKeys(keys: [10]), perPage: 2), + $page->previous() + ); + + /** @And the metadata carries every navigation flag in length-ascending key order */ + self::assertSame([ + 'has_next' => false, + 'per_page' => 2, + 'has_previous' => true + ], $page->metadata()); } } diff --git a/tests/Unit/CursorPaginationTest.php b/tests/Unit/CursorPaginationTest.php index 7dd6ae4..afac42e 100644 --- a/tests/Unit/CursorPaginationTest.php +++ b/tests/Unit/CursorPaginationTest.php @@ -8,7 +8,6 @@ use TinyBlocks\HttpQuery\Cursor; use TinyBlocks\HttpQuery\CursorPagination; use TinyBlocks\HttpQuery\Exceptions\PageSizeOutOfRange; -use TinyBlocks\HttpQuery\Schema; final class CursorPaginationTest extends TestCase { @@ -24,16 +23,16 @@ public function testFromWhenPageSizeIsTheMinimumThenCarriesThatLimit(): void self::assertSame(1, $limit); } - public function testToQueryStringWhenCursorAbsentThenRendersOnlyPerPage(): void + public function testToQueryStringWhenCursorAbsentThenRendersOnlyTheSize(): void { /** @Given a cursor pagination carrying an absent cursor and a page size */ $pagination = CursorPagination::from(cursor: Cursor::none(), perPage: 10); - /** @When rendering it as a query string against the default schema */ - $queryString = $pagination->toQueryString(schema: Schema::default()); + /** @When rendering it as a query string */ + $queryString = $pagination->toQueryString(); - /** @Then it renders only the page size */ - self::assertSame('per_page=10', $queryString); + /** @Then it renders only the page size in the JSON:API page family */ + self::assertSame('page[size]=10', $queryString); } public function testFromWhenAbsentCursorGivenThenCarriesLimitAndAbsentCursor(): void @@ -63,16 +62,16 @@ public function testFromWhenPageSizeBelowMinimumThenThrowsPageSizeOutOfRange(): CursorPagination::from(cursor: $cursor, perPage: 0); } - public function testToQueryStringWhenCursorPresentThenRendersCursorAndPerPage(): void + public function testToQueryStringWhenCursorPresentThenRendersCursorAndSize(): void { /** @Given a cursor pagination carrying an incoming cursor and a page size */ $pagination = CursorPagination::from(cursor: Cursor::from(token: 'abc'), perPage: 10); - /** @When rendering it as a query string against the default schema */ - $queryString = $pagination->toQueryString(schema: Schema::default()); + /** @When rendering it as a query string */ + $queryString = $pagination->toQueryString(); - /** @Then it renders the cursor token followed by the page size */ - self::assertSame('cursor=abc&per_page=10', $queryString); + /** @Then it renders the cursor token followed by the page size in the JSON:API page family */ + self::assertSame('page[cursor]=abc&page[size]=10', $queryString); } public function testFromWhenIncomingCursorGivenThenCarriesLimitAndTheCursorToken(): void diff --git a/tests/Unit/EndToEndTest.php b/tests/Unit/EndToEndTest.php index 84524f3..b648b34 100644 --- a/tests/Unit/EndToEndTest.php +++ b/tests/Unit/EndToEndTest.php @@ -9,44 +9,133 @@ use TinyBlocks\Collection\Collection; use TinyBlocks\Collection\KeyPreservation; use TinyBlocks\HttpQuery\Criteria; +use TinyBlocks\HttpQuery\Cursor; use TinyBlocks\HttpQuery\Links; -use TinyBlocks\HttpQuery\Page; -use TinyBlocks\HttpQuery\Pagination; +use TinyBlocks\HttpQuery\OffsetPage; +use TinyBlocks\HttpQuery\OffsetPagination; final class EndToEndTest extends TestCase { + public function testPipelineWhenRequestGivenThenOffsetPageRendersResponse(): void + { + /** @Given the canonical request query parameters */ + $query = Query::from(parameters: [ + 'filter' => 'status==paid;total=ge=100', + 'sort' => '-created_at,id', + 'page' => ['number' => '3', 'size' => '20'] + ]); + + /** @And the criteria parsed from those parameters */ + $criteria = Criteria::fromQuery(request: $query); + + /** @And the base URI the navigation links render against */ + $base = '/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id'; + + /** @And the third page of a 480-element result built from the criteria */ + $page = $criteria->offsetPage(items: ['a', 'b'], total: 480); + + /** @When rendering the page as a JSON:API response over the orders base URI */ + $response = $page->toResponse(baseUri: '/v1/orders'); + + /** @Then the body carries the data, the meta, and the navigation links preserving filter and sort */ + self::assertSame([ + 'data' => ['a', 'b'], + 'meta' => [ + 'total' => 480, + 'has_next' => true, + 'per_page' => 20, + 'total_pages' => 24, + 'current_page' => 3, + 'has_previous' => true + ], + 'links' => [ + 'self' => sprintf('%s&page[number]=3&page[size]=20', $base), + 'first' => sprintf('%s&page[number]=1&page[size]=20', $base), + 'prev' => sprintf('%s&page[number]=2&page[size]=20', $base), + 'next' => sprintf('%s&page[number]=4&page[size]=20', $base), + 'last' => sprintf('%s&page[number]=24&page[size]=20', $base) + ] + ], json_decode($response->getBody()->getContents(), true)); + } + + public function testPipelineWhenCursorRequestGivenThenCursorPageRendersResponse(): void + { + /** @Given an opaque token produced from ordering key values */ + $token = Cursor::fromKeys(keys: [5])->toString(); + + /** @And query parameters carrying a sort, that cursor, and a page size of two */ + $query = Query::from(parameters: ['sort' => 'id', 'page' => ['cursor' => $token, 'size' => '2']]); + + /** @And the criteria parsed from those parameters */ + $criteria = Criteria::fromQuery(request: $query); + + /** @And a cursor page built from the criteria over items fetched for the page size plus one */ + $page = $criteria->cursorPage(items: [10, 20, 30], keysOf: static fn(mixed $element): array => [$element]); + + /** @And the base URI the keyset links render against */ + $base = '/v1/orders?sort=id'; + + /** @When rendering the cursor page as a JSON:API response over the orders base URI */ + $response = $page->toResponse(baseUri: '/v1/orders'); + + /** @Then the body carries the data, the meta, and the keyset links preserving the sort */ + self::assertSame([ + 'data' => [10, 20], + 'meta' => [ + 'has_next' => true, + 'per_page' => 2, + 'has_previous' => true + ], + 'links' => [ + 'self' => sprintf('%s&page[cursor]=%s&page[size]=2', $base, $token), + 'prev' => sprintf('%s&page[cursor]=%s&page[size]=2', $base, Cursor::fromKeys(keys: [10])->toString()), + 'next' => sprintf('%s&page[cursor]=%s&page[size]=2', $base, Cursor::fromKeys(keys: [20])->toString()) + ] + ], json_decode($response->getBody()->getContents(), true)); + } + public function testPipelineWhenCanonicalRequestGivenThenLinkHeaderFoldsEveryRelation(): void { /** @Given the canonical request query parameters */ $query = Query::from(parameters: [ - 'filter' => 'status==paid;total=ge=100', - 'sort' => '-created_at,id', - 'page' => '3', - 'per_page' => '20' + 'filter' => 'status==paid;total=ge=100', + 'sort' => '-created_at,id', + 'page' => ['number' => '3', 'size' => '20'] ]); /** @And the criteria parsed from those parameters */ - $criteria = Criteria::fromQuery(query: $query); + $criteria = Criteria::fromQuery(request: $query); /** @And the offset pagination pointing at the third page */ - $pagination = Pagination::fromPage(page: 3, perPage: 20); + $pagination = OffsetPagination::fromPage(page: 3, perPage: 20); /** @And the third page of a 480-element result */ - $page = Page::from(items: Collection::createFromEmpty(), total: 480, pagination: $pagination); + $page = OffsetPage::from( + items: Collection::createFromEmpty(), + total: 480, + criteria: $criteria, + pagination: $pagination + ); /** @And the navigation for that page over the orders base URI */ $links = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $page->navigation()); + /** @And the base URI the relations render against */ + $base = '/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id'; + + /** @And the Link header template rendered per relation */ + $template = '<%s&page[number]=%d&page[size]=20>; rel="%s"'; + /** @When rendering the RFC 8288 Link header line */ $header = $links->toHeader()->toArray()['Link'][0]; /** @Then the line folds the five relations in navigation order */ self::assertSame(implode(', ', [ - '; rel="self"', - '; rel="first"', - '; rel="prev"', - '; rel="next"', - '; rel="last"' + sprintf($template, $base, 3, 'self'), + sprintf($template, $base, 1, 'first'), + sprintf($template, $base, 2, 'prev'), + sprintf($template, $base, 4, 'next'), + sprintf($template, $base, 24, 'last') ]), $header); } @@ -54,24 +143,31 @@ public function testPipelineWhenCanonicalRequestGivenThenJsonBodyCarriesDataMeta { /** @Given the canonical request query parameters */ $query = Query::from(parameters: [ - 'filter' => 'status==paid;total=ge=100', - 'sort' => '-created_at,id', - 'page' => '3', - 'per_page' => '20' + 'filter' => 'status==paid;total=ge=100', + 'sort' => '-created_at,id', + 'page' => ['number' => '3', 'size' => '20'] ]); /** @And the criteria parsed from those parameters */ - $criteria = Criteria::fromQuery(query: $query); + $criteria = Criteria::fromQuery(request: $query); /** @And the offset pagination pointing at the third page */ - $pagination = Pagination::fromPage(page: 3, perPage: 20); + $pagination = OffsetPagination::fromPage(page: 3, perPage: 20); /** @And the third page of a 480-element result */ - $page = Page::from(items: Collection::createFromEmpty(), total: 480, pagination: $pagination); + $page = OffsetPage::from( + items: Collection::createFromEmpty(), + total: 480, + criteria: $criteria, + pagination: $pagination + ); /** @And the navigation for that page over the orders base URI */ $links = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $page->navigation()); + /** @And the base URI the navigation links render against */ + $base = '/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id'; + /** @When assembling the JSON:API body from the data, the meta, and the links */ $body = [ 'data' => $page->items()->toArray(keyPreservation: KeyPreservation::DISCARD), @@ -91,11 +187,11 @@ public function testPipelineWhenCanonicalRequestGivenThenJsonBodyCarriesDataMeta 'has_previous' => true ], 'links' => [ - 'self' => '/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page=3&per_page=20', - 'first' => '/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page=1&per_page=20', - 'prev' => '/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page=2&per_page=20', - 'next' => '/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page=4&per_page=20', - 'last' => '/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page=24&per_page=20' + 'self' => sprintf('%s&page[number]=3&page[size]=20', $base), + 'first' => sprintf('%s&page[number]=1&page[size]=20', $base), + 'prev' => sprintf('%s&page[number]=2&page[size]=20', $base), + 'next' => sprintf('%s&page[number]=4&page[size]=20', $base), + 'last' => sprintf('%s&page[number]=24&page[size]=20', $base) ] ], $body); } diff --git a/tests/Unit/FilterTest.php b/tests/Unit/FilterTest.php index 8f24150..a8f9aaa 100644 --- a/tests/Unit/FilterTest.php +++ b/tests/Unit/FilterTest.php @@ -60,7 +60,7 @@ public function testFilteringWhenNoFilterGivenThenReturnsEmptyGroup(): void $query = Query::from(parameters: []); /** @When reading the filtering specification */ - $filter = Criteria::fromQuery(query: $query)->filtering(); + $filter = Criteria::fromQuery(request: $query)->filtering(); /** @Then the filter is an empty group joined by the AND connective */ self::assertEquals(Group::of(filters: [], operator: LogicalOperator::AND), $filter); @@ -72,7 +72,7 @@ public function testFilteringWhenOrGivenThenGroupJoinsTwoComparisons(): void $query = Query::from(parameters: ['filter' => 'a==1,b==2']); /** @When reading the filtering specification */ - $filter = Criteria::fromQuery(query: $query)->filtering(); + $filter = Criteria::fromQuery(request: $query)->filtering(); /** @Then the filter is an OR group joining the two comparison children in order */ self::assertEquals(Group::of(filters: [ @@ -87,7 +87,7 @@ public function testFilteringWhenAndGivenThenGroupJoinsTwoComparisons(): void $query = Query::from(parameters: ['filter' => 'a==1;b==2']); /** @When reading the filtering specification */ - $filter = Criteria::fromQuery(query: $query)->filtering(); + $filter = Criteria::fromQuery(request: $query)->filtering(); /** @Then the filter is an AND group joining the two comparison children in order */ self::assertEquals(Group::of(filters: [ @@ -102,7 +102,7 @@ public function testFilteringWhenInListGivenThenComparisonCarriesEveryValue(): v $query = Query::from(parameters: ['filter' => 'role=in=(admin,user)']); /** @When reading the filtering specification */ - $filter = Criteria::fromQuery(query: $query)->filtering(); + $filter = Criteria::fromQuery(request: $query)->filtering(); /** @Then the filter is an IN comparison carrying every listed value in order */ self::assertEquals(Comparison::of(field: 'role', values: ['admin', 'user'], operator: Operator::IN), $filter); @@ -156,7 +156,7 @@ public function testFilteringWhenMixedPrecedenceGivenThenAndBindsTighterThanOr() $query = Query::from(parameters: ['filter' => 'a==1;b==2,c==3']); /** @When reading the filtering specification */ - $filter = Criteria::fromQuery(query: $query)->filtering(); + $filter = Criteria::fromQuery(request: $query)->filtering(); /** @Then the top filter is an OR group whose first child is the tighter AND group */ self::assertEquals(Group::of(filters: [ @@ -174,7 +174,7 @@ public function testFilteringWhenNotInListGivenThenComparisonCarriesEveryValue() $query = Query::from(parameters: ['filter' => 'role=out=(a,b)']); /** @When reading the filtering specification */ - $filter = Criteria::fromQuery(query: $query)->filtering(); + $filter = Criteria::fromQuery(request: $query)->filtering(); /** @Then the filter is a NOT_IN comparison carrying every listed value in order */ self::assertEquals(Comparison::of(field: 'role', values: ['a', 'b'], operator: Operator::NOT_IN), $filter); @@ -219,7 +219,7 @@ public function testFilteringWhenDoubleQuotedValueGivenThenComparisonStripsQuote $query = Query::from(parameters: ['filter' => 'name=="John Doe"']); /** @When reading the filtering specification */ - $filter = Criteria::fromQuery(query: $query)->filtering(); + $filter = Criteria::fromQuery(request: $query)->filtering(); /** @Then the comparison carries the value with the surrounding quotes stripped */ self::assertEquals(Comparison::of(field: 'name', values: ['John Doe'], operator: Operator::EQUAL), $filter); @@ -231,7 +231,7 @@ public function testFilteringWhenSingleQuotedValueGivenThenComparisonStripsQuote $query = Query::from(parameters: ['filter' => "name=='John Doe'"]); /** @When reading the filtering specification */ - $filter = Criteria::fromQuery(query: $query)->filtering(); + $filter = Criteria::fromQuery(request: $query)->filtering(); /** @Then the comparison carries the value with the surrounding quotes stripped */ self::assertEquals(Comparison::of(field: 'name', values: ['John Doe'], operator: Operator::EQUAL), $filter); @@ -255,7 +255,7 @@ public function testFilteringWhenExplicitGroupingGivenThenParenthesesOverridePre $query = Query::from(parameters: ['filter' => '(a==1,b==2);c==3']); /** @When reading the filtering specification */ - $filter = Criteria::fromQuery(query: $query)->filtering(); + $filter = Criteria::fromQuery(request: $query)->filtering(); /** @Then the top filter is an AND group whose first child is the parenthesized OR group */ self::assertEquals(Group::of(filters: [ @@ -273,7 +273,7 @@ public function testFilteringWhenSingleComparisonGivenThenComparisonCarriesField $query = Query::from(parameters: ['filter' => 'status==paid']); /** @When reading the filtering specification */ - $filter = Criteria::fromQuery(query: $query)->filtering(); + $filter = Criteria::fromQuery(request: $query)->filtering(); /** @Then the filter is an equality comparison on the named field with its value */ self::assertEquals(Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL), $filter); @@ -288,7 +288,7 @@ public function testFilteringWhenComparisonOperatorGivenThenComparisonCarriesTha $query = Query::from(parameters: ['filter' => $expression]); /** @When reading the filtering specification */ - $filter = Criteria::fromQuery(query: $query)->filtering(); + $filter = Criteria::fromQuery(request: $query)->filtering(); /** @Then the filter is a comparison on the left field carrying the expected operator */ self::assertEquals(Comparison::of(field: 'a', values: ['b'], operator: $expected), $filter); @@ -306,7 +306,7 @@ public function testFilteringWhenMalformedExpressionGivenThenThrowsFilterExpress $this->expectExceptionMessage('could not be parsed'); /** @When building the criteria from the query */ - Criteria::fromQuery(query: $query); + Criteria::fromQuery(request: $query); } public function testValuesWhenComparisonGivenThenReturnsTheComparedValues(): void diff --git a/tests/Unit/LinksTest.php b/tests/Unit/LinksTest.php index 6962eed..f272f17 100644 --- a/tests/Unit/LinksTest.php +++ b/tests/Unit/LinksTest.php @@ -12,24 +12,25 @@ use TinyBlocks\HttpQuery\CursorPage; use TinyBlocks\HttpQuery\CursorPagination; use TinyBlocks\HttpQuery\Links; -use TinyBlocks\HttpQuery\Page; -use TinyBlocks\HttpQuery\Pagination; -use TinyBlocks\HttpQuery\Slice; +use TinyBlocks\HttpQuery\OffsetPage; +use TinyBlocks\HttpQuery\OffsetPagination; +use TinyBlocks\HttpQuery\OffsetSlice; final class LinksTest extends TestCase { public function testToArrayWhenPageIsTheLastThenOmitsTheNextRelation(): void { /** @Given an offset pagination pointing at the last page */ - $pagination = Pagination::fromPage(page: 24, perPage: 20); + $pagination = OffsetPagination::fromPage(page: 24, perPage: 20); /** @And a criteria over that pagination */ - $criteria = Criteria::fromQuery(query: Query::from(parameters: []))->withPagination(pagination: $pagination); + $criteria = Criteria::fromQuery(request: Query::from(parameters: []))->withPagination(pagination: $pagination); /** @And a page carrying a total spanning twenty-four pages */ - $result = Page::from( + $result = OffsetPage::from( items: Collection::createFrom(elements: range(1, 20)), total: 480, + criteria: $criteria, pagination: $pagination ); @@ -38,53 +39,58 @@ public function testToArrayWhenPageIsTheLastThenOmitsTheNextRelation(): void /** @Then the navigation exposes the self, first, previous, and last relations in that order */ self::assertSame([ - 'self' => '/v1/orders?page=24&per_page=20', - 'first' => '/v1/orders?page=1&per_page=20', - 'prev' => '/v1/orders?page=23&per_page=20', - 'last' => '/v1/orders?page=24&per_page=20' + 'self' => '/v1/orders?page[number]=24&page[size]=20', + 'first' => '/v1/orders?page[number]=1&page[size]=20', + 'prev' => '/v1/orders?page[number]=23&page[size]=20', + 'last' => '/v1/orders?page[number]=24&page[size]=20' ], $links->toArray()); /** @And the navigation carries no next relation */ self::assertArrayNotHasKey('next', $links->toArray()); } - public function testToArrayWhenSliceMiddleThenExposesSelfPrevAndNext(): void + public function testToArrayWhenSliceMiddleThenExposesSelfFirstPrevAndNext(): void { /** @Given an offset pagination pointing at a middle page */ - $pagination = Pagination::fromPage(page: 3, perPage: 20); + $pagination = OffsetPagination::fromPage(page: 3, perPage: 20); /** @And a criteria carrying a filter and a sort over that pagination */ - $criteria = Criteria::fromQuery(query: Query::from(parameters: [ + $criteria = Criteria::fromQuery(request: Query::from(parameters: [ 'sort' => '-created_at,id', 'filter' => 'status==paid' ]))->withPagination(pagination: $pagination); /** @And a slice fetched for the page size plus one so a next page exists */ - $result = Slice::from(items: Collection::createFrom(elements: range(1, 21)), pagination: $pagination); + $result = OffsetSlice::from( + items: Collection::createFrom(elements: range(1, 21)), + criteria: $criteria, + pagination: $pagination + ); /** @When rendering the navigation for the slice */ $links = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $result->navigation()); - /** @Then the navigation exposes the self, previous, and next relations preserving filter and sort */ + /** @Then the navigation exposes the self, first, previous, and next relations preserving filter and sort */ self::assertSame([ - 'self' => '/v1/orders?filter=status==paid&sort=-created_at,id&page=3&per_page=20', - 'prev' => '/v1/orders?filter=status==paid&sort=-created_at,id&page=2&per_page=20', - 'next' => '/v1/orders?filter=status==paid&sort=-created_at,id&page=4&per_page=20' + 'self' => '/v1/orders?filter=status==paid&sort=-created_at,id&page[number]=3&page[size]=20', + 'first' => '/v1/orders?filter=status==paid&sort=-created_at,id&page[number]=1&page[size]=20', + 'prev' => '/v1/orders?filter=status==paid&sort=-created_at,id&page[number]=2&page[size]=20', + 'next' => '/v1/orders?filter=status==paid&sort=-created_at,id&page[number]=4&page[size]=20' ], $links->toArray()); } public function testToArrayWhenCursorResultThenExposesOnlySelfAndNext(): void { /** @Given a cursor criteria carrying an incoming cursor token and a page size of two */ - $criteria = Criteria::fromQuery(query: Query::from(parameters: [ - 'cursor' => Cursor::fromKeys(keys: [5])->toString(), - 'per_page' => '2' + $criteria = Criteria::fromQuery(request: Query::from(parameters: [ + 'page' => ['cursor' => Cursor::fromKeys(keys: [5])->toString(), 'size' => '2'] ])); /** @And a cursor page fetched for the page size plus one with no incoming cursor */ $result = CursorPage::from( items: Collection::createFrom(elements: [10, 20, 30]), keysOf: static fn(mixed $element): array => [$element], + criteria: $criteria, pagination: CursorPagination::from(cursor: Cursor::none(), perPage: 2) ); @@ -93,23 +99,24 @@ public function testToArrayWhenCursorResultThenExposesOnlySelfAndNext(): void /** @Then the navigation exposes only the self and next relations */ self::assertSame([ - 'self' => sprintf('/v1/orders?cursor=%s&per_page=2', Cursor::fromKeys(keys: [5])->toString()), - 'next' => sprintf('/v1/orders?cursor=%s&per_page=2', Cursor::fromKeys(keys: [20])->toString()) + 'self' => sprintf('/v1/orders?page[cursor]=%s&page[size]=2', Cursor::fromKeys(keys: [5])->toString()), + 'next' => sprintf('/v1/orders?page[cursor]=%s&page[size]=2', Cursor::fromKeys(keys: [20])->toString()) ], $links->toArray()); } public function testToArrayWhenPageIsTheFirstThenOmitsThePreviousRelation(): void { /** @Given an offset pagination pointing at the first page */ - $pagination = Pagination::fromPage(page: 1, perPage: 20); + $pagination = OffsetPagination::fromPage(page: 1, perPage: 20); /** @And a criteria over that pagination */ - $criteria = Criteria::fromQuery(query: Query::from(parameters: []))->withPagination(pagination: $pagination); + $criteria = Criteria::fromQuery(request: Query::from(parameters: []))->withPagination(pagination: $pagination); /** @And a page carrying a total spanning twenty-four pages */ - $result = Page::from( + $result = OffsetPage::from( items: Collection::createFrom(elements: range(1, 20)), total: 480, + criteria: $criteria, pagination: $pagination ); @@ -118,32 +125,36 @@ public function testToArrayWhenPageIsTheFirstThenOmitsThePreviousRelation(): voi /** @Then the navigation exposes the self, first, next, and last relations in that order */ self::assertSame([ - 'self' => '/v1/orders?page=1&per_page=20', - 'first' => '/v1/orders?page=1&per_page=20', - 'next' => '/v1/orders?page=2&per_page=20', - 'last' => '/v1/orders?page=24&per_page=20' + 'self' => '/v1/orders?page[number]=1&page[size]=20', + 'first' => '/v1/orders?page[number]=1&page[size]=20', + 'next' => '/v1/orders?page[number]=2&page[size]=20', + 'last' => '/v1/orders?page[number]=24&page[size]=20' ], $links->toArray()); /** @And the navigation carries no previous relation */ self::assertArrayNotHasKey('prev', $links->toArray()); } - public function testToArrayWhenSliceMiddleThenCarriesNoFirstOrLastRelation(): void + public function testToArrayWhenSliceMiddleThenCarriesAFirstButNoLastRelation(): void { /** @Given an offset pagination pointing at a middle page */ - $pagination = Pagination::fromPage(page: 3, perPage: 20); + $pagination = OffsetPagination::fromPage(page: 3, perPage: 20); /** @And a criteria over that pagination */ - $criteria = Criteria::fromQuery(query: Query::from(parameters: []))->withPagination(pagination: $pagination); + $criteria = Criteria::fromQuery(request: Query::from(parameters: []))->withPagination(pagination: $pagination); /** @And a slice fetched for the page size plus one so a next page exists */ - $result = Slice::from(items: Collection::createFrom(elements: range(1, 21)), pagination: $pagination); + $result = OffsetSlice::from( + items: Collection::createFrom(elements: range(1, 21)), + criteria: $criteria, + pagination: $pagination + ); /** @When rendering the navigation for the slice */ $links = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $result->navigation()); - /** @Then the navigation carries no first relation */ - self::assertArrayNotHasKey('first', $links->toArray()); + /** @Then the navigation carries a first relation */ + self::assertArrayHasKey('first', $links->toArray()); /** @And the navigation carries no last relation */ self::assertArrayNotHasKey('last', $links->toArray()); @@ -152,15 +163,15 @@ public function testToArrayWhenSliceMiddleThenCarriesNoFirstOrLastRelation(): vo public function testToArrayWhenCursorResultThenCarriesNoFirstOrLastOrPreviousRelation(): void { /** @Given a cursor criteria carrying an incoming cursor token and a page size of two */ - $criteria = Criteria::fromQuery(query: Query::from(parameters: [ - 'cursor' => Cursor::fromKeys(keys: [5])->toString(), - 'per_page' => '2' + $criteria = Criteria::fromQuery(request: Query::from(parameters: [ + 'page' => ['cursor' => Cursor::fromKeys(keys: [5])->toString(), 'size' => '2'] ])); /** @And a cursor page fetched for the page size plus one with no incoming cursor */ $result = CursorPage::from( items: Collection::createFrom(elements: [10, 20, 30]), keysOf: static fn(mixed $element): array => [$element], + criteria: $criteria, pagination: CursorPagination::from(cursor: Cursor::none(), perPage: 2) ); @@ -180,18 +191,19 @@ public function testToArrayWhenCursorResultThenCarriesNoFirstOrLastOrPreviousRel public function testToHeaderWhenPageInTheMiddleThenFoldsEveryRelationIntoOneCommaJoinedValue(): void { /** @Given an offset pagination pointing at a middle page */ - $pagination = Pagination::fromPage(page: 3, perPage: 20); + $pagination = OffsetPagination::fromPage(page: 3, perPage: 20); /** @And a criteria carrying a filter and a sort over that pagination */ - $criteria = Criteria::fromQuery(query: Query::from(parameters: [ + $criteria = Criteria::fromQuery(request: Query::from(parameters: [ 'sort' => '-created_at,id', 'filter' => 'status==paid' ]))->withPagination(pagination: $pagination); /** @And a page carrying a total spanning twenty-four pages */ - $result = Page::from( + $result = OffsetPage::from( items: Collection::createFrom(elements: range(1, 20)), total: 480, + criteria: $criteria, pagination: $pagination ); @@ -201,29 +213,30 @@ public function testToHeaderWhenPageInTheMiddleThenFoldsEveryRelationIntoOneComm /** @Then every present relation is folded into one comma-joined Link header value */ self::assertSame(['Link' => [implode(', ', [ - '; rel="self"', - '; rel="first"', - '; rel="prev"', - '; rel="next"', - '; rel="last"' + '; rel="self"', + '; rel="first"', + '; rel="prev"', + '; rel="next"', + '; rel="last"' ])]], $header->toArray()); } public function testToArrayWhenPageInTheMiddleThenExposesEveryRelationPreservingFilterAndSort(): void { /** @Given an offset pagination pointing at a middle page */ - $pagination = Pagination::fromPage(page: 3, perPage: 20); + $pagination = OffsetPagination::fromPage(page: 3, perPage: 20); /** @And a criteria carrying a filter and a sort over that pagination */ - $criteria = Criteria::fromQuery(query: Query::from(parameters: [ + $criteria = Criteria::fromQuery(request: Query::from(parameters: [ 'sort' => '-created_at,id', 'filter' => 'status==paid' ]))->withPagination(pagination: $pagination); /** @And a page carrying a total spanning twenty-four pages */ - $result = Page::from( + $result = OffsetPage::from( items: Collection::createFrom(elements: range(1, 20)), total: 480, + criteria: $criteria, pagination: $pagination ); @@ -232,11 +245,11 @@ public function testToArrayWhenPageInTheMiddleThenExposesEveryRelationPreserving /** @Then the navigation exposes every relation in semantic order preserving filter and sort */ self::assertSame([ - 'self' => '/v1/orders?filter=status==paid&sort=-created_at,id&page=3&per_page=20', - 'first' => '/v1/orders?filter=status==paid&sort=-created_at,id&page=1&per_page=20', - 'prev' => '/v1/orders?filter=status==paid&sort=-created_at,id&page=2&per_page=20', - 'next' => '/v1/orders?filter=status==paid&sort=-created_at,id&page=4&per_page=20', - 'last' => '/v1/orders?filter=status==paid&sort=-created_at,id&page=24&per_page=20' + 'self' => '/v1/orders?filter=status==paid&sort=-created_at,id&page[number]=3&page[size]=20', + 'first' => '/v1/orders?filter=status==paid&sort=-created_at,id&page[number]=1&page[size]=20', + 'prev' => '/v1/orders?filter=status==paid&sort=-created_at,id&page[number]=2&page[size]=20', + 'next' => '/v1/orders?filter=status==paid&sort=-created_at,id&page[number]=4&page[size]=20', + 'last' => '/v1/orders?filter=status==paid&sort=-created_at,id&page[number]=24&page[size]=20' ], $links->toArray()); } } diff --git a/tests/Unit/PageTest.php b/tests/Unit/OffsetPageTest.php similarity index 58% rename from tests/Unit/PageTest.php rename to tests/Unit/OffsetPageTest.php index de0122c..7d024c9 100644 --- a/tests/Unit/PageTest.php +++ b/tests/Unit/OffsetPageTest.php @@ -5,23 +5,32 @@ namespace Test\TinyBlocks\HttpQuery\Unit; use PHPUnit\Framework\TestCase; +use Test\TinyBlocks\HttpQuery\Models\Query; use TinyBlocks\Collection\Collection; use TinyBlocks\Collection\KeyPreservation; use TinyBlocks\Http\LinkRelation; +use TinyBlocks\HttpQuery\Criteria; use TinyBlocks\HttpQuery\Exceptions\TotalIsNegative; use TinyBlocks\HttpQuery\NavigationTarget; -use TinyBlocks\HttpQuery\Page; -use TinyBlocks\HttpQuery\Pagination; +use TinyBlocks\HttpQuery\OffsetPage; +use TinyBlocks\HttpQuery\OffsetPagination; -final class PageTest extends TestCase +final class OffsetPageTest extends TestCase { + private Criteria $criteria; + + protected function setUp(): void + { + $this->criteria = Criteria::fromQuery(request: Query::from(parameters: [])); + } + public function testNavigationWhenTotalIsZeroThenThereIsNoPage(): void { /** @Given a pagination on the first page */ - $pagination = Pagination::fromPage(page: 1, perPage: 20); + $pagination = OffsetPagination::fromPage(page: 1, perPage: 20); /** @When building the page from a total of zero */ - $page = Page::from(items: Collection::createFromEmpty(), total: 0, pagination: $pagination); + $page = OffsetPage::from(items: [], total: 0, criteria: $this->criteria, pagination: $pagination); /** @Then there are no pages */ self::assertSame(0, $page->totalPages()); @@ -49,10 +58,10 @@ public function testNavigationWhenTotalIsZeroThenThereIsNoPage(): void public function testNavigationWhenLastPageGivenThenHasNoNextPage(): void { /** @Given a pagination on the last page */ - $pagination = Pagination::fromPage(page: 24, perPage: 20); + $pagination = OffsetPagination::fromPage(page: 24, perPage: 20); /** @When building the page from the total element count */ - $page = Page::from(items: Collection::createFrom(elements: ['a', 'b']), total: 480, pagination: $pagination); + $page = OffsetPage::from(items: ['a', 'b'], total: 480, criteria: $this->criteria, pagination: $pagination); /** @Then the page reports no next page */ self::assertFalse($page->hasNext()); @@ -70,59 +79,41 @@ public function testNavigationWhenLastPageGivenThenHasNoNextPage(): void self::assertSame(24, $page->last()?->page()); } - public function testItemsWhenPageGivenThenReturnsTheSameCollection(): void + public function testItemsWhenPageGivenThenCarriesTheProvidedItems(): void { /** @Given a collection of items */ $items = Collection::createFrom(elements: ['a', 'b']); /** @And a pagination on the third page */ - $pagination = Pagination::fromPage(page: 3, perPage: 20); + $pagination = OffsetPagination::fromPage(page: 3, perPage: 20); /** @When building the page and reading its items */ - $page = Page::from(items: $items, total: 480, pagination: $pagination); - - /** @Then the items are the same collection that was provided */ - self::assertSame($items, $page->items()); - } - - public function testTotalWhenPageGivenThenReturnsTheTotalElementCount(): void - { - /** @Given a collection of items */ - $items = Collection::createFrom(elements: ['a', 'b']); - - /** @And a pagination on the first page */ - $pagination = Pagination::fromPage(page: 1, perPage: 20); - - /** @When building the page from the total element count */ - $page = Page::from(items: $items, total: 480, pagination: $pagination); + $page = OffsetPage::from(items: $items, total: 480, criteria: $this->criteria, pagination: $pagination); - /** @Then the total is the count provided across every page */ - self::assertSame(480, $page->total()); + /** @Then the items carry the provided elements */ + self::assertSame(['a', 'b'], $page->items()->toArray(keyPreservation: KeyPreservation::DISCARD)); } public function testFromWhenTotalIsNegativeThenThrowsTotalIsNegative(): void { - /** @Given an empty collection of items */ - $items = Collection::createFromEmpty(); - - /** @And a pagination on the first page */ - $pagination = Pagination::fromPage(page: 1, perPage: 20); + /** @Given a pagination on the first page */ + $pagination = OffsetPagination::fromPage(page: 1, perPage: 20); /** @Then an exception indicating the total is negative is raised */ $this->expectException(TotalIsNegative::class); $this->expectExceptionMessage('Total'); /** @When building a page from a negative total */ - Page::from(items: $items, total: -1, pagination: $pagination); + OffsetPage::from(items: [], total: -1, criteria: $this->criteria, pagination: $pagination); } public function testNavigationWhenFirstPageGivenThenHasNoPreviousPage(): void { /** @Given a pagination on the first page */ - $pagination = Pagination::fromPage(page: 1, perPage: 20); + $pagination = OffsetPagination::fromPage(page: 1, perPage: 20); /** @When building the page from the total element count */ - $page = Page::from(items: Collection::createFrom(elements: ['a', 'b']), total: 480, pagination: $pagination); + $page = OffsetPage::from(items: ['a', 'b'], total: 480, criteria: $this->criteria, pagination: $pagination); /** @Then the page reports no previous page */ self::assertFalse($page->hasPrevious()); @@ -146,13 +137,28 @@ public function testNavigationWhenFirstPageGivenThenHasNoPreviousPage(): void self::assertSame(24, $page->last()?->page()); } + public function testTotalWhenPageGivenThenReturnsTheTotalElementCount(): void + { + /** @Given a collection of items */ + $items = Collection::createFrom(elements: ['a', 'b']); + + /** @And a pagination on the first page */ + $pagination = OffsetPagination::fromPage(page: 1, perPage: 20); + + /** @When building the page from the total element count */ + $page = OffsetPage::from(items: $items, total: 480, criteria: $this->criteria, pagination: $pagination); + + /** @Then the total is the count provided across every page */ + self::assertSame(480, $page->total()); + } + public function testTotalPagesWhenTotalIsNotAMultipleOfPerPageThenRoundsUp(): void { /** @Given a pagination on the first page */ - $pagination = Pagination::fromPage(page: 1, perPage: 20); + $pagination = OffsetPagination::fromPage(page: 1, perPage: 20); /** @When building the page from a total that is not a multiple of the page size */ - $page = Page::from(items: Collection::createFrom(elements: ['a', 'b']), total: 21, pagination: $pagination); + $page = OffsetPage::from(items: ['a', 'b'], total: 21, criteria: $this->criteria, pagination: $pagination); /** @Then the total number of pages rounds the division up */ self::assertSame(2, $page->totalPages()); @@ -161,10 +167,10 @@ public function testTotalPagesWhenTotalIsNotAMultipleOfPerPageThenRoundsUp(): vo public function testMetadataWhenMiddlePageGivenThenCarriesEveryFlagAndCount(): void { /** @Given a pagination on a middle page */ - $pagination = Pagination::fromPage(page: 3, perPage: 20); + $pagination = OffsetPagination::fromPage(page: 3, perPage: 20); /** @When building the page from the total element count */ - $page = Page::from(items: Collection::createFrom(elements: ['a', 'b']), total: 480, pagination: $pagination); + $page = OffsetPage::from(items: ['a', 'b'], total: 480, criteria: $this->criteria, pagination: $pagination); /** @Then the metadata carries every navigation flag and count in length-ascending key order */ self::assertSame([ @@ -179,12 +185,11 @@ public function testMetadataWhenMiddlePageGivenThenCarriesEveryFlagAndCount(): v public function testNavigationWhenFirstPageGivenThenOmitsThePreviousRelation(): void { - /** @Given a page on the first page of a multi-page result */ - $page = Page::from( - items: Collection::createFromEmpty(), - total: 480, - pagination: Pagination::fromPage(page: 1, perPage: 20) - ); + /** @Given a pagination on the first page of a multi-page result */ + $pagination = OffsetPagination::fromPage(page: 1, perPage: 20); + + /** @And a page on that first page */ + $page = OffsetPage::from(items: [], total: 480, criteria: $this->criteria, pagination: $pagination); /** @When reading the relations of the navigation targets */ $relations = $page->navigation()->targets() @@ -195,13 +200,57 @@ public function testNavigationWhenFirstPageGivenThenOmitsThePreviousRelation(): self::assertSame(['first', 'next', 'last'], $relations); } + public function testToResponseWhenMiddlePageGivenThenRendersBodyAndLinkHeader(): void + { + /** @Given query parameters on the third page with a page size of twenty */ + $query = Query::from(parameters: ['page' => ['number' => '3', 'size' => '20']]); + + /** @And the criteria parsed from those parameters */ + $criteria = Criteria::fromQuery(request: $query); + + /** @And a page built from the criteria over items keyed by their positions */ + $page = $criteria->offsetPage(items: [5 => 'a', 9 => 'b'], total: 480); + + /** @When rendering the page as a JSON:API response over the orders base URI */ + $response = $page->toResponse(baseUri: '/v1/orders'); + + /** @Then the response body carries the zero-based data, the meta, and the navigation links */ + self::assertSame([ + 'data' => ['a', 'b'], + 'meta' => [ + 'total' => 480, + 'has_next' => true, + 'per_page' => 20, + 'total_pages' => 24, + 'current_page' => 3, + 'has_previous' => true + ], + 'links' => [ + 'self' => '/v1/orders?page[number]=3&page[size]=20', + 'first' => '/v1/orders?page[number]=1&page[size]=20', + 'prev' => '/v1/orders?page[number]=2&page[size]=20', + 'next' => '/v1/orders?page[number]=4&page[size]=20', + 'last' => '/v1/orders?page[number]=24&page[size]=20' + ] + ], json_decode($response->getBody()->getContents(), true)); + + /** @And the Link header folds every relation in navigation order */ + self::assertSame(implode(', ', [ + '; rel="self"', + '; rel="first"', + '; rel="prev"', + '; rel="next"', + '; rel="last"' + ]), $response->getHeaderLine('Link')); + } + public function testNavigationWhenMiddlePageGivenThenExposesEverySurroundingPage(): void { /** @Given a pagination on a middle page */ - $pagination = Pagination::fromPage(page: 3, perPage: 20); + $pagination = OffsetPagination::fromPage(page: 3, perPage: 20); /** @When building the page from the total element count */ - $page = Page::from(items: Collection::createFrom(elements: ['a', 'b']), total: 480, pagination: $pagination); + $page = OffsetPage::from(items: ['a', 'b'], total: 480, criteria: $this->criteria, pagination: $pagination); /** @Then the current page number is preserved */ self::assertSame(3, $page->currentPage()); @@ -239,12 +288,11 @@ public function testNavigationWhenMiddlePageGivenThenExposesEverySurroundingPage public function testNavigationWhenMiddlePageGivenThenListsFirstPreviousNextAndLastTargets(): void { - /** @Given a page on a middle page of a multi-page result */ - $page = Page::from( - items: Collection::createFromEmpty(), - total: 480, - pagination: Pagination::fromPage(page: 3, perPage: 20) - ); + /** @Given a pagination on a middle page of a multi-page result */ + $pagination = OffsetPagination::fromPage(page: 3, perPage: 20); + + /** @And a page on that middle page */ + $page = OffsetPage::from(items: [], total: 480, criteria: $this->criteria, pagination: $pagination); /** @When reading the relations of the navigation targets */ $relations = $page->navigation()->targets() @@ -257,19 +305,21 @@ public function testNavigationWhenMiddlePageGivenThenListsFirstPreviousNextAndLa public function testNavigationWhenMiddlePageGivenThenTheNextTargetPointsAtTheFollowingPage(): void { - /** @Given a page on a middle page of a multi-page result */ - $page = Page::from( - items: Collection::createFromEmpty(), - total: 480, - pagination: Pagination::fromPage(page: 3, perPage: 20) - ); + /** @Given a pagination on a middle page of a multi-page result */ + $pagination = OffsetPagination::fromPage(page: 3, perPage: 20); + + /** @And a page on that middle page */ + $page = OffsetPage::from(items: [], total: 480, criteria: $this->criteria, pagination: $pagination); /** @When reading the first navigation target */ $target = $page->navigation()->targets()->first(); /** @Then the first target is the first page reached through the first relation */ self::assertEquals( - NavigationTarget::to(target: Pagination::fromPage(page: 1, perPage: 20), relation: LinkRelation::FIRST), + NavigationTarget::to( + target: OffsetPagination::fromPage(page: 1, perPage: 20), + relation: LinkRelation::FIRST + ), $target ); } diff --git a/tests/Unit/PaginationTest.php b/tests/Unit/OffsetPaginationTest.php similarity index 79% rename from tests/Unit/PaginationTest.php rename to tests/Unit/OffsetPaginationTest.php index db4fa77..91e8f3d 100644 --- a/tests/Unit/PaginationTest.php +++ b/tests/Unit/OffsetPaginationTest.php @@ -8,15 +8,14 @@ use TinyBlocks\HttpQuery\Exceptions\OffsetOutOfRange; use TinyBlocks\HttpQuery\Exceptions\PageNumberOutOfRange; use TinyBlocks\HttpQuery\Exceptions\PageSizeOutOfRange; -use TinyBlocks\HttpQuery\Pagination; -use TinyBlocks\HttpQuery\Schema; +use TinyBlocks\HttpQuery\OffsetPagination; -final class PaginationTest extends TestCase +final class OffsetPaginationTest extends TestCase { public function testFromOffsetWhenLimitIsOneThenLimitIsOne(): void { /** @When building a pagination from the minimum limit */ - $pagination = Pagination::fromOffset(offset: 0, limit: 1); + $pagination = OffsetPagination::fromOffset(offset: 0, limit: 1); /** @Then the limit equals the minimum limit */ self::assertSame(1, $pagination->limit()); @@ -25,7 +24,7 @@ public function testFromOffsetWhenLimitIsOneThenLimitIsOne(): void public function testFromPageWhenPerPageIsOneThenLimitIsOne(): void { /** @When building a pagination from the minimum page size */ - $pagination = Pagination::fromPage(page: 1, perPage: 1); + $pagination = OffsetPagination::fromPage(page: 1, perPage: 1); /** @Then the limit equals the minimum page size */ self::assertSame(1, $pagination->limit()); @@ -34,7 +33,7 @@ public function testFromPageWhenPerPageIsOneThenLimitIsOne(): void public function testFromOffsetWhenZeroOffsetGivenThenPageIsOne(): void { /** @When building a pagination from a zero offset */ - $pagination = Pagination::fromOffset(offset: 0, limit: 20); + $pagination = OffsetPagination::fromOffset(offset: 0, limit: 20); /** @Then the page number is one */ self::assertSame(1, $pagination->page()); @@ -49,7 +48,7 @@ public function testFromOffsetWhenZeroOffsetGivenThenPageIsOne(): void public function testFromPageWhenFirstPageGivenThenOffsetIsZero(): void { /** @When building a pagination from the first page */ - $pagination = Pagination::fromPage(page: 1, perPage: 20); + $pagination = OffsetPagination::fromPage(page: 1, perPage: 20); /** @Then the page number is one */ self::assertSame(1, $pagination->page()); @@ -64,7 +63,7 @@ public function testFromPageWhenFirstPageGivenThenOffsetIsZero(): void public function testFromPageWhenThirdPageGivenThenOffsetIsDerived(): void { /** @When building a pagination from the third page */ - $pagination = Pagination::fromPage(page: 3, perPage: 20); + $pagination = OffsetPagination::fromPage(page: 3, perPage: 20); /** @Then the page number is three */ self::assertSame(3, $pagination->page()); @@ -79,7 +78,7 @@ public function testFromPageWhenThirdPageGivenThenOffsetIsDerived(): void public function testFromOffsetWhenAlignedOffsetGivenThenPageIsDerived(): void { /** @When building a pagination from an offset aligned to the limit */ - $pagination = Pagination::fromOffset(offset: 40, limit: 20); + $pagination = OffsetPagination::fromOffset(offset: 40, limit: 20); /** @Then the page number is derived from the offset and the limit */ self::assertSame(3, $pagination->page()); @@ -94,7 +93,7 @@ public function testFromOffsetWhenAlignedOffsetGivenThenPageIsDerived(): void public function testFromOffsetWhenUnalignedOffsetGivenThenPageIsFloored(): void { /** @When building a pagination from an offset that is not aligned to the limit */ - $pagination = Pagination::fromOffset(offset: 45, limit: 20); + $pagination = OffsetPagination::fromOffset(offset: 45, limit: 20); /** @Then the page number floors the offset division and adds one */ self::assertSame(3, $pagination->page()); @@ -106,16 +105,16 @@ public function testFromOffsetWhenUnalignedOffsetGivenThenPageIsFloored(): void self::assertSame(20, $pagination->limit()); } - public function testToQueryStringWhenPageGivenThenRendersPageAndPerPage(): void + public function testToQueryStringWhenPageGivenThenRendersPageNumberAndSize(): void { /** @Given an offset pagination on the third page */ - $pagination = Pagination::fromPage(page: 3, perPage: 20); + $pagination = OffsetPagination::fromPage(page: 3, perPage: 20); - /** @When rendering it as a query string against the default schema */ - $queryString = $pagination->toQueryString(schema: Schema::default()); + /** @When rendering it as a query string */ + $queryString = $pagination->toQueryString(); - /** @Then it renders the page number and the page size */ - self::assertSame('page=3&per_page=20', $queryString); + /** @Then it renders the page number and the page size in the JSON:API page family */ + self::assertSame('page[number]=3&page[size]=20', $queryString); } public function testFromPageWhenPageBelowOneGivenThenPageNumberOutOfRange(): void @@ -125,7 +124,7 @@ public function testFromPageWhenPageBelowOneGivenThenPageNumberOutOfRange(): voi $this->expectExceptionMessage('Page number'); /** @When building a pagination from a page number below one */ - Pagination::fromPage(page: 0, perPage: 20); + OffsetPagination::fromPage(page: 0, perPage: 20); } public function testFromOffsetWhenLimitBelowOneGivenThenPageSizeOutOfRange(): void @@ -135,7 +134,7 @@ public function testFromOffsetWhenLimitBelowOneGivenThenPageSizeOutOfRange(): vo $this->expectExceptionMessage('Page size'); /** @When building a pagination from a limit below one */ - Pagination::fromOffset(offset: 0, limit: 0); + OffsetPagination::fromOffset(offset: 0, limit: 0); } public function testFromOffsetWhenOffsetBelowZeroGivenThenOffsetOutOfRange(): void @@ -145,7 +144,7 @@ public function testFromOffsetWhenOffsetBelowZeroGivenThenOffsetOutOfRange(): vo $this->expectExceptionMessage('Offset'); /** @When building a pagination from an offset below zero */ - Pagination::fromOffset(offset: -1, limit: 20); + OffsetPagination::fromOffset(offset: -1, limit: 20); } public function testFromPageWhenPerPageBelowOneGivenThenPageSizeOutOfRange(): void @@ -155,6 +154,6 @@ public function testFromPageWhenPerPageBelowOneGivenThenPageSizeOutOfRange(): vo $this->expectExceptionMessage('Page size'); /** @When building a pagination from a page size below one */ - Pagination::fromPage(page: 1, perPage: 0); + OffsetPagination::fromPage(page: 1, perPage: 0); } } diff --git a/tests/Unit/OffsetSliceTest.php b/tests/Unit/OffsetSliceTest.php new file mode 100644 index 0000000..a648051 --- /dev/null +++ b/tests/Unit/OffsetSliceTest.php @@ -0,0 +1,231 @@ +criteria = Criteria::fromQuery(request: Query::from(parameters: [])); + } + + public function testToResponseWhenSliceGivenThenRendersBodyAndLinkHeader(): void + { + /** @Given query parameters on the second page with a page size of three */ + $query = Query::from(parameters: ['page' => ['number' => '2', 'size' => '3']]); + + /** @And the criteria parsed from those parameters */ + $criteria = Criteria::fromQuery(request: $query); + + /** @And a slice built from the criteria over items fetched for the page size plus one */ + $slice = $criteria->offsetSlice(items: ['a', 'b', 'c', 'd']); + + /** @When rendering the slice as a JSON:API response over the orders base URI */ + $response = $slice->toResponse(baseUri: '/v1/orders'); + + /** @Then the response body carries the trimmed data, the meta, and the navigation links */ + self::assertSame([ + 'data' => ['a', 'b', 'c'], + 'meta' => [ + 'has_next' => true, + 'per_page' => 3, + 'current_page' => 2, + 'has_previous' => true + ], + 'links' => [ + 'self' => '/v1/orders?page[number]=2&page[size]=3', + 'first' => '/v1/orders?page[number]=1&page[size]=3', + 'prev' => '/v1/orders?page[number]=1&page[size]=3', + 'next' => '/v1/orders?page[number]=3&page[size]=3' + ] + ], json_decode($response->getBody()->getContents(), true)); + + /** @And the Link header folds the self, first, previous, and next relations */ + self::assertSame(implode(', ', [ + '; rel="self"', + '; rel="first"', + '; rel="prev"', + '; rel="next"' + ]), $response->getHeaderLine('Link')); + } + + public function testOffsetWhenSecondPageGivenThenReturnsTheZeroBasedOffset(): void + { + /** @Given a pagination on the second page with a page size of three */ + $pagination = OffsetPagination::fromPage(page: 2, perPage: 3); + + /** @And items fetched for the page size plus one */ + $items = Collection::createFrom(elements: ['a', 'b', 'c', 'd']); + + /** @When building the slice from the items and the pagination */ + $slice = OffsetSlice::from(items: $items, criteria: $this->criteria, pagination: $pagination); + + /** @Then the offset is derived from the page and the page size */ + self::assertSame(3, $slice->offset()); + } + + public function testNavigationWhenExtraElementFetchedThenHasNextAndTrimsItems(): void + { + /** @Given a pagination on the second page with a page size of three */ + $pagination = OffsetPagination::fromPage(page: 2, perPage: 3); + + /** @And items fetched for the page size plus one */ + $items = Collection::createFrom(elements: ['a', 'b', 'c', 'd']); + + /** @When building the slice from the items and the pagination */ + $slice = OffsetSlice::from(items: $items, criteria: $this->criteria, pagination: $pagination); + + /** @Then the slice reports a next page */ + self::assertTrue($slice->hasNext()); + + /** @And the items are trimmed to the page size */ + self::assertSame(['a', 'b', 'c'], $slice->items()->toArray(keyPreservation: KeyPreservation::DISCARD)); + + /** @And the current page number is preserved */ + self::assertSame(2, $slice->currentPage()); + + /** @And the slice has a previous page */ + self::assertTrue($slice->hasPrevious()); + + /** @And the first pagination points at the first page */ + self::assertSame(1, $slice->first()->page()); + + /** @And the next pagination points at the third page */ + self::assertSame(3, $slice->next()?->page()); + + /** @And the previous pagination points at the first page */ + self::assertSame(1, $slice->previous()?->page()); + + /** @And the metadata carries every navigation flag and count in length-ascending key order */ + self::assertSame([ + 'has_next' => true, + 'per_page' => 3, + 'current_page' => 2, + 'has_previous' => true + ], $slice->metadata()); + } + + public function testNavigationWhenNoExtraElementOnFirstPageThenNoNextAndNoPrevious(): void + { + /** @Given a pagination on the first page with a page size of three */ + $pagination = OffsetPagination::fromPage(page: 1, perPage: 3); + + /** @And items fetched within the page size */ + $items = Collection::createFrom(elements: ['a', 'b', 'c']); + + /** @When building the slice from the items and the pagination */ + $slice = OffsetSlice::from(items: $items, criteria: $this->criteria, pagination: $pagination); + + /** @Then the slice reports no next page */ + self::assertFalse($slice->hasNext()); + + /** @And the items keep every fetched element */ + self::assertSame(['a', 'b', 'c'], $slice->items()->toArray(keyPreservation: KeyPreservation::DISCARD)); + + /** @And the next pagination is null */ + self::assertNull($slice->next()); + + /** @And the slice has no previous page */ + self::assertFalse($slice->hasPrevious()); + + /** @And the previous pagination is null */ + self::assertNull($slice->previous()); + + /** @And the first pagination still points at the first page */ + self::assertSame(1, $slice->first()->page()); + } + + public function testNavigationWhenMiddlePageGivenThenListsFirstPreviousAndNextRelations(): void + { + /** @Given a slice on a middle page fetched for the page size plus one */ + $slice = OffsetSlice::from( + items: Collection::createFrom(elements: ['a', 'b', 'c', 'd']), + criteria: $this->criteria, + pagination: OffsetPagination::fromPage(page: 2, perPage: 3) + ); + + /** @When reading the relations of the navigation targets */ + $relations = $slice->navigation()->targets() + ->map(transformations: static fn(NavigationTarget $target): string => $target->relation()->value) + ->toArray(keyPreservation: KeyPreservation::DISCARD); + + /** @Then it lists the first, previous, and next relations in that order */ + self::assertSame(['first', 'prev', 'next'], $relations); + } + + public function testNavigationWhenMiddlePageGivenThenTheFirstTargetPointsAtTheFirstPage(): void + { + /** @Given a slice on a middle page fetched for the page size plus one */ + $slice = OffsetSlice::from( + items: Collection::createFrom(elements: ['a', 'b', 'c', 'd']), + criteria: $this->criteria, + pagination: OffsetPagination::fromPage(page: 2, perPage: 3) + ); + + /** @When reading the first navigation target */ + $target = $slice->navigation()->targets()->first(); + + /** @Then the first target is the first page reached through the first relation */ + self::assertEquals( + NavigationTarget::to( + target: OffsetPagination::fromPage(page: 1, perPage: 3), + relation: LinkRelation::FIRST + ), + $target + ); + } + + public function testNavigationWhenMiddlePageGivenThenTheNextTargetPointsAtTheFollowingPage(): void + { + /** @Given a slice on a middle page fetched for the page size plus one */ + $slice = OffsetSlice::from( + items: Collection::createFrom(elements: ['a', 'b', 'c', 'd']), + criteria: $this->criteria, + pagination: OffsetPagination::fromPage(page: 2, perPage: 3) + ); + + /** @When reading the last navigation target */ + $target = $slice->navigation()->targets()->last(); + + /** @Then the last target is the third page reached through the next relation */ + self::assertEquals( + NavigationTarget::to( + target: OffsetPagination::fromPage(page: 3, perPage: 3), + relation: LinkRelation::NEXT + ), + $target + ); + } + + public function testNavigationWhenFirstPageWithoutExtraElementThenListsOnlyTheFirstRelation(): void + { + /** @Given a slice on the first page fetched within the page size */ + $slice = OffsetSlice::from( + items: Collection::createFrom(elements: ['a', 'b', 'c']), + criteria: $this->criteria, + pagination: OffsetPagination::fromPage(page: 1, perPage: 3) + ); + + /** @When reading the relations of the navigation targets */ + $relations = $slice->navigation()->targets() + ->map(transformations: static fn(NavigationTarget $target): string => $target->relation()->value) + ->toArray(keyPreservation: KeyPreservation::DISCARD); + + /** @Then it lists only the first relation */ + self::assertSame(['first'], $relations); + } +} diff --git a/tests/Unit/SchemaTest.php b/tests/Unit/SchemaTest.php index d41a554..e814575 100644 --- a/tests/Unit/SchemaTest.php +++ b/tests/Unit/SchemaTest.php @@ -10,54 +10,6 @@ final class SchemaTest extends TestCase { - public function testDefaultThenCarriesTheCanonicalPageKey(): void - { - /** @Given the default schema */ - $schema = Schema::default(); - - /** @When reading the page key */ - $actual = $schema->pageKey(); - - /** @Then it is the canonical page key */ - self::assertSame('page', $actual); - } - - public function testDefaultThenCarriesTheCanonicalSortKey(): void - { - /** @Given the default schema */ - $schema = Schema::default(); - - /** @When reading the sort key */ - $actual = $schema->sortKey(); - - /** @Then it is the canonical sort key */ - self::assertSame('sort', $actual); - } - - public function testDefaultThenCarriesTheCanonicalCursorKey(): void - { - /** @Given the default schema */ - $schema = Schema::default(); - - /** @When reading the cursor key */ - $actual = $schema->cursorKey(); - - /** @Then it is the canonical cursor key */ - self::assertSame('cursor', $actual); - } - - public function testDefaultThenCarriesTheCanonicalFilterKey(): void - { - /** @Given the default schema */ - $schema = Schema::default(); - - /** @When reading the filter key */ - $actual = $schema->filterKey(); - - /** @Then it is the canonical filter key */ - self::assertSame('filter', $actual); - } - public function testDefaultThenCarriesTheCanonicalMaxPerPage(): void { /** @Given the default schema */ @@ -70,18 +22,6 @@ public function testDefaultThenCarriesTheCanonicalMaxPerPage(): void self::assertSame(100, $actual); } - public function testDefaultThenCarriesTheCanonicalPerPageKey(): void - { - /** @Given the default schema */ - $schema = Schema::default(); - - /** @When reading the per-page key */ - $actual = $schema->perPageKey(); - - /** @Then it is the canonical per-page key */ - self::assertSame('per_page', $actual); - } - public function testDefaultThenCarriesTheCanonicalDefaultPerPage(): void { /** @Given the default schema */ @@ -185,66 +125,6 @@ public function testWithDefaultPerPageWhenBelowMinimumThenThrowsPageSizeOutOfRan $schema->withDefaultPerPage(defaultPerPage: 0); } - public function testWithPageKeyWhenReplacedThenCopyCarriesItAndOriginalIsUnchanged(): void - { - /** @Given the default schema */ - $schema = Schema::default(); - - /** @When replacing the page key */ - $copy = $schema->withPageKey(pageKey: 'p'); - - /** @Then the copy carries the new page key */ - self::assertSame('p', $copy->pageKey()); - - /** @And the original schema keeps the canonical page key */ - self::assertSame('page', $schema->pageKey()); - } - - public function testWithSortKeyWhenReplacedThenCopyCarriesItAndOriginalIsUnchanged(): void - { - /** @Given the default schema */ - $schema = Schema::default(); - - /** @When replacing the sort key */ - $copy = $schema->withSortKey(sortKey: 'order'); - - /** @Then the copy carries the new sort key */ - self::assertSame('order', $copy->sortKey()); - - /** @And the original schema keeps the canonical sort key */ - self::assertSame('sort', $schema->sortKey()); - } - - public function testWithCursorKeyWhenReplacedThenCopyCarriesItAndOriginalIsUnchanged(): void - { - /** @Given the default schema */ - $schema = Schema::default(); - - /** @When replacing the cursor key */ - $copy = $schema->withCursorKey(cursorKey: 'after'); - - /** @Then the copy carries the new cursor key */ - self::assertSame('after', $copy->cursorKey()); - - /** @And the original schema keeps the canonical cursor key */ - self::assertSame('cursor', $schema->cursorKey()); - } - - public function testWithFilterKeyWhenReplacedThenCopyCarriesItAndOriginalIsUnchanged(): void - { - /** @Given the default schema */ - $schema = Schema::default(); - - /** @When replacing the filter key */ - $copy = $schema->withFilterKey(filterKey: 'q'); - - /** @Then the copy carries the new filter key */ - self::assertSame('q', $copy->filterKey()); - - /** @And the original schema keeps the canonical filter key */ - self::assertSame('filter', $schema->filterKey()); - } - public function testWithMaxPerPageWhenReplacedThenCopyCarriesItAndOriginalIsUnchanged(): void { /** @Given the default schema */ @@ -260,21 +140,6 @@ public function testWithMaxPerPageWhenReplacedThenCopyCarriesItAndOriginalIsUnch self::assertSame(100, $schema->maxPerPage()); } - public function testWithPerPageKeyWhenReplacedThenCopyCarriesItAndOriginalIsUnchanged(): void - { - /** @Given the default schema */ - $schema = Schema::default(); - - /** @When replacing the per-page key */ - $copy = $schema->withPerPageKey(perPageKey: 'size'); - - /** @Then the copy carries the new per-page key */ - self::assertSame('size', $copy->perPageKey()); - - /** @And the original schema keeps the canonical per-page key */ - self::assertSame('per_page', $schema->perPageKey()); - } - public function testWithDefaultPerPageWhenReplacedThenCopyCarriesItAndOriginalIsUnchanged(): void { /** @Given the default schema */ diff --git a/tests/Unit/SliceTest.php b/tests/Unit/SliceTest.php deleted file mode 100644 index 32ca8db..0000000 --- a/tests/Unit/SliceTest.php +++ /dev/null @@ -1,148 +0,0 @@ -hasNext()); - - /** @And the items are trimmed to the page size */ - self::assertSame(['a', 'b', 'c'], $slice->items()->toArray(keyPreservation: KeyPreservation::DISCARD)); - - /** @And the current page number is preserved */ - self::assertSame(2, $slice->currentPage()); - - /** @And the slice has a previous page */ - self::assertTrue($slice->hasPrevious()); - - /** @And the next pagination points at the third page */ - self::assertSame(3, $slice->next()?->page()); - - /** @And the previous pagination points at the first page */ - self::assertSame(1, $slice->previous()?->page()); - - /** @And the metadata carries every navigation flag and count in length-ascending key order */ - self::assertSame([ - 'has_next' => true, - 'per_page' => 3, - 'current_page' => 2, - 'has_previous' => true - ], $slice->metadata()); - } - - public function testOffsetWhenSecondPageGivenThenReturnsTheZeroBasedOffset(): void - { - /** @Given a pagination on the second page with a page size of three */ - $pagination = Pagination::fromPage(page: 2, perPage: 3); - - /** @And items fetched for the page size plus one */ - $items = Collection::createFrom(elements: ['a', 'b', 'c', 'd']); - - /** @When building the slice from the items and the pagination */ - $slice = Slice::from(items: $items, pagination: $pagination); - - /** @Then the offset is derived from the page and the page size */ - self::assertSame(3, $slice->offset()); - } - - public function testNavigationWhenFirstPageWithoutExtraElementThenListsNoRelation(): void - { - /** @Given a slice on the first page fetched within the page size */ - $slice = Slice::from( - items: Collection::createFrom(elements: ['a', 'b', 'c']), - pagination: Pagination::fromPage(page: 1, perPage: 3) - ); - - /** @When reading the relations of the navigation targets */ - $relations = $slice->navigation()->targets() - ->map(transformations: static fn(NavigationTarget $target): string => $target->relation()->value) - ->toArray(keyPreservation: KeyPreservation::DISCARD); - - /** @Then it lists no relation */ - self::assertSame([], $relations); - } - - public function testNavigationWhenMiddlePageGivenThenListsPreviousAndNextRelations(): void - { - /** @Given a slice on a middle page fetched for the page size plus one */ - $slice = Slice::from( - items: Collection::createFrom(elements: ['a', 'b', 'c', 'd']), - pagination: Pagination::fromPage(page: 2, perPage: 3) - ); - - /** @When reading the relations of the navigation targets */ - $relations = $slice->navigation()->targets() - ->map(transformations: static fn(NavigationTarget $target): string => $target->relation()->value) - ->toArray(keyPreservation: KeyPreservation::DISCARD); - - /** @Then it lists the previous and next relations in that order */ - self::assertSame(['prev', 'next'], $relations); - } - - public function testNavigationWhenNoExtraElementOnFirstPageThenNoNextAndNoPrevious(): void - { - /** @Given a pagination on the first page with a page size of three */ - $pagination = Pagination::fromPage(page: 1, perPage: 3); - - /** @And items fetched within the page size */ - $items = Collection::createFrom(elements: ['a', 'b', 'c']); - - /** @When building the slice from the items and the pagination */ - $slice = Slice::from(items: $items, pagination: $pagination); - - /** @Then the slice reports no next page */ - self::assertFalse($slice->hasNext()); - - /** @And the items keep every fetched element */ - self::assertSame(['a', 'b', 'c'], $slice->items()->toArray(keyPreservation: KeyPreservation::DISCARD)); - - /** @And the next pagination is null */ - self::assertNull($slice->next()); - - /** @And the slice has no previous page */ - self::assertFalse($slice->hasPrevious()); - - /** @And the previous pagination is null */ - self::assertNull($slice->previous()); - } - - public function testNavigationWhenMiddlePageGivenThenTheNextTargetPointsAtTheFollowingPage(): void - { - /** @Given a slice on a middle page fetched for the page size plus one */ - $slice = Slice::from( - items: Collection::createFrom(elements: ['a', 'b', 'c', 'd']), - pagination: Pagination::fromPage(page: 2, perPage: 3) - ); - - /** @When reading the last navigation target */ - $target = $slice->navigation()->targets()->last(); - - /** @Then the last target is the third page reached through the next relation */ - self::assertEquals( - NavigationTarget::to(target: Pagination::fromPage(page: 3, perPage: 3), relation: LinkRelation::NEXT), - $target - ); - } -} From 057b7d2645d5c8e286b46a8cd7e4603f274287af Mon Sep 17 00:00:00 2001 From: Gustavo Freze Date: Mon, 8 Jun 2026 15:21:42 -0300 Subject: [PATCH 03/14] refactor: Simplify Criteria class by removing pagination handling and related methods. --- README.md | 63 +++++------ phpstan.neon.dist | 2 +- src/Criteria.php | 54 +-------- src/Cursor.php | 2 +- src/CursorPage.php | 2 +- src/Internal/{ => Cursor}/CursorCodec.php | 2 +- src/Internal/{ => Cursor}/Keyset.php | 3 +- src/Internal/{ => Offset}/Offset.php | 3 +- src/Internal/{ => Offset}/OffsetNavigator.php | 3 +- src/Internal/{ => Offset}/PageCount.php | 4 +- src/Internal/{ => Offset}/PageNumber.php | 3 +- src/Internal/{ => Offset}/Total.php | 3 +- src/Internal/Uri.php | 36 ++++++ src/Links.php | 16 ++- src/OffsetPage.php | 10 +- src/OffsetPagination.php | 4 +- src/OffsetSlice.php | 6 +- tests/Unit/CriteriaTest.php | 86 -------------- tests/Unit/CursorTest.php | 2 +- tests/Unit/FilterTest.php | 12 ++ tests/Unit/LinksTest.php | 107 +++++++----------- 21 files changed, 161 insertions(+), 262 deletions(-) rename src/Internal/{ => Cursor}/CursorCodec.php (94%) rename src/Internal/{ => Cursor}/Keyset.php (95%) rename src/Internal/{ => Offset}/Offset.php (87%) rename src/Internal/{ => Offset}/OffsetNavigator.php (94%) rename src/Internal/{ => Offset}/PageCount.php (86%) rename src/Internal/{ => Offset}/PageNumber.php (91%) rename src/Internal/{ => Offset}/Total.php (86%) create mode 100644 src/Internal/Uri.php diff --git a/README.md b/README.md index 2c279ba..a589b3a 100644 --- a/README.md +++ b/README.md @@ -26,12 +26,6 @@ store, and it renders the response the consumer returns. Every computation is O( consumer supplies. The pagination style stays internal: the `Criteria` builds the result page, so the public API never exposes a concrete pagination type. -It builds on the [tiny-blocks](https://github.com/tiny-blocks) ecosystem: it reads the query parameters of a PSR-7 -request through [`tiny-blocks/http`](https://github.com/tiny-blocks/http), carries items in a -[`tiny-blocks/collection`](https://github.com/tiny-blocks/collection) `Collection`, encodes cursors through -[`tiny-blocks/encoder`](https://github.com/tiny-blocks/encoder), and renders the response and its `Link` header with the -`Response`, `Link`, and `LinkRelation` types from `tiny-blocks/http`. - ## Installation ```bash @@ -120,7 +114,8 @@ A malformed expression raises `SortExpressionIsInvalid`. ### Offset pagination -When no cursor is present, `Criteria::offsetPage` builds an `OffsetPage` from the items of the current page and the total +When no cursor is present, `Criteria::offsetPage` builds an `OffsetPage` from the items of the current page and the +total element count. The page derives the offset and the total pages from the request, so the consumer never builds the pagination itself. The items are any `iterable`, and `items()` returns them as a `Collection`. @@ -140,11 +135,12 @@ $criteria = Criteria::fromQuery(request: $request); $page = $criteria->offsetPage(items: $items, total: 480); $page->hasNext(); # true +$page->metadata(); # The JSON:API meta contents $page->totalPages(); # 24 -$page->metadata(); # the JSON:API meta contents ``` -Use `Criteria::offsetSlice` instead of `Criteria::offsetPage` when the total is unknown. The consumer fetches one element +Use `Criteria::offsetSlice` instead of `Criteria::offsetPage` when the total is unknown. The consumer fetches one +element beyond the page size, and the `OffsetSlice` trims it and reads its presence as the next-page hint. ```php @@ -162,7 +158,7 @@ $criteria = Criteria::fromQuery(request: $request); /** @var iterable $items */ $slice = $criteria->offsetSlice(items: $items); -$slice->hasNext(); # inferred from the extra fetched element +$slice->hasNext(); # Inferred from the extra fetched element ``` ### Cursor pagination @@ -189,9 +185,9 @@ $cursorPage = $criteria->cursorPage( keysOf: static fn(array $order): array => [$order['created_at'], $order['id']] ); -$cursorPage->hasNext(); # Inferred from the extra fetched element -$cursorPage->next(); # The CursorPagination for the next page, or null -$cursorPage->previous(); # The CursorPagination for the previous page, or null +$cursorPage->next(); # The CursorPagination for the next page, or null. +$cursorPage->hasNext(); # Inferred from the extra fetched element. +$cursorPage->previous(); # The CursorPagination for the previous page, or null. ``` An invalid cursor token raises `CursorIsInvalid` when it is decoded. @@ -218,8 +214,8 @@ $response = $criteria->offsetPage(items: $items, total: 480)->toResponse(baseUri ``` For full control over the body, assemble it from the parts. `Links::from` reads the navigation a result exposes through -`result->navigation()`, swaps the criteria's pagination for each target, and serializes it back through `Criteria::toUri`, -so the filter and the sort are preserved in every URI. `toArray()` returns the JSON:API body `links` object and +`result->navigation()` and builds each URI from the criteria's filter and sort plus the pagination of every target, so +the filter and the sort are preserved in every URI. `toArray()` returns the JSON:API body `links` object and `toHeader()` returns an RFC 8288 `Link`. ```php @@ -251,22 +247,22 @@ The body carries the navigation with the filter and the sort preserved in every ```json { - "data": [], - "meta": { - "total": 480, - "has_next": true, - "per_page": 20, - "total_pages": 24, - "current_page": 3, - "has_previous": true - }, - "links": { - "self": "/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page[number]=3&page[size]=20", - "first": "/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page[number]=1&page[size]=20", - "prev": "/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page[number]=2&page[size]=20", - "next": "/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page[number]=4&page[size]=20", - "last": "/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page[number]=24&page[size]=20" - } + "data": [], + "meta": { + "total": 480, + "has_next": true, + "per_page": 20, + "total_pages": 24, + "current_page": 3, + "has_previous": true + }, + "links": { + "self": "/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page[number]=3&page[size]=20", + "first": "/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page[number]=1&page[size]=20", + "prev": "/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page[number]=2&page[size]=20", + "next": "/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page[number]=4&page[size]=20", + "last": "/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page[number]=24&page[size]=20" + } } ``` @@ -347,11 +343,6 @@ Cursor pagination answers "give me the next slice after this point" without a to and avoids the drift of offset pagination under concurrent writes. The library models both, plus an `OffsetSlice` for offset navigation without a total. -### 04. How are the `meta` keys ordered? - -The keys are snake_case and ordered by key length ascending, with an alphabetical tiebreak. The order is fixed so the -serialized response is deterministic across requests. - ## License Http Query is licensed under [MIT](LICENSE). diff --git a/phpstan.neon.dist b/phpstan.neon.dist index dc7a292..a4367a3 100644 --- a/phpstan.neon.dist +++ b/phpstan.neon.dist @@ -28,7 +28,7 @@ parameters: path: src/Cursor.php # The cursor codec encodes and decodes opaque key values whose types are not known. - identifier: missingType.iterableValue - path: src/Internal/CursorCodec.php + path: src/Internal/Cursor/CursorCodec.php # Test fixtures and data providers carry raw arrays at the test boundary. - identifier: missingType.iterableValue path: tests diff --git a/src/Criteria.php b/src/Criteria.php index a94e816..ddd93cd 100644 --- a/src/Criteria.php +++ b/src/Criteria.php @@ -19,18 +19,13 @@ /** * Umbrella specification of a collection query, pairing filtering, sorting, and pagination. * - *

    It parses from the request query string and serializes back to a URI, so the navigation links - * built from it preserve the filter and the sort. It also builds the result page for the items the - * store returns, keeping the pagination style internal.

    + *

    It parses from the request query string and builds the result page for the items the store + * returns, keeping the pagination style internal.

    */ final readonly class Criteria { - private function __construct( - private PageParameters $page, - private Sort $sort, - private Filter $filter, - private Pagination $pagination - ) { + private function __construct(private PageParameters $page, private Sort $sort, private Filter $filter) + { } /** @@ -58,33 +53,7 @@ public static function fromQuery(ServerRequestInterface $request, ?Schema $schem $filter = $expression === '' ? Group::none() : FilterParser::from(input: $expression)->parse(); $sort = Sort::fromExpression(expression: $query->get(key: 'sort')->toString()); - return new Criteria(page: $page, sort: $sort, filter: $filter, pagination: $page->resolve()); - } - - /** - * Returns the criteria as a URI built on the given base. - * - * @param string $baseUri The base URI the query string is appended to. - * @return string The URI carrying the filter, sort, and pagination. - */ - public function toUri(string $baseUri): string - { - $parameters = []; - - if (!$this->filter->isEmpty()) { - $template = 'filter=%s'; - $parameters[] = sprintf($template, $this->filter->toExpression()->value()); - } - - if (!$this->sort->isEmpty()) { - $template = 'sort=%s'; - $parameters[] = sprintf($template, $this->sort->toExpression()); - } - - $parameters[] = $this->pagination->toQueryString(); - $template = '%s?%s'; - - return sprintf($template, $baseUri, implode('&', $parameters)); + return new Criteria(page: $page, sort: $sort, filter: $filter); } /** @@ -144,7 +113,7 @@ public function offsetPage(iterable $items, int $total): OffsetPage */ public function pagination(): Pagination { - return $this->pagination; + return $this->page->resolve(); } /** @@ -160,15 +129,4 @@ public function offsetSlice(iterable $items): OffsetSlice { return OffsetSlice::from(items: $items, criteria: $this, pagination: $this->page->toOffset()); } - - /** - * Returns a copy of the criteria with the pagination replaced. - * - * @param Pagination $pagination The pagination to apply. - * @return Criteria A new criteria carrying the given pagination with the filter and sort preserved. - */ - public function withPagination(Pagination $pagination): Criteria - { - return new Criteria(page: $this->page, sort: $this->sort, filter: $this->filter, pagination: $pagination); - } } diff --git a/src/Cursor.php b/src/Cursor.php index 8d299e8..0f24434 100644 --- a/src/Cursor.php +++ b/src/Cursor.php @@ -5,7 +5,7 @@ namespace TinyBlocks\HttpQuery; use TinyBlocks\HttpQuery\Exceptions\CursorIsInvalid; -use TinyBlocks\HttpQuery\Internal\CursorCodec; +use TinyBlocks\HttpQuery\Internal\Cursor\CursorCodec; /** * Opaque, URI-safe token wrapping the ordering key values of a keyset (cursor) page. diff --git a/src/CursorPage.php b/src/CursorPage.php index 2f6f0c2..d625097 100644 --- a/src/CursorPage.php +++ b/src/CursorPage.php @@ -9,7 +9,7 @@ use TinyBlocks\Collection\Collection; use TinyBlocks\Http\LinkRelation; use TinyBlocks\Http\Server\Response; -use TinyBlocks\HttpQuery\Internal\Keyset; +use TinyBlocks\HttpQuery\Internal\Cursor\Keyset; use TinyBlocks\HttpQuery\Internal\Limit; /** diff --git a/src/Internal/CursorCodec.php b/src/Internal/Cursor/CursorCodec.php similarity index 94% rename from src/Internal/CursorCodec.php rename to src/Internal/Cursor/CursorCodec.php index 6eca4be..994c3c3 100644 --- a/src/Internal/CursorCodec.php +++ b/src/Internal/Cursor/CursorCodec.php @@ -2,7 +2,7 @@ declare(strict_types=1); -namespace TinyBlocks\HttpQuery\Internal; +namespace TinyBlocks\HttpQuery\Internal\Cursor; use TinyBlocks\Encoder\Base62; use TinyBlocks\Encoder\Internal\Exceptions\InvalidDecoding; diff --git a/src/Internal/Keyset.php b/src/Internal/Cursor/Keyset.php similarity index 95% rename from src/Internal/Keyset.php rename to src/Internal/Cursor/Keyset.php index ff06495..8a0cfe9 100644 --- a/src/Internal/Keyset.php +++ b/src/Internal/Cursor/Keyset.php @@ -2,12 +2,13 @@ declare(strict_types=1); -namespace TinyBlocks\HttpQuery\Internal; +namespace TinyBlocks\HttpQuery\Internal\Cursor; use Closure; use TinyBlocks\Collection\Collection; use TinyBlocks\HttpQuery\Cursor; use TinyBlocks\HttpQuery\CursorPagination; +use TinyBlocks\HttpQuery\Internal\Window; /** * @template TValue diff --git a/src/Internal/Offset.php b/src/Internal/Offset/Offset.php similarity index 87% rename from src/Internal/Offset.php rename to src/Internal/Offset/Offset.php index 6558590..39f13fa 100644 --- a/src/Internal/Offset.php +++ b/src/Internal/Offset/Offset.php @@ -2,9 +2,10 @@ declare(strict_types=1); -namespace TinyBlocks\HttpQuery\Internal; +namespace TinyBlocks\HttpQuery\Internal\Offset; use TinyBlocks\HttpQuery\Exceptions\OffsetOutOfRange; +use TinyBlocks\HttpQuery\Internal\Limit; final readonly class Offset { diff --git a/src/Internal/OffsetNavigator.php b/src/Internal/Offset/OffsetNavigator.php similarity index 94% rename from src/Internal/OffsetNavigator.php rename to src/Internal/Offset/OffsetNavigator.php index 63e7b02..baca52c 100644 --- a/src/Internal/OffsetNavigator.php +++ b/src/Internal/Offset/OffsetNavigator.php @@ -2,8 +2,9 @@ declare(strict_types=1); -namespace TinyBlocks\HttpQuery\Internal; +namespace TinyBlocks\HttpQuery\Internal\Offset; +use TinyBlocks\HttpQuery\Internal\Limit; use TinyBlocks\HttpQuery\OffsetPagination; final readonly class OffsetNavigator diff --git a/src/Internal/PageCount.php b/src/Internal/Offset/PageCount.php similarity index 86% rename from src/Internal/PageCount.php rename to src/Internal/Offset/PageCount.php index e5f9636..0d1f544 100644 --- a/src/Internal/PageCount.php +++ b/src/Internal/Offset/PageCount.php @@ -2,7 +2,9 @@ declare(strict_types=1); -namespace TinyBlocks\HttpQuery\Internal; +namespace TinyBlocks\HttpQuery\Internal\Offset; + +use TinyBlocks\HttpQuery\Internal\Limit; final readonly class PageCount { diff --git a/src/Internal/PageNumber.php b/src/Internal/Offset/PageNumber.php similarity index 91% rename from src/Internal/PageNumber.php rename to src/Internal/Offset/PageNumber.php index abe6a6f..29270ad 100644 --- a/src/Internal/PageNumber.php +++ b/src/Internal/Offset/PageNumber.php @@ -2,9 +2,10 @@ declare(strict_types=1); -namespace TinyBlocks\HttpQuery\Internal; +namespace TinyBlocks\HttpQuery\Internal\Offset; use TinyBlocks\HttpQuery\Exceptions\PageNumberOutOfRange; +use TinyBlocks\HttpQuery\Internal\Limit; final readonly class PageNumber { diff --git a/src/Internal/Total.php b/src/Internal/Offset/Total.php similarity index 86% rename from src/Internal/Total.php rename to src/Internal/Offset/Total.php index 8b70bb8..558e6cc 100644 --- a/src/Internal/Total.php +++ b/src/Internal/Offset/Total.php @@ -2,9 +2,10 @@ declare(strict_types=1); -namespace TinyBlocks\HttpQuery\Internal; +namespace TinyBlocks\HttpQuery\Internal\Offset; use TinyBlocks\HttpQuery\Exceptions\TotalIsNegative; +use TinyBlocks\HttpQuery\Internal\Limit; final readonly class Total { diff --git a/src/Internal/Uri.php b/src/Internal/Uri.php new file mode 100644 index 0000000..d4dd270 --- /dev/null +++ b/src/Internal/Uri.php @@ -0,0 +1,36 @@ +isEmpty()) { + $template = 'filter=%s'; + $parameters[] = sprintf($template, $filter->toExpression()->value()); + } + + if (!$sort->isEmpty()) { + $template = 'sort=%s'; + $parameters[] = sprintf($template, $sort->toExpression()); + } + + $parameters[] = $pagination->toQueryString(); + $template = '%s?%s'; + + return sprintf($template, $baseUri, implode('&', $parameters)); + } +} diff --git a/src/Links.php b/src/Links.php index 2661f4a..a74490c 100644 --- a/src/Links.php +++ b/src/Links.php @@ -7,13 +7,14 @@ use TinyBlocks\Collection\Collection; use TinyBlocks\Http\Link; use TinyBlocks\Http\LinkRelation; +use TinyBlocks\HttpQuery\Internal\Uri; use TinyBlocks\HttpQuery\Internal\WebLink; /** * Navigation of a result, rendered as a JSON:API body links object or an RFC 8288 Link header. * - *

    It renders uniformly over a {@see Navigation}, building the self link from the criteria and - * each navigation target by swapping the criteria's pagination, so the filter and the sort are + *

    It renders uniformly over a {@see Navigation}, building each URI from the criteria's filter and + * sort plus the pagination of the self link and of every target, so the filter and the sort are * preserved in every URI.

    */ final readonly class Links @@ -35,12 +36,19 @@ private function __construct(private WebLink $self, private Collection $links) */ public static function from(string $baseUri, Criteria $criteria, Navigation $navigation): Links { - $self = new WebLink(uri: $criteria->toUri(baseUri: $baseUri), relation: LinkRelation::SELF); + $uriFor = static fn(Pagination $pagination): string => Uri::from( + sort: $criteria->sorting(), + filter: $criteria->filtering(), + baseUri: $baseUri, + pagination: $pagination + ); + + $self = new WebLink(uri: $uriFor($criteria->pagination()), relation: LinkRelation::SELF); /** @var Collection $links */ $links = $navigation->targets()->map( transformations: static fn(NavigationTarget $target): WebLink => new WebLink( - uri: $criteria->withPagination(pagination: $target->target())->toUri(baseUri: $baseUri), + uri: $uriFor($target->target()), relation: $target->relation() ) ); diff --git a/src/OffsetPage.php b/src/OffsetPage.php index caa519e..bb8af6c 100644 --- a/src/OffsetPage.php +++ b/src/OffsetPage.php @@ -10,11 +10,11 @@ use TinyBlocks\Http\Server\Response; use TinyBlocks\HttpQuery\Exceptions\TotalIsNegative; use TinyBlocks\HttpQuery\Internal\Limit; -use TinyBlocks\HttpQuery\Internal\Offset; -use TinyBlocks\HttpQuery\Internal\OffsetNavigator; -use TinyBlocks\HttpQuery\Internal\PageCount; -use TinyBlocks\HttpQuery\Internal\PageNumber; -use TinyBlocks\HttpQuery\Internal\Total; +use TinyBlocks\HttpQuery\Internal\Offset\Offset; +use TinyBlocks\HttpQuery\Internal\Offset\OffsetNavigator; +use TinyBlocks\HttpQuery\Internal\Offset\PageCount; +use TinyBlocks\HttpQuery\Internal\Offset\PageNumber; +use TinyBlocks\HttpQuery\Internal\Offset\Total; /** * Offset-based page carrying its items, the total element count, and the navigation targets. diff --git a/src/OffsetPagination.php b/src/OffsetPagination.php index 5a952f0..c5500e2 100644 --- a/src/OffsetPagination.php +++ b/src/OffsetPagination.php @@ -8,8 +8,8 @@ use TinyBlocks\HttpQuery\Exceptions\PageNumberOutOfRange; use TinyBlocks\HttpQuery\Exceptions\PageSizeOutOfRange; use TinyBlocks\HttpQuery\Internal\Limit; -use TinyBlocks\HttpQuery\Internal\Offset; -use TinyBlocks\HttpQuery\Internal\PageNumber; +use TinyBlocks\HttpQuery\Internal\Offset\Offset; +use TinyBlocks\HttpQuery\Internal\Offset\PageNumber; /** * Offset-based pagination request whose canonical state is an offset and a limit. diff --git a/src/OffsetSlice.php b/src/OffsetSlice.php index 054f218..1e76eb5 100644 --- a/src/OffsetSlice.php +++ b/src/OffsetSlice.php @@ -9,9 +9,9 @@ use TinyBlocks\Http\LinkRelation; use TinyBlocks\Http\Server\Response; use TinyBlocks\HttpQuery\Internal\Limit; -use TinyBlocks\HttpQuery\Internal\Offset; -use TinyBlocks\HttpQuery\Internal\OffsetNavigator; -use TinyBlocks\HttpQuery\Internal\PageNumber; +use TinyBlocks\HttpQuery\Internal\Offset\Offset; +use TinyBlocks\HttpQuery\Internal\Offset\OffsetNavigator; +use TinyBlocks\HttpQuery\Internal\Offset\PageNumber; use TinyBlocks\HttpQuery\Internal\Window; /** diff --git a/tests/Unit/CriteriaTest.php b/tests/Unit/CriteriaTest.php index b03177f..bc1a97c 100644 --- a/tests/Unit/CriteriaTest.php +++ b/tests/Unit/CriteriaTest.php @@ -59,18 +59,6 @@ public function testFromQueryWhenNoCursorThenPaginationIsOffsetBased(): void self::assertInstanceOf(OffsetPagination::class, $criteria->pagination()); } - public function testToUriWhenAndGroupNestedInOrThenLeavesItUnwrapped(): void - { - /** @Given a criteria whose filter nests an AND group inside an OR group */ - $criteria = Criteria::fromQuery(request: Query::from(parameters: ['filter' => 'a==1;b==2,c==3'])); - - /** @When serializing the criteria back to a URI */ - $actual = $criteria->toUri(baseUri: '/v1/orders'); - - /** @Then the tighter-binding AND group is left unwrapped */ - self::assertSame('/v1/orders?filter=a==1;b==2,c==3&page[number]=1&page[size]=20', $actual); - } - public function testFromQueryWhenPerPageIsAtTheMaximumThenItIsAccepted(): void { /** @Given query parameters carrying a page size at the default maximum */ @@ -116,18 +104,6 @@ public function testOffsetPageWhenBuiltFromRequestThenReturnsOffsetPage(): void self::assertSame(30, $page->total()); } - public function testToUriWhenOrGroupNestedInAndThenWrapsItInParentheses(): void - { - /** @Given a criteria whose filter nests an OR group inside an AND group */ - $criteria = Criteria::fromQuery(request: Query::from(parameters: ['filter' => '(a==1,b==2);c==3'])); - - /** @When serializing the criteria back to a URI */ - $actual = $criteria->toUri(baseUri: '/v1/orders'); - - /** @Then the nested OR group is wrapped in parentheses */ - self::assertSame('/v1/orders?filter=(a==1,b==2);c==3&page[number]=1&page[size]=20', $actual); - } - public function testOffsetSliceWhenBuiltFromRequestThenReturnsOffsetSlice(): void { /** @Given a criteria parsed from a request carrying a page size of three */ @@ -143,18 +119,6 @@ public function testOffsetSliceWhenBuiltFromRequestThenReturnsOffsetSlice(): voi self::assertTrue($slice->hasNext()); } - public function testToUriWhenValueCarriesReservedCharactersThenItIsQuoted(): void - { - /** @Given a criteria whose filter value carries a space */ - $criteria = Criteria::fromQuery(request: Query::from(parameters: ['filter' => 'name=="John Doe"'])); - - /** @When serializing the criteria back to a URI */ - $actual = $criteria->toUri(baseUri: '/v1/orders'); - - /** @Then the value is rendered with surrounding double quotes */ - self::assertSame('/v1/orders?filter=name=="John Doe"&page[number]=1&page[size]=20', $actual); - } - public function testFromQueryWhenCursorIsPresentThenPaginationIsCursorBased(): void { /** @Given query parameters carrying a cursor */ @@ -173,18 +137,6 @@ public function testFromQueryWhenCursorIsPresentThenPaginationIsCursorBased(): v self::assertSame('abc', $criteria->pagination()->cursor()->toString()); } - public function testToUriWhenValueCarriesQuoteAndBackslashThenBothAreEscaped(): void - { - /** @Given a criteria whose filter value carries a double quote and a backslash */ - $criteria = Criteria::fromQuery(request: Query::from(parameters: ['filter' => 'name=="a\"b\\\\c"'])); - - /** @When serializing the criteria back to a URI */ - $actual = $criteria->toUri(baseUri: '/v1/orders'); - - /** @Then the quote and the backslash are escaped within the double-quoted value */ - self::assertSame('/v1/orders?filter=name=="a\"b\\\\c"&page[number]=1&page[size]=20', $actual); - } - public function testFromQueryWhenEmptyThenPaginationCarriesDefaultPageAndLimit(): void { /** @Given empty query parameters */ @@ -203,25 +155,6 @@ public function testFromQueryWhenEmptyThenPaginationCarriesDefaultPageAndLimit() self::assertSame(20, $criteria->pagination()->limit()); } - public function testWithPaginationWhenPageReplacedThenFilterAndSortArePreserved(): void - { - /** @Given a criteria parsed from a filter, a sort, a page, and a page size */ - $criteria = Criteria::fromQuery(request: Query::from(parameters: [ - 'sort' => '-created_at,id', - 'page' => ['number' => '3', 'size' => '20'], - 'filter' => 'status==paid' - ])); - - /** @And a replacement pagination pointing at a new page */ - $pagination = OffsetPagination::fromPage(page: 5, perPage: 20); - - /** @When replacing the pagination and serializing back to a URI */ - $actual = $criteria->withPagination(pagination: $pagination)->toUri(baseUri: '/v1/orders'); - - /** @Then the URI keeps the filter and the sort while pointing at the new page */ - self::assertSame('/v1/orders?filter=status==paid&sort=-created_at,id&page[number]=5&page[size]=20', $actual); - } - public function testFromQueryWhenCustomSchemaGivenThenAppliesItsDefaultPageSize(): void { /** @Given query parameters carrying a page number without a page size */ @@ -256,25 +189,6 @@ public function testFromQueryWhenPerPageAboveMaximumThenThrowsPageSizeOutOfRange Criteria::fromQuery(request: $query); } - public function testToUriWhenFilterSortAndPageGivenThenRoundTripsToTheCanonicalUri(): void - { - /** @Given a criteria parsed from a filter, a sort, a page, and a page size */ - $criteria = Criteria::fromQuery(request: Query::from(parameters: [ - 'sort' => '-created_at,id', - 'page' => ['number' => '3', 'size' => '20'], - 'filter' => 'status==paid;total=ge=100' - ])); - - /** @When serializing the criteria back to a URI */ - $actual = $criteria->toUri(baseUri: '/v1/orders'); - - /** @Then the URI preserves the filter, the sort, and the pagination */ - self::assertSame( - '/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page[number]=3&page[size]=20', - $actual - ); - } - public function testFromQueryWhenFilterSortAndPageGivenThenEachSpecificationIsParsed(): void { /** @Given query parameters carrying a filter, a sort, a page, and a page size */ diff --git a/tests/Unit/CursorTest.php b/tests/Unit/CursorTest.php index 51a30ad..7f8d945 100644 --- a/tests/Unit/CursorTest.php +++ b/tests/Unit/CursorTest.php @@ -10,7 +10,7 @@ use TinyBlocks\Encoder\Base62; use TinyBlocks\HttpQuery\Cursor; use TinyBlocks\HttpQuery\Exceptions\CursorIsInvalid; -use TinyBlocks\HttpQuery\Internal\CursorCodec; +use TinyBlocks\HttpQuery\Internal\Cursor\CursorCodec; final class CursorTest extends TestCase { diff --git a/tests/Unit/FilterTest.php b/tests/Unit/FilterTest.php index a8f9aaa..47733a2 100644 --- a/tests/Unit/FilterTest.php +++ b/tests/Unit/FilterTest.php @@ -150,6 +150,18 @@ public function testToExpressionWhenValueCarriesReservedCharacterThenQuotesIt(): self::assertSame('name=="John Doe"', $expression); } + public function testToExpressionWhenValueCarriesQuoteAndBackslashThenEscapesBoth(): void + { + /** @Given a comparison whose value carries a double quote and a backslash */ + $comparison = Comparison::of(field: 'name', values: ['a"b\\c'], operator: Operator::EQUAL); + + /** @When rendering it as an RSQL expression */ + $expression = $comparison->toExpression()->value(); + + /** @Then the quote and the backslash are escaped within the double-quoted value */ + self::assertSame('name=="a\\"b\\\\c"', $expression); + } + public function testFilteringWhenMixedPrecedenceGivenThenAndBindsTighterThanOr(): void { /** @Given a query mixing AND and OR connectives without explicit grouping */ diff --git a/tests/Unit/LinksTest.php b/tests/Unit/LinksTest.php index f272f17..8bac15c 100644 --- a/tests/Unit/LinksTest.php +++ b/tests/Unit/LinksTest.php @@ -5,34 +5,28 @@ namespace Test\TinyBlocks\HttpQuery\Unit; use PHPUnit\Framework\TestCase; +use ReflectionClass; +use ReflectionMethod; use Test\TinyBlocks\HttpQuery\Models\Query; use TinyBlocks\Collection\Collection; use TinyBlocks\HttpQuery\Criteria; use TinyBlocks\HttpQuery\Cursor; use TinyBlocks\HttpQuery\CursorPage; use TinyBlocks\HttpQuery\CursorPagination; +use TinyBlocks\HttpQuery\Internal\Uri; use TinyBlocks\HttpQuery\Links; -use TinyBlocks\HttpQuery\OffsetPage; -use TinyBlocks\HttpQuery\OffsetPagination; -use TinyBlocks\HttpQuery\OffsetSlice; final class LinksTest extends TestCase { public function testToArrayWhenPageIsTheLastThenOmitsTheNextRelation(): void { - /** @Given an offset pagination pointing at the last page */ - $pagination = OffsetPagination::fromPage(page: 24, perPage: 20); - - /** @And a criteria over that pagination */ - $criteria = Criteria::fromQuery(request: Query::from(parameters: []))->withPagination(pagination: $pagination); + /** @Given a criteria pointing at the twenty-fourth page */ + $criteria = Criteria::fromQuery(request: Query::from(parameters: [ + 'page' => ['number' => '24', 'size' => '20'] + ])); /** @And a page carrying a total spanning twenty-four pages */ - $result = OffsetPage::from( - items: Collection::createFrom(elements: range(1, 20)), - total: 480, - criteria: $criteria, - pagination: $pagination - ); + $result = $criteria->offsetPage(items: Collection::createFrom(elements: range(1, 20)), total: 480); /** @When rendering the navigation for the last page */ $links = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $result->navigation()); @@ -51,21 +45,15 @@ public function testToArrayWhenPageIsTheLastThenOmitsTheNextRelation(): void public function testToArrayWhenSliceMiddleThenExposesSelfFirstPrevAndNext(): void { - /** @Given an offset pagination pointing at a middle page */ - $pagination = OffsetPagination::fromPage(page: 3, perPage: 20); - - /** @And a criteria carrying a filter and a sort over that pagination */ + /** @Given a criteria carrying a filter and a sort at a middle page */ $criteria = Criteria::fromQuery(request: Query::from(parameters: [ 'sort' => '-created_at,id', + 'page' => ['number' => '3', 'size' => '20'], 'filter' => 'status==paid' - ]))->withPagination(pagination: $pagination); + ])); /** @And a slice fetched for the page size plus one so a next page exists */ - $result = OffsetSlice::from( - items: Collection::createFrom(elements: range(1, 21)), - criteria: $criteria, - pagination: $pagination - ); + $result = $criteria->offsetSlice(items: Collection::createFrom(elements: range(1, 21))); /** @When rendering the navigation for the slice */ $links = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $result->navigation()); @@ -106,19 +94,11 @@ public function testToArrayWhenCursorResultThenExposesOnlySelfAndNext(): void public function testToArrayWhenPageIsTheFirstThenOmitsThePreviousRelation(): void { - /** @Given an offset pagination pointing at the first page */ - $pagination = OffsetPagination::fromPage(page: 1, perPage: 20); - - /** @And a criteria over that pagination */ - $criteria = Criteria::fromQuery(request: Query::from(parameters: []))->withPagination(pagination: $pagination); + /** @Given a criteria pointing at the first page */ + $criteria = Criteria::fromQuery(request: Query::from(parameters: [])); /** @And a page carrying a total spanning twenty-four pages */ - $result = OffsetPage::from( - items: Collection::createFrom(elements: range(1, 20)), - total: 480, - criteria: $criteria, - pagination: $pagination - ); + $result = $criteria->offsetPage(items: Collection::createFrom(elements: range(1, 20)), total: 480); /** @When rendering the navigation for the first page */ $links = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $result->navigation()); @@ -137,18 +117,13 @@ public function testToArrayWhenPageIsTheFirstThenOmitsThePreviousRelation(): voi public function testToArrayWhenSliceMiddleThenCarriesAFirstButNoLastRelation(): void { - /** @Given an offset pagination pointing at a middle page */ - $pagination = OffsetPagination::fromPage(page: 3, perPage: 20); - - /** @And a criteria over that pagination */ - $criteria = Criteria::fromQuery(request: Query::from(parameters: []))->withPagination(pagination: $pagination); + /** @Given a criteria pointing at a middle page */ + $criteria = Criteria::fromQuery(request: Query::from(parameters: [ + 'page' => ['number' => '3', 'size' => '20'] + ])); /** @And a slice fetched for the page size plus one so a next page exists */ - $result = OffsetSlice::from( - items: Collection::createFrom(elements: range(1, 21)), - criteria: $criteria, - pagination: $pagination - ); + $result = $criteria->offsetSlice(items: Collection::createFrom(elements: range(1, 21))); /** @When rendering the navigation for the slice */ $links = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $result->navigation()); @@ -190,22 +165,15 @@ public function testToArrayWhenCursorResultThenCarriesNoFirstOrLastOrPreviousRel public function testToHeaderWhenPageInTheMiddleThenFoldsEveryRelationIntoOneCommaJoinedValue(): void { - /** @Given an offset pagination pointing at a middle page */ - $pagination = OffsetPagination::fromPage(page: 3, perPage: 20); - - /** @And a criteria carrying a filter and a sort over that pagination */ + /** @Given a criteria carrying a filter and a sort at a middle page */ $criteria = Criteria::fromQuery(request: Query::from(parameters: [ 'sort' => '-created_at,id', + 'page' => ['number' => '3', 'size' => '20'], 'filter' => 'status==paid' - ]))->withPagination(pagination: $pagination); + ])); /** @And a page carrying a total spanning twenty-four pages */ - $result = OffsetPage::from( - items: Collection::createFrom(elements: range(1, 20)), - total: 480, - criteria: $criteria, - pagination: $pagination - ); + $result = $criteria->offsetPage(items: Collection::createFrom(elements: range(1, 20)), total: 480); /** @When rendering the navigation as an RFC 8288 Link header */ $header = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $result->navigation()) @@ -223,22 +191,15 @@ public function testToHeaderWhenPageInTheMiddleThenFoldsEveryRelationIntoOneComm public function testToArrayWhenPageInTheMiddleThenExposesEveryRelationPreservingFilterAndSort(): void { - /** @Given an offset pagination pointing at a middle page */ - $pagination = OffsetPagination::fromPage(page: 3, perPage: 20); - - /** @And a criteria carrying a filter and a sort over that pagination */ + /** @Given a criteria carrying a filter and a sort at a middle page */ $criteria = Criteria::fromQuery(request: Query::from(parameters: [ 'sort' => '-created_at,id', + 'page' => ['number' => '3', 'size' => '20'], 'filter' => 'status==paid' - ]))->withPagination(pagination: $pagination); + ])); /** @And a page carrying a total spanning twenty-four pages */ - $result = OffsetPage::from( - items: Collection::createFrom(elements: range(1, 20)), - total: 480, - criteria: $criteria, - pagination: $pagination - ); + $result = $criteria->offsetPage(items: Collection::createFrom(elements: range(1, 20)), total: 480); /** @When rendering the navigation for the page */ $links = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $result->navigation()); @@ -252,4 +213,16 @@ public function testToArrayWhenPageInTheMiddleThenExposesEveryRelationPreserving 'last' => '/v1/orders?filter=status==paid&sort=-created_at,id&page[number]=24&page[size]=20' ], $links->toArray()); } + + public function testConstructorWhenInvokedThroughReflectionThenInstantiatesTheStaticOnlyUri(): void + { + /** @Given an uninitialized instance of the static-only URI assembler */ + $uri = new ReflectionClass(Uri::class)->newInstanceWithoutConstructor(); + + /** @When invoking its otherwise-uncallable private constructor */ + new ReflectionMethod(Uri::class, '__construct')->invoke($uri); + + /** @Then the static-only URI assembler is instantiated */ + self::assertInstanceOf(Uri::class, $uri); + } } From 6c0c0f24622d809cffb39bfdb0beb2f02bcc6668 Mon Sep 17 00:00:00 2001 From: Gustavo Freze Date: Tue, 9 Jun 2026 00:22:50 -0300 Subject: [PATCH 04/14] refactor: Restructure the HTTP query toolkit. - Relocate the cursor, offset, and shared types into the Cursor, Offset, and Internal namespaces, with public exceptions under Exceptions. - Encode cursor tokens as URL-safe base64 over their JSON key values. - Merge OffsetNavigator into OffsetNavigation, holding the pagination and derived page number once. - Order constructor and factory parameters by ascending name length. --- README.md | 332 +++++++------- composer.json | 5 +- phpstan.neon.dist | 35 +- src/Comparison.php | 50 +- src/Criteria.php | 132 ------ src/Cursor.php | 105 ----- src/Cursor/Criteria.php | 117 +++++ src/Cursor/Keyset.php | 103 +++++ src/Cursor/Page.php | 168 +++++++ .../Pagination.php} | 21 +- src/Cursor/Token.php | 130 ++++++ src/CursorPage.php | 167 ------- src/Exceptions/FilterFieldNotAllowed.php | 36 ++ src/Exceptions/FilterOperatorNotAllowed.php | 38 ++ src/Exceptions/FilterShapeNotSupported.php | 36 ++ src/Exceptions/FilterValueNotAllowed.php | 54 +++ src/Exceptions/SortFieldNotAllowed.php | 36 ++ src/Exceptions/SortIsRequired.php | 23 + src/Expression.php | 65 --- src/Filter.php | 11 +- src/Group.php | 17 - src/Internal/AllowedField.php | 50 ++ src/Internal/AllowedFilters.php | 48 ++ src/Internal/Conjunction.php | 44 ++ src/Internal/Cursor/CursorCodec.php | 17 +- src/Internal/Cursor/Keyset.php | 72 --- src/Internal/Cursor/Seek.php | 61 +++ src/Internal/Cursor/SortKeys.php | 22 + src/Internal/Iso8601.php | 15 + src/Internal/Offset/OffsetNavigation.php | 85 ++++ src/Internal/Offset/OffsetNavigator.php | 59 --- src/Internal/Offset/PageNumber.php | 2 +- src/Internal/PageParameters.php | 52 --- src/Internal/Query.php | 87 ++++ src/Internal/Rendering.php | 39 ++ src/Internal/Rsql/Expression.php | 40 ++ src/Internal/Rsql/Renderer.php | 70 +++ src/Internal/Uri.php | 3 +- src/Internal/Window.php | 2 +- src/Links.php | 30 +- src/Offset/Criteria.php | 152 ++++++ src/{OffsetPage.php => Offset/Page.php} | 134 +++--- .../Pagination.php} | 25 +- src/{OffsetSlice.php => Offset/Slice.php} | 98 ++-- src/Pagination.php | 5 +- src/Schema.php | 180 ++++++-- src/ValueKind.php | 35 ++ tests/Unit/ComparisonTest.php | 120 +++++ tests/Unit/CriteriaTest.php | 228 --------- tests/Unit/Cursor/CriteriaTest.php | 173 +++++++ tests/Unit/Cursor/KeysetTest.php | 144 ++++++ tests/Unit/Cursor/PageTest.php | 232 ++++++++++ .../PaginationTest.php} | 22 +- tests/Unit/Cursor/TokenTest.php | 206 +++++++++ tests/Unit/CursorPageTest.php | 204 --------- tests/Unit/CursorTest.php | 147 ------ tests/Unit/EndToEndTest.php | 155 ++----- tests/Unit/ExpressionTest.php | 78 ---- tests/Unit/FilterTest.php | 432 ++++++++---------- tests/Unit/GroupTest.php | 73 +++ tests/Unit/LinksTest.php | 348 +++++++++----- tests/Unit/Offset/CriteriaTest.php | 209 +++++++++ .../PageTest.php} | 205 ++++----- .../PaginationTest.php} | 30 +- .../SliceTest.php} | 125 ++--- tests/Unit/RenderingTest.php | 25 + tests/Unit/SchemaTest.php | 123 +++-- tests/Unit/ValueKindTest.php | 61 +++ 68 files changed, 4004 insertions(+), 2444 deletions(-) delete mode 100644 src/Criteria.php delete mode 100644 src/Cursor.php create mode 100644 src/Cursor/Criteria.php create mode 100644 src/Cursor/Keyset.php create mode 100644 src/Cursor/Page.php rename src/{CursorPagination.php => Cursor/Pagination.php} (58%) create mode 100644 src/Cursor/Token.php delete mode 100644 src/CursorPage.php create mode 100644 src/Exceptions/FilterFieldNotAllowed.php create mode 100644 src/Exceptions/FilterOperatorNotAllowed.php create mode 100644 src/Exceptions/FilterShapeNotSupported.php create mode 100644 src/Exceptions/FilterValueNotAllowed.php create mode 100644 src/Exceptions/SortFieldNotAllowed.php create mode 100644 src/Exceptions/SortIsRequired.php delete mode 100644 src/Expression.php create mode 100644 src/Internal/AllowedField.php create mode 100644 src/Internal/AllowedFilters.php create mode 100644 src/Internal/Conjunction.php delete mode 100644 src/Internal/Cursor/Keyset.php create mode 100644 src/Internal/Cursor/Seek.php create mode 100644 src/Internal/Cursor/SortKeys.php create mode 100644 src/Internal/Iso8601.php create mode 100644 src/Internal/Offset/OffsetNavigation.php delete mode 100644 src/Internal/Offset/OffsetNavigator.php delete mode 100644 src/Internal/PageParameters.php create mode 100644 src/Internal/Query.php create mode 100644 src/Internal/Rendering.php create mode 100644 src/Internal/Rsql/Expression.php create mode 100644 src/Internal/Rsql/Renderer.php create mode 100644 src/Offset/Criteria.php rename src/{OffsetPage.php => Offset/Page.php} (58%) rename src/{OffsetPagination.php => Offset/Pagination.php} (67%) rename src/{OffsetSlice.php => Offset/Slice.php} (56%) create mode 100644 src/ValueKind.php create mode 100644 tests/Unit/ComparisonTest.php delete mode 100644 tests/Unit/CriteriaTest.php create mode 100644 tests/Unit/Cursor/CriteriaTest.php create mode 100644 tests/Unit/Cursor/KeysetTest.php create mode 100644 tests/Unit/Cursor/PageTest.php rename tests/Unit/{CursorPaginationTest.php => Cursor/PaginationTest.php} (79%) create mode 100644 tests/Unit/Cursor/TokenTest.php delete mode 100644 tests/Unit/CursorPageTest.php delete mode 100644 tests/Unit/CursorTest.php delete mode 100644 tests/Unit/ExpressionTest.php create mode 100644 tests/Unit/GroupTest.php create mode 100644 tests/Unit/Offset/CriteriaTest.php rename tests/Unit/{OffsetPageTest.php => Offset/PageTest.php} (64%) rename tests/Unit/{OffsetPaginationTest.php => Offset/PaginationTest.php} (84%) rename tests/Unit/{OffsetSliceTest.php => Offset/SliceTest.php} (60%) create mode 100644 tests/Unit/RenderingTest.php create mode 100644 tests/Unit/ValueKindTest.php diff --git a/README.md b/README.md index a589b3a..78d03c0 100644 --- a/README.md +++ b/README.md @@ -5,26 +5,31 @@ * [Overview](#overview) * [Installation](#installation) * [How to use](#how-to-use) + + [Declaring the query contract](#declaring-the-query-contract) + [Filtering with RSQL](#filtering-with-rsql) + [Sorting](#sorting) + [Offset pagination](#offset-pagination) + [Cursor pagination](#cursor-pagination) + [Rendering navigation links](#rendering-navigation-links) - + [Configuring the schema](#configuring-the-schema) * [FAQ](#faq) * [License](#license) * [Contributing](#contributing) ## Overview -A typed, framework- and database-agnostic toolkit for the query of an HTTP collection endpoint. It parses an incoming -request query string into typed specifications for filtering (RSQL), sorting, and pagination (offset and cursor), and it -renders the result as a JSON:API response carrying an RFC 8288 `Link` header and a body `links` object. +A typed, framework- and database-agnostic toolkit for the query of an HTTP collection endpoint. The endpoint declares +the query contract once on a `Schema`, the library parses an incoming request query string against it, and the consumer +reads an already-validated result: a conjunction of comparisons for filtering, an effective sort, and a pagination view. +The result renders as a JSON:API response carrying an RFC 8288 `Link` header and a body `links` object. The library never touches a data store. It turns the query string into value objects the consumer applies to its own store, and it renders the response the consumer returns. Every computation is O(1) value-object math over the inputs the -consumer supplies. The pagination style stays internal: the `Criteria` builds the result page, so the public API never -exposes a concrete pagination type. +consumer supplies. + +The pagination approach is a fixed decision of the endpoint, not a runtime property of a request. The public API splits +into two contexts, `Cursor` and `Offset`, each complete and approach-only, with the building blocks common to both at +the root. Each page renders a `self` link consistent with its own approach, so a cursor page renders a cursor `self` +and an offset page renders an offset `self`. ## Installation @@ -34,9 +39,18 @@ composer require tiny-blocks/http-query ## How to use -The entry point is `Criteria::fromQuery`, which reads the request query parameters from a PSR-7 request and produces a -`Criteria` carrying the filter, the sort, and the pagination. The `Criteria` then builds the result page and renders it, -so the pagination style stays internal. +There are two entry points, one per pagination approach. `TinyBlocks\HttpQuery\Offset\Criteria` reads an offset request +(`page[number]`, `page[size]`) and builds offset pages, while `TinyBlocks\HttpQuery\Cursor\Criteria` reads a keyset +request (`page[cursor]`, `page[size]`) and builds forward-only cursor pages. Both read the same `filter` and `sort` +parameters, validate them against the schema, and expose the same `comparisons()` and `sort()` building blocks. + +### Declaring the query contract + +`Schema` is the contract of the query an endpoint accepts. `filterable` declares a field with its permitted operators +and, optionally, the permitted values and the `ValueKind` every value must match. `sortable` declares the fields the +client may sort by. `defaultSort` declares the sort applied when the client sends none. `maxPerPage` and +`defaultPerPage` +bound the page size. The query parameter names follow JSON:API and are fixed: `filter`, `sort`, and the `page` family. ```php maxPerPage(maxPerPage: 100) + ->sortable(fields: ['created_at', 'id']) + ->defaultSort(sort: Sort::fromExpression(expression: '-created_at')) + ->filterable(field: 'total', operators: [Operator::GREATER_THAN_OR_EQUAL], kind: ValueKind::INTEGER) + ->filterable(field: 'status', operators: [Operator::EQUAL, Operator::IN], values: ['paid', 'pending']); # GET /v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page[number]=3&page[size]=20 /** @var ServerRequestInterface $request */ -$criteria = Criteria::fromQuery(request: $request); +$criteria = Criteria::fromQuery(request: $request, schema: $schema); ``` +When `Criteria::fromQuery` receives no schema, an empty contract applies: the default page-size bounds, no filterable +or sortable field, and no default sort. Any incoming filter or sort is then rejected. + +| Setting | Default | Meaning | +|------------------|---------|-------------------------------------------------| +| `defaultPerPage` | `20` | The page size applied when the query omits one. | +| `maxPerPage` | `100` | The maximum allowed page size. | + +A page size above `maxPerPage` raises `PageSizeOutOfRange`. + ### Filtering with RSQL -The `filter` parameter is an RSQL expression. `Criteria::filtering()` returns the parsed expression tree as a `Filter`, -which is either a `Comparison` leaf or a `Group` composite. The consumer matches on the node type to translate the tree -to its own store. +The `filter` parameter is an RSQL expression. It is validated against the schema at parse and flattened into the +conjunction of comparisons the consumer applies to its store. `Criteria::comparisons()` returns that validated +`list`, empty when there is no filter. ```php sprintf( - '%s %s %s', - $filter->field(), - $filter->operator()->value, - implode(',', $filter->values()) - ), - $filter instanceof Group => implode( - $filter->operator()->value, - array_map(describe(...), $filter->filters()) - ) - }; +use TinyBlocks\HttpQuery\Offset\Criteria; +use TinyBlocks\HttpQuery\Operator; + +# filter=status==paid;total=ge=100 -> a validated list. +/** @var Criteria $criteria */ +foreach ($criteria->comparisons() as $comparison) { + $comparison->field(); # 'status', then 'total'. + $comparison->values(); # ['paid'], then ['100']. + $comparison->firstValue(); # The first compared value, 'paid'. + $comparison->hasField(field: 'status'); # True for the status leaf. + $comparison->hasOperator(operator: Operator::EQUAL); # True for an equality leaf. } - -# filter=status==paid;total=ge=100 parses to a Group(AND) of two Comparison leaves. ``` The supported operators map to their RSQL tokens through the `Operator` enum (`==`, `!=`, `=lt=`, `=gt=`, `=le=`, `=ge=`, `=in=`, `=out=`). The logical connectives map through the `LogicalOperator` enum, where `;` (AND) binds tighter -than `,` (OR), and parentheses group. A malformed expression raises `FilterExpressionIsInvalid`. +than `,` (OR), and parentheses group. The library is conjunction-only for the consumer, so the filter must be a single +comparison or an AND group of comparisons. A malformed expression raises `FilterExpressionIsInvalid`, and anything +outside the contract raises a dedicated exception, each implementing `HttpQueryException`. + +| Exception | Raised when | +|-----------------------------|-------------------------------------------------------------------------| +| `FilterExpressionIsInvalid` | The filter expression cannot be parsed as RSQL. | +| `FilterShapeNotSupported` | The filter is an OR group, or nests a group, rather than a conjunction. | +| `FilterFieldNotAllowed` | A comparison targets a field that was never declared filterable. | +| `FilterOperatorNotAllowed` | A comparison uses an operator not allowed for its field. | +| `FilterValueNotAllowed` | A compared value falls outside the permitted set or the expected kind. | + +`ValueKind` is the kind a value is validated against. For the multi-valued operators (`=in=`, `=out=`) every value is +checked. + +| Kind | Matches | +|-----------------------|--------------------------------------------------------| +| `ValueKind::STRING` | A non-empty string. | +| `ValueKind::INTEGER` | An optionally signed sequence of digits, `-7` or `42`. | +| `ValueKind::DATETIME` | An ISO-8601 date or date-time, `2023-01-15T10:30:00Z`. | ### Sorting The `sort` parameter is a comma-separated list of fields, where a leading minus marks descending order, following the -JSON:API convention. `Criteria::sorting()` returns a `Sort` whose `Order` list preserves the request order. +JSON:API convention. `Criteria::sort()` returns the effective `Sort`: the client sort when present, validated so every +field is declared `sortable`, otherwise the schema `defaultSort`. An order by an undeclared field raises +`SortFieldNotAllowed`, and a malformed expression raises `SortExpressionIsInvalid`. ```php orders() as $order) { - $order->field(); # 'created_at' then 'id' - $order->direction() === Direction::DESCENDING; # true then false +# sort=-created_at,id -> the effective Sort, ordered as requested. +/** @var Criteria $criteria */ +foreach ($criteria->sort()->orders() as $order) { + $order->field(); # 'created_at' then 'id'. + $order->direction() === Direction::DESCENDING; # true then false. } ``` -A malformed expression raises `SortExpressionIsInvalid`. - ### Offset pagination -When no cursor is present, `Criteria::offsetPage` builds an `OffsetPage` from the items of the current page and the -total -element count. The page derives the offset and the total pages from the request, so the consumer never builds the -pagination itself. The items are any `iterable`, and `items()` returns them as a `Collection`. +`Offset\Criteria::page` builds an `Offset\Page` from the total element count and the items of the current page. The page +derives the offset and the total pages from the request, so the consumer never builds the pagination itself. The items +are any `iterable`, and `items()` returns them as a `Collection`. ```php $items */ -$page = $criteria->offsetPage(items: $items, total: 480); +$page = $criteria->page(total: 480, items: $items); $page->hasNext(); # true -$page->metadata(); # The JSON:API meta contents +$page->metadata(); # The JSON:API meta contents. $page->totalPages(); # 24 ``` -Use `Criteria::offsetSlice` instead of `Criteria::offsetPage` when the total is unknown. The consumer fetches one -element -beyond the page size, and the `OffsetSlice` trims it and reads its presence as the next-page hint. +Use `Offset\Criteria::slice` instead of `page` when the total is unknown. The consumer fetches one element beyond the +page size, and the `Offset\Slice` trims it and reads its presence as the next-page hint. ```php $items */ -$slice = $criteria->offsetSlice(items: $items); +$slice = $criteria->slice(items: $items); -$slice->hasNext(); # Inferred from the extra fetched element +$slice->hasNext(); # Inferred from the extra fetched element. ``` ### Cursor pagination -When the `cursor` parameter is present, `Criteria::cursorPage` builds a keyset `CursorPage`. A `Cursor` is an opaque, -URI-safe token wrapping the last-seen ordering key values, encoded through `tiny-blocks/encoder`. The `keysOf` closure -extracts the ordering key values from an element, and the page derives the forward and backward cursors from them. +Cursor pages are forward-only. `Cursor\Criteria::keyset` pairs the effective sort with the cursor view, exposing the +seek inputs the consumer needs before fetching: the page size, the orders, and the incoming cursor key values keyed by +sort field. A keyset needs a deterministic order, so the schema must declare a `defaultSort` or the client must sort, +otherwise `keyset` raises `SortIsRequired`. A `Token` is an opaque, URI-safe value wrapping the last-seen ordering key +values, encoded as URL-safe base64. ```php sortable(fields: ['created_at', 'id']); # GET /v1/orders?sort=-created_at,id&page[cursor]=BS3RvKY4LqEjYD19mQ0mCpJ&page[size]=20 /** @var ServerRequestInterface $request */ -$criteria = Criteria::fromQuery(request: $request); +$keyset = Criteria::fromQuery(request: $request, schema: $schema)->keyset(); -/** @var iterable $items */ -$cursorPage = $criteria->cursorPage( - items: $items, - keysOf: static fn(array $order): array => [$order['created_at'], $order['id']] -); - -$cursorPage->next(); # The CursorPagination for the next page, or null. -$cursorPage->hasNext(); # Inferred from the extra fetched element. -$cursorPage->previous(); # The CursorPagination for the previous page, or null. +$keyset->limit(); # The page size, 20. +$keyset->orders(); # The list the seek is ordered by. +$keyset->cursor(); # ['created_at' => ..., 'id' => ...], null per field on the first page. ``` -An invalid cursor token raises `CursorIsInvalid` when it is decoded. - -### Rendering navigation links - -`toResponse` renders a result as a JSON:API response in one call. It builds the body from the data, the meta, and the -navigation links, and folds the same relations into an RFC 8288 `Link` header. It returns a PSR-7 `ResponseInterface`. +The seek inputs feed the store query. The consumer fetches one element beyond the page size and hands the rows to +`page`, which trims the extra element and reads its presence as the next-page hint. The ordering keys default to the +sort fields read from each array-shaped row, so the cursor keys come from the source rows. Pass an explicit `keysOf` to +extract them differently. ```php $items */ +$cursorPage = $keyset->page(items: $items); -/** @var iterable $items */ -$response = $criteria->offsetPage(items: $items, total: 480)->toResponse(baseUri: '/v1/orders'); +$cursorPage->next(); # The Cursor\Pagination for the next page, or null. +$cursorPage->hasNext(); # Inferred from the extra fetched element. ``` -For full control over the body, assemble it from the parts. `Links::from` reads the navigation a result exposes through -`result->navigation()` and builds each URI from the criteria's filter and sort plus the pagination of every target, so -the filter and the sort are preserved in every URI. `toArray()` returns the JSON:API body `links` object and -`toHeader()` returns an RFC 8288 `Link`. +`map` projects the items for rendering while preserving the cursor, so raw rows drive the ordering keys and a view is +rendered from the same page. + +```php +$cursorPage->map(transformation: static fn(array $row): array => ['id' => $row['id']]); +``` + +An invalid cursor token raises `CursorIsInvalid` when it is decoded. + +### Rendering navigation links + +`toResponse` renders a result as a JSON:API response in one call. It builds the body from the data, the meta, and the +navigation links, and folds the same relations into an RFC 8288 `Link` header. It returns a PSR-7 `ResponseInterface`. +The submitted filter and sort are preserved in every URI, and the `self` link is built from the page's own current +pagination, so an offset page renders an offset `self` and a cursor page renders a cursor `self`. ```php sortable(fields: ['created_at', 'id']); + +# GET /v1/orders?filter=status==paid&sort=-created_at,id&page[number]=3&page[size]=20 /** @var ServerRequestInterface $request */ -$criteria = Criteria::fromQuery(request: $request); +$criteria = Criteria::fromQuery(request: $request, schema: $schema); /** @var iterable $items */ -$page = $criteria->offsetPage(items: $items, total: 480); -$links = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $page->navigation()); - -$response = Response::ok([ - 'data' => $page->items()->toArray(), - 'meta' => $page->metadata(), - 'links' => $links->toArray() -], $links->toHeader()); +$response = $criteria->page(total: 480, items: $items)->toResponse(baseUri: '/v1/orders'); ``` The body carries the navigation with the filter and the sort preserved in every URI. @@ -257,11 +303,11 @@ The body carries the navigation with the filter and the sort preserved in every "has_previous": true }, "links": { - "self": "/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page[number]=3&page[size]=20", - "first": "/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page[number]=1&page[size]=20", - "prev": "/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page[number]=2&page[size]=20", - "next": "/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page[number]=4&page[size]=20", - "last": "/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id&page[number]=24&page[size]=20" + "self": "/v1/orders?filter=status==paid&sort=-created_at,id&page[number]=3&page[size]=20", + "first": "/v1/orders?filter=status==paid&sort=-created_at,id&page[number]=1&page[size]=20", + "prev": "/v1/orders?filter=status==paid&sort=-created_at,id&page[number]=2&page[size]=20", + "next": "/v1/orders?filter=status==paid&sort=-created_at,id&page[number]=4&page[size]=20", + "last": "/v1/orders?filter=status==paid&sort=-created_at,id&page[number]=24&page[size]=20" } } ``` @@ -269,16 +315,16 @@ The body carries the navigation with the filter and the sort preserved in every The header folds the same relations into one RFC 8288 `Link` line. ```text -Link: ; rel="self", - ; rel="first", - ; rel="prev", - ; rel="next", - ; rel="last" +Link: ; rel="self", + ; rel="first", + ; rel="prev", + ; rel="next", + ; rel="last" ``` The `links` keys are the canonical JSON:API relations, in the semantic order below. Unavailable relations are omitted, -so the first page carries no `prev` and the last page carries no `next`. An `OffsetSlice` exposes `self`, `first`, -`prev`, and `next` (no `last`), and a `CursorPage` exposes only `self`, `prev`, and `next`. +so the first page carries no `prev` and the last page carries no `next`. An `Offset\Slice` exposes `self`, `first`, +`prev`, and `next` (no `last`), and a `Cursor\Page` is forward-only, so it exposes only `self` and `next`. | Relation | Meaning | |----------|--------------------| @@ -288,37 +334,6 @@ so the first page carries no `prev` and the last page carries no `next`. An `Off | `next` | The next page. | | `last` | The last page. | -### Configuring the schema - -The query parameter names follow JSON:API and are fixed: `filter`, `sort`, and the `page` family (`page[number]`, -`page[size]`, `page[cursor]`). `Schema` carries only the page-size bounds. `Schema::default()` is applied when -`Criteria::fromQuery` receives no schema, and the fluent `with*` copies override either bound. - -| Setting | Default | Meaning | -|------------------|---------|-------------------------------------------------| -| `defaultPerPage` | `20` | The page size applied when the query omits one. | -| `maxPerPage` | `100` | The maximum allowed page size. | - -```php -withMaxPerPage(maxPerPage: 200) - ->withDefaultPerPage(defaultPerPage: 50); - -# GET /v1/orders?filter=status==paid&page[size]=50 -/** @var ServerRequestInterface $request */ -$criteria = Criteria::fromQuery(request: $request, schema: $schema); -``` - -A page size above `maxPerPage` raises `PageSizeOutOfRange`. - ## FAQ ### 01. Why does the library never touch a data store? @@ -328,20 +343,29 @@ half. It parses the request into typed specifications and renders the response n apply the specifications to any store, SQL, a document database, or an in-memory list. Keeping the store out makes every operation pure value-object math and keeps the library framework- and database-agnostic. -### 02. Why RSQL for filtering instead of ad-hoc query parameters? +### 02. Why is the query validated at parse instead of by the consumer? + +A filter or a sort enters the system at parse, so that is where it is validated. The endpoint declares the contract once +on the `Schema`, and `Criteria::fromQuery` returns an already-validated result. The consumer reads `comparisons()` and +`sort()` without flattening a tree, enforcing an allowlist, or rendering an expression. A request outside the contract +fails at the boundary with a dedicated `HttpQueryException`, never reaching the store. + +### 03. Why RSQL for filtering instead of ad-hoc query parameters? RSQL is a small, URI-safe grammar with a published reference, so the filter survives a query string without encoding and -the same expression reads the same on the client and the server. The parser produces an immutable expression tree the -consumer walks, rather than a flat map of parameters that cannot express grouping or disjunction. +the same expression reads the same on the client and the server. The library is conjunction-only for the consumer: a +single comparison or an AND group of comparisons flattens into the `list` the consumer applies, +`AND` an `OR` or nested filter is rejected at parse. > Zdenek Jirutka, *RSQL / FIQL parser* (https://github.com/jirutka/rsql-parser). -### 03. Why are both offset and cursor pagination supported? +### 04. Why are the two pagination approaches split into separate contexts? -Offset pagination answers "how many pages are there" and "jump to page N", which an `OffsetPage` with a total provides. -Cursor pagination answers "give me the next slice after this point" without a total, which scales to large collections -and avoids the drift of offset pagination under concurrent writes. The library models both, plus an `OffsetSlice` for -offset navigation without a total. +The pagination approach is a fixed decision of the endpoint, not a runtime property of a request. A single specification +that infers the approach at runtime renders an inconsistent `self` link: the first page of a cursor feed would carry an +offset-style `self` while its `next` is cursor-style. Splitting the API into a `Cursor` context and an `Offset` context, +each complete and approach-only, with the common building blocks at the root, makes every `self` link consistent with +the page's own approach. ## License diff --git a/composer.json b/composer.json index b36ca5d..6fa5abe 100644 --- a/composer.json +++ b/composer.json @@ -26,9 +26,8 @@ }, "require": { "php": "^8.5", - "tiny-blocks/collection": "^2.4", - "tiny-blocks/encoder": "^3.2", - "tiny-blocks/http": "^6.1" + "tiny-blocks/collection": "^2.5", + "tiny-blocks/http": "^6.2" }, "require-dev": { "ergebnis/composer-normalize": "^2.52", diff --git a/phpstan.neon.dist b/phpstan.neon.dist index a4367a3..8c48bf8 100644 --- a/phpstan.neon.dist +++ b/phpstan.neon.dist @@ -20,12 +20,45 @@ parameters: path: src/Sort.php - identifier: return.type path: src/Sort.php + # The sortable fields are a list of strings carried on the schema constructor. + - identifier: missingType.iterableValue + path: src/Schema.php + # The validated conjunction is a list of comparisons produced by the shape walker. + - identifier: missingType.iterableValue + path: src/Internal/Conjunction.php + # The filter marker is sealed by Comparison and Group, so the renderer match is exhaustive. + - identifier: match.unhandled + path: src/Internal/Rsql/Renderer.php + # The parsed and validated specifications are lists carried by the internal query. + - identifier: missingType.iterableValue + path: src/Internal/Query.php + # The validated comparisons are a list carried on the cursor criteria. + - identifier: missingType.iterableValue + path: src/Cursor/Criteria.php + - identifier: return.type + path: src/Cursor/Criteria.php + # The validated comparisons are a list carried on the offset criteria. + - identifier: missingType.iterableValue + path: src/Offset/Criteria.php + - identifier: return.type + path: src/Offset/Criteria.php + # The permitted operators and values are lists carried on a value-object collaborator. + - identifier: missingType.iterableValue + path: src/Internal/AllowedField.php + - identifier: missingType.iterableValue + path: src/Internal/AllowedFilters.php # reduce() folds the links into the associative body; phpstan widens the carry to array. - identifier: return.type path: src/Links.php + # The page metadata is an associative array of scalars passed through to the response body. + - identifier: missingType.iterableValue + path: src/Internal/Rendering.php + # The page items are an opaque collection forwarded as-is to the response body. + - identifier: missingType.generics + path: src/Internal/Rendering.php # Cursor key values are opaque, decoded scalars carried on a constructor parameter. - identifier: missingType.iterableValue - path: src/Cursor.php + path: src/Cursor/Token.php # The cursor codec encodes and decodes opaque key values whose types are not known. - identifier: missingType.iterableValue path: src/Internal/Cursor/CursorCodec.php diff --git a/src/Comparison.php b/src/Comparison.php index 924045f..e8d3d48 100644 --- a/src/Comparison.php +++ b/src/Comparison.php @@ -4,8 +4,6 @@ namespace TinyBlocks\HttpQuery; -use TinyBlocks\Collection\Collection; - /** * Leaf of the filter tree pairing a field with an operator and the values compared against it. */ @@ -53,6 +51,17 @@ public function isEmpty(): bool return false; } + /** + * Tells whether the comparison targets the given field. + * + * @param string $field The field to compare against. + * @return bool True when the comparison targets the field. + */ + public function hasField(string $field): bool + { + return $this->field === $field; + } + /** * Returns the comparison operator. * @@ -63,27 +72,24 @@ public function operator(): Operator return $this->operator; } - public function toExpression(): Expression + /** + * Returns the first compared value. + * + * @return string The first of the values compared against the field. + */ + public function firstValue(): string { - /** @var Collection $values */ - $values = Collection::createFrom(elements: $this->values); - - $arguments = $values - ->map(transformations: static function (string $value): string { - if ($value !== '' && preg_match('/[\s"\'();,=!~<>]/', $value) !== 1) { - return $value; - } - - $escaped = str_replace(['\\', '"'], ['\\\\', '\\"'], $value); - $template = '"%s"'; - - return sprintf($template, $escaped); - }) - ->joinToString(separator: ','); - - $wrapped = $this->operator->isMultiValued(); - $template = $wrapped ? '%s%s(%s)' : '%s%s%s'; + return $this->values[0]; + } - return Expression::atomic(value: sprintf($template, $this->field, $this->operator->value, $arguments)); + /** + * Tells whether the comparison carries the given operator. + * + * @param Operator $operator The operator to compare against. + * @return bool True when the comparison carries the operator. + */ + public function hasOperator(Operator $operator): bool + { + return $this->operator === $operator; } } diff --git a/src/Criteria.php b/src/Criteria.php deleted file mode 100644 index ddd93cd..0000000 --- a/src/Criteria.php +++ /dev/null @@ -1,132 +0,0 @@ -It parses from the request query string and builds the result page for the items the store - * returns, keeping the pagination style internal.

    - */ -final readonly class Criteria -{ - private function __construct(private PageParameters $page, private Sort $sort, private Filter $filter) - { - } - - /** - * Creates a Criteria from the request and an optional schema. - * - *

    When the schema is omitted, the default page-size bounds apply. The pagination is a - * {@see CursorPagination} when the cursor is present, otherwise an {@see OffsetPagination}.

    - * - * @param ServerRequestInterface $request The incoming PSR-7 server request. - * @param Schema|null $schema The schema carrying the page-size bounds, or null for the default. - * @return Criteria The criteria carrying the parsed filter, sort, and pagination. - * @throws FilterExpressionIsInvalid If the filter expression cannot be parsed. - * @throws SortExpressionIsInvalid If the sort expression cannot be parsed. - * @throws PageNumberOutOfRange If the page number is less than 1. - * @throws PageSizeOutOfRange If the page size falls outside the valid range. - * @throws OffsetOutOfRange If the offset is less than 0. - */ - public static function fromQuery(ServerRequestInterface $request, ?Schema $schema = null): Criteria - { - $schema = $schema ?? Schema::default(); - $query = QueryParameters::from(request: $request); - $page = PageParameters::from(query: $query, schema: $schema); - - $expression = $query->get(key: 'filter')->toString(); - $filter = $expression === '' ? Group::none() : FilterParser::from(input: $expression)->parse(); - $sort = Sort::fromExpression(expression: $query->get(key: 'sort')->toString()); - - return new Criteria(page: $page, sort: $sort, filter: $filter); - } - - /** - * Returns the sorting specification. - * - * @return Sort The sorting specification. - */ - public function sorting(): Sort - { - return $this->sort; - } - - /** - * Returns the filtering specification as the root of the filter tree. - * - * @return Filter The filter tree root, an empty {@see Group} when no filter is present. - */ - public function filtering(): Filter - { - return $this->filter; - } - - /** - * Creates a CursorPage from the items and the ordering-key extractor. - * - * @template TValue - * @param iterable $items The items fetched for the page size plus one. - * @param Closure(TValue): list $keysOf Extracts the ordering key values from an element. - * @return CursorPage The cursor page carrying the trimmed items and the cursors. - * @throws PageSizeOutOfRange If the page size is less than 1. - */ - public function cursorPage(iterable $items, Closure $keysOf): CursorPage - { - return CursorPage::from(items: $items, keysOf: $keysOf, criteria: $this, pagination: $this->page->toCursor()); - } - - /** - * Creates an OffsetPage from the items and the total element count. - * - * @template TValue - * @param iterable $items The items on the current page. - * @param int $total The total element count across every page. - * @return OffsetPage The offset page carrying the items, the total, and the navigation. - * @throws TotalIsNegative If the total is less than 0. - * @throws PageNumberOutOfRange If the page number is less than 1. - * @throws PageSizeOutOfRange If the page size falls outside the valid range. - */ - public function offsetPage(iterable $items, int $total): OffsetPage - { - return OffsetPage::from(items: $items, total: $total, criteria: $this, pagination: $this->page->toOffset()); - } - - /** - * Returns the pagination specification. - * - * @return Pagination The pagination, cursor-based when a cursor is present. - */ - public function pagination(): Pagination - { - return $this->page->resolve(); - } - - /** - * Creates an OffsetSlice from the items, without a total element count. - * - * @template TValue - * @param iterable $items The items fetched for the page size plus one. - * @return OffsetSlice The offset slice carrying the trimmed items and the next-page hint. - * @throws PageNumberOutOfRange If the page number is less than 1. - * @throws PageSizeOutOfRange If the page size falls outside the valid range. - */ - public function offsetSlice(iterable $items): OffsetSlice - { - return OffsetSlice::from(items: $items, criteria: $this, pagination: $this->page->toOffset()); - } -} diff --git a/src/Cursor.php b/src/Cursor.php deleted file mode 100644 index 0f24434..0000000 --- a/src/Cursor.php +++ /dev/null @@ -1,105 +0,0 @@ -A cursor is built either from an incoming token (decoded on demand) or from the last-seen - * ordering key values (encoded on demand). The token is the only form that travels in the query - * string, the key values are the form the consumer feeds back to the store.

    - */ -final readonly class Cursor -{ - private function __construct(private ?array $keys, private ?string $token) - { - } - - /** - * Creates a Cursor wrapping an incoming opaque token, decoded on demand. - * - * @param string $token The opaque token received in the query string. - * @return Cursor A Cursor backed by the incoming token. - */ - public static function from(string $token): Cursor - { - return new Cursor(keys: null, token: $token); - } - - /** - * Creates an absent Cursor that carries neither a token nor key values. - * - * @return Cursor The absent cursor. - */ - public static function none(): Cursor - { - return new Cursor(keys: null, token: null); - } - - /** - * Creates a Cursor from the last-seen ordering key values, encoded on demand. - * - * @param array $keys The last-seen ordering key values. - * @return Cursor A Cursor backed by the given key values. - */ - public static function fromKeys(array $keys): Cursor - { - return new Cursor(keys: $keys, token: null); - } - - /** - * Returns the decoded ordering key values. - * - * @return array The decoded key values, empty when the cursor is absent. - * @throws CursorIsInvalid If the wrapped token cannot be decoded. - */ - public function toArray(): array - { - if (!is_null($this->keys)) { - return array_values($this->keys); - } - - if (is_null($this->token) || $this->token === '') { - return []; - } - - return CursorCodec::decode(token: $this->token); - } - - /** - * Tells whether the cursor carries neither a token nor key values. - * - * @return bool True when the cursor is absent. - */ - public function isAbsent(): bool - { - return match (true) { - !is_null($this->keys) => false, - is_null($this->token) => true, - default => $this->token === '' - }; - } - - /** - * Returns the opaque, URI-safe token. - * - * @return string The opaque token, empty when the cursor is absent. - */ - public function toString(): string - { - if (!is_null($this->token)) { - return $this->token; - } - - if (is_null($this->keys)) { - return ''; - } - - return CursorCodec::encode(keys: $this->keys); - } -} diff --git a/src/Cursor/Criteria.php b/src/Cursor/Criteria.php new file mode 100644 index 0000000..99dec81 --- /dev/null +++ b/src/Cursor/Criteria.php @@ -0,0 +1,117 @@ +It parses the request query string and, against the schema, validates the filter into a + * conjunction of comparisons and resolves the effective sort. It then produces the {@see Keyset} + * view the consumer drives to fetch and render a forward-only cursor page. The pagination approach + * is fixed, never inferred, so a cursor page always renders a cursor self link.

    + */ +final readonly class Criteria +{ + private function __construct( + private Sort $sort, + private Filter $filter, + private Pagination $pagination, + private array $comparisons, + private Sort $submittedSort + ) { + } + + /** + * Creates a Criteria from the request and an optional schema. + * + *

    When the schema is omitted, an empty contract applies: the default page-size bounds, no + * filterable or sortable field, and no default sort. Any incoming filter or sort is then + * rejected. The pagination always carries the incoming cursor token and the page size.

    + * + * @param ServerRequestInterface $request The incoming PSR-7 server request. + * @param Schema|null $schema The query contract, or null for the empty contract. + * @return Criteria The criteria carrying the validated comparisons, the effective sort, and the pagination. + * @throws FilterExpressionIsInvalid If the filter expression cannot be parsed. + * @throws SortExpressionIsInvalid If the sort expression cannot be parsed. + * @throws PageSizeOutOfRange If the page size falls outside the valid range. + * @throws FilterShapeNotSupported If the filter is not a comparison or an AND group of comparisons. + * @throws FilterFieldNotAllowed If a comparison targets a field that was never allowed. + * @throws FilterOperatorNotAllowed If a comparison uses an operator not allowed for its field. + * @throws FilterValueNotAllowed If a compared value falls outside the permitted set or kind. + * @throws SortFieldNotAllowed If the sort orders by a field that was never declared sortable. + */ + public static function fromQuery(ServerRequestInterface $request, ?Schema $schema = null): Criteria + { + $query = Query::from(schema: $schema ?? Schema::default(), request: $request); + $cursor = Token::from(token: $query->cursorToken()); + + return new Criteria( + sort: $query->sort(), + filter: $query->filter(), + pagination: Pagination::from(cursor: $cursor, perPage: $query->pageSize()), + comparisons: $query->comparisons(), + submittedSort: $query->submittedSort() + ); + } + + /** + * Returns the effective sort. + * + * @return Sort The client sort when present, otherwise the schema default sort. + */ + public function sort(): Sort + { + return $this->sort; + } + + /** + * Creates a Keyset cursor view ordered by the effective sort. + * + *

    It pairs the effective sort with the validated filter and the cursor view. It works whether + * an incoming cursor token is present, the first page yielding an empty cursor.

    + * + * @return Keyset The cursor view carrying the seek inputs and the page builder. + * @throws SortIsRequired If the effective sort is empty, so the keyset cannot anchor a page. + */ + public function keyset(): Keyset + { + if ($this->sort->isEmpty()) { + throw new SortIsRequired(); + } + + return Keyset::from( + sort: $this->sort, + filter: $this->filter, + pagination: $this->pagination, + submittedSort: $this->submittedSort + ); + } + + /** + * Returns the validated conjunction of comparisons. + * + * @return list The validated comparisons, an empty list when there is no filter. + */ + public function comparisons(): array + { + return $this->comparisons; + } +} diff --git a/src/Cursor/Keyset.php b/src/Cursor/Keyset.php new file mode 100644 index 0000000..280aab4 --- /dev/null +++ b/src/Cursor/Keyset.php @@ -0,0 +1,103 @@ +It exposes the seek inputs the consumer needs before fetching (the incoming cursor key values + * keyed by sort field and the page size), and it builds the result page once the items are + * fetched. The seek is ordered by the effective sort, while the submitted sort is the one preserved + * in every rendered URI. It is produced only by {@see Criteria::keyset()}.

    + */ +final readonly class Keyset +{ + private function __construct( + private Sort $sort, + private Filter $filter, + private Pagination $pagination, + private Sort $submittedSort + ) { + } + + /** + * Creates a Keyset from the effective sort, the filter, the pagination, and the submitted sort. + * + * @param Sort $sort The effective sort the seek is ordered by. + * @param Filter $filter The filter preserved in every rendered URI. + * @param Pagination $pagination The cursor pagination carrying the incoming cursor and the limit. + * @param Sort $submittedSort The submitted sort preserved in every rendered URI. + * @return Keyset The cursor view. + */ + public static function from(Sort $sort, Filter $filter, Pagination $pagination, Sort $submittedSort): Keyset + { + return new Keyset(sort: $sort, filter: $filter, pagination: $pagination, submittedSort: $submittedSort); + } + + /** + * Builds the cursor page from the items and an optional ordering-key extractor. + * + *

    When the extractor is omitted, the ordering keys are read from the effective sort fields on + * each array-shaped row, so the cursor keys come from the source rows.

    + * + * @template TElement + * @param iterable $items The items fetched for the page size plus one. + * @param Closure(TElement): list|null $keysOf Extracts the ordering key values from an element. + * @return Page The cursor page carrying the trimmed items and the next cursor. + */ + public function page(iterable $items, ?Closure $keysOf = null): Page + { + return Page::from( + sort: $this->submittedSort, + items: $items, + filter: $this->filter, + keysOf: $keysOf ?? SortKeys::from(sort: $this->sort), + pagination: $this->pagination + ); + } + + /** + * Returns the page size. + * + * @return int The page size. + */ + public function limit(): int + { + return $this->pagination->limit(); + } + + /** + * Returns the incoming cursor key values keyed by sort field name. + * + *

    Every effective sort field is present. The value is null when there is no incoming cursor, + * that is on the first page.

    + * + * @return array The cursor key values keyed by sort field name. + * @throws CursorIsInvalid If the decoded value count does not match the number of sort orders. + */ + public function cursor(): array + { + $fields = array_map(static fn(Order $order): string => $order->field(), $this->sort->orders()); + + return $this->pagination->cursor()->keyedBy(fields: $fields); + } + + /** + * Returns the effective sort orders. + * + * @return list The orders the seek is ordered by. + */ + public function orders(): array + { + return $this->sort->orders(); + } +} diff --git a/src/Cursor/Page.php b/src/Cursor/Page.php new file mode 100644 index 0000000..b560340 --- /dev/null +++ b/src/Cursor/Page.php @@ -0,0 +1,168 @@ + $items + */ + private function __construct( + private Sort $sort, + private Collection $items, + private Filter $filter, + private bool $hasNext, + private Token $nextCursor, + private Pagination $pagination + ) { + } + + /** + * Creates a Page from the sort, the items, the filter, the key extractor, and the pagination. + * + *

    The consumer fetches one element beyond the page size via keyset. The extra element is + * trimmed and its presence is read as the next-page hint. The next cursor anchors on the last + * retained element.

    + * + * @template TElement + * @param Sort $sort The submitted sort preserved in every rendered URI. + * @param iterable $items The items fetched for the page size plus one. + * @param Filter $filter The filter preserved in every rendered URI. + * @param Closure(TElement): list $keysOf Extracts the ordering key values from an element. + * @param Pagination $pagination The pagination describing the current page. + * @return Page The cursor page carrying the trimmed items and the next cursor. + */ + public static function from( + Sort $sort, + iterable $items, + Filter $filter, + Closure $keysOf, + Pagination $pagination + ): Page { + /** @var Collection $collection */ + $collection = Collection::createFrom(elements: $items); + $seek = Seek::from(limit: $pagination->limit(), items: $collection, keysOf: $keysOf); + + return new Page( + sort: $sort, + items: $seek->items(), + filter: $filter, + hasNext: $seek->hasNext(), + nextCursor: $seek->next(), + pagination: $pagination + ); + } + + /** + * Returns a copy of the cursor page with the items mapped through the transformation. + * + * @template TNew + * @param Closure(TValue): TNew $transformation The transformation applied to each item. + * @return Page A copy carrying the mapped items, preserving the cursor and the page size. + */ + public function map(Closure $transformation): Page + { + /** @var Collection $items */ + $items = $this->items->map(transformations: $transformation); + + return new Page( + sort: $this->sort, + items: $items, + filter: $this->filter, + hasNext: $this->hasNext, + nextCursor: $this->nextCursor, + pagination: $this->pagination + ); + } + + /** + * Returns the pagination for the next page, or null when there is none. + * + * @return Pagination|null The pagination for the next page, or null. + */ + public function next(): ?Pagination + { + return $this->nextCursor->isAbsent() + ? null + : Pagination::from(cursor: $this->nextCursor, perPage: $this->pagination->limit()); + } + + /** + * Returns the items on the current page. + * + * @return Collection The items on the current page. + */ + public function items(): Collection + { + return $this->items; + } + + /** + * Tells whether a next page exists. + * + * @return bool True when a next page exists. + */ + public function hasNext(): bool + { + return $this->hasNext; + } + + /** + * Returns the cursor page as the JSON:API meta contents. + * + * @return array The meta contents keyed in length-ascending order. + */ + public function metadata(): array + { + return [ + 'has_next' => $this->hasNext, + 'per_page' => $this->pagination->limit() + ]; + } + + /** + * Returns the navigation exposing only the next target. + * + * @return Navigation The navigation listing the next page when present. + */ + public function navigation(): Navigation + { + return Navigation::empty()->with(target: $this->next(), relation: LinkRelation::NEXT); + } + + /** + * Returns the cursor page as a JSON:API response carrying the body and the RFC 8288 Link header. + * + * @param string $baseUri The base URI the navigation URIs are built on. + * @return ResponseInterface The response with the data, meta, and links, plus the Link header. + */ + public function toResponse(string $baseUri): ResponseInterface + { + return Rendering::of( + sort: $this->sort, + self: $this->pagination, + items: $this->items, + filter: $this->filter, + baseUri: $baseUri, + metadata: $this->metadata(), + navigation: $this->navigation() + ); + } +} diff --git a/src/CursorPagination.php b/src/Cursor/Pagination.php similarity index 58% rename from src/CursorPagination.php rename to src/Cursor/Pagination.php index 76600e7..fe7869e 100644 --- a/src/CursorPagination.php +++ b/src/Cursor/Pagination.php @@ -2,31 +2,32 @@ declare(strict_types=1); -namespace TinyBlocks\HttpQuery; +namespace TinyBlocks\HttpQuery\Cursor; use TinyBlocks\HttpQuery\Exceptions\PageSizeOutOfRange; use TinyBlocks\HttpQuery\Internal\Limit; +use TinyBlocks\HttpQuery\Pagination as PaginationContract; /** * Keyset (cursor) pagination request carrying the incoming cursor and the page size. */ -final readonly class CursorPagination implements Pagination +final readonly class Pagination implements PaginationContract { - private function __construct(private Limit $limit, private Cursor $cursor) + private function __construct(private Limit $limit, private Token $cursor) { } /** - * Creates a CursorPagination from a cursor and a page size. + * Creates a Pagination from a cursor and a page size. * - * @param Cursor $cursor The incoming cursor. + * @param Token $cursor The incoming cursor. * @param int $perPage The page size. - * @return CursorPagination The pagination carrying the cursor and the limit. + * @return Pagination The pagination carrying the cursor and the limit. * @throws PageSizeOutOfRange If the page size is less than 1. */ - public static function from(Cursor $cursor, int $perPage): CursorPagination + public static function from(Token $cursor, int $perPage): Pagination { - return new CursorPagination(limit: Limit::from(value: $perPage), cursor: $cursor); + return new Pagination(limit: Limit::from(value: $perPage), cursor: $cursor); } public function limit(): int @@ -37,9 +38,9 @@ public function limit(): int /** * Returns the incoming cursor. * - * @return Cursor The cursor. + * @return Token The cursor. */ - public function cursor(): Cursor + public function cursor(): Token { return $this->cursor; } diff --git a/src/Cursor/Token.php b/src/Cursor/Token.php new file mode 100644 index 0000000..d68f13f --- /dev/null +++ b/src/Cursor/Token.php @@ -0,0 +1,130 @@ +A token is built either from an incoming string (decoded on demand) or from the last-seen + * ordering key values (encoded on demand). The string is the only form that travels in the query + * string, the key values are the form the consumer feeds back to the store.

    + */ +final readonly class Token +{ + private function __construct(private ?array $keys, private ?string $token) + { + } + + /** + * Creates a Token wrapping an incoming opaque string, decoded on demand. + * + * @param string $token The opaque token received in the query string. + * @return Token A Token backed by the incoming string. + */ + public static function from(string $token): Token + { + return new Token(keys: null, token: $token); + } + + /** + * Creates an absent Token that carries neither a string nor key values. + * + * @return Token The absent token. + */ + public static function none(): Token + { + return new Token(keys: null, token: null); + } + + /** + * Creates a Token from the last-seen ordering key values, encoded on demand. + * + * @param array $keys The last-seen ordering key values. + * @return Token A Token backed by the given key values. + */ + public static function fromKeys(array $keys): Token + { + return new Token(keys: $keys, token: null); + } + + /** + * Returns the decoded ordering key values keyed by the given field names. + * + *

    Every field is present. The value is null for every field when the token is absent, that is + * on the first page.

    + * + * @param list $fields The field names the decoded values are keyed by. + * @return array The decoded key values keyed by field name. + * @throws CursorIsInvalid If the decoded value count does not match the number of fields. + */ + public function keyedBy(array $fields): array + { + if ($this->isAbsent()) { + return array_fill_keys($fields, null); + } + + $values = $this->toArray(); + + if (count($values) !== count($fields)) { + throw CursorIsInvalid::from(token: $this->toString()); + } + + return array_combine($fields, $values); + } + + /** + * Returns the decoded ordering key values. + * + * @return array The decoded key values, empty when the token is absent. + * @throws CursorIsInvalid If the wrapped token cannot be decoded. + */ + public function toArray(): array + { + if (!is_null($this->keys)) { + return array_values($this->keys); + } + + if (is_null($this->token) || $this->token === '') { + return []; + } + + return CursorCodec::decode(token: $this->token); + } + + /** + * Tells whether the token carries neither a string nor key values. + * + * @return bool True when the token is absent. + */ + public function isAbsent(): bool + { + return match (true) { + !is_null($this->keys) => false, + is_null($this->token) => true, + default => $this->token === '' + }; + } + + /** + * Returns the opaque, URI-safe token. + * + * @return string The opaque token, empty when the token is absent. + */ + public function toString(): string + { + if (!is_null($this->token)) { + return $this->token; + } + + if (is_null($this->keys)) { + return ''; + } + + return CursorCodec::encode(keys: $this->keys); + } +} diff --git a/src/CursorPage.php b/src/CursorPage.php deleted file mode 100644 index d625097..0000000 --- a/src/CursorPage.php +++ /dev/null @@ -1,167 +0,0 @@ - $items - */ - private function __construct( - private Collection $items, - private Limit $limit, - private bool $hasNext, - private Criteria $criteria, - private Cursor $nextCursor, - private bool $hasPrevious, - private Cursor $previousCursor - ) { - } - - /** - * Creates a CursorPage from the items, the key extractor, the criteria, and the pagination. - * - *

    The consumer fetches one element beyond the page size via keyset. The extra element is - * trimmed and its presence is read as the next-page hint. The forward cursor anchors on the - * last retained element, the backward cursor on the first.

    - * - * @template TElement - * @param iterable $items The items fetched for the page size plus one. - * @param Closure(TElement): list $keysOf Extracts the ordering key values from an element. - * @param Criteria $criteria The criteria that produced the result. - * @param CursorPagination $pagination The pagination describing the current page. - * @return CursorPage The cursor page carrying the trimmed items and the cursors. - */ - public static function from( - iterable $items, - Closure $keysOf, - Criteria $criteria, - CursorPagination $pagination - ): CursorPage { - /** @var Collection $collection */ - $collection = Collection::createFrom(elements: $items); - $keyset = Keyset::from(items: $collection, keysOf: $keysOf, pagination: $pagination); - - return new CursorPage( - items: $keyset->items(), - limit: Limit::from(value: $pagination->limit()), - hasNext: $keyset->hasNext(), - criteria: $criteria, - nextCursor: $keyset->next(), - hasPrevious: $keyset->hasPrevious(), - previousCursor: $keyset->previous() - ); - } - - /** - * Returns the pagination for the next page, or null when there is none. - * - * @return CursorPagination|null The pagination for the next page, or null. - */ - public function next(): ?CursorPagination - { - return $this->nextCursor->isAbsent() - ? null - : CursorPagination::from(cursor: $this->nextCursor, perPage: $this->limit->value()); - } - - /** - * Returns the items on the current page. - * - * @return Collection The items on the current page. - */ - public function items(): Collection - { - return $this->items; - } - - /** - * Tells whether a next page exists. - * - * @return bool True when a next page exists. - */ - public function hasNext(): bool - { - return $this->hasNext; - } - - /** - * Returns the cursor page as the JSON:API meta contents. - * - * @return array The meta contents keyed in length-ascending order. - */ - public function metadata(): array - { - return [ - 'has_next' => $this->hasNext, - 'per_page' => $this->limit->value(), - 'has_previous' => $this->hasPrevious - ]; - } - - /** - * Returns the pagination for the previous page, or null when there is none. - * - * @return CursorPagination|null The pagination for the previous page, or null. - */ - public function previous(): ?CursorPagination - { - return $this->previousCursor->isAbsent() - ? null - : CursorPagination::from(cursor: $this->previousCursor, perPage: $this->limit->value()); - } - - /** - * Returns the navigation exposing the previous and next targets. - * - * @return Navigation The navigation listing the keyset pages present for this page. - */ - public function navigation(): Navigation - { - return Navigation::empty() - ->with(target: $this->previous(), relation: LinkRelation::PREVIOUS) - ->with(target: $this->next(), relation: LinkRelation::NEXT); - } - - /** - * Returns the cursor page as a JSON:API response carrying the body and the RFC 8288 Link header. - * - * @param string $baseUri The base URI the navigation URIs are built on. - * @return ResponseInterface The response with the data, meta, and links, plus the Link header. - */ - public function toResponse(string $baseUri): ResponseInterface - { - $links = Links::from(baseUri: $baseUri, criteria: $this->criteria, navigation: $this->navigation()); - - return Response::ok([ - 'data' => $this->items->toArray(), - 'meta' => $this->metadata(), - 'links' => $links->toArray() - ], $links->toHeader()); - } - - /** - * Tells whether a previous page exists. - * - * @return bool True when a previous page exists. - */ - public function hasPrevious(): bool - { - return $this->hasPrevious; - } -} diff --git a/src/Exceptions/FilterFieldNotAllowed.php b/src/Exceptions/FilterFieldNotAllowed.php new file mode 100644 index 0000000..e3de168 --- /dev/null +++ b/src/Exceptions/FilterFieldNotAllowed.php @@ -0,0 +1,36 @@ + is not allowed.'; + + private function __construct(string $field) + { + $template = FilterFieldNotAllowed::REASON_TEMPLATE; + + parent::__construct(message: sprintf($template, $field)); + } + + /** + * Creates a FilterFieldNotAllowed from the disallowed field. + * + * @param string $field The field that was never declared through the filter rules. + * @return FilterFieldNotAllowed The composed exception describing the disallowed field. + */ + public static function from(string $field): FilterFieldNotAllowed + { + return new FilterFieldNotAllowed(field: $field); + } +} diff --git a/src/Exceptions/FilterOperatorNotAllowed.php b/src/Exceptions/FilterOperatorNotAllowed.php new file mode 100644 index 0000000..f914627 --- /dev/null +++ b/src/Exceptions/FilterOperatorNotAllowed.php @@ -0,0 +1,38 @@ + is not allowed for filter field <%s>.'; + + private function __construct(string $field, Operator $operator) + { + $template = FilterOperatorNotAllowed::REASON_TEMPLATE; + + parent::__construct(message: sprintf($template, $operator->value, $field)); + } + + /** + * Creates a FilterOperatorNotAllowed from the field and its disallowed operator. + * + * @param string $field The field whose operator was rejected. + * @param Operator $operator The operator that was never declared for the field. + * @return FilterOperatorNotAllowed The composed exception describing the disallowed operator. + */ + public static function from(string $field, Operator $operator): FilterOperatorNotAllowed + { + return new FilterOperatorNotAllowed(field: $field, operator: $operator); + } +} diff --git a/src/Exceptions/FilterShapeNotSupported.php b/src/Exceptions/FilterShapeNotSupported.php new file mode 100644 index 0000000..267bd7d --- /dev/null +++ b/src/Exceptions/FilterShapeNotSupported.php @@ -0,0 +1,36 @@ + is not supported.'; + + private function __construct(string $expression) + { + $template = FilterShapeNotSupported::REASON_TEMPLATE; + + parent::__construct(message: sprintf($template, $expression)); + } + + /** + * Creates a FilterShapeNotSupported from the raw filter query string of the rejected filter. + * + * @param string $expression The raw filter query string whose shape is not supported. + * @return FilterShapeNotSupported The composed exception describing the unsupported shape. + */ + public static function from(string $expression): FilterShapeNotSupported + { + return new FilterShapeNotSupported(expression: $expression); + } +} diff --git a/src/Exceptions/FilterValueNotAllowed.php b/src/Exceptions/FilterValueNotAllowed.php new file mode 100644 index 0000000..2ada6a9 --- /dev/null +++ b/src/Exceptions/FilterValueNotAllowed.php @@ -0,0 +1,54 @@ + does not match the %s kind for filter field <%s>.'; + private const string NOT_PERMITTED = 'Value <%s> is not permitted for filter field <%s>.'; + + private function __construct(string $reason) + { + parent::__construct(message: $reason); + } + + /** + * Creates a FilterValueNotAllowed signaling that the value does not match the expected kind. + * + * @param ValueKind $kind The value kind the field expects. + * @param string $field The field whose value was rejected. + * @param string $value The value that does not match the kind. + * @return FilterValueNotAllowed The composed exception describing the kind mismatch. + */ + public static function kindMismatch(ValueKind $kind, string $field, string $value): FilterValueNotAllowed + { + $template = FilterValueNotAllowed::KIND_MISMATCH; + + return new FilterValueNotAllowed(reason: sprintf($template, $value, $kind->value, $field)); + } + + /** + * Creates a FilterValueNotAllowed signaling that the value falls outside the permitted set. + * + * @param string $field The field whose value was rejected. + * @param string $value The value that falls outside the permitted set. + * @return FilterValueNotAllowed The composed exception describing the disallowed value. + */ + public static function notPermitted(string $field, string $value): FilterValueNotAllowed + { + $template = FilterValueNotAllowed::NOT_PERMITTED; + + return new FilterValueNotAllowed(reason: sprintf($template, $value, $field)); + } +} diff --git a/src/Exceptions/SortFieldNotAllowed.php b/src/Exceptions/SortFieldNotAllowed.php new file mode 100644 index 0000000..1f4396a --- /dev/null +++ b/src/Exceptions/SortFieldNotAllowed.php @@ -0,0 +1,36 @@ + is not allowed.'; + + private function __construct(string $field) + { + $template = SortFieldNotAllowed::REASON_TEMPLATE; + + parent::__construct(message: sprintf($template, $field)); + } + + /** + * Creates a SortFieldNotAllowed from the disallowed field. + * + * @param string $field The field that was never declared through the sort rules. + * @return SortFieldNotAllowed The composed exception describing the disallowed field. + */ + public static function from(string $field): SortFieldNotAllowed + { + return new SortFieldNotAllowed(field: $field); + } +} diff --git a/src/Exceptions/SortIsRequired.php b/src/Exceptions/SortIsRequired.php new file mode 100644 index 0000000..7edecf7 --- /dev/null +++ b/src/Exceptions/SortIsRequired.php @@ -0,0 +1,23 @@ +value; - } - - /** - * Returns the expression parenthesized when it binds looser than the given connective. - * - * @param LogicalOperator $parent The connective the expression is nested within. - * @return string The expression, parenthesized when required. - */ - public function nestedWithin(LogicalOperator $parent): string - { - if (!is_null($this->connective) && $parent->bindsTighterThan(other: $this->connective)) { - $template = '(%s)'; - - return sprintf($template, $this->value); - } - - return $this->value; - } -} diff --git a/src/Filter.php b/src/Filter.php index bc29331..657485e 100644 --- a/src/Filter.php +++ b/src/Filter.php @@ -8,8 +8,8 @@ * Node of the immutable filter tree parsed from an RSQL expression. * *

    A node is either a {@see Comparison} leaf or a {@see Group} composite. The marker is sealed - * by the two implementations the library ships, so consumers match on the concrete type when they - * translate the tree to their own store.

    + * by the two implementations the library ships, so the parser builds the tree and the criteria + * validates it into the conjunction of comparisons the consumer reads.

    */ interface Filter { @@ -19,11 +19,4 @@ interface Filter * @return bool True when the filter is empty. */ public function isEmpty(): bool; - - /** - * Returns the filter as its RSQL expression. - * - * @return Expression The RSQL expression. - */ - public function toExpression(): Expression; } diff --git a/src/Group.php b/src/Group.php index cbd11cf..1d989a3 100644 --- a/src/Group.php +++ b/src/Group.php @@ -4,8 +4,6 @@ namespace TinyBlocks\HttpQuery; -use TinyBlocks\Collection\Collection; - /** * Composite of the filter tree joining child filters under a single logical connective. */ @@ -61,19 +59,4 @@ public function operator(): LogicalOperator { return $this->operator; } - - public function toExpression(): Expression - { - $operator = $this->operator; - - /** @var Collection $filters */ - $filters = Collection::createFrom(elements: $this->filters); - - $value = $filters - ->map(transformations: static fn(Filter $filter): string => $filter->toExpression() - ->nestedWithin(parent: $operator)) - ->joinToString(separator: $operator->value); - - return Expression::grouped(value: $value, connective: $operator); - } } diff --git a/src/Internal/AllowedField.php b/src/Internal/AllowedField.php new file mode 100644 index 0000000..84fec09 --- /dev/null +++ b/src/Internal/AllowedField.php @@ -0,0 +1,50 @@ +field === $field; + } + + public function permit(Comparison $comparison): Comparison + { + if (!in_array($comparison->operator(), $this->operators, true)) { + throw FilterOperatorNotAllowed::from(field: $this->field, operator: $comparison->operator()); + } + + foreach ($comparison->values() as $value) { + if (!is_null($this->values) && !in_array($value, $this->values, true)) { + throw FilterValueNotAllowed::notPermitted(field: $this->field, value: $value); + } + + if (!is_null($this->kind) && !$this->kind->matches(value: $value)) { + throw FilterValueNotAllowed::kindMismatch(kind: $this->kind, field: $this->field, value: $value); + } + } + + return $comparison; + } +} diff --git a/src/Internal/AllowedFilters.php b/src/Internal/AllowedFilters.php new file mode 100644 index 0000000..c7fae10 --- /dev/null +++ b/src/Internal/AllowedFilters.php @@ -0,0 +1,48 @@ + $fields + */ + private function __construct(private Collection $fields) + { + } + + public static function createFromEmpty(): AllowedFilters + { + /** @var Collection $fields */ + $fields = Collection::createFromEmpty(); + + return new AllowedFilters(fields: $fields); + } + + public function with(?ValueKind $kind, string $field, ?array $values, array $operators): AllowedFilters + { + $rule = AllowedField::from(kind: $kind, field: $field, values: $values, operators: $operators); + + return new AllowedFilters(fields: $this->fields->add($rule)); + } + + public function permit(Comparison $comparison): Comparison + { + $rule = $this->fields->findBy( + predicates: static fn(AllowedField $allowed): bool => $allowed->hasField(field: $comparison->field()) + ); + + if (is_null($rule)) { + throw FilterFieldNotAllowed::from(field: $comparison->field()); + } + + return $rule->permit(comparison: $comparison); + } +} diff --git a/src/Internal/Conjunction.php b/src/Internal/Conjunction.php new file mode 100644 index 0000000..6abc308 --- /dev/null +++ b/src/Internal/Conjunction.php @@ -0,0 +1,44 @@ +operator() !== LogicalOperator::AND) { + throw FilterShapeNotSupported::from(expression: $expression); + } + + return array_map( + static fn(Filter $filter): Comparison => Conjunction::leaf(filter: $filter, expression: $expression), + $group->filters() + ); + } + + private static function leaf(Filter $filter, string $expression): Comparison + { + if ($filter instanceof Comparison) { + return $filter; + } + + throw FilterShapeNotSupported::from(expression: $expression); + } +} diff --git a/src/Internal/Cursor/CursorCodec.php b/src/Internal/Cursor/CursorCodec.php index 994c3c3..d04ecc5 100644 --- a/src/Internal/Cursor/CursorCodec.php +++ b/src/Internal/Cursor/CursorCodec.php @@ -4,8 +4,6 @@ namespace TinyBlocks\HttpQuery\Internal\Cursor; -use TinyBlocks\Encoder\Base62; -use TinyBlocks\Encoder\Internal\Exceptions\InvalidDecoding; use TinyBlocks\HttpQuery\Exceptions\CursorIsInvalid; final class CursorCodec @@ -16,13 +14,13 @@ private function __construct() public static function decode(string $token): array { - try { - $payload = Base62::from(value: $token)->decode(); - } catch (InvalidDecoding $exception) { - throw CursorIsInvalid::from(token: $token, previous: $exception); + $decoded = base64_decode(strtr($token, '-_', '+/'), true); + + if ($decoded === false) { + throw CursorIsInvalid::from(token: $token); } - $keys = json_decode($payload); + $keys = json_decode($decoded); if (!is_array($keys)) { throw CursorIsInvalid::from(token: $token); @@ -35,6 +33,9 @@ public static function encode(array $keys): string { $payload = json_encode($keys, JSON_THROW_ON_ERROR); - return Base62::from(value: $payload)->encode(); + return $payload + |> base64_encode(...) + |> (fn($x) => strtr($x, '+/', '-_')) + |> (fn($x) => rtrim($x, '=')); } } diff --git a/src/Internal/Cursor/Keyset.php b/src/Internal/Cursor/Keyset.php deleted file mode 100644 index 8a0cfe9..0000000 --- a/src/Internal/Cursor/Keyset.php +++ /dev/null @@ -1,72 +0,0 @@ - $keysOf - * @param Window $window - */ - private function __construct(private Cursor $cursor, private Closure $keysOf, private Window $window) - { - } - - /** - * @template TElement - * @param Collection $items - * @param Closure(TElement): list $keysOf - * @return Keyset - */ - public static function from(Collection $items, Closure $keysOf, CursorPagination $pagination): Keyset - { - /** @var Window $window */ - $window = Window::from(items: $items, limit: $pagination->limit()); - - return new Keyset(cursor: $pagination->cursor(), keysOf: $keysOf, window: $window); - } - - public function next(): Cursor - { - return $this->cursorFor(element: $this->hasNext() ? $this->window->items()->last() : null); - } - - /** - * @return Collection - */ - public function items(): Collection - { - return $this->window->items(); - } - - public function hasNext(): bool - { - return $this->window->hasNext(); - } - - public function previous(): Cursor - { - return $this->cursorFor(element: $this->hasPrevious() ? $this->window->items()->first() : null); - } - - private function cursorFor(mixed $element): Cursor - { - return is_null($element) ? Cursor::none() : Cursor::fromKeys(keys: ($this->keysOf)($element)); - } - - public function hasPrevious(): bool - { - return !$this->cursor->isAbsent(); - } -} diff --git a/src/Internal/Cursor/Seek.php b/src/Internal/Cursor/Seek.php new file mode 100644 index 0000000..ee996bb --- /dev/null +++ b/src/Internal/Cursor/Seek.php @@ -0,0 +1,61 @@ + $window + * @param Closure(TValue): list $keysOf + */ + private function __construct(private Window $window, private Closure $keysOf) + { + } + + /** + * @template TElement + * @param Collection $items + * @param Closure(TElement): list $keysOf + * @return Seek + */ + public static function from(int $limit, Collection $items, Closure $keysOf): Seek + { + /** @var Window $window */ + $window = Window::from(limit: $limit, items: $items); + + return new Seek(window: $window, keysOf: $keysOf); + } + + public function next(): Token + { + return $this->cursorFor(element: $this->hasNext() ? $this->window->items()->last() : null); + } + + /** + * @return Collection + */ + public function items(): Collection + { + return $this->window->items(); + } + + public function hasNext(): bool + { + return $this->window->hasNext(); + } + + private function cursorFor(mixed $element): Token + { + return is_null($element) ? Token::none() : Token::fromKeys(keys: ($this->keysOf)($element)); + } +} diff --git a/src/Internal/Cursor/SortKeys.php b/src/Internal/Cursor/SortKeys.php new file mode 100644 index 0000000..51a91d3 --- /dev/null +++ b/src/Internal/Cursor/SortKeys.php @@ -0,0 +1,22 @@ +orders(); + + return static fn(array $row): array => array_map( + static fn(Order $order): mixed => $row[$order->field()], + $orders + ); + } +} diff --git a/src/Internal/Iso8601.php b/src/Internal/Iso8601.php new file mode 100644 index 0000000..75ed31f --- /dev/null +++ b/src/Internal/Iso8601.php @@ -0,0 +1,15 @@ +limit()); + $offset = Offset::from(value: $pagination->offset()); + + return new OffsetNavigation( + hasNext: $hasNext, + pagination: $pagination, + pageNumber: PageNumber::fromOffset(limit: $limit, offset: $offset) + ); + } + + public function next(): ?Pagination + { + if (!$this->hasNext) { + return null; + } + + $next = $this->pageNumber->next(); + + return Pagination::fromPage(page: $next->value(), perPage: $this->pagination->limit()); + } + + public function first(): Pagination + { + return Pagination::fromPage(page: 1, perPage: $this->pagination->limit()); + } + + public function limit(): int + { + return $this->pagination->limit(); + } + + public function atPage(int $page): Pagination + { + return Pagination::fromPage(page: $page, perPage: $this->pagination->limit()); + } + + public function offset(): int + { + return $this->pagination->offset(); + } + + public function hasNext(): bool + { + return $this->hasNext; + } + + public function previous(): ?Pagination + { + $previous = $this->pageNumber->previous(); + + return is_null($previous) + ? null + : Pagination::fromPage(page: $previous->value(), perPage: $this->pagination->limit()); + } + + public function currentPage(): int + { + return $this->pageNumber->value(); + } + + public function hasPrevious(): bool + { + return !$this->pageNumber->isFirst(); + } +} diff --git a/src/Internal/Offset/OffsetNavigator.php b/src/Internal/Offset/OffsetNavigator.php deleted file mode 100644 index baca52c..0000000 --- a/src/Internal/Offset/OffsetNavigator.php +++ /dev/null @@ -1,59 +0,0 @@ -pageNumber()->next(); - - return OffsetPagination::fromPage(page: $next->value(), perPage: $this->pagination->limit()); - } - - public function first(): OffsetPagination - { - return OffsetPagination::fromPage(page: 1, perPage: $this->pagination->limit()); - } - - public function atPage(int $page): OffsetPagination - { - return OffsetPagination::fromPage(page: $page, perPage: $this->pagination->limit()); - } - - public function isFirst(): bool - { - return $this->pageNumber()->isFirst(); - } - - public function previous(): ?OffsetPagination - { - $previous = $this->pageNumber()->previous(); - - return is_null($previous) - ? null - : OffsetPagination::fromPage(page: $previous->value(), perPage: $this->pagination->limit()); - } - - private function pageNumber(): PageNumber - { - return PageNumber::fromOffset( - offset: Offset::from(value: $this->pagination->offset()), - limit: Limit::from(value: $this->pagination->limit()) - ); - } -} diff --git a/src/Internal/Offset/PageNumber.php b/src/Internal/Offset/PageNumber.php index 29270ad..4c7aaff 100644 --- a/src/Internal/Offset/PageNumber.php +++ b/src/Internal/Offset/PageNumber.php @@ -22,7 +22,7 @@ public static function from(int $value): PageNumber return new PageNumber(value: $value); } - public static function fromOffset(Offset $offset, Limit $limit): PageNumber + public static function fromOffset(Limit $limit, Offset $offset): PageNumber { return new PageNumber(value: intdiv($offset->value(), $limit->value()) + 1); } diff --git a/src/Internal/PageParameters.php b/src/Internal/PageParameters.php deleted file mode 100644 index f15c361..0000000 --- a/src/Internal/PageParameters.php +++ /dev/null @@ -1,52 +0,0 @@ -get(key: 'page')->toArray(); - - $size = Attribute::from(value: $page['size'] ?? null); - $cursor = Attribute::from(value: $page['cursor'] ?? null); - $number = Attribute::from(value: $page['number'] ?? null); - - $requested = $size->toString() === '' ? $schema->defaultPerPage() : $size->toInteger(); - - return new PageParameters( - cursor: Cursor::from(token: $cursor->toString()), - perPage: $schema->pageSizeFor(requested: $requested), - pageNumber: $number->toString() === '' ? 1 : $number->toInteger() - ); - } - - public function resolve(): Pagination - { - return $this->cursor->isAbsent() ? $this->toOffset() : $this->toCursor(); - } - - public function toCursor(): CursorPagination - { - return CursorPagination::from(cursor: $this->cursor, perPage: $this->perPage); - } - - public function toOffset(): OffsetPagination - { - return OffsetPagination::fromPage(page: $this->pageNumber, perPage: $this->perPage); - } -} diff --git a/src/Internal/Query.php b/src/Internal/Query.php new file mode 100644 index 0000000..c4311cd --- /dev/null +++ b/src/Internal/Query.php @@ -0,0 +1,87 @@ +get(key: 'page')->toArray(); + + $size = Attribute::from(value: $page['size'] ?? null); + $cursor = Attribute::from(value: $page['cursor'] ?? null); + $number = Attribute::from(value: $page['number'] ?? null); + + $expression = $parameters->get(key: 'filter')->toString(); + $filter = $expression === '' ? Group::none() : FilterParser::from(input: $expression)->parse(); + $submittedSort = Sort::fromExpression(expression: $parameters->get(key: 'sort')->toString()); + + return new Query( + sort: $schema->sortFor(sort: $submittedSort), + filter: $filter, + pageSize: $schema->pageSizeFor(requested: $size->toString() === '' ? null : $size->toInteger()), + pageNumber: $number->toString() === '' ? 1 : $number->toInteger(), + comparisons: $schema->comparisonsFor(filter: $filter, expression: $expression), + cursorToken: $cursor->toString(), + submittedSort: $submittedSort + ); + } + + public function sort(): Sort + { + return $this->sort; + } + + public function filter(): Filter + { + return $this->filter; + } + + public function pageSize(): int + { + return $this->pageSize; + } + + public function pageNumber(): int + { + return $this->pageNumber; + } + + public function comparisons(): array + { + return $this->comparisons; + } + + public function cursorToken(): string + { + return $this->cursorToken; + } + + public function submittedSort(): Sort + { + return $this->submittedSort; + } +} diff --git a/src/Internal/Rendering.php b/src/Internal/Rendering.php new file mode 100644 index 0000000..1a46ddf --- /dev/null +++ b/src/Internal/Rendering.php @@ -0,0 +1,39 @@ + $items->toArray(), + 'meta' => $metadata, + 'links' => $links->toArray() + ], $links->toHeader()); + } +} diff --git a/src/Internal/Rsql/Expression.php b/src/Internal/Rsql/Expression.php new file mode 100644 index 0000000..df2e7b7 --- /dev/null +++ b/src/Internal/Rsql/Expression.php @@ -0,0 +1,40 @@ +value; + } + + public function nestedWithin(LogicalOperator $parent): string + { + if (!is_null($this->connective) && $parent->bindsTighterThan(other: $this->connective)) { + $template = '(%s)'; + + return sprintf($template, $this->value); + } + + return $this->value; + } +} diff --git a/src/Internal/Rsql/Renderer.php b/src/Internal/Rsql/Renderer.php new file mode 100644 index 0000000..1168590 --- /dev/null +++ b/src/Internal/Rsql/Renderer.php @@ -0,0 +1,70 @@ +value(); + } + + private static function expressionOf(Filter $filter): Expression + { + return match (true) { + $filter instanceof Group => Renderer::grouped(group: $filter), + $filter instanceof Comparison => Renderer::atomic(comparison: $filter) + }; + } + + private static function atomic(Comparison $comparison): Expression + { + /** @var Collection $values */ + $values = Collection::createFrom(elements: $comparison->values()); + + $arguments = $values + ->map(transformations: static function (string $value): string { + if ($value !== '' && preg_match('/[\s"\'();,=!~<>]/', $value) !== 1) { + return $value; + } + + $escaped = str_replace(['\\', '"'], ['\\\\', '\\"'], $value); + $template = '"%s"'; + + return sprintf($template, $escaped); + }) + ->joinToString(separator: ','); + + $template = $comparison->operator()->isMultiValued() ? '%s%s(%s)' : '%s%s%s'; + + return Expression::atomic( + value: sprintf($template, $comparison->field(), $comparison->operator()->value, $arguments) + ); + } + + private static function grouped(Group $group): Expression + { + $operator = $group->operator(); + + /** @var Collection $filters */ + $filters = Collection::createFrom(elements: $group->filters()); + + $value = $filters + ->map(transformations: static fn(Filter $filter): string => Renderer::expressionOf(filter: $filter) + ->nestedWithin(parent: $operator)) + ->joinToString(separator: $operator->value); + + return Expression::grouped(value: $value, connective: $operator); + } +} diff --git a/src/Internal/Uri.php b/src/Internal/Uri.php index d4dd270..cc07a68 100644 --- a/src/Internal/Uri.php +++ b/src/Internal/Uri.php @@ -5,6 +5,7 @@ namespace TinyBlocks\HttpQuery\Internal; use TinyBlocks\HttpQuery\Filter; +use TinyBlocks\HttpQuery\Internal\Rsql\Renderer; use TinyBlocks\HttpQuery\Pagination; use TinyBlocks\HttpQuery\Sort; @@ -20,7 +21,7 @@ public static function from(Sort $sort, Filter $filter, string $baseUri, Paginat if (!$filter->isEmpty()) { $template = 'filter=%s'; - $parameters[] = sprintf($template, $filter->toExpression()->value()); + $parameters[] = sprintf($template, Renderer::from(filter: $filter)); } if (!$sort->isEmpty()) { diff --git a/src/Internal/Window.php b/src/Internal/Window.php index 961783c..d9f68ed 100644 --- a/src/Internal/Window.php +++ b/src/Internal/Window.php @@ -22,7 +22,7 @@ private function __construct(private Collection $items, private bool $hasNext) * @param Collection $items * @return Window */ - public static function from(Collection $items, int $limit): Window + public static function from(int $limit, Collection $items): Window { $elements = [...$items]; $hasNext = count($elements) > $limit; diff --git a/src/Links.php b/src/Links.php index a74490c..4997038 100644 --- a/src/Links.php +++ b/src/Links.php @@ -13,9 +13,10 @@ /** * Navigation of a result, rendered as a JSON:API body links object or an RFC 8288 Link header. * - *

    It renders uniformly over a {@see Navigation}, building each URI from the criteria's filter and - * sort plus the pagination of the self link and of every target, so the filter and the sort are - * preserved in every URI.

    + *

    It renders uniformly over a {@see Navigation}, building each URI from the given filter and sort + * plus the pagination of the self link and of every target, so the filter and the sort are + * preserved in every URI. The self link is built from the page's own current pagination, so a cursor + * page renders a cursor self and an offset page renders an offset self.

    */ final readonly class Links { @@ -27,23 +28,30 @@ private function __construct(private WebLink $self, private Collection $links) } /** - * Creates a Links from the base URI, the criteria, and the navigation of a result. + * Creates a Links from the sort, the page pagination, the filter, the base URI, and the navigation. * + * @param Sort $sort The sort preserved in every URI. + * @param Pagination $self The page's own current pagination, rendered as the self link. + * @param Filter $filter The filter preserved in every URI. * @param string $baseUri The base URI the navigation URIs are built on. - * @param Criteria $criteria The criteria that produced the result. * @param Navigation $navigation The navigation the result exposes. * @return Links The navigation for the result. */ - public static function from(string $baseUri, Criteria $criteria, Navigation $navigation): Links - { + public static function from( + Sort $sort, + Pagination $self, + Filter $filter, + string $baseUri, + Navigation $navigation + ): Links { $uriFor = static fn(Pagination $pagination): string => Uri::from( - sort: $criteria->sorting(), - filter: $criteria->filtering(), + sort: $sort, + filter: $filter, baseUri: $baseUri, pagination: $pagination ); - $self = new WebLink(uri: $uriFor($criteria->pagination()), relation: LinkRelation::SELF); + $current = new WebLink(uri: $uriFor($self), relation: LinkRelation::SELF); /** @var Collection $links */ $links = $navigation->targets()->map( @@ -53,7 +61,7 @@ public static function from(string $baseUri, Criteria $criteria, Navigation $nav ) ); - return new Links(self: $self, links: $links); + return new Links(self: $current, links: $links); } /** diff --git a/src/Offset/Criteria.php b/src/Offset/Criteria.php new file mode 100644 index 0000000..876cc96 --- /dev/null +++ b/src/Offset/Criteria.php @@ -0,0 +1,152 @@ +It parses the request query string and, against the schema, validates the filter into a + * conjunction of comparisons and resolves the effective sort. It then builds the offset {@see Page} + * or {@see Slice} the consumer renders. The pagination approach is fixed, never inferred, so every + * page renders an offset self link.

    + */ +final readonly class Criteria +{ + private function __construct( + private Sort $sort, + private Filter $filter, + private Pagination $pagination, + private array $comparisons, + private Sort $submittedSort + ) { + } + + /** + * Creates a Criteria from the request and an optional schema. + * + *

    When the schema is omitted, an empty contract applies: the default page-size bounds, no + * filterable or sortable field, and no default sort. Any incoming filter or sort is then + * rejected. The pagination derives its offset from the one-based page number and the page size.

    + * + * @param ServerRequestInterface $request The incoming PSR-7 server request. + * @param Schema|null $schema The query contract, or null for the empty contract. + * @return Criteria The criteria carrying the validated comparisons, the effective sort, and the pagination. + * @throws FilterExpressionIsInvalid If the filter expression cannot be parsed. + * @throws SortExpressionIsInvalid If the sort expression cannot be parsed. + * @throws PageNumberOutOfRange If the page number is less than 1. + * @throws PageSizeOutOfRange If the page size falls outside the valid range. + * @throws FilterShapeNotSupported If the filter is not a comparison or an AND group of comparisons. + * @throws FilterFieldNotAllowed If a comparison targets a field that was never allowed. + * @throws FilterOperatorNotAllowed If a comparison uses an operator not allowed for its field. + * @throws FilterValueNotAllowed If a compared value falls outside the permitted set or kind. + * @throws SortFieldNotAllowed If the sort orders by a field that was never declared sortable. + */ + public static function fromQuery(ServerRequestInterface $request, ?Schema $schema = null): Criteria + { + $query = Query::from(schema: $schema ?? Schema::default(), request: $request); + + return new Criteria( + sort: $query->sort(), + filter: $query->filter(), + pagination: Pagination::fromPage(page: $query->pageNumber(), perPage: $query->pageSize()), + comparisons: $query->comparisons(), + submittedSort: $query->submittedSort() + ); + } + + /** + * Creates a Page from the total element count and the items. + * + * @template TValue + * @param int $total The total element count across every page. + * @param iterable $items The items on the current page. + * @return Page The offset page carrying the items, the total, and the navigation. + * @throws TotalIsNegative If the total is less than 0. + */ + public function page(int $total, iterable $items): Page + { + return Page::from( + sort: $this->submittedSort, + total: $total, + items: $items, + filter: $this->filter, + pagination: $this->pagination + ); + } + + /** + * Returns the effective sort. + * + * @return Sort The client sort when present, otherwise the schema default sort. + */ + public function sort(): Sort + { + return $this->sort; + } + + /** + * Returns the page size. + * + * @return int The page size. + */ + public function limit(): int + { + return $this->pagination->limit(); + } + + /** + * Creates a Slice from the items, without a total element count. + * + * @template TValue + * @param iterable $items The items fetched for the page size plus one. + * @return Slice The offset slice carrying the trimmed items and the next-page hint. + */ + public function slice(iterable $items): Slice + { + return Slice::from( + sort: $this->submittedSort, + items: $items, + filter: $this->filter, + pagination: $this->pagination + ); + } + + /** + * Returns the zero-based offset of the current page. + * + * @return int The offset of the current page. + */ + public function offset(): int + { + return $this->pagination->offset(); + } + + /** + * Returns the validated conjunction of comparisons. + * + * @return list The validated comparisons, an empty list when there is no filter. + */ + public function comparisons(): array + { + return $this->comparisons; + } +} diff --git a/src/OffsetPage.php b/src/Offset/Page.php similarity index 58% rename from src/OffsetPage.php rename to src/Offset/Page.php index bb8af6c..14de7c3 100644 --- a/src/OffsetPage.php +++ b/src/Offset/Page.php @@ -2,72 +2,76 @@ declare(strict_types=1); -namespace TinyBlocks\HttpQuery; +namespace TinyBlocks\HttpQuery\Offset; use Psr\Http\Message\ResponseInterface; use TinyBlocks\Collection\Collection; use TinyBlocks\Http\LinkRelation; -use TinyBlocks\Http\Server\Response; use TinyBlocks\HttpQuery\Exceptions\TotalIsNegative; +use TinyBlocks\HttpQuery\Filter; use TinyBlocks\HttpQuery\Internal\Limit; use TinyBlocks\HttpQuery\Internal\Offset\Offset; -use TinyBlocks\HttpQuery\Internal\Offset\OffsetNavigator; +use TinyBlocks\HttpQuery\Internal\Offset\OffsetNavigation; use TinyBlocks\HttpQuery\Internal\Offset\PageCount; use TinyBlocks\HttpQuery\Internal\Offset\PageNumber; use TinyBlocks\HttpQuery\Internal\Offset\Total; +use TinyBlocks\HttpQuery\Internal\Rendering; +use TinyBlocks\HttpQuery\Navigation; +use TinyBlocks\HttpQuery\Sort; /** * Offset-based page carrying its items, the total element count, and the navigation targets. * * @template TValue */ -final readonly class OffsetPage +final readonly class Page { /** * @param Collection $items */ private function __construct( - private Collection $items, + private Sort $sort, private Total $total, - private Criteria $criteria, - private OffsetNavigator $navigator, + private Collection $items, + private Filter $filter, + private OffsetNavigation $paging, private PageCount $pageCount, - private PageNumber $pageNumber, - private OffsetPagination $pagination + private Pagination $pagination ) { } /** - * Creates an OffsetPage from the items, the total element count, the criteria, and the pagination. + * Creates a Page from the sort, the total element count, the items, the filter, and the pagination. * * @template TElement - * @param iterable $items The items on the current page. + * @param Sort $sort The submitted sort preserved in every rendered URI. * @param int $total The total element count across every page. - * @param Criteria $criteria The criteria that produced the result. - * @param OffsetPagination $pagination The pagination describing the current page. - * @return OffsetPage The page carrying the items, the total, and the navigation. + * @param iterable $items The items on the current page. + * @param Filter $filter The filter preserved in every rendered URI. + * @param Pagination $pagination The pagination describing the current page. + * @return Page The page carrying the items, the total, and the navigation. * @throws TotalIsNegative If the total is less than 0. */ - public static function from( - iterable $items, - int $total, - Criteria $criteria, - OffsetPagination $pagination - ): OffsetPage { + public static function from(Sort $sort, int $total, iterable $items, Filter $filter, Pagination $pagination): Page + { $count = Total::from(value: $total); $limit = Limit::from(value: $pagination->limit()); - $offset = Offset::from(value: $pagination->offset()); + $pageCount = $count->pageCount(limit: $limit); + $pageNumber = PageNumber::fromOffset(limit: $limit, offset: Offset::from(value: $pagination->offset())); /** @var Collection $collection */ $collection = Collection::createFrom(elements: [...$items]); - return new OffsetPage( - items: $collection, + return new Page( + sort: $sort, total: $count, - criteria: $criteria, - navigator: OffsetNavigator::from(pagination: $pagination), - pageCount: $count->pageCount(limit: $limit), - pageNumber: PageNumber::fromOffset(offset: $offset, limit: $limit), + items: $collection, + filter: $filter, + paging: OffsetNavigation::from( + hasNext: $pageCount->hasPageAfter(page: $pageNumber), + pagination: $pagination + ), + pageCount: $pageCount, pagination: $pagination ); } @@ -75,31 +79,31 @@ public static function from( /** * Returns the pagination for the last page, or null when there is no page. * - * @return OffsetPagination|null The pagination for the last page, or null. + * @return Pagination|null The pagination for the last page, or null. */ - public function last(): ?OffsetPagination + public function last(): ?Pagination { - return $this->pageCount->isEmpty() ? null : $this->navigator->atPage(page: $this->pageCount->value()); + return $this->pageCount->isEmpty() ? null : $this->paging->atPage(page: $this->pageCount->value()); } /** * Returns the pagination for the next page, or null when there is none. * - * @return OffsetPagination|null The pagination for the next page, or null. + * @return Pagination|null The pagination for the next page, or null. */ - public function next(): ?OffsetPagination + public function next(): ?Pagination { - return $this->hasNext() ? $this->navigator->next() : null; + return $this->paging->next(); } /** * Returns the pagination for the first page, or null when there is no page. * - * @return OffsetPagination|null The pagination for the first page, or null. + * @return Pagination|null The pagination for the first page, or null. */ - public function first(): ?OffsetPagination + public function first(): ?Pagination { - return $this->pageCount->isEmpty() ? null : $this->navigator->first(); + return $this->pageCount->isEmpty() ? null : $this->paging->first(); } /** @@ -122,16 +126,6 @@ public function total(): int return $this->total->value(); } - /** - * Tells whether the current page is the last page. - * - * @return bool True when the current page is the last page. - */ - public function isLast(): bool - { - return !$this->hasNext(); - } - /** * Returns the zero-based offset of the current page. * @@ -139,7 +133,7 @@ public function isLast(): bool */ public function offset(): int { - return $this->pagination->offset(); + return $this->paging->offset(); } /** @@ -149,17 +143,7 @@ public function offset(): int */ public function hasNext(): bool { - return $this->pageCount->hasPageAfter(page: $this->pageNumber); - } - - /** - * Tells whether the current page is the first page. - * - * @return bool True when the current page is the first page. - */ - public function isFirst(): bool - { - return $this->navigator->isFirst(); + return $this->paging->hasNext(); } /** @@ -171,22 +155,22 @@ public function metadata(): array { return [ 'total' => $this->total->value(), - 'has_next' => $this->hasNext(), - 'per_page' => $this->pagination->limit(), + 'has_next' => $this->paging->hasNext(), + 'per_page' => $this->paging->limit(), 'total_pages' => $this->pageCount->value(), - 'current_page' => $this->pageNumber->value(), - 'has_previous' => $this->hasPrevious() + 'current_page' => $this->paging->currentPage(), + 'has_previous' => $this->paging->hasPrevious() ]; } /** * Returns the pagination for the previous page, or null when there is none. * - * @return OffsetPagination|null The pagination for the previous page, or null. + * @return Pagination|null The pagination for the previous page, or null. */ - public function previous(): ?OffsetPagination + public function previous(): ?Pagination { - return $this->navigator->previous(); + return $this->paging->previous(); } /** @@ -211,13 +195,15 @@ public function navigation(): Navigation */ public function toResponse(string $baseUri): ResponseInterface { - $links = Links::from(baseUri: $baseUri, criteria: $this->criteria, navigation: $this->navigation()); - - return Response::ok([ - 'data' => $this->items->toArray(), - 'meta' => $this->metadata(), - 'links' => $links->toArray() - ], $links->toHeader()); + return Rendering::of( + sort: $this->sort, + self: $this->pagination, + items: $this->items, + filter: $this->filter, + baseUri: $baseUri, + metadata: $this->metadata(), + navigation: $this->navigation() + ); } /** @@ -237,7 +223,7 @@ public function totalPages(): int */ public function currentPage(): int { - return $this->pageNumber->value(); + return $this->paging->currentPage(); } /** @@ -247,6 +233,6 @@ public function currentPage(): int */ public function hasPrevious(): bool { - return !$this->navigator->isFirst(); + return $this->paging->hasPrevious(); } } diff --git a/src/OffsetPagination.php b/src/Offset/Pagination.php similarity index 67% rename from src/OffsetPagination.php rename to src/Offset/Pagination.php index c5500e2..155e474 100644 --- a/src/OffsetPagination.php +++ b/src/Offset/Pagination.php @@ -2,7 +2,7 @@ declare(strict_types=1); -namespace TinyBlocks\HttpQuery; +namespace TinyBlocks\HttpQuery\Offset; use TinyBlocks\HttpQuery\Exceptions\OffsetOutOfRange; use TinyBlocks\HttpQuery\Exceptions\PageNumberOutOfRange; @@ -10,47 +10,48 @@ use TinyBlocks\HttpQuery\Internal\Limit; use TinyBlocks\HttpQuery\Internal\Offset\Offset; use TinyBlocks\HttpQuery\Internal\Offset\PageNumber; +use TinyBlocks\HttpQuery\Pagination as PaginationContract; /** * Offset-based pagination request whose canonical state is an offset and a limit. * *

    The page-based factory derives the offset from the one-based page number and the page size.

    */ -final readonly class OffsetPagination implements Pagination +final readonly class Pagination implements PaginationContract { private function __construct(private Limit $limit, private Offset $offset) { } /** - * Creates an OffsetPagination from a one-based page number and a page size. + * Creates a Pagination from a one-based page number and a page size. * * @param int $page The one-based page number. * @param int $perPage The page size. - * @return OffsetPagination The pagination whose offset is derived from the page and the page size. + * @return Pagination The pagination whose offset is derived from the page and the page size. * @throws PageNumberOutOfRange If the page number is less than 1. * @throws PageSizeOutOfRange If the page size is less than 1. */ - public static function fromPage(int $page, int $perPage): OffsetPagination + public static function fromPage(int $page, int $perPage): Pagination { $limit = Limit::from(value: $perPage); $number = PageNumber::from(value: $page); - return new OffsetPagination(limit: $limit, offset: Offset::fromPage(page: $number, limit: $limit)); + return new Pagination(limit: $limit, offset: Offset::fromPage(page: $number, limit: $limit)); } /** - * Creates an OffsetPagination from a zero-based offset and a limit. + * Creates a Pagination from a limit and a zero-based offset. * - * @param int $offset The zero-based offset. * @param int $limit The maximum number of elements per page. - * @return OffsetPagination The pagination carrying the offset and the limit. + * @param int $offset The zero-based offset. + * @return Pagination The pagination carrying the offset and the limit. * @throws OffsetOutOfRange If the offset is less than 0. * @throws PageSizeOutOfRange If the limit is less than 1. */ - public static function fromOffset(int $offset, int $limit): OffsetPagination + public static function fromOffset(int $limit, int $offset): Pagination { - return new OffsetPagination(limit: Limit::from(value: $limit), offset: Offset::from(value: $offset)); + return new Pagination(limit: Limit::from(value: $limit), offset: Offset::from(value: $offset)); } /** @@ -60,7 +61,7 @@ public static function fromOffset(int $offset, int $limit): OffsetPagination */ public function page(): int { - return PageNumber::fromOffset(offset: $this->offset, limit: $this->limit)->value(); + return PageNumber::fromOffset(limit: $this->limit, offset: $this->offset)->value(); } public function limit(): int diff --git a/src/OffsetSlice.php b/src/Offset/Slice.php similarity index 56% rename from src/OffsetSlice.php rename to src/Offset/Slice.php index 1e76eb5..3df8097 100644 --- a/src/OffsetSlice.php +++ b/src/Offset/Slice.php @@ -2,68 +2,64 @@ declare(strict_types=1); -namespace TinyBlocks\HttpQuery; +namespace TinyBlocks\HttpQuery\Offset; use Psr\Http\Message\ResponseInterface; use TinyBlocks\Collection\Collection; use TinyBlocks\Http\LinkRelation; -use TinyBlocks\Http\Server\Response; -use TinyBlocks\HttpQuery\Internal\Limit; -use TinyBlocks\HttpQuery\Internal\Offset\Offset; -use TinyBlocks\HttpQuery\Internal\Offset\OffsetNavigator; -use TinyBlocks\HttpQuery\Internal\Offset\PageNumber; +use TinyBlocks\HttpQuery\Filter; +use TinyBlocks\HttpQuery\Internal\Offset\OffsetNavigation; +use TinyBlocks\HttpQuery\Internal\Rendering; use TinyBlocks\HttpQuery\Internal\Window; +use TinyBlocks\HttpQuery\Navigation; +use TinyBlocks\HttpQuery\Sort; /** * Offset-based slice carrying its items and the next-page hint, without a total element count. * * @template TValue */ -final readonly class OffsetSlice +final readonly class Slice { /** * @param Collection $items */ private function __construct( + private Sort $sort, private Collection $items, - private bool $hasNext, - private Criteria $criteria, - private OffsetNavigator $navigator, - private PageNumber $pageNumber, - private OffsetPagination $pagination + private Filter $filter, + private OffsetNavigation $paging, + private Pagination $pagination ) { } /** - * Creates an OffsetSlice from the items, the criteria, and the pagination. + * Creates a Slice from the sort, the items, the filter, and the pagination. * *

    The consumer fetches one element beyond the page size. The extra element is trimmed and * its presence is read as the next-page hint.

    * * @template TElement + * @param Sort $sort The submitted sort preserved in every rendered URI. * @param iterable $items The items fetched for the page size plus one. - * @param Criteria $criteria The criteria that produced the result. - * @param OffsetPagination $pagination The pagination describing the current page. - * @return OffsetSlice The slice carrying the trimmed items and the next-page hint. + * @param Filter $filter The filter preserved in every rendered URI. + * @param Pagination $pagination The pagination describing the current page. + * @return Slice The slice carrying the trimmed items and the next-page hint. */ - public static function from(iterable $items, Criteria $criteria, OffsetPagination $pagination): OffsetSlice + public static function from(Sort $sort, iterable $items, Filter $filter, Pagination $pagination): Slice { - $limit = Limit::from(value: $pagination->limit()); - $offset = Offset::from(value: $pagination->offset()); - /** @var Collection $collection */ $collection = Collection::createFrom(elements: $items); - $window = Window::from(items: $collection, limit: $pagination->limit()); + $window = Window::from(limit: $pagination->limit(), items: $collection); /** @var Collection $trimmed */ $trimmed = $window->items(); - return new OffsetSlice( + return new Slice( + sort: $sort, items: $trimmed, - hasNext: $window->hasNext(), - criteria: $criteria, - navigator: OffsetNavigator::from(pagination: $pagination), - pageNumber: PageNumber::fromOffset(offset: $offset, limit: $limit), + filter: $filter, + paging: OffsetNavigation::from(hasNext: $window->hasNext(), pagination: $pagination), pagination: $pagination ); } @@ -71,21 +67,21 @@ public static function from(iterable $items, Criteria $criteria, OffsetPaginatio /** * Returns the pagination for the next page, or null when there is none. * - * @return OffsetPagination|null The pagination for the next page, or null. + * @return Pagination|null The pagination for the next page, or null. */ - public function next(): ?OffsetPagination + public function next(): ?Pagination { - return $this->hasNext ? $this->navigator->next() : null; + return $this->paging->next(); } /** * Returns the pagination for the first page. * - * @return OffsetPagination The pagination for the first page. + * @return Pagination The pagination for the first page. */ - public function first(): OffsetPagination + public function first(): Pagination { - return $this->navigator->first(); + return $this->paging->first(); } /** @@ -105,7 +101,7 @@ public function items(): Collection */ public function offset(): int { - return $this->pagination->offset(); + return $this->paging->offset(); } /** @@ -115,7 +111,7 @@ public function offset(): int */ public function hasNext(): bool { - return $this->hasNext; + return $this->paging->hasNext(); } /** @@ -126,21 +122,21 @@ public function hasNext(): bool public function metadata(): array { return [ - 'has_next' => $this->hasNext, - 'per_page' => $this->pagination->limit(), - 'current_page' => $this->pageNumber->value(), - 'has_previous' => $this->hasPrevious() + 'has_next' => $this->paging->hasNext(), + 'per_page' => $this->paging->limit(), + 'current_page' => $this->paging->currentPage(), + 'has_previous' => $this->paging->hasPrevious() ]; } /** * Returns the pagination for the previous page, or null when there is none. * - * @return OffsetPagination|null The pagination for the previous page, or null. + * @return Pagination|null The pagination for the previous page, or null. */ - public function previous(): ?OffsetPagination + public function previous(): ?Pagination { - return $this->navigator->previous(); + return $this->paging->previous(); } /** @@ -164,13 +160,15 @@ public function navigation(): Navigation */ public function toResponse(string $baseUri): ResponseInterface { - $links = Links::from(baseUri: $baseUri, criteria: $this->criteria, navigation: $this->navigation()); - - return Response::ok([ - 'data' => $this->items->toArray(), - 'meta' => $this->metadata(), - 'links' => $links->toArray() - ], $links->toHeader()); + return Rendering::of( + sort: $this->sort, + self: $this->pagination, + items: $this->items, + filter: $this->filter, + baseUri: $baseUri, + metadata: $this->metadata(), + navigation: $this->navigation() + ); } /** @@ -180,7 +178,7 @@ public function toResponse(string $baseUri): ResponseInterface */ public function currentPage(): int { - return $this->pageNumber->value(); + return $this->paging->currentPage(); } /** @@ -190,6 +188,6 @@ public function currentPage(): int */ public function hasPrevious(): bool { - return !$this->navigator->isFirst(); + return $this->paging->hasPrevious(); } } diff --git a/src/Pagination.php b/src/Pagination.php index 91c244d..c668d44 100644 --- a/src/Pagination.php +++ b/src/Pagination.php @@ -7,8 +7,9 @@ /** * Pagination request that knows its page size and how to serialize itself into a query string. * - *

    It is implemented by the offset-based {@see OffsetPagination} and the keyset {@see CursorPagination}, - * so a {@see Criteria} carries either one without branching on the concrete type.

    + *

    It is implemented by the offset-based {@see Offset\Pagination} and the + * keyset {@see Cursor\Pagination}, so {@see Links} renders a page over either + * approach without branching on the concrete type.

    */ interface Pagination { diff --git a/src/Schema.php b/src/Schema.php index a7dd2d1..c5b73aa 100644 --- a/src/Schema.php +++ b/src/Schema.php @@ -4,18 +4,32 @@ namespace TinyBlocks\HttpQuery; +use TinyBlocks\HttpQuery\Exceptions\FilterFieldNotAllowed; +use TinyBlocks\HttpQuery\Exceptions\FilterOperatorNotAllowed; +use TinyBlocks\HttpQuery\Exceptions\FilterShapeNotSupported; +use TinyBlocks\HttpQuery\Exceptions\FilterValueNotAllowed; use TinyBlocks\HttpQuery\Exceptions\PageSizeOutOfRange; +use TinyBlocks\HttpQuery\Exceptions\SortFieldNotAllowed; +use TinyBlocks\HttpQuery\Internal\AllowedFilters; +use TinyBlocks\HttpQuery\Internal\Conjunction; /** - * Page-size bounds used to read and write a Criteria. + * Declarative contract of the query an endpoint accepts, used to validate an incoming request. * - *

    The query parameter names follow JSON:API and are fixed: filter, sort, + *

    It declares the filterable fields with their permitted operators, values, and kinds, the + * client-sortable fields, the sort applied when the client sends none, and the page-size bounds. + * The query parameter names follow JSON:API and are fixed: filter, sort, * and the page family. The default page size is 20 and the maximum is 100.

    */ final readonly class Schema { - private function __construct(private int $maxPerPage, private int $defaultPerPage) - { + private function __construct( + private AllowedFilters $allowed, + private Sort $byDefault, + private int $maxPerPage, + private int $defaultPerPage, + private array $sortableFields + ) { if ($maxPerPage < 1) { throw PageSizeOutOfRange::belowMinimum(perPage: $maxPerPage); } @@ -30,49 +44,88 @@ private function __construct(private int $maxPerPage, private int $defaultPerPag } /** - * Creates a Schema carrying the default page-size bounds. + * Creates a Schema with an empty contract and the default page-size bounds. * - * @return Schema The default schema. + * @return Schema The empty schema. */ - public static function default(): Schema + public static function create(): Schema { - return new Schema(maxPerPage: 100, defaultPerPage: 20); + return Schema::default(); } /** - * Returns the maximum allowed page size. + * Creates a Schema with an empty contract and the default page-size bounds. * - * @return int The maximum page size. + * @return Schema The default schema. */ - public function maxPerPage(): int + public static function default(): Schema { - return $this->maxPerPage; + return new Schema( + allowed: AllowedFilters::createFromEmpty(), + byDefault: Sort::fromExpression(expression: ''), + maxPerPage: 100, + defaultPerPage: 20, + sortableFields: [] + ); } /** - * Returns the requested page size bounded by the maximum allowed. + * Returns the effective sort, the configured default when the client omits one. * - * @param int $requested The requested page size. - * @return int The requested page size when it is within the maximum. - * @throws PageSizeOutOfRange If the requested size exceeds the maximum. + * @param Sort $sort The incoming sort parsed from the request. + * @return Sort The effective sort applied to the store. + * @throws SortFieldNotAllowed If an order targets a field that was never declared sortable. */ - public function pageSizeFor(int $requested): int + public function sortFor(Sort $sort): Sort { - if ($requested > $this->maxPerPage) { - throw PageSizeOutOfRange::aboveMaximum(maximum: $this->maxPerPage, perPage: $requested); + if ($sort->isEmpty()) { + return $this->byDefault; + } + + foreach ($sort->orders() as $order) { + if (!in_array($order->field(), $this->sortableFields, true)) { + throw SortFieldNotAllowed::from(field: $order->field()); + } } - return $requested; + return $sort; } /** - * Returns the page size applied when the query omits one. + * Returns a copy of the Schema declaring the fields the client may sort by. * - * @return int The default page size. + * @param list $fields The fields the client may sort by. + * @return Schema A copy carrying the client-sortable fields. */ - public function defaultPerPage(): int + public function sortable(array $fields): Schema { - return $this->defaultPerPage; + return new Schema( + allowed: $this->allowed, + byDefault: $this->byDefault, + maxPerPage: $this->maxPerPage, + defaultPerPage: $this->defaultPerPage, + sortableFields: $fields + ); + } + + /** + * Returns a copy of the Schema allowing the field under the operators, values, and kind. + * + * @param string $field The field the endpoint exposes for filtering. + * @param list $operators The operators permitted for the field. + * @param ValueKind|null $kind The kind every value must match, or null to skip the kind check. + * @param list|null $values The permitted values, or null to permit any value. + * @return Schema A copy carrying the original contract plus the allowed field. + */ + public function filterable(string $field, array $operators, ?ValueKind $kind = null, ?array $values = null): Schema + { + return new Schema( + allowed: $this->allowed->with(kind: $kind, field: $field, values: $values, operators: $operators), + byDefault: $this->byDefault, + maxPerPage: $this->maxPerPage, + defaultPerPage: $this->defaultPerPage, + sortableFields: $this->sortableFields + ); } /** @@ -80,10 +133,74 @@ public function defaultPerPage(): int * * @param int $maxPerPage The maximum allowed page size. * @return Schema A copy of the schema carrying the new maximum page size. + * @throws PageSizeOutOfRange If the maximum is below 1 or below the default page size. */ - public function withMaxPerPage(int $maxPerPage): Schema + public function maxPerPage(int $maxPerPage): Schema { - return new Schema(maxPerPage: $maxPerPage, defaultPerPage: $this->defaultPerPage); + return new Schema( + allowed: $this->allowed, + byDefault: $this->byDefault, + maxPerPage: $maxPerPage, + defaultPerPage: $this->defaultPerPage, + sortableFields: $this->sortableFields + ); + } + + /** + * Returns a copy of the Schema with the sort applied when the client sends none. + * + * @param Sort $sort The sort applied when the client omits one. + * @return Schema A copy carrying the default sort. + */ + public function defaultSort(Sort $sort): Schema + { + return new Schema( + allowed: $this->allowed, + byDefault: $sort, + maxPerPage: $this->maxPerPage, + defaultPerPage: $this->defaultPerPage, + sortableFields: $this->sortableFields + ); + } + + /** + * Returns the requested page size, the default when none is requested, bounded by the maximum. + * + * @param int|null $requested The requested page size, or null when the query omits one. + * @return int The effective page size within the maximum. + * @throws PageSizeOutOfRange If the requested size exceeds the maximum. + */ + public function pageSizeFor(?int $requested): int + { + $size = is_null($requested) ? $this->defaultPerPage : $requested; + + if ($size > $this->maxPerPage) { + throw PageSizeOutOfRange::aboveMaximum(maximum: $this->maxPerPage, perPage: $size); + } + + return $size; + } + + /** + * Returns the validated conjunction of comparisons flattened from the filter. + * + * @param Filter $filter The incoming filter parsed from the request. + * @param string $expression The raw filter query string, rendered in shape-violation messages. + * @return list The validated comparison leaves in filter order. + * @throws FilterShapeNotSupported If the filter is not a comparison or an AND group of comparisons. + * @throws FilterFieldNotAllowed If a comparison targets a field that was never allowed. + * @throws FilterOperatorNotAllowed If a comparison uses an operator not allowed for its field. + * @throws FilterValueNotAllowed If a compared value falls outside the permitted set or kind. + */ + public function comparisonsFor(Filter $filter, string $expression): array + { + /** @var list $comparisons */ + $comparisons = Conjunction::from(filter: $filter, expression: $expression); + + return array_map( + fn(Comparison $comparison): Comparison => $this->allowed->permit(comparison: $comparison), + $comparisons + ); } /** @@ -91,9 +208,16 @@ public function withMaxPerPage(int $maxPerPage): Schema * * @param int $defaultPerPage The page size applied when the query omits one. * @return Schema A copy of the schema carrying the new default page size. + * @throws PageSizeOutOfRange If the default is below 1 or above the maximum page size. */ - public function withDefaultPerPage(int $defaultPerPage): Schema + public function defaultPerPage(int $defaultPerPage): Schema { - return new Schema(maxPerPage: $this->maxPerPage, defaultPerPage: $defaultPerPage); + return new Schema( + allowed: $this->allowed, + byDefault: $this->byDefault, + maxPerPage: $this->maxPerPage, + defaultPerPage: $defaultPerPage, + sortableFields: $this->sortableFields + ); } } diff --git a/src/ValueKind.php b/src/ValueKind.php new file mode 100644 index 0000000..7943a0d --- /dev/null +++ b/src/ValueKind.php @@ -0,0 +1,35 @@ +A STRING is any non-empty string, an INTEGER is an optionally + * signed sequence of digits, and a DATETIME is an ISO-8601 date or date-time.

    + */ +enum ValueKind: string +{ + case STRING = 'string'; + case INTEGER = 'integer'; + case DATETIME = 'datetime'; + + /** + * Tells whether the value matches this kind. + * + * @param string $value The value to test against the kind. + * @return bool True when the value matches the kind. + */ + public function matches(string $value): bool + { + return match ($this) { + ValueKind::STRING => $value !== '', + ValueKind::INTEGER => preg_match('/^-?\d+$/', $value) === 1, + ValueKind::DATETIME => Iso8601::isValid(value: $value) + }; + } +} diff --git a/tests/Unit/ComparisonTest.php b/tests/Unit/ComparisonTest.php new file mode 100644 index 0000000..a438c0e --- /dev/null +++ b/tests/Unit/ComparisonTest.php @@ -0,0 +1,120 @@ +field(); + + /** @Then it returns the field being compared */ + self::assertSame('status', $field); + } + + public function testValuesThenReturnsTheComparedValues(): void + { + /** @Given an IN comparison carrying several values */ + $comparison = Comparison::of(field: 'role', values: ['admin', 'user'], operator: Operator::IN); + + /** @When reading the compared values */ + $values = $comparison->values(); + + /** @Then it returns the values compared against the field in order */ + self::assertSame(['admin', 'user'], $values); + } + + public function testIsEmptyThenReportsItIsNotEmpty(): void + { + /** @Given an equality comparison */ + $comparison = Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL); + + /** @When checking whether it is empty */ + $isEmpty = $comparison->isEmpty(); + + /** @Then it reports itself as not empty */ + self::assertFalse($isEmpty); + } + + public function testOperatorThenReturnsTheComparisonOperator(): void + { + /** @Given an equality comparison */ + $comparison = Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL); + + /** @When reading the comparison operator */ + $operator = $comparison->operator(); + + /** @Then it returns the operator the comparison carries */ + self::assertSame(Operator::EQUAL, $operator); + } + + public function testHasFieldWhenFieldMatchesThenIsTrue(): void + { + /** @Given an equality comparison on a field */ + $comparison = Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL); + + /** @When asking whether it targets that field */ + $hasField = $comparison->hasField(field: 'status'); + + /** @Then it reports that it targets the field */ + self::assertTrue($hasField); + } + + public function testHasFieldWhenFieldDiffersThenIsFalse(): void + { + /** @Given an equality comparison on a field */ + $comparison = Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL); + + /** @When asking whether it targets another field */ + $hasField = $comparison->hasField(field: 'total'); + + /** @Then it reports that it does not target the field */ + self::assertFalse($hasField); + } + + public function testFirstValueWhenMultipleValuesThenReturnsTheFirst(): void + { + /** @Given an IN comparison carrying several values */ + $comparison = Comparison::of(field: 'role', values: ['admin', 'user'], operator: Operator::IN); + + /** @When reading the first compared value */ + $firstValue = $comparison->firstValue(); + + /** @Then it returns the first of the compared values */ + self::assertSame('admin', $firstValue); + } + + public function testHasOperatorWhenOperatorMatchesThenIsTrue(): void + { + /** @Given an equality comparison */ + $comparison = Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL); + + /** @When asking whether it carries the equality operator */ + $hasOperator = $comparison->hasOperator(operator: Operator::EQUAL); + + /** @Then it reports that it carries the operator */ + self::assertTrue($hasOperator); + } + + public function testHasOperatorWhenOperatorDiffersThenIsFalse(): void + { + /** @Given an equality comparison */ + $comparison = Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL); + + /** @When asking whether it carries another operator */ + $hasOperator = $comparison->hasOperator(operator: Operator::NOT_EQUAL); + + /** @Then it reports that it does not carry the operator */ + self::assertFalse($hasOperator); + } +} diff --git a/tests/Unit/CriteriaTest.php b/tests/Unit/CriteriaTest.php deleted file mode 100644 index bc1a97c..0000000 --- a/tests/Unit/CriteriaTest.php +++ /dev/null @@ -1,228 +0,0 @@ -sorting()->isEmpty()); - } - - public function testFromQueryWhenEmptyThenFilteringIsAnEmptyGroup(): void - { - /** @Given empty query parameters */ - $query = Query::from(parameters: []); - - /** @When building the criteria from the query */ - $criteria = Criteria::fromQuery(request: $query); - - /** @Then the filtering is an empty group */ - self::assertInstanceOf(Group::class, $criteria->filtering()); - - /** @And the group carries no child filter */ - self::assertSame([], $criteria->filtering()->filters()); - } - - public function testFromQueryWhenNoCursorThenPaginationIsOffsetBased(): void - { - /** @Given query parameters without a cursor */ - $query = Query::from(parameters: ['page' => ['number' => '2', 'size' => '15']]); - - /** @When building the criteria from the query */ - $criteria = Criteria::fromQuery(request: $query); - - /** @Then the pagination is offset-based */ - self::assertInstanceOf(OffsetPagination::class, $criteria->pagination()); - } - - public function testFromQueryWhenPerPageIsAtTheMaximumThenItIsAccepted(): void - { - /** @Given query parameters carrying a page size at the default maximum */ - $query = Query::from(parameters: ['page' => ['size' => '100']]); - - /** @When building the criteria from the query */ - $criteria = Criteria::fromQuery(request: $query); - - /** @Then the pagination is offset-based */ - self::assertInstanceOf(OffsetPagination::class, $criteria->pagination()); - - /** @And it carries the maximum page size */ - self::assertSame(100, $criteria->pagination()->limit()); - } - - public function testCursorPageWhenBuiltFromRequestThenReturnsCursorPage(): void - { - /** @Given a criteria parsed from a request carrying a page size of two */ - $criteria = Criteria::fromQuery(request: Query::from(parameters: ['page' => ['size' => '2']])); - - /** @When building a cursor page from the items fetched for the page size plus one */ - $page = $criteria->cursorPage(items: [10, 20, 30], keysOf: static fn(mixed $element): array => [$element]); - - /** @Then the result is a cursor page */ - self::assertInstanceOf(CursorPage::class, $page); - - /** @And the items are trimmed to the page size */ - self::assertSame([10, 20], $page->items()->toArray()); - } - - public function testOffsetPageWhenBuiltFromRequestThenReturnsOffsetPage(): void - { - /** @Given a criteria parsed from a request carrying a page size of three */ - $criteria = Criteria::fromQuery(request: Query::from(parameters: ['page' => ['size' => '3']])); - - /** @When building an offset page from the items and the total element count */ - $page = $criteria->offsetPage(items: ['a', 'b', 'c'], total: 30); - - /** @Then the result is an offset page */ - self::assertInstanceOf(OffsetPage::class, $page); - - /** @And it carries the total element count */ - self::assertSame(30, $page->total()); - } - - public function testOffsetSliceWhenBuiltFromRequestThenReturnsOffsetSlice(): void - { - /** @Given a criteria parsed from a request carrying a page size of three */ - $criteria = Criteria::fromQuery(request: Query::from(parameters: ['page' => ['size' => '3']])); - - /** @When building an offset slice from the items fetched for the page size plus one */ - $slice = $criteria->offsetSlice(items: ['a', 'b', 'c', 'd']); - - /** @Then the result is an offset slice */ - self::assertInstanceOf(OffsetSlice::class, $slice); - - /** @And it reports a next page from the trimmed extra element */ - self::assertTrue($slice->hasNext()); - } - - public function testFromQueryWhenCursorIsPresentThenPaginationIsCursorBased(): void - { - /** @Given query parameters carrying a cursor */ - $query = Query::from(parameters: ['page' => ['cursor' => 'abc', 'size' => '10']]); - - /** @When building the criteria from the query */ - $criteria = Criteria::fromQuery(request: $query); - - /** @Then the pagination is cursor-based */ - self::assertInstanceOf(CursorPagination::class, $criteria->pagination()); - - /** @And it carries the requested page size */ - self::assertSame(10, $criteria->pagination()->limit()); - - /** @And it carries the incoming cursor token */ - self::assertSame('abc', $criteria->pagination()->cursor()->toString()); - } - - public function testFromQueryWhenEmptyThenPaginationCarriesDefaultPageAndLimit(): void - { - /** @Given empty query parameters */ - $query = Query::from(parameters: []); - - /** @When building the criteria from the query */ - $criteria = Criteria::fromQuery(request: $query); - - /** @Then the pagination is offset-based */ - self::assertInstanceOf(OffsetPagination::class, $criteria->pagination()); - - /** @And it starts at the first page */ - self::assertSame(1, $criteria->pagination()->page()); - - /** @And it carries the default page size */ - self::assertSame(20, $criteria->pagination()->limit()); - } - - public function testFromQueryWhenCustomSchemaGivenThenAppliesItsDefaultPageSize(): void - { - /** @Given query parameters carrying a page number without a page size */ - $query = Query::from(parameters: ['page' => ['number' => '2']]); - - /** @And a schema lowering the default page size */ - $schema = Schema::default()->withDefaultPerPage(defaultPerPage: 5); - - /** @When building the criteria from the query and the schema */ - $criteria = Criteria::fromQuery(request: $query, schema: $schema); - - /** @Then the pagination is offset-based */ - self::assertInstanceOf(OffsetPagination::class, $criteria->pagination()); - - /** @And the pagination points at the requested page */ - self::assertSame(2, $criteria->pagination()->page()); - - /** @And the pagination carries the schema default page size */ - self::assertSame(5, $criteria->pagination()->limit()); - } - - public function testFromQueryWhenPerPageAboveMaximumThenThrowsPageSizeOutOfRange(): void - { - /** @Given query parameters carrying a page size above the default maximum */ - $query = Query::from(parameters: ['page' => ['size' => '500']]); - - /** @Then an exception indicating the page size is out of range is raised */ - $this->expectException(PageSizeOutOfRange::class); - $this->expectExceptionMessage('Page size'); - - /** @When building the criteria from the query */ - Criteria::fromQuery(request: $query); - } - - public function testFromQueryWhenFilterSortAndPageGivenThenEachSpecificationIsParsed(): void - { - /** @Given query parameters carrying a filter, a sort, a page, and a page size */ - $query = Query::from(parameters: [ - 'sort' => '-created_at', - 'page' => ['number' => '2', 'size' => '15'], - 'filter' => 'status==paid' - ]); - - /** @When building the criteria from the query */ - $criteria = Criteria::fromQuery(request: $query); - - /** @Then the filtering is a comparison */ - self::assertInstanceOf(Comparison::class, $criteria->filtering()); - - /** @And the comparison targets the filtered field */ - self::assertSame('status', $criteria->filtering()->field()); - - /** @And the sorting carries exactly one order */ - self::assertCount(1, $criteria->sorting()->orders()); - - /** @And the single order sorts by the descending field */ - self::assertSame('created_at', $criteria->sorting()->orders()[0]->field()); - - /** @And the single order applies descending direction */ - self::assertSame(Direction::DESCENDING, $criteria->sorting()->orders()[0]->direction()); - - /** @And the pagination is offset-based */ - self::assertInstanceOf(OffsetPagination::class, $criteria->pagination()); - - /** @And it points at the requested page */ - self::assertSame(2, $criteria->pagination()->page()); - - /** @And it carries the requested page size */ - self::assertSame(15, $criteria->pagination()->limit()); - } -} diff --git a/tests/Unit/Cursor/CriteriaTest.php b/tests/Unit/Cursor/CriteriaTest.php new file mode 100644 index 0000000..7eba9fe --- /dev/null +++ b/tests/Unit/Cursor/CriteriaTest.php @@ -0,0 +1,173 @@ +sort()->isEmpty()); + } + + public function testFromQueryWhenEmptyThenComparisonsAreEmpty(): void + { + /** @Given empty query parameters */ + $query = Query::from(parameters: []); + + /** @When building the criteria from the query */ + $criteria = Criteria::fromQuery(request: $query); + + /** @Then there is no comparison */ + self::assertSame([], $criteria->comparisons()); + } + + public function testKeysetWhenEffectiveSortIsEmptyThenThrowsSortIsRequired(): void + { + /** @Given a criteria parsed from a request carrying no sort and no schema default */ + $criteria = Criteria::fromQuery(request: Query::from(parameters: [])); + + /** @Then an exception indicating a deterministic order is required is raised */ + $this->expectException(SortIsRequired::class); + $this->expectExceptionMessage('A keyset requires a deterministic order, but the effective sort is empty.'); + + /** @When building the keyset view */ + $criteria->keyset(); + } + + public function testKeysetWhenBuiltWithoutCursorThenBuildsCursorPage(): void + { + /** @Given a schema declaring a default sort over the identifier */ + $schema = Schema::create()->defaultSort(sort: Sort::fromExpression(expression: 'id')); + + /** @And a criteria parsed from a request carrying a page size of two and no cursor */ + $criteria = Criteria::fromQuery(request: Query::from(parameters: ['page' => ['size' => '2']]), schema: $schema); + + /** @When building a cursor page through the keyset view over the array rows fetched */ + $page = $criteria->keyset()->page(items: [['id' => 10], ['id' => 20], ['id' => 30]]); + + /** @Then the result is a cursor page */ + self::assertInstanceOf(Page::class, $page); + + /** @And the items are trimmed to the page size */ + self::assertSame([['id' => 10], ['id' => 20]], $page->items()->toArray()); + } + + public function testKeysetWhenIncomingCursorPresentThenBuildsCursorPage(): void + { + /** @Given an opaque token produced from ordering key values */ + $token = Token::fromKeys(keys: [5])->toString(); + + /** @And a schema declaring a default sort over the identifier */ + $schema = Schema::create()->defaultSort(sort: Sort::fromExpression(expression: 'id')); + + /** @And a criteria parsed from a request carrying that cursor and a page size of two */ + $criteria = Criteria::fromQuery( + request: Query::from(parameters: ['page' => ['cursor' => $token, 'size' => '2']]), + schema: $schema + ); + + /** @When building a cursor page through the keyset view over the items fetched */ + $page = $criteria->keyset()->page(items: [10, 20, 30], keysOf: static fn(int $element): array => [$element]); + + /** @Then the cursor page reports a next page */ + self::assertTrue($page->hasNext()); + + /** @And the items are trimmed to the page size */ + self::assertSame([10, 20], $page->items()->toArray()); + } + + public function testFromQueryWhenCursorPresentThenKeysetCarriesPageSizeAndCursor(): void + { + /** @Given an opaque token produced from a single ordering key value */ + $token = Token::fromKeys(keys: [5])->toString(); + + /** @And a schema declaring a default sort over the identifier */ + $schema = Schema::create()->defaultSort(sort: Sort::fromExpression(expression: 'id')); + + /** @And a criteria parsed from a request carrying that cursor and a page size of ten */ + $criteria = Criteria::fromQuery( + request: Query::from(parameters: ['page' => ['cursor' => $token, 'size' => '10']]), + schema: $schema + ); + + /** @When building the keyset view */ + $keyset = $criteria->keyset(); + + /** @Then the keyset carries the requested page size */ + self::assertSame(10, $keyset->limit()); + + /** @And the keyset decodes the incoming cursor keyed by the sort field */ + self::assertSame(['id' => 5], $keyset->cursor()); + } + + public function testFromQueryWhenCustomSchemaGivenThenAppliesItsDefaultPageSize(): void + { + /** @Given a schema lowering the default page size and declaring a default sort */ + $schema = Schema::create() + ->defaultPerPage(defaultPerPage: 5) + ->defaultSort(sort: Sort::fromExpression(expression: 'id')); + + /** @When building the keyset view from a query carrying no page size and the schema */ + $keyset = Criteria::fromQuery(request: Query::from(parameters: []), schema: $schema)->keyset(); + + /** @Then the keyset carries the schema default page size */ + self::assertSame(5, $keyset->limit()); + } + + public function testFromQueryWhenFilterAndSortGivenThenEachSpecificationIsValidated(): void + { + /** @Given a schema allowing the filtered and sorted fields */ + $schema = Schema::create() + ->sortable(fields: ['created_at']) + ->filterable(field: 'status', operators: [Operator::EQUAL]); + + /** @And a query carrying a filter and a sort */ + $query = Query::from(parameters: ['sort' => '-created_at', 'filter' => 'status==paid']); + + /** @When building the criteria from the query and the schema */ + $criteria = Criteria::fromQuery(request: $query, schema: $schema); + + /** @Then the validated comparisons carry the filtered field and value */ + self::assertEquals( + [Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL)], + $criteria->comparisons() + ); + + /** @And the effective sort is the client sort */ + self::assertEquals(Sort::fromExpression(expression: '-created_at'), $criteria->sort()); + } + + public function testFromQueryWhenPerPageAboveMaximumThenThrowsPageSizeOutOfRange(): void + { + /** @Given query parameters carrying a page size above the default maximum */ + $query = Query::from(parameters: ['page' => ['size' => '500']]); + + /** @Then an exception indicating the page size is out of range is raised */ + $this->expectException(PageSizeOutOfRange::class); + $this->expectExceptionMessage('Page size'); + + /** @When building the criteria from the query */ + Criteria::fromQuery(request: $query); + } +} diff --git a/tests/Unit/Cursor/KeysetTest.php b/tests/Unit/Cursor/KeysetTest.php new file mode 100644 index 0000000..cabd19c --- /dev/null +++ b/tests/Unit/Cursor/KeysetTest.php @@ -0,0 +1,144 @@ +schema = Schema::create()->sortable(fields: ['id', 'name', 'created_at']); + } + + public function testLimitThenReturnsThePageSize(): void + { + /** @Given a keyset view built from a request carrying a sort and a page size of fifteen */ + $keyset = Criteria::fromQuery( + request: Query::from(parameters: ['sort' => 'id', 'page' => ['size' => '15']]), + schema: $this->schema + )->keyset(); + + /** @When reading the page size */ + $limit = $keyset->limit(); + + /** @Then it returns the requested page size */ + self::assertSame(15, $limit); + } + + public function testOrdersWhenSortGivenThenReturnsItsOrders(): void + { + /** @Given a keyset view built from a descending sort over a single field */ + $keyset = Criteria::fromQuery(request: Query::from(parameters: ['sort' => '-name']), schema: $this->schema) + ->keyset(); + + /** @When reading the orders */ + $orders = $keyset->orders(); + + /** @Then it returns the orders of the effective sort */ + self::assertEquals([Order::from(field: 'name', direction: Direction::DESCENDING)], $orders); + } + + public function testPageWhenKeysOfGivenThenUsesTheExtractor(): void + { + /** @Given a keyset view built from a request carrying a sort and a page size of two */ + $keyset = Criteria::fromQuery( + request: Query::from(parameters: ['sort' => 'id', 'page' => ['size' => '2']]), + schema: $this->schema + )->keyset(); + + /** @When building the page from the items and an explicit key extractor */ + $page = $keyset->page(items: [10, 20, 30], keysOf: static fn(int $element): array => [$element]); + + /** @Then the items are trimmed to the page size */ + self::assertSame([10, 20], $page->items()->toArray()); + + /** @And the next pagination anchors on the keys extracted from the last retained element */ + self::assertEquals(Pagination::from(perPage: 2, cursor: Token::fromKeys(keys: [20])), $page->next()); + } + + public function testPageWhenNoKeysOfGivenThenDerivesKeysFromTheSortFields(): void + { + /** @Given a keyset view built from a request carrying a sort and a page size of two */ + $keyset = Criteria::fromQuery( + request: Query::from(parameters: ['sort' => 'id', 'page' => ['size' => '2']]), + schema: $this->schema + )->keyset(); + + /** @When building the page from array rows without a key extractor */ + $page = $keyset->page(items: [['id' => 10], ['id' => 20], ['id' => 30]]); + + /** @Then the items are trimmed to the page size */ + self::assertSame([['id' => 10], ['id' => 20]], $page->items()->toArray()); + + /** @And the next pagination anchors on the sort-field keys of the last retained row */ + self::assertEquals(Pagination::from(perPage: 2, cursor: Token::fromKeys(keys: [20])), $page->next()); + } + + public function testCursorWhenNoIncomingCursorThenEverySortFieldIsNull(): void + { + /** @Given a keyset view built from a request carrying a sort over two fields */ + $keyset = Criteria::fromQuery( + request: Query::from(parameters: ['sort' => 'created_at,id', 'page' => ['size' => '2']]), + schema: $this->schema + )->keyset(); + + /** @When reading the incoming cursor key values */ + $cursor = $keyset->cursor(); + + /** @Then every sort field is present with a null value */ + self::assertSame(['created_at' => null, 'id' => null], $cursor); + } + + public function testCursorWhenIncomingCursorGivenThenKeysValuesBySortField(): void + { + /** @Given an opaque token produced from the ordering key values */ + $token = Token::fromKeys(keys: ['2023-01-15T10:30:00Z', 5])->toString(); + + /** @And a keyset view built from a request carrying that cursor and a sort over two fields */ + $keyset = Criteria::fromQuery( + request: Query::from( + parameters: ['sort' => 'created_at,id', 'page' => ['cursor' => $token, 'size' => '2']] + ), + schema: $this->schema + )->keyset(); + + /** @When reading the incoming cursor key values */ + $cursor = $keyset->cursor(); + + /** @Then the values are keyed by the sort field names */ + self::assertSame(['created_at' => '2023-01-15T10:30:00Z', 'id' => 5], $cursor); + } + + public function testCursorWhenDecodedCountMismatchesThenThrowsCursorIsInvalid(): void + { + /** @Given an opaque token carrying a single key value */ + $token = Token::fromKeys(keys: [5])->toString(); + + /** @And a keyset view whose sort carries two fields */ + $keyset = Criteria::fromQuery( + request: Query::from( + parameters: ['sort' => 'created_at,id', 'page' => ['cursor' => $token, 'size' => '2']] + ), + schema: $this->schema + )->keyset(); + + /** @Then an exception indicating the cursor is invalid is raised */ + $this->expectException(CursorIsInvalid::class); + + /** @When reading the incoming cursor key values */ + $keyset->cursor(); + } +} diff --git a/tests/Unit/Cursor/PageTest.php b/tests/Unit/Cursor/PageTest.php new file mode 100644 index 0000000..eb894cd --- /dev/null +++ b/tests/Unit/Cursor/PageTest.php @@ -0,0 +1,232 @@ +sort = Sort::fromExpression(expression: ''); + $this->filter = Group::none(); + } + + public function testNavigationWhenNoExtraElementThenHasNoNextPage(): void + { + /** @Given a keyset pagination with an absent incoming cursor and a page size of two */ + $pagination = Pagination::from(perPage: 2, cursor: Token::none()); + + /** @And a cursor page built from items fetched within the page size */ + $page = Page::from( + sort: $this->sort, + filter: $this->filter, + items: [10, 20], + keysOf: static fn(int $element): array => [$element], + pagination: $pagination + ); + + /** @Then the page reports no next page */ + self::assertFalse($page->hasNext()); + + /** @And there is no next pagination */ + self::assertNull($page->next()); + + /** @And the navigation lists no target */ + self::assertCount(0, $page->navigation()->targets()->toArray()); + + /** @And the metadata reports no next page in length-ascending key order */ + self::assertSame(['has_next' => false, 'per_page' => 2], $page->metadata()); + } + + public function testToResponseWhenCursorPageGivenThenRendersBodyAndLinkHeader(): void + { + /** @Given an opaque token produced from ordering key values */ + $token = Token::fromKeys(keys: [5])->toString(); + + /** @And a cursor page built over items fetched for the page size plus one */ + $page = Page::from( + sort: $this->sort, + filter: $this->filter, + items: [10, 20, 30], + keysOf: static fn(int $element): array => [$element], + pagination: Pagination::from(perPage: 2, cursor: Token::from(token: $token)) + ); + + /** @When rendering the cursor page as a JSON:API response over the orders base URI */ + $response = $page->toResponse(baseUri: '/v1/orders'); + + /** @Then the response body carries the trimmed data, the meta, and the forward-only links */ + self::assertSame([ + 'data' => [10, 20], + 'meta' => [ + 'has_next' => true, + 'per_page' => 2 + ], + 'links' => [ + 'self' => sprintf('/v1/orders?page[cursor]=%s&page[size]=2', $token), + 'next' => sprintf('/v1/orders?page[cursor]=%s&page[size]=2', Token::fromKeys(keys: [20])->toString()) + ] + ], json_decode($response->getBody()->getContents(), true)); + + /** @And the Link header folds the self and next relations */ + self::assertSame(implode(', ', [ + sprintf('; rel="self"', $token), + sprintf('; rel="next"', Token::fromKeys(keys: [20])->toString()) + ]), $response->getHeaderLine('Link')); + } + + public function testToResponseWhenFirstCursorPageThenSelfLinkIsCursorStyle(): void + { + /** @Given a cursor page on the first page with no incoming cursor */ + $page = Page::from( + sort: $this->sort, + filter: $this->filter, + items: [10, 20, 30], + keysOf: static fn(int $element): array => [$element], + pagination: Pagination::from(perPage: 2, cursor: Token::none()) + ); + + /** @When rendering the first cursor page as a JSON:API response over the orders base URI */ + $response = $page->toResponse(baseUri: '/v1/orders'); + + /** @Then the self link is cursor-style, carrying only the page size and never an offset page number */ + self::assertSame([ + 'data' => [10, 20], + 'meta' => [ + 'has_next' => true, + 'per_page' => 2 + ], + 'links' => [ + 'self' => '/v1/orders?page[size]=2', + 'next' => sprintf('/v1/orders?page[cursor]=%s&page[size]=2', Token::fromKeys(keys: [20])->toString()) + ] + ], json_decode($response->getBody()->getContents(), true)); + } + + public function testNavigationWhenExtraElementFetchedThenListsOnlyTheNextTarget(): void + { + /** @Given a keyset page fetched for the page size plus one with an absent incoming cursor */ + $page = Page::from( + sort: $this->sort, + filter: $this->filter, + items: [10, 20, 30], + keysOf: static fn(int $element): array => [$element], + pagination: Pagination::from(perPage: 2, cursor: Token::none()) + ); + + /** @When reading the navigation targets */ + $targets = $page->navigation()->targets(); + + /** @Then it lists a single navigation target */ + self::assertCount(1, $targets->toArray()); + + /** @And the only target is the next target anchored on the forward cursor */ + self::assertEquals( + NavigationTarget::to( + target: Pagination::from(perPage: 2, cursor: Token::fromKeys(keys: [20])), + relation: LinkRelation::NEXT + ), + $targets->first() + ); + } + + public function testMapWhenTransformationGivenThenProjectsItemsAndPreservesTheCursor(): void + { + /** @Given a cursor page built over items fetched for the page size plus one */ + $page = Page::from( + sort: $this->sort, + filter: $this->filter, + items: [10, 20, 30], + keysOf: static fn(int $element): array => [$element], + pagination: Pagination::from(perPage: 2, cursor: Token::none()) + ); + + /** @When mapping the items through a projection */ + $mapped = $page->map(transformation: static fn(int $element): string => sprintf('#%d', $element)); + + /** @Then the items are projected through the transformation */ + self::assertSame(['#10', '#20'], $mapped->items()->toArray()); + + /** @And the next page hint is preserved */ + self::assertTrue($mapped->hasNext()); + + /** @And the next pagination still anchors on the source keys */ + self::assertEquals(Pagination::from(perPage: 2, cursor: Token::fromKeys(keys: [20])), $mapped->next()); + + /** @And the metadata is preserved in length-ascending key order */ + self::assertSame(['has_next' => true, 'per_page' => 2], $mapped->metadata()); + } + + public function testToResponseWhenPageIsMappedThenRendersProjectedDataAndPreservedLinks(): void + { + /** @Given an opaque token produced from ordering key values */ + $token = Token::fromKeys(keys: [5])->toString(); + + /** @And a cursor page built over array rows then projected to their identifiers */ + $page = Page::from( + sort: $this->sort, + filter: $this->filter, + items: [['id' => 10], ['id' => 20], ['id' => 30]], + keysOf: static fn(array $row): array => [$row['id']], + pagination: Pagination::from(perPage: 2, cursor: Token::from(token: $token)) + )->map(transformation: static fn(array $row): int => (int)$row['id']); + + /** @When rendering the mapped cursor page as a JSON:API response over the orders base URI */ + $response = $page->toResponse(baseUri: '/v1/orders'); + + /** @Then the body carries the projected data, the meta, and the forward-only links */ + self::assertSame([ + 'data' => [10, 20], + 'meta' => [ + 'has_next' => true, + 'per_page' => 2 + ], + 'links' => [ + 'self' => sprintf('/v1/orders?page[cursor]=%s&page[size]=2', $token), + 'next' => sprintf('/v1/orders?page[cursor]=%s&page[size]=2', Token::fromKeys(keys: [20])->toString()) + ] + ], json_decode($response->getBody()->getContents(), true)); + } + + public function testNavigationWhenExtraElementFetchedThenHasNextAndNextCursorAnchorsLastItem(): void + { + /** @Given a keyset pagination with an absent incoming cursor and a page size of two */ + $pagination = Pagination::from(perPage: 2, cursor: Token::none()); + + /** @And a cursor page built over items fetched for the page size plus one */ + $page = Page::from( + sort: $this->sort, + filter: $this->filter, + items: [10, 20, 30], + keysOf: static fn(int $element): array => [$element], + pagination: $pagination + ); + + /** @Then the page reports a next page */ + self::assertTrue($page->hasNext()); + + /** @And the items are trimmed to the page size */ + self::assertSame([10, 20], $page->items()->toArray()); + + /** @And the next pagination anchors on the last retained element with the page size */ + self::assertEquals(Pagination::from(perPage: 2, cursor: Token::fromKeys(keys: [20])), $page->next()); + + /** @And the metadata carries the navigation flags in length-ascending key order */ + self::assertSame(['has_next' => true, 'per_page' => 2], $page->metadata()); + } +} diff --git a/tests/Unit/CursorPaginationTest.php b/tests/Unit/Cursor/PaginationTest.php similarity index 79% rename from tests/Unit/CursorPaginationTest.php rename to tests/Unit/Cursor/PaginationTest.php index afac42e..fea673a 100644 --- a/tests/Unit/CursorPaginationTest.php +++ b/tests/Unit/Cursor/PaginationTest.php @@ -2,19 +2,19 @@ declare(strict_types=1); -namespace Test\TinyBlocks\HttpQuery\Unit; +namespace Test\TinyBlocks\HttpQuery\Unit\Cursor; use PHPUnit\Framework\TestCase; -use TinyBlocks\HttpQuery\Cursor; -use TinyBlocks\HttpQuery\CursorPagination; +use TinyBlocks\HttpQuery\Cursor\Pagination; +use TinyBlocks\HttpQuery\Cursor\Token; use TinyBlocks\HttpQuery\Exceptions\PageSizeOutOfRange; -final class CursorPaginationTest extends TestCase +final class PaginationTest extends TestCase { public function testFromWhenPageSizeIsTheMinimumThenCarriesThatLimit(): void { /** @Given a cursor pagination built from an absent cursor and the minimum page size of 1 */ - $pagination = CursorPagination::from(cursor: Cursor::none(), perPage: 1); + $pagination = Pagination::from(perPage: 1, cursor: Token::none()); /** @When reading the page size limit */ $limit = $pagination->limit(); @@ -26,7 +26,7 @@ public function testFromWhenPageSizeIsTheMinimumThenCarriesThatLimit(): void public function testToQueryStringWhenCursorAbsentThenRendersOnlyTheSize(): void { /** @Given a cursor pagination carrying an absent cursor and a page size */ - $pagination = CursorPagination::from(cursor: Cursor::none(), perPage: 10); + $pagination = Pagination::from(perPage: 10, cursor: Token::none()); /** @When rendering it as a query string */ $queryString = $pagination->toQueryString(); @@ -38,7 +38,7 @@ public function testToQueryStringWhenCursorAbsentThenRendersOnlyTheSize(): void public function testFromWhenAbsentCursorGivenThenCarriesLimitAndAbsentCursor(): void { /** @Given a cursor pagination built from an absent cursor and a page size of 20 */ - $pagination = CursorPagination::from(cursor: Cursor::none(), perPage: 20); + $pagination = Pagination::from(perPage: 20, cursor: Token::none()); /** @When reading the page size limit */ $limit = $pagination->limit(); @@ -53,19 +53,19 @@ public function testFromWhenAbsentCursorGivenThenCarriesLimitAndAbsentCursor(): public function testFromWhenPageSizeBelowMinimumThenThrowsPageSizeOutOfRange(): void { /** @Given an absent cursor */ - $cursor = Cursor::none(); + $cursor = Token::none(); /** @Then an exception indicating the page size is out of range is raised */ $this->expectException(PageSizeOutOfRange::class); /** @When building a cursor pagination with a page size below the minimum */ - CursorPagination::from(cursor: $cursor, perPage: 0); + Pagination::from(perPage: 0, cursor: $cursor); } public function testToQueryStringWhenCursorPresentThenRendersCursorAndSize(): void { /** @Given a cursor pagination carrying an incoming cursor and a page size */ - $pagination = CursorPagination::from(cursor: Cursor::from(token: 'abc'), perPage: 10); + $pagination = Pagination::from(perPage: 10, cursor: Token::from(token: 'abc')); /** @When rendering it as a query string */ $queryString = $pagination->toQueryString(); @@ -77,7 +77,7 @@ public function testToQueryStringWhenCursorPresentThenRendersCursorAndSize(): vo public function testFromWhenIncomingCursorGivenThenCarriesLimitAndTheCursorToken(): void { /** @Given a cursor pagination built from an incoming cursor and a page size of 50 */ - $pagination = CursorPagination::from(cursor: Cursor::from(token: 'abc'), perPage: 50); + $pagination = Pagination::from(perPage: 50, cursor: Token::from(token: 'abc')); /** @When reading the page size limit */ $limit = $pagination->limit(); diff --git a/tests/Unit/Cursor/TokenTest.php b/tests/Unit/Cursor/TokenTest.php new file mode 100644 index 0000000..875e322 --- /dev/null +++ b/tests/Unit/Cursor/TokenTest.php @@ -0,0 +1,206 @@ +isAbsent(); + + /** @Then it reports itself as present */ + self::assertFalse($isAbsent); + } + + public function testFromWhenEmptyTokenGivenThenIsAbsent(): void + { + /** @Given a token backed by an empty incoming string */ + $token = Token::from(token: ''); + + /** @When inspecting whether the token is absent */ + $isAbsent = $token->isAbsent(); + + /** @Then it reports itself as absent */ + self::assertTrue($isAbsent); + } + + public function testFromWhenNonEmptyTokenGivenThenIsPresent(): void + { + /** @Given a token backed by a non-empty incoming string */ + $token = Token::from(token: 'abc'); + + /** @When inspecting whether the token is absent */ + $isAbsent = $token->isAbsent(); + + /** @Then it reports itself as present */ + self::assertFalse($isAbsent); + } + + public function testNoneThenAbsentWithEmptyKeysAndEmptyToken(): void + { + /** @Given an absent token */ + $token = Token::none(); + + /** @When inspecting the absent token */ + $isAbsent = $token->isAbsent(); + + /** @Then it reports itself as absent */ + self::assertTrue($isAbsent); + + /** @And it decodes to no key values */ + self::assertSame([], $token->toArray()); + + /** @And it renders an empty string */ + self::assertSame('', $token->toString()); + } + + public function testFromKeysWhenKeysGivenThenDecodesToTheSameKeys(): void + { + /** @Given a token backed by ordering key values */ + $token = Token::fromKeys(keys: ['2024-01-01', 42]); + + /** @When decoding the token into key values */ + $keys = $token->toArray(); + + /** @Then it yields the original key values */ + self::assertSame(['2024-01-01', 42], $keys); + } + + public function testFromKeysWhenKeysAreGappedThenDecodesToAReindexedList(): void + { + /** @Given a token backed by ordering key values held under gapped integer keys */ + $token = Token::fromKeys(keys: [5 => 'x', 9 => 'y']); + + /** @When decoding the token into key values */ + $keys = $token->toArray(); + + /** @Then it yields the values as a zero-based list */ + self::assertSame(['x', 'y'], $keys); + } + + public function testKeyedByWhenTokenAbsentThenEveryFieldIsNull(): void + { + /** @Given an absent token */ + $token = Token::none(); + + /** @When keying the decoded values by the sort field names */ + $keyed = $token->keyedBy(fields: ['created_at', 'id']); + + /** @Then every field is present with a null value */ + self::assertSame(['created_at' => null, 'id' => null], $keyed); + } + + public function testKeyedByWhenKeysPresentThenValuesAreKeyedByField(): void + { + /** @Given a token backed by ordering key values */ + $token = Token::fromKeys(keys: ['2024-01-01', 42]); + + /** @When keying the decoded values by the sort field names */ + $keyed = $token->keyedBy(fields: ['created_at', 'id']); + + /** @Then the values are keyed by the field names in order */ + self::assertSame(['created_at' => '2024-01-01', 'id' => 42], $keyed); + } + + public function testKeyedByWhenCountMismatchesThenThrowsCursorIsInvalid(): void + { + /** @Given a token backed by a single key value */ + $token = Token::fromKeys(keys: [5]); + + /** @Then an exception indicating the cursor token is invalid is raised */ + $this->expectException(CursorIsInvalid::class); + + /** @When keying the decoded values by two field names */ + $token->keyedBy(fields: ['created_at', 'id']); + } + + public function testToArrayWhenTokenCarriesInvalidCharacterThenThrowsCursorIsInvalid(): void + { + /** @Given a token carrying a character outside the base64url alphabet */ + $token = Token::from(token: 'WzEsMl0!'); + + /** @Then an exception indicating the cursor token is invalid is raised */ + $this->expectException(CursorIsInvalid::class); + $this->expectExceptionMessage('could not be decoded'); + + /** @When decoding the token into key values */ + $token->toArray(); + } + + public function testToArrayWhenTokenDecodesToScalarThenThrowsCursorIsInvalid(): void + { + /** @Given a base64url token whose decoded payload is the JSON scalar 5 */ + $token = Token::from(token: rtrim(strtr(base64_encode('5'), '+/', '-_'), '=')); + + /** @Then an exception indicating the cursor token is invalid is raised */ + $this->expectException(CursorIsInvalid::class); + $this->expectExceptionMessage('could not be decoded'); + + /** @When decoding the token into key values */ + $token->toArray(); + } + + public function testFromKeysWhenRoundTrippedThroughTokenThenYieldsTheOriginalKeys(): void + { + /** @Given the opaque token produced from ordering key values */ + $token = Token::fromKeys(keys: ['2024-01-01', 42])->toString(); + + /** @And the token is not empty */ + self::assertNotSame('', $token); + + /** @When rebuilding a token from that string and decoding it */ + $keys = Token::from(token: $token)->toArray(); + + /** @Then it yields the original key values */ + self::assertSame(['2024-01-01', 42], $keys); + } + + public function testFromKeysWhenEncodedThenTokenIsUrlSafeAndUnpadded(): void + { + /** @Given a token backed by key values whose base64 payload carries plus, slash, and padding */ + $token = Token::fromKeys(keys: ['>>>???']); + + /** @When rendering the opaque token */ + $rendered = $token->toString(); + + /** @Then it renders the base64url form, translating plus and slash and dropping the padding */ + self::assertSame('WyI-Pj4_Pz8iXQ', $rendered); + } + + public function testFromKeysWhenRoundTrippedThroughUrlSafeTokenThenYieldsTheOriginalKeys(): void + { + /** @Given the opaque token produced from key values whose base64 payload carries plus and slash */ + $token = Token::fromKeys(keys: ['>>>???'])->toString(); + + /** @When rebuilding a token from that URL-safe string and decoding it */ + $keys = Token::from(token: $token)->toArray(); + + /** @Then it yields the original key values */ + self::assertSame(['>>>???'], $keys); + } + + public function testConstructorWhenInvokedThroughReflectionThenInstantiatesTheStaticOnlyCodec(): void + { + /** @Given an uninitialized instance of the static-only cursor codec */ + $codec = new ReflectionClass(CursorCodec::class)->newInstanceWithoutConstructor(); + + /** @When invoking its otherwise-uncallable private constructor */ + new ReflectionMethod(CursorCodec::class, '__construct')->invoke($codec); + + /** @Then the static-only cursor codec is instantiated */ + self::assertInstanceOf(CursorCodec::class, $codec); + } +} diff --git a/tests/Unit/CursorPageTest.php b/tests/Unit/CursorPageTest.php deleted file mode 100644 index 8d1cafa..0000000 --- a/tests/Unit/CursorPageTest.php +++ /dev/null @@ -1,204 +0,0 @@ -criteria = Criteria::fromQuery(request: Query::from(parameters: [])); - } - - public function testToResponseWhenCursorPageGivenThenRendersBodyAndLinkHeader(): void - { - /** @Given an opaque token produced from ordering key values */ - $token = Cursor::fromKeys(keys: [5])->toString(); - - /** @And query parameters carrying that cursor and a page size of two */ - $query = Query::from(parameters: ['page' => ['cursor' => $token, 'size' => '2']]); - - /** @And the criteria parsed from those parameters */ - $criteria = Criteria::fromQuery(request: $query); - - /** @And a cursor page built from the criteria over items fetched for the page size plus one */ - $page = $criteria->cursorPage(items: [10, 20, 30], keysOf: static fn(mixed $element): array => [$element]); - - /** @When rendering the cursor page as a JSON:API response over the orders base URI */ - $response = $page->toResponse(baseUri: '/v1/orders'); - - /** @Then the response body carries the trimmed data, the meta, and the keyset links */ - self::assertSame([ - 'data' => [10, 20], - 'meta' => [ - 'has_next' => true, - 'per_page' => 2, - 'has_previous' => true - ], - 'links' => [ - 'self' => sprintf('/v1/orders?page[cursor]=%s&page[size]=2', $token), - 'prev' => sprintf('/v1/orders?page[cursor]=%s&page[size]=2', Cursor::fromKeys(keys: [10])->toString()), - 'next' => sprintf('/v1/orders?page[cursor]=%s&page[size]=2', Cursor::fromKeys(keys: [20])->toString()) - ] - ], json_decode($response->getBody()->getContents(), true)); - - /** @And the Link header folds the self, previous, and next relations */ - self::assertSame(implode(', ', [ - sprintf('; rel="self"', $token), - sprintf('; rel="prev"', Cursor::fromKeys(keys: [10])->toString()), - sprintf('; rel="next"', Cursor::fromKeys(keys: [20])->toString()) - ]), $response->getHeaderLine('Link')); - } - - public function testNavigationWhenExtraElementFetchedThenListsOnlyTheNextTarget(): void - { - /** @Given a keyset page fetched for the page size plus one with an absent incoming cursor */ - $page = CursorPage::from( - items: Collection::createFrom(elements: [10, 20, 30]), - keysOf: static fn(mixed $element): array => [$element], - criteria: $this->criteria, - pagination: CursorPagination::from(cursor: Cursor::none(), perPage: 2) - ); - - /** @When reading the navigation targets */ - $targets = $page->navigation()->targets(); - - /** @Then it lists a single navigation target */ - self::assertCount(1, $targets->toArray()); - - /** @And the only target is the next target anchored on the forward cursor */ - self::assertEquals( - NavigationTarget::to( - target: CursorPagination::from(cursor: Cursor::fromKeys(keys: [20]), perPage: 2), - relation: LinkRelation::NEXT - ), - $targets->first() - ); - } - - public function testNavigationWhenExtraElementFetchedThenHasNextAndForwardCursorAnchorsLastItem(): void - { - /** @Given a keyset pagination with an absent incoming cursor and a page size of two */ - $pagination = CursorPagination::from(cursor: Cursor::none(), perPage: 2); - - /** @And items fetched for the page size plus one */ - $items = Collection::createFrom(elements: [10, 20, 30]); - - /** @When building the cursor page from the items, the key extractor, and the pagination */ - $page = CursorPage::from( - items: $items, - keysOf: static fn(mixed $element): array => [$element], - criteria: $this->criteria, - pagination: $pagination - ); - - /** @Then the page reports a next page */ - self::assertTrue($page->hasNext()); - - /** @And the items are trimmed to the page size */ - self::assertSame([10, 20], $page->items()->toArray()); - - /** @And the page has no previous page */ - self::assertFalse($page->hasPrevious()); - - /** @And the next pagination anchors on the last retained element with the page size */ - self::assertEquals( - CursorPagination::from(cursor: Cursor::fromKeys(keys: [20]), perPage: 2), - $page->next() - ); - - /** @And there is no previous pagination */ - self::assertNull($page->previous()); - - /** @And the metadata carries every navigation flag in length-ascending key order */ - self::assertSame([ - 'has_next' => true, - 'per_page' => 2, - 'has_previous' => false - ], $page->metadata()); - } - - public function testNavigationWhenIncomingCursorAndNoExtraElementThenListsOnlyThePreviousTarget(): void - { - /** @Given the opaque token produced from ordering key values */ - $token = Cursor::fromKeys(keys: [5])->toString(); - - /** @And a keyset page fetched within the page size reached through that incoming cursor */ - $page = CursorPage::from( - items: Collection::createFrom(elements: [10, 20]), - keysOf: static fn(mixed $element): array => [$element], - criteria: $this->criteria, - pagination: CursorPagination::from(cursor: Cursor::from(token: $token), perPage: 2) - ); - - /** @When reading the navigation targets */ - $targets = $page->navigation()->targets(); - - /** @Then it lists a single navigation target */ - self::assertCount(1, $targets->toArray()); - - /** @And the only target is the previous target anchored on the backward cursor */ - self::assertEquals( - NavigationTarget::to( - target: CursorPagination::from(cursor: Cursor::fromKeys(keys: [10]), perPage: 2), - relation: LinkRelation::PREVIOUS - ), - $targets->first() - ); - } - - public function testNavigationWhenNoExtraElementAndIncomingCursorThenNoNextAndBackwardCursorAnchorsFirstItem(): void - { - /** @Given the opaque token produced from ordering key values */ - $existingToken = Cursor::fromKeys(keys: [5])->toString(); - - /** @And a keyset pagination with a present incoming cursor and a page size of two */ - $pagination = CursorPagination::from(cursor: Cursor::from(token: $existingToken), perPage: 2); - - /** @And items fetched within the page size */ - $items = Collection::createFrom(elements: [10, 20]); - - /** @When building the cursor page from the items, the key extractor, and the pagination */ - $page = CursorPage::from( - items: $items, - keysOf: static fn(mixed $element): array => [$element], - criteria: $this->criteria, - pagination: $pagination - ); - - /** @Then the page reports no next page */ - self::assertFalse($page->hasNext()); - - /** @And the page has a previous page */ - self::assertTrue($page->hasPrevious()); - - /** @And there is no next pagination */ - self::assertNull($page->next()); - - /** @And the previous pagination anchors on the first retained element with the page size */ - self::assertEquals( - CursorPagination::from(cursor: Cursor::fromKeys(keys: [10]), perPage: 2), - $page->previous() - ); - - /** @And the metadata carries every navigation flag in length-ascending key order */ - self::assertSame([ - 'has_next' => false, - 'per_page' => 2, - 'has_previous' => true - ], $page->metadata()); - } -} diff --git a/tests/Unit/CursorTest.php b/tests/Unit/CursorTest.php deleted file mode 100644 index 7f8d945..0000000 --- a/tests/Unit/CursorTest.php +++ /dev/null @@ -1,147 +0,0 @@ -isAbsent(); - - /** @Then it reports itself as present */ - self::assertFalse($isAbsent); - } - - public function testFromWhenEmptyTokenGivenThenIsAbsent(): void - { - /** @Given a cursor backed by an empty incoming token */ - $cursor = Cursor::from(token: ''); - - /** @When inspecting whether the cursor is absent */ - $isAbsent = $cursor->isAbsent(); - - /** @Then it reports itself as absent */ - self::assertTrue($isAbsent); - } - - public function testFromWhenNonEmptyTokenGivenThenIsPresent(): void - { - /** @Given a cursor backed by a non-empty incoming token */ - $cursor = Cursor::from(token: 'abc'); - - /** @When inspecting whether the cursor is absent */ - $isAbsent = $cursor->isAbsent(); - - /** @Then it reports itself as present */ - self::assertFalse($isAbsent); - } - - public function testNoneThenAbsentWithEmptyKeysAndEmptyToken(): void - { - /** @Given an absent cursor */ - $cursor = Cursor::none(); - - /** @When inspecting the absent cursor */ - $isAbsent = $cursor->isAbsent(); - - /** @Then it reports itself as absent */ - self::assertTrue($isAbsent); - - /** @And it decodes to no key values */ - self::assertSame([], $cursor->toArray()); - - /** @And it renders an empty token */ - self::assertSame('', $cursor->toString()); - } - - public function testFromKeysWhenKeysGivenThenDecodesToTheSameKeys(): void - { - /** @Given a cursor backed by ordering key values */ - $cursor = Cursor::fromKeys(keys: ['2024-01-01', 42]); - - /** @When decoding the cursor into key values */ - $keys = $cursor->toArray(); - - /** @Then it yields the original key values */ - self::assertSame(['2024-01-01', 42], $keys); - } - - public function testFromKeysWhenKeysAreGappedThenDecodesToAReindexedList(): void - { - /** @Given a cursor backed by ordering key values held under gapped integer keys */ - $cursor = Cursor::fromKeys(keys: [5 => 'x', 9 => 'y']); - - /** @When decoding the cursor into key values */ - $keys = $cursor->toArray(); - - /** @Then it yields the values as a zero-based list */ - self::assertSame(['x', 'y'], $keys); - } - - public function testToArrayWhenTokenIsNotBase62ThenThrowsCursorIsInvalid(): void - { - /** @Given a cursor backed by a token carrying characters outside the base62 alphabet */ - $cursor = Cursor::from(token: 'not valid base62 !!!'); - - /** @Then an exception indicating the cursor token is invalid is raised */ - $this->expectException(CursorIsInvalid::class); - $this->expectExceptionMessage('could not be decoded'); - - /** @When decoding the cursor into key values */ - $cursor->toArray(); - } - - public function testToArrayWhenTokenDecodesToScalarThenThrowsCursorIsInvalid(): void - { - /** @Given a base62 token whose decoded payload is the JSON scalar 5 */ - $cursor = Cursor::from(token: Base62::from(value: '5')->encode()); - - /** @Then an exception indicating the cursor token is invalid is raised */ - $this->expectException(CursorIsInvalid::class); - $this->expectExceptionMessage('could not be decoded'); - - /** @When decoding the cursor into key values */ - $cursor->toArray(); - } - - public function testFromKeysWhenRoundTrippedThroughTokenThenYieldsTheOriginalKeys(): void - { - /** @Given the opaque token produced from ordering key values */ - $token = Cursor::fromKeys(keys: ['2024-01-01', 42])->toString(); - - /** @And the token is not empty */ - self::assertNotSame('', $token); - - /** @When rebuilding a cursor from that token and decoding it */ - $keys = Cursor::from(token: $token)->toArray(); - - /** @Then it yields the original key values */ - self::assertSame(['2024-01-01', 42], $keys); - } - - public function testConstructorWhenInvokedThroughReflectionThenInstantiatesTheStaticOnlyCodec(): void - { - /** @Given an uninitialized instance of the static-only cursor codec */ - $codec = new ReflectionClass(CursorCodec::class)->newInstanceWithoutConstructor(); - - /** @When invoking its otherwise-uncallable private constructor */ - new ReflectionMethod(CursorCodec::class, '__construct')->invoke($codec); - - /** @Then the static-only cursor codec is instantiated */ - self::assertInstanceOf(CursorCodec::class, $codec); - } -} diff --git a/tests/Unit/EndToEndTest.php b/tests/Unit/EndToEndTest.php index b648b34..d709242 100644 --- a/tests/Unit/EndToEndTest.php +++ b/tests/Unit/EndToEndTest.php @@ -6,19 +6,23 @@ use PHPUnit\Framework\TestCase; use Test\TinyBlocks\HttpQuery\Models\Query; -use TinyBlocks\Collection\Collection; -use TinyBlocks\Collection\KeyPreservation; -use TinyBlocks\HttpQuery\Criteria; -use TinyBlocks\HttpQuery\Cursor; -use TinyBlocks\HttpQuery\Links; -use TinyBlocks\HttpQuery\OffsetPage; -use TinyBlocks\HttpQuery\OffsetPagination; +use TinyBlocks\HttpQuery\Cursor\Criteria as CursorCriteria; +use TinyBlocks\HttpQuery\Cursor\Token; +use TinyBlocks\HttpQuery\Offset\Criteria as OffsetCriteria; +use TinyBlocks\HttpQuery\Operator; +use TinyBlocks\HttpQuery\Schema; final class EndToEndTest extends TestCase { - public function testPipelineWhenRequestGivenThenOffsetPageRendersResponse(): void + public function testPipelineWhenOffsetRequestGivenThenPageRendersTheResponse(): void { - /** @Given the canonical request query parameters */ + /** @Given the query contract of the orders endpoint */ + $schema = Schema::create() + ->sortable(fields: ['created_at', 'id']) + ->filterable(field: 'total', operators: [Operator::GREATER_THAN_OR_EQUAL]) + ->filterable(field: 'status', operators: [Operator::EQUAL]); + + /** @And the canonical request query parameters */ $query = Query::from(parameters: [ 'filter' => 'status==paid;total=ge=100', 'sort' => '-created_at,id', @@ -26,13 +30,13 @@ public function testPipelineWhenRequestGivenThenOffsetPageRendersResponse(): voi ]); /** @And the criteria parsed from those parameters */ - $criteria = Criteria::fromQuery(request: $query); + $criteria = OffsetCriteria::fromQuery(request: $query, schema: $schema); /** @And the base URI the navigation links render against */ $base = '/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id'; /** @And the third page of a 480-element result built from the criteria */ - $page = $criteria->offsetPage(items: ['a', 'b'], total: 480); + $page = $criteria->page(total: 480, items: ['a', 'b']); /** @When rendering the page as a JSON:API response over the orders base URI */ $response = $page->toResponse(baseUri: '/v1/orders'); @@ -58,45 +62,15 @@ public function testPipelineWhenRequestGivenThenOffsetPageRendersResponse(): voi ], json_decode($response->getBody()->getContents(), true)); } - public function testPipelineWhenCursorRequestGivenThenCursorPageRendersResponse(): void + public function testPipelineWhenOffsetRequestGivenThenLinkHeaderFoldsEveryRelation(): void { - /** @Given an opaque token produced from ordering key values */ - $token = Cursor::fromKeys(keys: [5])->toString(); - - /** @And query parameters carrying a sort, that cursor, and a page size of two */ - $query = Query::from(parameters: ['sort' => 'id', 'page' => ['cursor' => $token, 'size' => '2']]); - - /** @And the criteria parsed from those parameters */ - $criteria = Criteria::fromQuery(request: $query); - - /** @And a cursor page built from the criteria over items fetched for the page size plus one */ - $page = $criteria->cursorPage(items: [10, 20, 30], keysOf: static fn(mixed $element): array => [$element]); - - /** @And the base URI the keyset links render against */ - $base = '/v1/orders?sort=id'; - - /** @When rendering the cursor page as a JSON:API response over the orders base URI */ - $response = $page->toResponse(baseUri: '/v1/orders'); - - /** @Then the body carries the data, the meta, and the keyset links preserving the sort */ - self::assertSame([ - 'data' => [10, 20], - 'meta' => [ - 'has_next' => true, - 'per_page' => 2, - 'has_previous' => true - ], - 'links' => [ - 'self' => sprintf('%s&page[cursor]=%s&page[size]=2', $base, $token), - 'prev' => sprintf('%s&page[cursor]=%s&page[size]=2', $base, Cursor::fromKeys(keys: [10])->toString()), - 'next' => sprintf('%s&page[cursor]=%s&page[size]=2', $base, Cursor::fromKeys(keys: [20])->toString()) - ] - ], json_decode($response->getBody()->getContents(), true)); - } + /** @Given the query contract of the orders endpoint */ + $schema = Schema::create() + ->sortable(fields: ['created_at', 'id']) + ->filterable(field: 'total', operators: [Operator::GREATER_THAN_OR_EQUAL]) + ->filterable(field: 'status', operators: [Operator::EQUAL]); - public function testPipelineWhenCanonicalRequestGivenThenLinkHeaderFoldsEveryRelation(): void - { - /** @Given the canonical request query parameters */ + /** @And the canonical request query parameters */ $query = Query::from(parameters: [ 'filter' => 'status==paid;total=ge=100', 'sort' => '-created_at,id', @@ -104,21 +78,7 @@ public function testPipelineWhenCanonicalRequestGivenThenLinkHeaderFoldsEveryRel ]); /** @And the criteria parsed from those parameters */ - $criteria = Criteria::fromQuery(request: $query); - - /** @And the offset pagination pointing at the third page */ - $pagination = OffsetPagination::fromPage(page: 3, perPage: 20); - - /** @And the third page of a 480-element result */ - $page = OffsetPage::from( - items: Collection::createFromEmpty(), - total: 480, - criteria: $criteria, - pagination: $pagination - ); - - /** @And the navigation for that page over the orders base URI */ - $links = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $page->navigation()); + $criteria = OffsetCriteria::fromQuery(request: $query, schema: $schema); /** @And the base URI the relations render against */ $base = '/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id'; @@ -126,8 +86,8 @@ public function testPipelineWhenCanonicalRequestGivenThenLinkHeaderFoldsEveryRel /** @And the Link header template rendered per relation */ $template = '<%s&page[number]=%d&page[size]=20>; rel="%s"'; - /** @When rendering the RFC 8288 Link header line */ - $header = $links->toHeader()->toArray()['Link'][0]; + /** @When rendering the page as a JSON:API response and reading its RFC 8288 Link header line */ + $header = $criteria->page(total: 480, items: [])->toResponse(baseUri: '/v1/orders')->getHeaderLine('Link'); /** @Then the line folds the five relations in navigation order */ self::assertSame(implode(', ', [ @@ -139,60 +99,39 @@ public function testPipelineWhenCanonicalRequestGivenThenLinkHeaderFoldsEveryRel ]), $header); } - public function testPipelineWhenCanonicalRequestGivenThenJsonBodyCarriesDataMetaAndLinks(): void + public function testPipelineWhenCursorRequestGivenThenCursorPageRendersTheResponse(): void { - /** @Given the canonical request query parameters */ - $query = Query::from(parameters: [ - 'filter' => 'status==paid;total=ge=100', - 'sort' => '-created_at,id', - 'page' => ['number' => '3', 'size' => '20'] - ]); - - /** @And the criteria parsed from those parameters */ - $criteria = Criteria::fromQuery(request: $query); + /** @Given the query contract of the orders endpoint */ + $schema = Schema::create()->sortable(fields: ['id']); - /** @And the offset pagination pointing at the third page */ - $pagination = OffsetPagination::fromPage(page: 3, perPage: 20); + /** @And an opaque token produced from ordering key values */ + $token = Token::fromKeys(keys: [5])->toString(); - /** @And the third page of a 480-element result */ - $page = OffsetPage::from( - items: Collection::createFromEmpty(), - total: 480, - criteria: $criteria, - pagination: $pagination - ); + /** @And query parameters carrying a sort, that cursor, and a page size of two */ + $query = Query::from(parameters: ['sort' => 'id', 'page' => ['cursor' => $token, 'size' => '2']]); - /** @And the navigation for that page over the orders base URI */ - $links = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $page->navigation()); + /** @And a cursor page built through the keyset view over the array rows fetched */ + $page = CursorCriteria::fromQuery(request: $query, schema: $schema) + ->keyset() + ->page(items: [['id' => 10], ['id' => 20], ['id' => 30]]); - /** @And the base URI the navigation links render against */ - $base = '/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id'; + /** @And the base URI the keyset links render against */ + $base = '/v1/orders?sort=id'; - /** @When assembling the JSON:API body from the data, the meta, and the links */ - $body = [ - 'data' => $page->items()->toArray(keyPreservation: KeyPreservation::DISCARD), - 'meta' => $page->metadata(), - 'links' => $links->toArray() - ]; + /** @When rendering the cursor page as a JSON:API response over the orders base URI */ + $response = $page->toResponse(baseUri: '/v1/orders'); - /** @Then the body carries the empty data, the meta, and the five navigation links in order */ + /** @Then the body carries the data, the meta, and the forward-only keyset links preserving the sort */ self::assertSame([ - 'data' => [], + 'data' => [['id' => 10], ['id' => 20]], 'meta' => [ - 'total' => 480, - 'has_next' => true, - 'per_page' => 20, - 'total_pages' => 24, - 'current_page' => 3, - 'has_previous' => true + 'has_next' => true, + 'per_page' => 2 ], 'links' => [ - 'self' => sprintf('%s&page[number]=3&page[size]=20', $base), - 'first' => sprintf('%s&page[number]=1&page[size]=20', $base), - 'prev' => sprintf('%s&page[number]=2&page[size]=20', $base), - 'next' => sprintf('%s&page[number]=4&page[size]=20', $base), - 'last' => sprintf('%s&page[number]=24&page[size]=20', $base) + 'self' => sprintf('%s&page[cursor]=%s&page[size]=2', $base, $token), + 'next' => sprintf('%s&page[cursor]=%s&page[size]=2', $base, Token::fromKeys(keys: [20])->toString()) ] - ], $body); + ], json_decode($response->getBody()->getContents(), true)); } } diff --git a/tests/Unit/ExpressionTest.php b/tests/Unit/ExpressionTest.php deleted file mode 100644 index 26d4b8c..0000000 --- a/tests/Unit/ExpressionTest.php +++ /dev/null @@ -1,78 +0,0 @@ -value(); - - /** @Then it returns the rendered leaf */ - self::assertSame('status==paid', $actual); - } - - public function testValueWhenGroupedGivenThenReturnsJoinedChildren(): void - { - /** @Given a grouped expression rendered from children joined by a connective */ - $expression = Expression::grouped(value: 'a==1;b==2', connective: LogicalOperator::AND); - - /** @When reading the RSQL expression */ - $actual = $expression->value(); - - /** @Then it returns the joined children */ - self::assertSame('a==1;b==2', $actual); - } - - #[DataProvider('nestingCases')] - public function testNestedWithinWhenNestedThenParenthesizesByPrecedence( - Expression $expression, - LogicalOperator $parent, - string $expected - ): void { - /** @Given a rendered expression and the connective it is nested within */ - - /** @When rendering it nested within the parent connective */ - $actual = $expression->nestedWithin(parent: $parent); - - /** @Then it is parenthesized only when it binds looser than the parent */ - self::assertSame($expected, $actual); - } - - public static function nestingCases(): array - { - return [ - 'OR grouped within AND' => [ - 'expression' => Expression::grouped(value: 'a==1,b==2', connective: LogicalOperator::OR), - 'parent' => LogicalOperator::AND, - 'expected' => '(a==1,b==2)' - ], - 'AND grouped within OR' => [ - 'expression' => Expression::grouped(value: 'a==1;b==2', connective: LogicalOperator::AND), - 'parent' => LogicalOperator::OR, - 'expected' => 'a==1;b==2' - ], - 'OR grouped within OR' => [ - 'expression' => Expression::grouped(value: 'a==1,b==2', connective: LogicalOperator::OR), - 'parent' => LogicalOperator::OR, - 'expected' => 'a==1,b==2' - ], - 'atomic within AND' => [ - 'expression' => Expression::atomic(value: 'a==1'), - 'parent' => LogicalOperator::AND, - 'expected' => 'a==1' - ] - ]; - } -} diff --git a/tests/Unit/FilterTest.php b/tests/Unit/FilterTest.php index 47733a2..b425a72 100644 --- a/tests/Unit/FilterTest.php +++ b/tests/Unit/FilterTest.php @@ -8,306 +8,303 @@ use PHPUnit\Framework\TestCase; use Test\TinyBlocks\HttpQuery\Models\Query; use TinyBlocks\HttpQuery\Comparison; -use TinyBlocks\HttpQuery\Criteria; use TinyBlocks\HttpQuery\Exceptions\FilterExpressionIsInvalid; -use TinyBlocks\HttpQuery\Group; -use TinyBlocks\HttpQuery\LogicalOperator; +use TinyBlocks\HttpQuery\Exceptions\FilterFieldNotAllowed; +use TinyBlocks\HttpQuery\Exceptions\FilterOperatorNotAllowed; +use TinyBlocks\HttpQuery\Exceptions\FilterShapeNotSupported; +use TinyBlocks\HttpQuery\Exceptions\FilterValueNotAllowed; +use TinyBlocks\HttpQuery\Offset\Criteria; use TinyBlocks\HttpQuery\Operator; +use TinyBlocks\HttpQuery\Schema; +use TinyBlocks\HttpQuery\ValueKind; final class FilterTest extends TestCase { - public function testIsEmptyWhenGroupHasNoChildThenIsEmpty(): void - { - /** @Given an empty group */ - $group = Group::none(); - - /** @When checking whether it is empty */ - $isEmpty = $group->isEmpty(); - - /** @Then it reports itself as empty */ - self::assertTrue($isEmpty); - } - - public function testIsEmptyWhenGroupHasChildThenIsNotEmpty(): void - { - /** @Given a group joining a single comparison */ - $group = Group::of(filters: [ - Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL) - ], operator: LogicalOperator::AND); - - /** @When checking whether it is empty */ - $isEmpty = $group->isEmpty(); + private Schema $schema; - /** @Then it reports itself as not empty */ - self::assertFalse($isEmpty); - } - - public function testIsEmptyWhenComparisonGivenThenIsNotEmpty(): void + protected function setUp(): void { - /** @Given an equality comparison */ - $comparison = Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL); - - /** @When checking whether it is empty */ - $isEmpty = $comparison->isEmpty(); - - /** @Then it reports itself as not empty */ - self::assertFalse($isEmpty); + $this->schema = Schema::create() + ->filterable(field: 'a', operators: Operator::cases()) + ->filterable(field: 'b', operators: Operator::cases()) + ->filterable(field: 'c', operators: Operator::cases()) + ->filterable(field: 'role', operators: Operator::cases()) + ->filterable(field: 'name', operators: Operator::cases()) + ->filterable(field: 'status', operators: Operator::cases()); } - public function testFilteringWhenNoFilterGivenThenReturnsEmptyGroup(): void + public function testFromQueryWhenNoFilterThenComparisonsAreEmpty(): void { /** @Given a query carrying no filter parameter at all */ $query = Query::from(parameters: []); - /** @When reading the filtering specification */ - $filter = Criteria::fromQuery(request: $query)->filtering(); + /** @When reading the validated comparisons */ + $comparisons = Criteria::fromQuery(request: $query, schema: $this->schema)->comparisons(); - /** @Then the filter is an empty group joined by the AND connective */ - self::assertEquals(Group::of(filters: [], operator: LogicalOperator::AND), $filter); + /** @Then there is no comparison */ + self::assertSame([], $comparisons); } - public function testFilteringWhenOrGivenThenGroupJoinsTwoComparisons(): void + public function testFromQueryWhenSingleComparisonThenComparisonCarriesFieldAndValue(): void { - /** @Given a query carrying an OR expression of two comparisons */ - $query = Query::from(parameters: ['filter' => 'a==1,b==2']); + /** @Given a query carrying a single equality comparison */ + $query = Query::from(parameters: ['filter' => 'status==paid']); - /** @When reading the filtering specification */ - $filter = Criteria::fromQuery(request: $query)->filtering(); + /** @When reading the validated comparisons */ + $comparisons = Criteria::fromQuery(request: $query, schema: $this->schema)->comparisons(); - /** @Then the filter is an OR group joining the two comparison children in order */ - self::assertEquals(Group::of(filters: [ - Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), - Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) - ], operator: LogicalOperator::OR), $filter); + /** @Then the only comparison is an equality on the named field with its value */ + self::assertEquals( + [Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL)], + $comparisons + ); } - public function testFilteringWhenAndGivenThenGroupJoinsTwoComparisons(): void + public function testFromQueryWhenAndGroupThenComparisonsCarryEveryLeaf(): void { /** @Given a query carrying an AND expression of two comparisons */ $query = Query::from(parameters: ['filter' => 'a==1;b==2']); - /** @When reading the filtering specification */ - $filter = Criteria::fromQuery(request: $query)->filtering(); + /** @When reading the validated comparisons */ + $comparisons = Criteria::fromQuery(request: $query, schema: $this->schema)->comparisons(); - /** @Then the filter is an AND group joining the two comparison children in order */ - self::assertEquals(Group::of(filters: [ + /** @Then the comparisons carry both leaves in order */ + self::assertEquals([ Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) - ], operator: LogicalOperator::AND), $filter); + ], $comparisons); } - public function testFilteringWhenInListGivenThenComparisonCarriesEveryValue(): void + public function testFromQueryWhenInListThenComparisonCarriesEveryValue(): void { /** @Given a query carrying an IN list comparison */ $query = Query::from(parameters: ['filter' => 'role=in=(admin,user)']); - /** @When reading the filtering specification */ - $filter = Criteria::fromQuery(request: $query)->filtering(); + /** @When reading the validated comparisons */ + $comparisons = Criteria::fromQuery(request: $query, schema: $this->schema)->comparisons(); - /** @Then the filter is an IN comparison carrying every listed value in order */ - self::assertEquals(Comparison::of(field: 'role', values: ['admin', 'user'], operator: Operator::IN), $filter); - } - - public function testToExpressionWhenAndGroupNestedInOrThenLeavesItUnwrapped(): void - { - /** @Given an OR group whose first child is an AND group */ - $group = Group::of(filters: [ - Group::of(filters: [ - Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), - Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) - ], operator: LogicalOperator::AND), - Comparison::of(field: 'c', values: ['3'], operator: Operator::EQUAL) - ], operator: LogicalOperator::OR); - - /** @When rendering it as an RSQL expression */ - $expression = $group->toExpression()->value(); - - /** @Then the tighter-binding AND group is left unwrapped */ - self::assertSame('a==1;b==2,c==3', $expression); + /** @Then the only comparison is an IN comparison carrying every listed value in order */ + self::assertEquals( + [Comparison::of(field: 'role', values: ['admin', 'user'], operator: Operator::IN)], + $comparisons + ); } - public function testToExpressionWhenInListGivenThenWrapsValuesInParentheses(): void + public function testFromQueryWhenNotInListThenComparisonCarriesEveryValue(): void { - /** @Given an IN comparison carrying several values */ - $comparison = Comparison::of(field: 'role', values: ['admin', 'user'], operator: Operator::IN); + /** @Given a query carrying a NOT_IN list comparison */ + $query = Query::from(parameters: ['filter' => 'role=out=(a,b)']); - /** @When rendering it as an RSQL expression */ - $expression = $comparison->toExpression()->value(); + /** @When reading the validated comparisons */ + $comparisons = Criteria::fromQuery(request: $query, schema: $this->schema)->comparisons(); - /** @Then it wraps the comma-joined values in parentheses */ - self::assertSame('role=in=(admin,user)', $expression); + /** @Then the only comparison is a NOT_IN comparison carrying every listed value in order */ + self::assertEquals( + [Comparison::of(field: 'role', values: ['a', 'b'], operator: Operator::NOT_IN)], + $comparisons + ); } - public function testToExpressionWhenValueCarriesReservedCharacterThenQuotesIt(): void + public function testFromQueryWhenDoubleQuotedValueThenComparisonStripsQuotes(): void { - /** @Given a comparison whose value carries a space */ - $comparison = Comparison::of(field: 'name', values: ['John Doe'], operator: Operator::EQUAL); + /** @Given a query carrying a double-quoted value with whitespace */ + $query = Query::from(parameters: ['filter' => 'name=="John Doe"']); - /** @When rendering it as an RSQL expression */ - $expression = $comparison->toExpression()->value(); + /** @When reading the validated comparisons */ + $comparisons = Criteria::fromQuery(request: $query, schema: $this->schema)->comparisons(); - /** @Then it renders the value within double quotes */ - self::assertSame('name=="John Doe"', $expression); + /** @Then the comparison carries the value with the surrounding quotes stripped */ + self::assertEquals( + [Comparison::of(field: 'name', values: ['John Doe'], operator: Operator::EQUAL)], + $comparisons + ); } - public function testToExpressionWhenValueCarriesQuoteAndBackslashThenEscapesBoth(): void + public function testFromQueryWhenSingleQuotedValueThenComparisonStripsQuotes(): void { - /** @Given a comparison whose value carries a double quote and a backslash */ - $comparison = Comparison::of(field: 'name', values: ['a"b\\c'], operator: Operator::EQUAL); + /** @Given a query carrying a single-quoted value with whitespace */ + $query = Query::from(parameters: ['filter' => "name=='John Doe'"]); - /** @When rendering it as an RSQL expression */ - $expression = $comparison->toExpression()->value(); + /** @When reading the validated comparisons */ + $comparisons = Criteria::fromQuery(request: $query, schema: $this->schema)->comparisons(); - /** @Then the quote and the backslash are escaped within the double-quoted value */ - self::assertSame('name=="a\\"b\\\\c"', $expression); + /** @Then the comparison carries the value with the surrounding quotes stripped */ + self::assertEquals( + [Comparison::of(field: 'name', values: ['John Doe'], operator: Operator::EQUAL)], + $comparisons + ); } - public function testFilteringWhenMixedPrecedenceGivenThenAndBindsTighterThanOr(): void + public function testFromQueryWhenDateTimeValueMatchesKindThenComparisonIsReturned(): void { - /** @Given a query mixing AND and OR connectives without explicit grouping */ - $query = Query::from(parameters: ['filter' => 'a==1;b==2,c==3']); - - /** @When reading the filtering specification */ - $filter = Criteria::fromQuery(request: $query)->filtering(); - - /** @Then the top filter is an OR group whose first child is the tighter AND group */ - self::assertEquals(Group::of(filters: [ - Group::of(filters: [ - Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), - Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) - ], operator: LogicalOperator::AND), - Comparison::of(field: 'c', values: ['3'], operator: Operator::EQUAL) - ], operator: LogicalOperator::OR), $filter); + /** @Given a schema allowing a date-time field under the greater-than operator */ + $schema = Schema::create()->filterable( + field: 'created_at', + operators: [Operator::GREATER_THAN], + kind: ValueKind::DATETIME + ); + + /** @And a query carrying a valid date-time value */ + $query = Query::from(parameters: ['filter' => 'created_at=gt=2023-01-15T10:30:00Z']); + + /** @When reading the validated comparisons */ + $comparisons = Criteria::fromQuery(request: $query, schema: $schema)->comparisons(); + + /** @Then the only comparison carries the date-time value */ + self::assertEquals([Comparison::of( + field: 'created_at', + values: ['2023-01-15T10:30:00Z'], + operator: Operator::GREATER_THAN + )], $comparisons); } - public function testFilteringWhenNotInListGivenThenComparisonCarriesEveryValue(): void + public function testFromQueryWhenOrGroupThenThrowsFilterShapeNotSupported(): void { - /** @Given a query carrying a NOT_IN list comparison */ - $query = Query::from(parameters: ['filter' => 'role=out=(a,b)']); + /** @Given a query carrying an OR expression of two comparisons */ + $query = Query::from(parameters: ['filter' => 'a==1,b==2']); - /** @When reading the filtering specification */ - $filter = Criteria::fromQuery(request: $query)->filtering(); + /** @Then an exception carrying the raw filter query string is raised */ + $this->expectException(FilterShapeNotSupported::class); + $this->expectExceptionMessage('Filter shape is not supported.'); - /** @Then the filter is a NOT_IN comparison carrying every listed value in order */ - self::assertEquals(Comparison::of(field: 'role', values: ['a', 'b'], operator: Operator::NOT_IN), $filter); + /** @When building the criteria from the query */ + Criteria::fromQuery(request: $query, schema: $this->schema); } - public function testToExpressionWhenAndGroupGivenThenJoinsChildrenWithAndToken(): void + public function testFromQueryWhenMixedPrecedenceThenThrowsFilterShapeNotSupported(): void { - /** @Given an AND group of two comparisons */ - $group = Group::of(filters: [ - Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), - Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) - ], operator: LogicalOperator::AND); + /** @Given a query mixing AND and OR connectives so the top filter is an OR group */ + $query = Query::from(parameters: ['filter' => 'a==1;b==2,c==3']); - /** @When rendering it as an RSQL expression */ - $expression = $group->toExpression()->value(); + /** @Then an exception indicating the filter shape is not supported is raised */ + $this->expectException(FilterShapeNotSupported::class); + $this->expectExceptionMessage('is not supported'); - /** @Then it joins the children with the AND token */ - self::assertSame('a==1;b==2', $expression); + /** @When building the criteria from the query */ + Criteria::fromQuery(request: $query, schema: $this->schema); } - public function testToExpressionWhenOrGroupNestedInAndThenWrapsItInParentheses(): void + public function testFromQueryWhenNestedGroupThenThrowsFilterShapeNotSupported(): void { - /** @Given an AND group whose first child is an OR group */ - $group = Group::of(filters: [ - Group::of(filters: [ - Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), - Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) - ], operator: LogicalOperator::OR), - Comparison::of(field: 'c', values: ['3'], operator: Operator::EQUAL) - ], operator: LogicalOperator::AND); - - /** @When rendering it as an RSQL expression */ - $expression = $group->toExpression()->value(); - - /** @Then the nested OR group is wrapped in parentheses */ - self::assertSame('(a==1,b==2);c==3', $expression); + /** @Given a query whose parentheses nest an OR group inside an AND group */ + $query = Query::from(parameters: ['filter' => '(a==1,b==2);c==3']); + + /** @Then an exception carrying the raw filter query string is raised */ + $this->expectException(FilterShapeNotSupported::class); + $this->expectExceptionMessage('Filter shape <(a==1,b==2);c==3> is not supported.'); + + /** @When building the criteria from the query */ + Criteria::fromQuery(request: $query, schema: $this->schema); } - public function testFilteringWhenDoubleQuotedValueGivenThenComparisonStripsQuotes(): void + public function testFromQueryWhenFieldNotAllowedThenThrowsFilterFieldNotAllowed(): void { - /** @Given a query carrying a double-quoted value with whitespace */ - $query = Query::from(parameters: ['filter' => 'name=="John Doe"']); + /** @Given a schema allowing only the status field */ + $schema = Schema::create()->filterable(field: 'status', operators: [Operator::EQUAL]); - /** @When reading the filtering specification */ - $filter = Criteria::fromQuery(request: $query)->filtering(); + /** @And a query filtering by a field that was never allowed */ + $query = Query::from(parameters: ['filter' => 'discount==10']); - /** @Then the comparison carries the value with the surrounding quotes stripped */ - self::assertEquals(Comparison::of(field: 'name', values: ['John Doe'], operator: Operator::EQUAL), $filter); + /** @Then an exception indicating the filter field is not allowed is raised */ + $this->expectException(FilterFieldNotAllowed::class); + $this->expectExceptionMessage('Filter field is not allowed.'); + + /** @When building the criteria from the query */ + Criteria::fromQuery(request: $query, schema: $schema); } - public function testFilteringWhenSingleQuotedValueGivenThenComparisonStripsQuotes(): void + public function testFromQueryWhenOperatorNotAllowedThenThrowsFilterOperatorNotAllowed(): void { - /** @Given a query carrying a single-quoted value with whitespace */ - $query = Query::from(parameters: ['filter' => "name=='John Doe'"]); + /** @Given a schema allowing the status field under equality only */ + $schema = Schema::create()->filterable(field: 'status', operators: [Operator::EQUAL]); - /** @When reading the filtering specification */ - $filter = Criteria::fromQuery(request: $query)->filtering(); + /** @And a query filtering the field with a disallowed operator */ + $query = Query::from(parameters: ['filter' => 'status!=paid']); - /** @Then the comparison carries the value with the surrounding quotes stripped */ - self::assertEquals(Comparison::of(field: 'name', values: ['John Doe'], operator: Operator::EQUAL), $filter); + /** @Then an exception indicating the filter operator is not allowed is raised */ + $this->expectException(FilterOperatorNotAllowed::class); + $this->expectExceptionMessage('Operator is not allowed for filter field .'); + + /** @When building the criteria from the query */ + Criteria::fromQuery(request: $query, schema: $schema); } - public function testToExpressionWhenComparisonGivenThenRendersFieldOperatorAndValue(): void + public function testFromQueryWhenValueNotPermittedThenThrowsFilterValueNotAllowed(): void { - /** @Given an equality comparison on a field */ - $comparison = Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL); + /** @Given a schema permitting only a fixed set of status values */ + $schema = Schema::create()->filterable( + field: 'status', + operators: [Operator::EQUAL], + values: ['paid', 'pending'] + ); - /** @When rendering it as an RSQL expression */ - $expression = $comparison->toExpression()->value(); + /** @And a query filtering by a value outside the permitted set */ + $query = Query::from(parameters: ['filter' => 'status==shipped']); - /** @Then it renders the field, the operator token, and the value */ - self::assertSame('status==paid', $expression); + /** @Then an exception indicating the value is not permitted is raised */ + $this->expectException(FilterValueNotAllowed::class); + $this->expectExceptionMessage('Value is not permitted for filter field .'); + + /** @When building the criteria from the query */ + Criteria::fromQuery(request: $query, schema: $schema); } - public function testFilteringWhenExplicitGroupingGivenThenParenthesesOverridePrecedence(): void + public function testFromQueryWhenValueBreaksKindThenThrowsFilterValueNotAllowed(): void { - /** @Given a query whose parentheses force the OR group to bind first */ - $query = Query::from(parameters: ['filter' => '(a==1,b==2);c==3']); + /** @Given a schema expecting a date-time kind on the created_at field */ + $schema = Schema::create()->filterable( + field: 'created_at', + operators: [Operator::GREATER_THAN], + kind: ValueKind::DATETIME + ); + + /** @And a query whose value is not a valid date-time */ + $query = Query::from(parameters: ['filter' => 'created_at=gt=not-a-date']); + + /** @Then an exception indicating the value does not match the expected kind is raised */ + $this->expectException(FilterValueNotAllowed::class); + $this->expectExceptionMessage('does not match the datetime kind'); - /** @When reading the filtering specification */ - $filter = Criteria::fromQuery(request: $query)->filtering(); - - /** @Then the top filter is an AND group whose first child is the parenthesized OR group */ - self::assertEquals(Group::of(filters: [ - Group::of(filters: [ - Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), - Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) - ], operator: LogicalOperator::OR), - Comparison::of(field: 'c', values: ['3'], operator: Operator::EQUAL) - ], operator: LogicalOperator::AND), $filter); + /** @When building the criteria from the query */ + Criteria::fromQuery(request: $query, schema: $schema); } - public function testFilteringWhenSingleComparisonGivenThenComparisonCarriesFieldAndValue(): void + public function testFromQueryWhenInListHasDisallowedValueThenThrowsFilterValueNotAllowed(): void { - /** @Given a query carrying a single equality comparison */ - $query = Query::from(parameters: ['filter' => 'status==paid']); + /** @Given a schema permitting only a fixed set of status values under IN */ + $schema = Schema::create()->filterable( + field: 'status', + operators: [Operator::IN], + values: ['paid', 'pending'] + ); + + /** @And a query whose IN list carries a value outside the permitted set */ + $query = Query::from(parameters: ['filter' => 'status=in=(paid,shipped)']); - /** @When reading the filtering specification */ - $filter = Criteria::fromQuery(request: $query)->filtering(); + /** @Then an exception indicating the filter value is not allowed is raised */ + $this->expectException(FilterValueNotAllowed::class); - /** @Then the filter is an equality comparison on the named field with its value */ - self::assertEquals(Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL), $filter); + /** @When building the criteria from the query */ + Criteria::fromQuery(request: $query, schema: $schema); } #[DataProvider('comparisonOperatorCases')] - public function testFilteringWhenComparisonOperatorGivenThenComparisonCarriesThatOperator( + public function testFromQueryWhenComparisonOperatorThenComparisonCarriesThatOperator( string $expression, Operator $expected ): void { /** @Given a query carrying a binary comparison using one RSQL operator */ $query = Query::from(parameters: ['filter' => $expression]); - /** @When reading the filtering specification */ - $filter = Criteria::fromQuery(request: $query)->filtering(); + /** @When reading the validated comparisons */ + $comparisons = Criteria::fromQuery(request: $query, schema: $this->schema)->comparisons(); - /** @Then the filter is a comparison on the left field carrying the expected operator */ - self::assertEquals(Comparison::of(field: 'a', values: ['b'], operator: $expected), $filter); + /** @Then the only comparison carries the expected operator */ + self::assertEquals([Comparison::of(field: 'a', values: ['b'], operator: $expected)], $comparisons); } #[DataProvider('malformedExpressionCases')] - public function testFilteringWhenMalformedExpressionGivenThenThrowsFilterExpressionIsInvalid( + public function testFromQueryWhenMalformedExpressionThenThrowsFilterExpressionIsInvalid( string $expression ): void { /** @Given a query carrying a filter expression that breaks the RSQL grammar */ @@ -318,46 +315,7 @@ public function testFilteringWhenMalformedExpressionGivenThenThrowsFilterExpress $this->expectExceptionMessage('could not be parsed'); /** @When building the criteria from the query */ - Criteria::fromQuery(request: $query); - } - - public function testValuesWhenComparisonGivenThenReturnsTheComparedValues(): void - { - /** @Given an IN comparison carrying several values */ - $comparison = Comparison::of(field: 'role', values: ['admin', 'user'], operator: Operator::IN); - - /** @When reading the compared values */ - $values = $comparison->values(); - - /** @Then it returns the values compared against the field in order */ - self::assertSame(['admin', 'user'], $values); - } - - public function testOperatorWhenComparisonGivenThenReturnsTheComparisonOperator(): void - { - /** @Given an equality comparison */ - $comparison = Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL); - - /** @When reading the comparison operator */ - $operator = $comparison->operator(); - - /** @Then it returns the operator the comparison carries */ - self::assertSame(Operator::EQUAL, $operator); - } - - public function testOperatorWhenGroupGivenThenReturnsTheLogicalConnective(): void - { - /** @Given an AND group joining two comparisons */ - $group = Group::of(filters: [ - Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), - Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) - ], operator: LogicalOperator::AND); - - /** @When reading the logical connective */ - $operator = $group->operator(); - - /** @Then it returns the connective joining the children */ - self::assertSame(LogicalOperator::AND, $operator); + Criteria::fromQuery(request: $query, schema: $this->schema); } public static function comparisonOperatorCases(): array diff --git a/tests/Unit/GroupTest.php b/tests/Unit/GroupTest.php new file mode 100644 index 0000000..af38620 --- /dev/null +++ b/tests/Unit/GroupTest.php @@ -0,0 +1,73 @@ +filters(); + + /** @Then it returns the child filters in order */ + self::assertSame([$first, $second], $filters); + } + + public function testIsEmptyWhenGroupHasNoChildThenIsEmpty(): void + { + /** @Given an empty group */ + $group = Group::none(); + + /** @When checking whether it is empty */ + $isEmpty = $group->isEmpty(); + + /** @Then it reports itself as empty */ + self::assertTrue($isEmpty); + } + + public function testIsEmptyWhenGroupHasChildThenIsNotEmpty(): void + { + /** @Given a group joining a single comparison */ + $group = Group::of(filters: [ + Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL) + ], operator: LogicalOperator::AND); + + /** @When checking whether it is empty */ + $isEmpty = $group->isEmpty(); + + /** @Then it reports itself as not empty */ + self::assertFalse($isEmpty); + } + + public function testOperatorThenReturnsTheLogicalConnective(): void + { + /** @Given an AND group joining two comparisons */ + $group = Group::of(filters: [ + Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), + Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) + ], operator: LogicalOperator::AND); + + /** @When reading the logical connective */ + $operator = $group->operator(); + + /** @Then it returns the connective joining the children */ + self::assertSame(LogicalOperator::AND, $operator); + } +} diff --git a/tests/Unit/LinksTest.php b/tests/Unit/LinksTest.php index 8bac15c..8a145ef 100644 --- a/tests/Unit/LinksTest.php +++ b/tests/Unit/LinksTest.php @@ -8,28 +8,190 @@ use ReflectionClass; use ReflectionMethod; use Test\TinyBlocks\HttpQuery\Models\Query; -use TinyBlocks\Collection\Collection; -use TinyBlocks\HttpQuery\Criteria; -use TinyBlocks\HttpQuery\Cursor; -use TinyBlocks\HttpQuery\CursorPage; -use TinyBlocks\HttpQuery\CursorPagination; +use TinyBlocks\HttpQuery\Comparison; +use TinyBlocks\HttpQuery\Group; use TinyBlocks\HttpQuery\Internal\Uri; use TinyBlocks\HttpQuery\Links; +use TinyBlocks\HttpQuery\LogicalOperator; +use TinyBlocks\HttpQuery\Navigation; +use TinyBlocks\HttpQuery\Offset\Criteria; +use TinyBlocks\HttpQuery\Offset\Pagination; +use TinyBlocks\HttpQuery\Operator; +use TinyBlocks\HttpQuery\Sort; final class LinksTest extends TestCase { + public function testToArrayWhenInListFilterThenRendersParenthesizedValues(): void + { + /** @Given an IN comparison carrying several values */ + $filter = Comparison::of(field: 'role', values: ['admin', 'user'], operator: Operator::IN); + + /** @When rendering the navigation for a page carrying that filter */ + $links = Links::from( + sort: Sort::fromExpression(expression: ''), + filter: $filter, + baseUri: '/v1/orders', + self: Pagination::fromPage(page: 1, perPage: 20), + navigation: Navigation::empty() + ); + + /** @Then the self link wraps the comma-joined values in parentheses */ + self::assertSame( + '/v1/orders?filter=role=in=(admin,user)&page[number]=1&page[size]=20', + $links->toArray()['self'] + ); + } + + public function testToArrayWhenReservedCharacterInValueThenQuotesIt(): void + { + /** @Given a comparison whose value carries a space */ + $filter = Comparison::of(field: 'name', values: ['John Doe'], operator: Operator::EQUAL); + + /** @When rendering the navigation for a page carrying that filter */ + $links = Links::from( + sort: Sort::fromExpression(expression: ''), + filter: $filter, + baseUri: '/v1/orders', + self: Pagination::fromPage(page: 1, perPage: 20), + navigation: Navigation::empty() + ); + + /** @Then the self link renders the value within double quotes */ + self::assertSame( + '/v1/orders?filter=name=="John Doe"&page[number]=1&page[size]=20', + $links->toArray()['self'] + ); + } + + public function testToArrayWhenQuoteAndBackslashInValueThenEscapesBoth(): void + { + /** @Given a comparison whose value carries a double quote and a backslash */ + $filter = Comparison::of(field: 'name', values: ['a"b\\c'], operator: Operator::EQUAL); + + /** @When rendering the navigation for a page carrying that filter */ + $links = Links::from( + sort: Sort::fromExpression(expression: ''), + filter: $filter, + baseUri: '/v1/orders', + self: Pagination::fromPage(page: 1, perPage: 20), + navigation: Navigation::empty() + ); + + /** @Then the self link escapes the quote and the backslash within the double-quoted value */ + self::assertSame( + '/v1/orders?filter=name=="a\\"b\\\\c"&page[number]=1&page[size]=20', + $links->toArray()['self'] + ); + } + + public function testToArrayWhenAndGroupFilterThenJoinsChildrenWithTheAndToken(): void + { + /** @Given an AND group of two comparisons */ + $filter = Group::of(filters: [ + Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), + Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) + ], operator: LogicalOperator::AND); + + /** @When rendering the navigation for a page carrying that filter */ + $links = Links::from( + sort: Sort::fromExpression(expression: ''), + filter: $filter, + baseUri: '/v1/orders', + self: Pagination::fromPage(page: 1, perPage: 20), + navigation: Navigation::empty() + ); + + /** @Then the self link joins the children with the AND token */ + self::assertSame('/v1/orders?filter=a==1;b==2&page[number]=1&page[size]=20', $links->toArray()['self']); + } + + public function testToArrayWhenOrGroupFilterThenJoinsChildrenWithTheOrToken(): void + { + /** @Given an OR group of two comparisons */ + $filter = Group::of(filters: [ + Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), + Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) + ], operator: LogicalOperator::OR); + + /** @When rendering the navigation for a page carrying that filter */ + $links = Links::from( + sort: Sort::fromExpression(expression: ''), + filter: $filter, + baseUri: '/v1/orders', + self: Pagination::fromPage(page: 1, perPage: 20), + navigation: Navigation::empty() + ); + + /** @Then the self link joins the children with the OR token */ + self::assertSame('/v1/orders?filter=a==1,b==2&page[number]=1&page[size]=20', $links->toArray()['self']); + } + + public function testToArrayWhenOrGroupNestedInAndThenWrapsItInParentheses(): void + { + /** @Given an AND group whose first child is an OR group */ + $filter = Group::of(filters: [ + Group::of(filters: [ + Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), + Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) + ], operator: LogicalOperator::OR), + Comparison::of(field: 'c', values: ['3'], operator: Operator::EQUAL) + ], operator: LogicalOperator::AND); + + /** @When rendering the navigation for a page carrying that filter */ + $links = Links::from( + sort: Sort::fromExpression(expression: ''), + filter: $filter, + baseUri: '/v1/orders', + self: Pagination::fromPage(page: 1, perPage: 20), + navigation: Navigation::empty() + ); + + /** @Then the self link wraps the tighter-binding OR group in parentheses */ + self::assertSame('/v1/orders?filter=(a==1,b==2);c==3&page[number]=1&page[size]=20', $links->toArray()['self']); + } + + public function testToArrayWhenAndGroupNestedInOrThenLeavesItUnwrapped(): void + { + /** @Given an OR group whose first child is an AND group */ + $filter = Group::of(filters: [ + Group::of(filters: [ + Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), + Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) + ], operator: LogicalOperator::AND), + Comparison::of(field: 'c', values: ['3'], operator: Operator::EQUAL) + ], operator: LogicalOperator::OR); + + /** @When rendering the navigation for a page carrying that filter */ + $links = Links::from( + sort: Sort::fromExpression(expression: ''), + filter: $filter, + baseUri: '/v1/orders', + self: Pagination::fromPage(page: 1, perPage: 20), + navigation: Navigation::empty() + ); + + /** @Then the self link leaves the tighter-binding AND group unwrapped */ + self::assertSame('/v1/orders?filter=a==1;b==2,c==3&page[number]=1&page[size]=20', $links->toArray()['self']); + } + public function testToArrayWhenPageIsTheLastThenOmitsTheNextRelation(): void { /** @Given a criteria pointing at the twenty-fourth page */ - $criteria = Criteria::fromQuery(request: Query::from(parameters: [ - 'page' => ['number' => '24', 'size' => '20'] - ])); + $criteria = Criteria::fromQuery( + request: Query::from(parameters: ['page' => ['number' => '24', 'size' => '20']]) + ); /** @And a page carrying a total spanning twenty-four pages */ - $result = $criteria->offsetPage(items: Collection::createFrom(elements: range(1, 20)), total: 480); - - /** @When rendering the navigation for the last page */ - $links = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $result->navigation()); + $result = $criteria->page(total: 480, items: range(1, 20)); + + /** @When rendering the navigation for the last page from its own pagination */ + $links = Links::from( + sort: Sort::fromExpression(expression: ''), + filter: Group::none(), + baseUri: '/v1/orders', + self: Pagination::fromPage(page: 24, perPage: 20), + navigation: $result->navigation() + ); /** @Then the navigation exposes the self, first, previous, and last relations in that order */ self::assertSame([ @@ -45,18 +207,22 @@ public function testToArrayWhenPageIsTheLastThenOmitsTheNextRelation(): void public function testToArrayWhenSliceMiddleThenExposesSelfFirstPrevAndNext(): void { - /** @Given a criteria carrying a filter and a sort at a middle page */ - $criteria = Criteria::fromQuery(request: Query::from(parameters: [ - 'sort' => '-created_at,id', - 'page' => ['number' => '3', 'size' => '20'], - 'filter' => 'status==paid' - ])); + /** @Given a criteria at a middle page */ + $criteria = Criteria::fromQuery( + request: Query::from(parameters: ['page' => ['number' => '3', 'size' => '20']]) + ); /** @And a slice fetched for the page size plus one so a next page exists */ - $result = $criteria->offsetSlice(items: Collection::createFrom(elements: range(1, 21))); - - /** @When rendering the navigation for the slice */ - $links = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $result->navigation()); + $result = $criteria->slice(items: range(1, 21)); + + /** @When rendering the navigation preserving a filter and a sort */ + $links = Links::from( + sort: Sort::fromExpression(expression: '-created_at,id'), + filter: Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL), + baseUri: '/v1/orders', + self: Pagination::fromPage(page: 3, perPage: 20), + navigation: $result->navigation() + ); /** @Then the navigation exposes the self, first, previous, and next relations preserving filter and sort */ self::assertSame([ @@ -67,41 +233,24 @@ public function testToArrayWhenSliceMiddleThenExposesSelfFirstPrevAndNext(): voi ], $links->toArray()); } - public function testToArrayWhenCursorResultThenExposesOnlySelfAndNext(): void - { - /** @Given a cursor criteria carrying an incoming cursor token and a page size of two */ - $criteria = Criteria::fromQuery(request: Query::from(parameters: [ - 'page' => ['cursor' => Cursor::fromKeys(keys: [5])->toString(), 'size' => '2'] - ])); - - /** @And a cursor page fetched for the page size plus one with no incoming cursor */ - $result = CursorPage::from( - items: Collection::createFrom(elements: [10, 20, 30]), - keysOf: static fn(mixed $element): array => [$element], - criteria: $criteria, - pagination: CursorPagination::from(cursor: Cursor::none(), perPage: 2) - ); - - /** @When rendering the navigation for the cursor page */ - $links = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $result->navigation()); - - /** @Then the navigation exposes only the self and next relations */ - self::assertSame([ - 'self' => sprintf('/v1/orders?page[cursor]=%s&page[size]=2', Cursor::fromKeys(keys: [5])->toString()), - 'next' => sprintf('/v1/orders?page[cursor]=%s&page[size]=2', Cursor::fromKeys(keys: [20])->toString()) - ], $links->toArray()); - } - public function testToArrayWhenPageIsTheFirstThenOmitsThePreviousRelation(): void { /** @Given a criteria pointing at the first page */ - $criteria = Criteria::fromQuery(request: Query::from(parameters: [])); + $criteria = Criteria::fromQuery( + request: Query::from(parameters: ['page' => ['number' => '1', 'size' => '20']]) + ); /** @And a page carrying a total spanning twenty-four pages */ - $result = $criteria->offsetPage(items: Collection::createFrom(elements: range(1, 20)), total: 480); - - /** @When rendering the navigation for the first page */ - $links = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $result->navigation()); + $result = $criteria->page(total: 480, items: range(1, 20)); + + /** @When rendering the navigation for the first page from its own pagination */ + $links = Links::from( + sort: Sort::fromExpression(expression: ''), + filter: Group::none(), + baseUri: '/v1/orders', + self: Pagination::fromPage(page: 1, perPage: 20), + navigation: $result->navigation() + ); /** @Then the navigation exposes the self, first, next, and last relations in that order */ self::assertSame([ @@ -118,15 +267,21 @@ public function testToArrayWhenPageIsTheFirstThenOmitsThePreviousRelation(): voi public function testToArrayWhenSliceMiddleThenCarriesAFirstButNoLastRelation(): void { /** @Given a criteria pointing at a middle page */ - $criteria = Criteria::fromQuery(request: Query::from(parameters: [ - 'page' => ['number' => '3', 'size' => '20'] - ])); + $criteria = Criteria::fromQuery( + request: Query::from(parameters: ['page' => ['number' => '3', 'size' => '20']]) + ); /** @And a slice fetched for the page size plus one so a next page exists */ - $result = $criteria->offsetSlice(items: Collection::createFrom(elements: range(1, 21))); - - /** @When rendering the navigation for the slice */ - $links = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $result->navigation()); + $result = $criteria->slice(items: range(1, 21)); + + /** @When rendering the navigation for the slice from its own pagination */ + $links = Links::from( + sort: Sort::fromExpression(expression: ''), + filter: Group::none(), + baseUri: '/v1/orders', + self: Pagination::fromPage(page: 3, perPage: 20), + navigation: $result->navigation() + ); /** @Then the navigation carries a first relation */ self::assertArrayHasKey('first', $links->toArray()); @@ -135,49 +290,24 @@ public function testToArrayWhenSliceMiddleThenCarriesAFirstButNoLastRelation(): self::assertArrayNotHasKey('last', $links->toArray()); } - public function testToArrayWhenCursorResultThenCarriesNoFirstOrLastOrPreviousRelation(): void - { - /** @Given a cursor criteria carrying an incoming cursor token and a page size of two */ - $criteria = Criteria::fromQuery(request: Query::from(parameters: [ - 'page' => ['cursor' => Cursor::fromKeys(keys: [5])->toString(), 'size' => '2'] - ])); - - /** @And a cursor page fetched for the page size plus one with no incoming cursor */ - $result = CursorPage::from( - items: Collection::createFrom(elements: [10, 20, 30]), - keysOf: static fn(mixed $element): array => [$element], - criteria: $criteria, - pagination: CursorPagination::from(cursor: Cursor::none(), perPage: 2) - ); - - /** @When rendering the navigation for the cursor page */ - $links = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $result->navigation()); - - /** @Then the navigation carries no first relation */ - self::assertArrayNotHasKey('first', $links->toArray()); - - /** @And the navigation carries no last relation */ - self::assertArrayNotHasKey('last', $links->toArray()); - - /** @And the navigation carries no previous relation */ - self::assertArrayNotHasKey('prev', $links->toArray()); - } - public function testToHeaderWhenPageInTheMiddleThenFoldsEveryRelationIntoOneCommaJoinedValue(): void { - /** @Given a criteria carrying a filter and a sort at a middle page */ - $criteria = Criteria::fromQuery(request: Query::from(parameters: [ - 'sort' => '-created_at,id', - 'page' => ['number' => '3', 'size' => '20'], - 'filter' => 'status==paid' - ])); + /** @Given a criteria at a middle page */ + $criteria = Criteria::fromQuery( + request: Query::from(parameters: ['page' => ['number' => '3', 'size' => '20']]) + ); /** @And a page carrying a total spanning twenty-four pages */ - $result = $criteria->offsetPage(items: Collection::createFrom(elements: range(1, 20)), total: 480); + $result = $criteria->page(total: 480, items: range(1, 20)); - /** @When rendering the navigation as an RFC 8288 Link header */ - $header = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $result->navigation()) - ->toHeader(); + /** @When rendering the navigation as an RFC 8288 Link header preserving a filter and a sort */ + $header = Links::from( + sort: Sort::fromExpression(expression: '-created_at,id'), + filter: Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL), + baseUri: '/v1/orders', + self: Pagination::fromPage(page: 3, perPage: 20), + navigation: $result->navigation() + )->toHeader(); /** @Then every present relation is folded into one comma-joined Link header value */ self::assertSame(['Link' => [implode(', ', [ @@ -191,18 +321,22 @@ public function testToHeaderWhenPageInTheMiddleThenFoldsEveryRelationIntoOneComm public function testToArrayWhenPageInTheMiddleThenExposesEveryRelationPreservingFilterAndSort(): void { - /** @Given a criteria carrying a filter and a sort at a middle page */ - $criteria = Criteria::fromQuery(request: Query::from(parameters: [ - 'sort' => '-created_at,id', - 'page' => ['number' => '3', 'size' => '20'], - 'filter' => 'status==paid' - ])); + /** @Given a criteria at a middle page */ + $criteria = Criteria::fromQuery( + request: Query::from(parameters: ['page' => ['number' => '3', 'size' => '20']]) + ); /** @And a page carrying a total spanning twenty-four pages */ - $result = $criteria->offsetPage(items: Collection::createFrom(elements: range(1, 20)), total: 480); - - /** @When rendering the navigation for the page */ - $links = Links::from(baseUri: '/v1/orders', criteria: $criteria, navigation: $result->navigation()); + $result = $criteria->page(total: 480, items: range(1, 20)); + + /** @When rendering the navigation preserving a filter and a sort */ + $links = Links::from( + sort: Sort::fromExpression(expression: '-created_at,id'), + filter: Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL), + baseUri: '/v1/orders', + self: Pagination::fromPage(page: 3, perPage: 20), + navigation: $result->navigation() + ); /** @Then the navigation exposes every relation in semantic order preserving filter and sort */ self::assertSame([ diff --git a/tests/Unit/Offset/CriteriaTest.php b/tests/Unit/Offset/CriteriaTest.php new file mode 100644 index 0000000..ce5beb1 --- /dev/null +++ b/tests/Unit/Offset/CriteriaTest.php @@ -0,0 +1,209 @@ +offset()); + + /** @And the limit carries the default page size */ + self::assertSame(20, $criteria->limit()); + } + + public function testFromQueryWhenPerPageAtMaximumThenLimitIsAccepted(): void + { + /** @Given query parameters carrying a page size at the default maximum */ + $query = Query::from(parameters: ['page' => ['size' => '100']]); + + /** @When building the criteria from the query */ + $criteria = Criteria::fromQuery(request: $query); + + /** @Then the limit carries the maximum page size */ + self::assertSame(100, $criteria->limit()); + } + + public function testSortWhenClientSortsAllowedFieldsThenReturnsTheClientSort(): void + { + /** @Given a schema allowing the client to sort by two fields */ + $schema = Schema::create()->sortable(fields: ['created_at', 'id']); + + /** @When reading the effective sort from a client sort over both fields */ + $sort = Criteria::fromQuery(request: Query::from(parameters: ['sort' => '-created_at,id']), schema: $schema) + ->sort(); + + /** @Then the effective sort is the client sort */ + self::assertEquals(Sort::fromExpression(expression: '-created_at,id'), $sort); + } + + public function testSortWhenNoClientSortAndDefaultGivenThenReturnsTheDefault(): void + { + /** @Given a schema declaring a default sort */ + $schema = Schema::create()->defaultSort(sort: Sort::fromExpression(expression: '-created_at')); + + /** @When reading the effective sort from a query carrying no sort */ + $sort = Criteria::fromQuery(request: Query::from(parameters: []), schema: $schema)->sort(); + + /** @Then the effective sort is the schema default */ + self::assertEquals(Sort::fromExpression(expression: '-created_at'), $sort); + } + + public function testSortWhenNoClientSortAndNoDefaultThenIsEmpty(): void + { + /** @Given a schema declaring no sortable field and no default sort */ + $schema = Schema::create(); + + /** @When reading the effective sort from a query carrying no sort */ + $sort = Criteria::fromQuery(request: Query::from(parameters: []), schema: $schema)->sort(); + + /** @Then the effective sort is empty */ + self::assertTrue($sort->isEmpty()); + } + + public function testSortWhenClientSortsDisallowedFieldThenThrowsSortFieldNotAllowed(): void + { + /** @Given a schema allowing the client to sort by a single field */ + $schema = Schema::create()->sortable(fields: ['id']); + + /** @And a query sorting by a field that was never declared sortable */ + $query = Query::from(parameters: ['sort' => 'name']); + + /** @Then an exception indicating the sort field is not allowed is raised */ + $this->expectException(SortFieldNotAllowed::class); + $this->expectExceptionMessage('Sort field is not allowed.'); + + /** @When building the criteria from the query */ + Criteria::fromQuery(request: $query, schema: $schema); + } + + public function testSortWhenServerControlledAndClientSortsThenThrowsSortFieldNotAllowed(): void + { + /** @Given a schema with a server-controlled default and no client-sortable field */ + $schema = Schema::create()->defaultSort(sort: Sort::fromExpression(expression: '-created_at')); + + /** @And a query carrying a client sort */ + $query = Query::from(parameters: ['sort' => 'id']); + + /** @Then an exception indicating the sort field is not allowed is raised */ + $this->expectException(SortFieldNotAllowed::class); + + /** @When building the criteria from the query */ + Criteria::fromQuery(request: $query, schema: $schema); + } + + public function testPageWhenBuiltFromRequestThenReturnsOffsetPage(): void + { + /** @Given a criteria parsed from a request carrying a page size of three */ + $criteria = Criteria::fromQuery(request: Query::from(parameters: ['page' => ['size' => '3']])); + + /** @When building an offset page from the total element count and the items */ + $page = $criteria->page(total: 30, items: ['a', 'b', 'c']); + + /** @Then the result is an offset page */ + self::assertInstanceOf(Page::class, $page); + + /** @And it carries the total element count */ + self::assertSame(30, $page->total()); + } + + public function testSliceWhenBuiltFromRequestThenReturnsOffsetSlice(): void + { + /** @Given a criteria parsed from a request carrying a page size of three */ + $criteria = Criteria::fromQuery(request: Query::from(parameters: ['page' => ['size' => '3']])); + + /** @When building an offset slice from the items fetched for the page size plus one */ + $slice = $criteria->slice(items: ['a', 'b', 'c', 'd']); + + /** @Then the result is an offset slice */ + self::assertInstanceOf(Slice::class, $slice); + + /** @And it reports a next page from the trimmed extra element */ + self::assertTrue($slice->hasNext()); + } + + public function testFromQueryWhenCustomSchemaGivenThenAppliesItsDefaultPageSize(): void + { + /** @Given query parameters carrying a page number without a page size */ + $query = Query::from(parameters: ['page' => ['number' => '2']]); + + /** @And a schema lowering the default page size */ + $schema = Schema::create()->defaultPerPage(defaultPerPage: 5); + + /** @When building the criteria from the query and the schema */ + $criteria = Criteria::fromQuery(request: $query, schema: $schema); + + /** @Then the offset is derived from the requested page and the schema default page size */ + self::assertSame(5, $criteria->offset()); + + /** @And the limit carries the schema default page size */ + self::assertSame(5, $criteria->limit()); + } + + public function testFromQueryWhenFilterSortAndPageGivenThenEachSpecificationIsValidated(): void + { + /** @Given a schema allowing the filtered and sorted fields */ + $schema = Schema::create() + ->sortable(fields: ['created_at']) + ->filterable(field: 'status', operators: [Operator::EQUAL]); + + /** @And a query carrying a filter, a sort, a page, and a page size */ + $query = Query::from(parameters: [ + 'sort' => '-created_at', + 'page' => ['number' => '2', 'size' => '15'], + 'filter' => 'status==paid' + ]); + + /** @When building the criteria from the query and the schema */ + $criteria = Criteria::fromQuery(request: $query, schema: $schema); + + /** @Then the validated comparisons carry the filtered field and value */ + self::assertEquals( + [Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL)], + $criteria->comparisons() + ); + + /** @And the effective sort is the client sort */ + self::assertEquals(Sort::fromExpression(expression: '-created_at'), $criteria->sort()); + + /** @And the offset is derived from the requested page and page size */ + self::assertSame(15, $criteria->offset()); + + /** @And the limit carries the requested page size */ + self::assertSame(15, $criteria->limit()); + } + + public function testFromQueryWhenPerPageAboveMaximumThenThrowsPageSizeOutOfRange(): void + { + /** @Given query parameters carrying a page size above the default maximum */ + $query = Query::from(parameters: ['page' => ['size' => '500']]); + + /** @Then an exception indicating the page size is out of range is raised */ + $this->expectException(PageSizeOutOfRange::class); + $this->expectExceptionMessage('Page size'); + + /** @When building the criteria from the query */ + Criteria::fromQuery(request: $query); + } +} diff --git a/tests/Unit/OffsetPageTest.php b/tests/Unit/Offset/PageTest.php similarity index 64% rename from tests/Unit/OffsetPageTest.php rename to tests/Unit/Offset/PageTest.php index 7d024c9..288d9b4 100644 --- a/tests/Unit/OffsetPageTest.php +++ b/tests/Unit/Offset/PageTest.php @@ -2,35 +2,71 @@ declare(strict_types=1); -namespace Test\TinyBlocks\HttpQuery\Unit; +namespace Test\TinyBlocks\HttpQuery\Unit\Offset; use PHPUnit\Framework\TestCase; use Test\TinyBlocks\HttpQuery\Models\Query; -use TinyBlocks\Collection\Collection; use TinyBlocks\Collection\KeyPreservation; use TinyBlocks\Http\LinkRelation; -use TinyBlocks\HttpQuery\Criteria; use TinyBlocks\HttpQuery\Exceptions\TotalIsNegative; use TinyBlocks\HttpQuery\NavigationTarget; -use TinyBlocks\HttpQuery\OffsetPage; -use TinyBlocks\HttpQuery\OffsetPagination; +use TinyBlocks\HttpQuery\Offset\Criteria; +use TinyBlocks\HttpQuery\Offset\Pagination; -final class OffsetPageTest extends TestCase +final class PageTest extends TestCase { - private Criteria $criteria; + public function testTotalWhenPageGivenThenReturnsTheTotalElementCount(): void + { + /** @Given a criteria on the first page with a page size of twenty */ + $criteria = Criteria::fromQuery( + request: Query::from(parameters: ['page' => ['number' => '1', 'size' => '20']]) + ); + + /** @When building the page from the total element count */ + $page = $criteria->page(total: 480, items: ['a', 'b']); - protected function setUp(): void + /** @Then the total is the count provided across every page */ + self::assertSame(480, $page->total()); + } + + public function testItemsWhenPageGivenThenCarriesTheProvidedItems(): void { - $this->criteria = Criteria::fromQuery(request: Query::from(parameters: [])); + /** @Given a criteria on the third page with a page size of twenty */ + $criteria = Criteria::fromQuery( + request: Query::from(parameters: ['page' => ['number' => '3', 'size' => '20']]) + ); + + /** @When building the page and reading its items */ + $page = $criteria->page(total: 480, items: ['a', 'b']); + + /** @Then the items carry the provided elements */ + self::assertSame(['a', 'b'], $page->items()->toArray(keyPreservation: KeyPreservation::DISCARD)); + } + + public function testFromWhenTotalIsNegativeThenThrowsTotalIsNegative(): void + { + /** @Given a criteria on the first page */ + $criteria = Criteria::fromQuery( + request: Query::from(parameters: ['page' => ['number' => '1', 'size' => '20']]) + ); + + /** @Then an exception indicating the total is negative is raised */ + $this->expectException(TotalIsNegative::class); + $this->expectExceptionMessage('Total'); + + /** @When building a page from a negative total */ + $criteria->page(total: -1, items: []); } public function testNavigationWhenTotalIsZeroThenThereIsNoPage(): void { - /** @Given a pagination on the first page */ - $pagination = OffsetPagination::fromPage(page: 1, perPage: 20); + /** @Given a criteria on the first page */ + $criteria = Criteria::fromQuery( + request: Query::from(parameters: ['page' => ['number' => '1', 'size' => '20']]) + ); /** @When building the page from a total of zero */ - $page = OffsetPage::from(items: [], total: 0, criteria: $this->criteria, pagination: $pagination); + $page = $criteria->page(total: 0, items: []); /** @Then there are no pages */ self::assertSame(0, $page->totalPages()); @@ -57,18 +93,17 @@ public function testNavigationWhenTotalIsZeroThenThereIsNoPage(): void public function testNavigationWhenLastPageGivenThenHasNoNextPage(): void { - /** @Given a pagination on the last page */ - $pagination = OffsetPagination::fromPage(page: 24, perPage: 20); + /** @Given a criteria on the last page */ + $criteria = Criteria::fromQuery( + request: Query::from(parameters: ['page' => ['number' => '24', 'size' => '20']]) + ); /** @When building the page from the total element count */ - $page = OffsetPage::from(items: ['a', 'b'], total: 480, criteria: $this->criteria, pagination: $pagination); + $page = $criteria->page(total: 480, items: ['a', 'b']); /** @Then the page reports no next page */ self::assertFalse($page->hasNext()); - /** @And the page is the last page */ - self::assertTrue($page->isLast()); - /** @And the page has a previous page */ self::assertTrue($page->hasPrevious()); @@ -79,48 +114,19 @@ public function testNavigationWhenLastPageGivenThenHasNoNextPage(): void self::assertSame(24, $page->last()?->page()); } - public function testItemsWhenPageGivenThenCarriesTheProvidedItems(): void - { - /** @Given a collection of items */ - $items = Collection::createFrom(elements: ['a', 'b']); - - /** @And a pagination on the third page */ - $pagination = OffsetPagination::fromPage(page: 3, perPage: 20); - - /** @When building the page and reading its items */ - $page = OffsetPage::from(items: $items, total: 480, criteria: $this->criteria, pagination: $pagination); - - /** @Then the items carry the provided elements */ - self::assertSame(['a', 'b'], $page->items()->toArray(keyPreservation: KeyPreservation::DISCARD)); - } - - public function testFromWhenTotalIsNegativeThenThrowsTotalIsNegative(): void - { - /** @Given a pagination on the first page */ - $pagination = OffsetPagination::fromPage(page: 1, perPage: 20); - - /** @Then an exception indicating the total is negative is raised */ - $this->expectException(TotalIsNegative::class); - $this->expectExceptionMessage('Total'); - - /** @When building a page from a negative total */ - OffsetPage::from(items: [], total: -1, criteria: $this->criteria, pagination: $pagination); - } - public function testNavigationWhenFirstPageGivenThenHasNoPreviousPage(): void { - /** @Given a pagination on the first page */ - $pagination = OffsetPagination::fromPage(page: 1, perPage: 20); + /** @Given a criteria on the first page */ + $criteria = Criteria::fromQuery( + request: Query::from(parameters: ['page' => ['number' => '1', 'size' => '20']]) + ); /** @When building the page from the total element count */ - $page = OffsetPage::from(items: ['a', 'b'], total: 480, criteria: $this->criteria, pagination: $pagination); + $page = $criteria->page(total: 480, items: ['a', 'b']); /** @Then the page reports no previous page */ self::assertFalse($page->hasPrevious()); - /** @And the page is the first page */ - self::assertTrue($page->isFirst()); - /** @And the page has a next page */ self::assertTrue($page->hasNext()); @@ -137,28 +143,15 @@ public function testNavigationWhenFirstPageGivenThenHasNoPreviousPage(): void self::assertSame(24, $page->last()?->page()); } - public function testTotalWhenPageGivenThenReturnsTheTotalElementCount(): void - { - /** @Given a collection of items */ - $items = Collection::createFrom(elements: ['a', 'b']); - - /** @And a pagination on the first page */ - $pagination = OffsetPagination::fromPage(page: 1, perPage: 20); - - /** @When building the page from the total element count */ - $page = OffsetPage::from(items: $items, total: 480, criteria: $this->criteria, pagination: $pagination); - - /** @Then the total is the count provided across every page */ - self::assertSame(480, $page->total()); - } - public function testTotalPagesWhenTotalIsNotAMultipleOfPerPageThenRoundsUp(): void { - /** @Given a pagination on the first page */ - $pagination = OffsetPagination::fromPage(page: 1, perPage: 20); + /** @Given a criteria on the first page with a page size of twenty */ + $criteria = Criteria::fromQuery( + request: Query::from(parameters: ['page' => ['number' => '1', 'size' => '20']]) + ); /** @When building the page from a total that is not a multiple of the page size */ - $page = OffsetPage::from(items: ['a', 'b'], total: 21, criteria: $this->criteria, pagination: $pagination); + $page = $criteria->page(total: 21, items: ['a', 'b']); /** @Then the total number of pages rounds the division up */ self::assertSame(2, $page->totalPages()); @@ -166,11 +159,13 @@ public function testTotalPagesWhenTotalIsNotAMultipleOfPerPageThenRoundsUp(): vo public function testMetadataWhenMiddlePageGivenThenCarriesEveryFlagAndCount(): void { - /** @Given a pagination on a middle page */ - $pagination = OffsetPagination::fromPage(page: 3, perPage: 20); + /** @Given a criteria on a middle page with a page size of twenty */ + $criteria = Criteria::fromQuery( + request: Query::from(parameters: ['page' => ['number' => '3', 'size' => '20']]) + ); /** @When building the page from the total element count */ - $page = OffsetPage::from(items: ['a', 'b'], total: 480, criteria: $this->criteria, pagination: $pagination); + $page = $criteria->page(total: 480, items: ['a', 'b']); /** @Then the metadata carries every navigation flag and count in length-ascending key order */ self::assertSame([ @@ -185,11 +180,13 @@ public function testMetadataWhenMiddlePageGivenThenCarriesEveryFlagAndCount(): v public function testNavigationWhenFirstPageGivenThenOmitsThePreviousRelation(): void { - /** @Given a pagination on the first page of a multi-page result */ - $pagination = OffsetPagination::fromPage(page: 1, perPage: 20); + /** @Given a criteria on the first page of a multi-page result */ + $criteria = Criteria::fromQuery( + request: Query::from(parameters: ['page' => ['number' => '1', 'size' => '20']]) + ); /** @And a page on that first page */ - $page = OffsetPage::from(items: [], total: 480, criteria: $this->criteria, pagination: $pagination); + $page = $criteria->page(total: 480, items: []); /** @When reading the relations of the navigation targets */ $relations = $page->navigation()->targets() @@ -202,14 +199,13 @@ public function testNavigationWhenFirstPageGivenThenOmitsThePreviousRelation(): public function testToResponseWhenMiddlePageGivenThenRendersBodyAndLinkHeader(): void { - /** @Given query parameters on the third page with a page size of twenty */ - $query = Query::from(parameters: ['page' => ['number' => '3', 'size' => '20']]); - - /** @And the criteria parsed from those parameters */ - $criteria = Criteria::fromQuery(request: $query); + /** @Given a criteria on the third page with a page size of twenty */ + $criteria = Criteria::fromQuery( + request: Query::from(parameters: ['page' => ['number' => '3', 'size' => '20']]) + ); - /** @And a page built from the criteria over items keyed by their positions */ - $page = $criteria->offsetPage(items: [5 => 'a', 9 => 'b'], total: 480); + /** @And a page built over items keyed by their positions */ + $page = $criteria->page(total: 480, items: [5 => 'a', 9 => 'b']); /** @When rendering the page as a JSON:API response over the orders base URI */ $response = $page->toResponse(baseUri: '/v1/orders'); @@ -246,11 +242,13 @@ public function testToResponseWhenMiddlePageGivenThenRendersBodyAndLinkHeader(): public function testNavigationWhenMiddlePageGivenThenExposesEverySurroundingPage(): void { - /** @Given a pagination on a middle page */ - $pagination = OffsetPagination::fromPage(page: 3, perPage: 20); + /** @Given a criteria on a middle page with a page size of twenty */ + $criteria = Criteria::fromQuery( + request: Query::from(parameters: ['page' => ['number' => '3', 'size' => '20']]) + ); /** @When building the page from the total element count */ - $page = OffsetPage::from(items: ['a', 'b'], total: 480, criteria: $this->criteria, pagination: $pagination); + $page = $criteria->page(total: 480, items: ['a', 'b']); /** @Then the current page number is preserved */ self::assertSame(3, $page->currentPage()); @@ -261,18 +259,6 @@ public function testNavigationWhenMiddlePageGivenThenExposesEverySurroundingPage /** @And the offset is derived from the page and the page size */ self::assertSame(40, $page->offset()); - /** @And the page has a next page */ - self::assertTrue($page->hasNext()); - - /** @And the page has a previous page */ - self::assertTrue($page->hasPrevious()); - - /** @And the page is not the first page */ - self::assertFalse($page->isFirst()); - - /** @And the page is not the last page */ - self::assertFalse($page->isLast()); - /** @And the next pagination points at the fourth page */ self::assertSame(4, $page->next()?->page()); @@ -288,11 +274,13 @@ public function testNavigationWhenMiddlePageGivenThenExposesEverySurroundingPage public function testNavigationWhenMiddlePageGivenThenListsFirstPreviousNextAndLastTargets(): void { - /** @Given a pagination on a middle page of a multi-page result */ - $pagination = OffsetPagination::fromPage(page: 3, perPage: 20); + /** @Given a criteria on a middle page of a multi-page result */ + $criteria = Criteria::fromQuery( + request: Query::from(parameters: ['page' => ['number' => '3', 'size' => '20']]) + ); /** @And a page on that middle page */ - $page = OffsetPage::from(items: [], total: 480, criteria: $this->criteria, pagination: $pagination); + $page = $criteria->page(total: 480, items: []); /** @When reading the relations of the navigation targets */ $relations = $page->navigation()->targets() @@ -303,23 +291,22 @@ public function testNavigationWhenMiddlePageGivenThenListsFirstPreviousNextAndLa self::assertSame(['first', 'prev', 'next', 'last'], $relations); } - public function testNavigationWhenMiddlePageGivenThenTheNextTargetPointsAtTheFollowingPage(): void + public function testNavigationWhenMiddlePageGivenThenTheFirstTargetPointsAtTheFirstPage(): void { - /** @Given a pagination on a middle page of a multi-page result */ - $pagination = OffsetPagination::fromPage(page: 3, perPage: 20); + /** @Given a criteria on a middle page of a multi-page result */ + $criteria = Criteria::fromQuery( + request: Query::from(parameters: ['page' => ['number' => '3', 'size' => '20']]) + ); /** @And a page on that middle page */ - $page = OffsetPage::from(items: [], total: 480, criteria: $this->criteria, pagination: $pagination); + $page = $criteria->page(total: 480, items: []); /** @When reading the first navigation target */ $target = $page->navigation()->targets()->first(); /** @Then the first target is the first page reached through the first relation */ self::assertEquals( - NavigationTarget::to( - target: OffsetPagination::fromPage(page: 1, perPage: 20), - relation: LinkRelation::FIRST - ), + NavigationTarget::to(target: Pagination::fromPage(page: 1, perPage: 20), relation: LinkRelation::FIRST), $target ); } diff --git a/tests/Unit/OffsetPaginationTest.php b/tests/Unit/Offset/PaginationTest.php similarity index 84% rename from tests/Unit/OffsetPaginationTest.php rename to tests/Unit/Offset/PaginationTest.php index 91e8f3d..f7e9b8b 100644 --- a/tests/Unit/OffsetPaginationTest.php +++ b/tests/Unit/Offset/PaginationTest.php @@ -2,20 +2,20 @@ declare(strict_types=1); -namespace Test\TinyBlocks\HttpQuery\Unit; +namespace Test\TinyBlocks\HttpQuery\Unit\Offset; use PHPUnit\Framework\TestCase; use TinyBlocks\HttpQuery\Exceptions\OffsetOutOfRange; use TinyBlocks\HttpQuery\Exceptions\PageNumberOutOfRange; use TinyBlocks\HttpQuery\Exceptions\PageSizeOutOfRange; -use TinyBlocks\HttpQuery\OffsetPagination; +use TinyBlocks\HttpQuery\Offset\Pagination; -final class OffsetPaginationTest extends TestCase +final class PaginationTest extends TestCase { public function testFromOffsetWhenLimitIsOneThenLimitIsOne(): void { /** @When building a pagination from the minimum limit */ - $pagination = OffsetPagination::fromOffset(offset: 0, limit: 1); + $pagination = Pagination::fromOffset(limit: 1, offset: 0); /** @Then the limit equals the minimum limit */ self::assertSame(1, $pagination->limit()); @@ -24,7 +24,7 @@ public function testFromOffsetWhenLimitIsOneThenLimitIsOne(): void public function testFromPageWhenPerPageIsOneThenLimitIsOne(): void { /** @When building a pagination from the minimum page size */ - $pagination = OffsetPagination::fromPage(page: 1, perPage: 1); + $pagination = Pagination::fromPage(page: 1, perPage: 1); /** @Then the limit equals the minimum page size */ self::assertSame(1, $pagination->limit()); @@ -33,7 +33,7 @@ public function testFromPageWhenPerPageIsOneThenLimitIsOne(): void public function testFromOffsetWhenZeroOffsetGivenThenPageIsOne(): void { /** @When building a pagination from a zero offset */ - $pagination = OffsetPagination::fromOffset(offset: 0, limit: 20); + $pagination = Pagination::fromOffset(limit: 20, offset: 0); /** @Then the page number is one */ self::assertSame(1, $pagination->page()); @@ -48,7 +48,7 @@ public function testFromOffsetWhenZeroOffsetGivenThenPageIsOne(): void public function testFromPageWhenFirstPageGivenThenOffsetIsZero(): void { /** @When building a pagination from the first page */ - $pagination = OffsetPagination::fromPage(page: 1, perPage: 20); + $pagination = Pagination::fromPage(page: 1, perPage: 20); /** @Then the page number is one */ self::assertSame(1, $pagination->page()); @@ -63,7 +63,7 @@ public function testFromPageWhenFirstPageGivenThenOffsetIsZero(): void public function testFromPageWhenThirdPageGivenThenOffsetIsDerived(): void { /** @When building a pagination from the third page */ - $pagination = OffsetPagination::fromPage(page: 3, perPage: 20); + $pagination = Pagination::fromPage(page: 3, perPage: 20); /** @Then the page number is three */ self::assertSame(3, $pagination->page()); @@ -78,7 +78,7 @@ public function testFromPageWhenThirdPageGivenThenOffsetIsDerived(): void public function testFromOffsetWhenAlignedOffsetGivenThenPageIsDerived(): void { /** @When building a pagination from an offset aligned to the limit */ - $pagination = OffsetPagination::fromOffset(offset: 40, limit: 20); + $pagination = Pagination::fromOffset(limit: 20, offset: 40); /** @Then the page number is derived from the offset and the limit */ self::assertSame(3, $pagination->page()); @@ -93,7 +93,7 @@ public function testFromOffsetWhenAlignedOffsetGivenThenPageIsDerived(): void public function testFromOffsetWhenUnalignedOffsetGivenThenPageIsFloored(): void { /** @When building a pagination from an offset that is not aligned to the limit */ - $pagination = OffsetPagination::fromOffset(offset: 45, limit: 20); + $pagination = Pagination::fromOffset(limit: 20, offset: 45); /** @Then the page number floors the offset division and adds one */ self::assertSame(3, $pagination->page()); @@ -108,7 +108,7 @@ public function testFromOffsetWhenUnalignedOffsetGivenThenPageIsFloored(): void public function testToQueryStringWhenPageGivenThenRendersPageNumberAndSize(): void { /** @Given an offset pagination on the third page */ - $pagination = OffsetPagination::fromPage(page: 3, perPage: 20); + $pagination = Pagination::fromPage(page: 3, perPage: 20); /** @When rendering it as a query string */ $queryString = $pagination->toQueryString(); @@ -124,7 +124,7 @@ public function testFromPageWhenPageBelowOneGivenThenPageNumberOutOfRange(): voi $this->expectExceptionMessage('Page number'); /** @When building a pagination from a page number below one */ - OffsetPagination::fromPage(page: 0, perPage: 20); + Pagination::fromPage(page: 0, perPage: 20); } public function testFromOffsetWhenLimitBelowOneGivenThenPageSizeOutOfRange(): void @@ -134,7 +134,7 @@ public function testFromOffsetWhenLimitBelowOneGivenThenPageSizeOutOfRange(): vo $this->expectExceptionMessage('Page size'); /** @When building a pagination from a limit below one */ - OffsetPagination::fromOffset(offset: 0, limit: 0); + Pagination::fromOffset(limit: 0, offset: 0); } public function testFromOffsetWhenOffsetBelowZeroGivenThenOffsetOutOfRange(): void @@ -144,7 +144,7 @@ public function testFromOffsetWhenOffsetBelowZeroGivenThenOffsetOutOfRange(): vo $this->expectExceptionMessage('Offset'); /** @When building a pagination from an offset below zero */ - OffsetPagination::fromOffset(offset: -1, limit: 20); + Pagination::fromOffset(limit: 20, offset: -1); } public function testFromPageWhenPerPageBelowOneGivenThenPageSizeOutOfRange(): void @@ -154,6 +154,6 @@ public function testFromPageWhenPerPageBelowOneGivenThenPageSizeOutOfRange(): vo $this->expectExceptionMessage('Page size'); /** @When building a pagination from a page size below one */ - OffsetPagination::fromPage(page: 1, perPage: 0); + Pagination::fromPage(page: 1, perPage: 0); } } diff --git a/tests/Unit/OffsetSliceTest.php b/tests/Unit/Offset/SliceTest.php similarity index 60% rename from tests/Unit/OffsetSliceTest.php rename to tests/Unit/Offset/SliceTest.php index a648051..626b347 100644 --- a/tests/Unit/OffsetSliceTest.php +++ b/tests/Unit/Offset/SliceTest.php @@ -2,37 +2,37 @@ declare(strict_types=1); -namespace Test\TinyBlocks\HttpQuery\Unit; +namespace Test\TinyBlocks\HttpQuery\Unit\Offset; use PHPUnit\Framework\TestCase; use Test\TinyBlocks\HttpQuery\Models\Query; -use TinyBlocks\Collection\Collection; use TinyBlocks\Collection\KeyPreservation; use TinyBlocks\Http\LinkRelation; -use TinyBlocks\HttpQuery\Criteria; use TinyBlocks\HttpQuery\NavigationTarget; -use TinyBlocks\HttpQuery\OffsetPagination; -use TinyBlocks\HttpQuery\OffsetSlice; +use TinyBlocks\HttpQuery\Offset\Criteria; +use TinyBlocks\HttpQuery\Offset\Pagination; -final class OffsetSliceTest extends TestCase +final class SliceTest extends TestCase { - private Criteria $criteria; - - protected function setUp(): void + public function testOffsetWhenSecondPageGivenThenReturnsTheZeroBasedOffset(): void { - $this->criteria = Criteria::fromQuery(request: Query::from(parameters: [])); + /** @Given a criteria on the second page with a page size of three */ + $criteria = Criteria::fromQuery(request: Query::from(parameters: ['page' => ['number' => '2', 'size' => '3']])); + + /** @When building the slice from the items fetched for the page size plus one */ + $slice = $criteria->slice(items: ['a', 'b', 'c', 'd']); + + /** @Then the offset is derived from the page and the page size */ + self::assertSame(3, $slice->offset()); } public function testToResponseWhenSliceGivenThenRendersBodyAndLinkHeader(): void { - /** @Given query parameters on the second page with a page size of three */ - $query = Query::from(parameters: ['page' => ['number' => '2', 'size' => '3']]); - - /** @And the criteria parsed from those parameters */ - $criteria = Criteria::fromQuery(request: $query); + /** @Given a criteria on the second page with a page size of three */ + $criteria = Criteria::fromQuery(request: Query::from(parameters: ['page' => ['number' => '2', 'size' => '3']])); - /** @And a slice built from the criteria over items fetched for the page size plus one */ - $slice = $criteria->offsetSlice(items: ['a', 'b', 'c', 'd']); + /** @And a slice built from items fetched for the page size plus one */ + $slice = $criteria->slice(items: ['a', 'b', 'c', 'd']); /** @When rendering the slice as a JSON:API response over the orders base URI */ $response = $slice->toResponse(baseUri: '/v1/orders'); @@ -63,31 +63,13 @@ public function testToResponseWhenSliceGivenThenRendersBodyAndLinkHeader(): void ]), $response->getHeaderLine('Link')); } - public function testOffsetWhenSecondPageGivenThenReturnsTheZeroBasedOffset(): void - { - /** @Given a pagination on the second page with a page size of three */ - $pagination = OffsetPagination::fromPage(page: 2, perPage: 3); - - /** @And items fetched for the page size plus one */ - $items = Collection::createFrom(elements: ['a', 'b', 'c', 'd']); - - /** @When building the slice from the items and the pagination */ - $slice = OffsetSlice::from(items: $items, criteria: $this->criteria, pagination: $pagination); - - /** @Then the offset is derived from the page and the page size */ - self::assertSame(3, $slice->offset()); - } - public function testNavigationWhenExtraElementFetchedThenHasNextAndTrimsItems(): void { - /** @Given a pagination on the second page with a page size of three */ - $pagination = OffsetPagination::fromPage(page: 2, perPage: 3); - - /** @And items fetched for the page size plus one */ - $items = Collection::createFrom(elements: ['a', 'b', 'c', 'd']); + /** @Given a criteria on the second page with a page size of three */ + $criteria = Criteria::fromQuery(request: Query::from(parameters: ['page' => ['number' => '2', 'size' => '3']])); - /** @When building the slice from the items and the pagination */ - $slice = OffsetSlice::from(items: $items, criteria: $this->criteria, pagination: $pagination); + /** @When building the slice from the items fetched for the page size plus one */ + $slice = $criteria->slice(items: ['a', 'b', 'c', 'd']); /** @Then the slice reports a next page */ self::assertTrue($slice->hasNext()); @@ -121,14 +103,11 @@ public function testNavigationWhenExtraElementFetchedThenHasNextAndTrimsItems(): public function testNavigationWhenNoExtraElementOnFirstPageThenNoNextAndNoPrevious(): void { - /** @Given a pagination on the first page with a page size of three */ - $pagination = OffsetPagination::fromPage(page: 1, perPage: 3); + /** @Given a criteria on the first page with a page size of three */ + $criteria = Criteria::fromQuery(request: Query::from(parameters: ['page' => ['number' => '1', 'size' => '3']])); - /** @And items fetched within the page size */ - $items = Collection::createFrom(elements: ['a', 'b', 'c']); - - /** @When building the slice from the items and the pagination */ - $slice = OffsetSlice::from(items: $items, criteria: $this->criteria, pagination: $pagination); + /** @When building the slice from items fetched within the page size */ + $slice = $criteria->slice(items: ['a', 'b', 'c']); /** @Then the slice reports no next page */ self::assertFalse($slice->hasNext()); @@ -151,12 +130,11 @@ public function testNavigationWhenNoExtraElementOnFirstPageThenNoNextAndNoPrevio public function testNavigationWhenMiddlePageGivenThenListsFirstPreviousAndNextRelations(): void { - /** @Given a slice on a middle page fetched for the page size plus one */ - $slice = OffsetSlice::from( - items: Collection::createFrom(elements: ['a', 'b', 'c', 'd']), - criteria: $this->criteria, - pagination: OffsetPagination::fromPage(page: 2, perPage: 3) - ); + /** @Given a criteria on a middle page fetched for the page size plus one */ + $criteria = Criteria::fromQuery(request: Query::from(parameters: ['page' => ['number' => '2', 'size' => '3']])); + + /** @And a slice on that middle page */ + $slice = $criteria->slice(items: ['a', 'b', 'c', 'd']); /** @When reading the relations of the navigation targets */ $relations = $slice->navigation()->targets() @@ -169,56 +147,47 @@ public function testNavigationWhenMiddlePageGivenThenListsFirstPreviousAndNextRe public function testNavigationWhenMiddlePageGivenThenTheFirstTargetPointsAtTheFirstPage(): void { - /** @Given a slice on a middle page fetched for the page size plus one */ - $slice = OffsetSlice::from( - items: Collection::createFrom(elements: ['a', 'b', 'c', 'd']), - criteria: $this->criteria, - pagination: OffsetPagination::fromPage(page: 2, perPage: 3) - ); + /** @Given a criteria on a middle page fetched for the page size plus one */ + $criteria = Criteria::fromQuery(request: Query::from(parameters: ['page' => ['number' => '2', 'size' => '3']])); + + /** @And a slice on that middle page */ + $slice = $criteria->slice(items: ['a', 'b', 'c', 'd']); /** @When reading the first navigation target */ $target = $slice->navigation()->targets()->first(); /** @Then the first target is the first page reached through the first relation */ self::assertEquals( - NavigationTarget::to( - target: OffsetPagination::fromPage(page: 1, perPage: 3), - relation: LinkRelation::FIRST - ), + NavigationTarget::to(target: Pagination::fromPage(page: 1, perPage: 3), relation: LinkRelation::FIRST), $target ); } public function testNavigationWhenMiddlePageGivenThenTheNextTargetPointsAtTheFollowingPage(): void { - /** @Given a slice on a middle page fetched for the page size plus one */ - $slice = OffsetSlice::from( - items: Collection::createFrom(elements: ['a', 'b', 'c', 'd']), - criteria: $this->criteria, - pagination: OffsetPagination::fromPage(page: 2, perPage: 3) - ); + /** @Given a criteria on a middle page fetched for the page size plus one */ + $criteria = Criteria::fromQuery(request: Query::from(parameters: ['page' => ['number' => '2', 'size' => '3']])); + + /** @And a slice on that middle page */ + $slice = $criteria->slice(items: ['a', 'b', 'c', 'd']); /** @When reading the last navigation target */ $target = $slice->navigation()->targets()->last(); /** @Then the last target is the third page reached through the next relation */ self::assertEquals( - NavigationTarget::to( - target: OffsetPagination::fromPage(page: 3, perPage: 3), - relation: LinkRelation::NEXT - ), + NavigationTarget::to(target: Pagination::fromPage(page: 3, perPage: 3), relation: LinkRelation::NEXT), $target ); } public function testNavigationWhenFirstPageWithoutExtraElementThenListsOnlyTheFirstRelation(): void { - /** @Given a slice on the first page fetched within the page size */ - $slice = OffsetSlice::from( - items: Collection::createFrom(elements: ['a', 'b', 'c']), - criteria: $this->criteria, - pagination: OffsetPagination::fromPage(page: 1, perPage: 3) - ); + /** @Given a criteria on the first page fetched within the page size */ + $criteria = Criteria::fromQuery(request: Query::from(parameters: ['page' => ['number' => '1', 'size' => '3']])); + + /** @And a slice on that first page */ + $slice = $criteria->slice(items: ['a', 'b', 'c']); /** @When reading the relations of the navigation targets */ $relations = $slice->navigation()->targets() diff --git a/tests/Unit/RenderingTest.php b/tests/Unit/RenderingTest.php new file mode 100644 index 0000000..36ffc5a --- /dev/null +++ b/tests/Unit/RenderingTest.php @@ -0,0 +1,25 @@ +newInstanceWithoutConstructor(); + + /** @When invoking its otherwise-uncallable private constructor */ + new ReflectionMethod(Rendering::class, '__construct')->invoke($assembler); + + /** @Then the static-only response assembler is instantiated */ + self::assertInstanceOf(Rendering::class, $assembler); + } +} diff --git a/tests/Unit/SchemaTest.php b/tests/Unit/SchemaTest.php index e814575..c3006ab 100644 --- a/tests/Unit/SchemaTest.php +++ b/tests/Unit/SchemaTest.php @@ -10,45 +10,30 @@ final class SchemaTest extends TestCase { - public function testDefaultThenCarriesTheCanonicalMaxPerPage(): void + public function testCreateThenAppliesTheDefaultPageSize(): void { - /** @Given the default schema */ - $schema = Schema::default(); + /** @Given a schema created with an empty contract */ + $schema = Schema::create(); - /** @When reading the maximum page size */ - $actual = $schema->maxPerPage(); + /** @When asking for a page size with no requested value */ + $actual = $schema->pageSizeFor(requested: null); - /** @Then it is the canonical maximum page size */ - self::assertSame(100, $actual); + /** @Then it returns the canonical default page size */ + self::assertSame(20, $actual); } - public function testDefaultThenCarriesTheCanonicalDefaultPerPage(): void + public function testDefaultThenAppliesTheDefaultPageSize(): void { /** @Given the default schema */ $schema = Schema::default(); - /** @When reading the default page size */ - $actual = $schema->defaultPerPage(); + /** @When asking for a page size with no requested value */ + $actual = $schema->pageSizeFor(requested: null); - /** @Then it is the canonical default page size */ + /** @Then it returns the canonical default page size */ self::assertSame(20, $actual); } - public function testWithBoundsWhenBothAtMinimumThenSchemaCarriesThem(): void - { - /** @Given a schema with the default and maximum page sizes lowered to the minimum */ - $schema = Schema::default()->withDefaultPerPage(defaultPerPage: 1)->withMaxPerPage(maxPerPage: 1); - - /** @When reading the maximum page size */ - $actual = $schema->maxPerPage(); - - /** @Then it is the minimum page size */ - self::assertSame(1, $actual); - - /** @And the default page size is the minimum too */ - self::assertSame(1, $schema->defaultPerPage()); - } - public function testPageSizeForWhenAtMaximumThenReturnsTheMaximumSize(): void { /** @Given the default schema */ @@ -61,58 +46,68 @@ public function testPageSizeForWhenAtMaximumThenReturnsTheMaximumSize(): void self::assertSame(100, $actual); } - public function testPageSizeForWhenAboveMaximumThenThrowsPageSizeOutOfRange(): void + public function testPageSizeForWhenWithinMaximumThenReturnsTheRequestedSize(): void { /** @Given the default schema */ $schema = Schema::default(); - /** @Then an exception indicating the page size is out of range is raised */ - $this->expectException(PageSizeOutOfRange::class); - $this->expectExceptionMessage('Page size'); + /** @When asking for a page size within the maximum */ + $actual = $schema->pageSizeFor(requested: 50); - /** @When asking for a page size above the maximum */ - $schema->pageSizeFor(requested: 101); + /** @Then it returns the requested page size */ + self::assertSame(50, $actual); } - public function testPageSizeForWhenWithinMaximumThenReturnsTheRequestedSize(): void + public function testMaxPerPageWhenRaisedThenTheCopyAcceptsTheLargerSize(): void { /** @Given the default schema */ $schema = Schema::default(); - /** @When asking for a page size within the maximum */ - $actual = $schema->pageSizeFor(requested: 50); + /** @When raising the maximum page size and asking for the larger size */ + $actual = $schema->maxPerPage(maxPerPage: 250)->pageSizeFor(requested: 250); - /** @Then it returns the requested page size */ - self::assertSame(50, $actual); + /** @Then the larger size is accepted */ + self::assertSame(250, $actual); } - public function testWithMaxPerPageWhenBelowMinimumThenThrowsPageSizeOutOfRange(): void + public function testDefaultPerPageWhenLoweredThenTheCopyAppliesIt(): void { /** @Given the default schema */ $schema = Schema::default(); - /** @Then an exception indicating the page size is out of range is raised */ - $this->expectException(PageSizeOutOfRange::class); - $this->expectExceptionMessage('Page size <0> must be greater than or equal to 1.'); + /** @When lowering the default page size and asking with no requested value */ + $actual = $schema->defaultPerPage(defaultPerPage: 5)->pageSizeFor(requested: null); - /** @When lowering the maximum page size below the minimum */ - $schema->withMaxPerPage(maxPerPage: 0); + /** @Then the lowered default page size is applied */ + self::assertSame(5, $actual); + } + + public function testBoundsWhenBothAtMinimumThenAcceptsTheMinimumSize(): void + { + /** @Given a schema with the default and maximum page sizes lowered to the minimum */ + $schema = Schema::create()->defaultPerPage(defaultPerPage: 1)->maxPerPage(maxPerPage: 1); + + /** @When asking for a page size of one */ + $actual = $schema->pageSizeFor(requested: 1); + + /** @Then the minimum page size is accepted */ + self::assertSame(1, $actual); } - public function testWithDefaultPerPageWhenAboveMaximumThenThrowsPageSizeOutOfRange(): void + public function testPageSizeForWhenAboveMaximumThenThrowsPageSizeOutOfRange(): void { /** @Given the default schema */ $schema = Schema::default(); /** @Then an exception indicating the page size is out of range is raised */ $this->expectException(PageSizeOutOfRange::class); - $this->expectExceptionMessage('Page size <150> must be less than or equal to 100.'); + $this->expectExceptionMessage('Page size <101> must be less than or equal to 100.'); - /** @When raising the default page size above the maximum */ - $schema->withDefaultPerPage(defaultPerPage: 150); + /** @When asking for a page size above the maximum */ + $schema->pageSizeFor(requested: 101); } - public function testWithDefaultPerPageWhenBelowMinimumThenThrowsPageSizeOutOfRange(): void + public function testMaxPerPageWhenBelowMinimumThenThrowsPageSizeOutOfRange(): void { /** @Given the default schema */ $schema = Schema::default(); @@ -121,37 +116,33 @@ public function testWithDefaultPerPageWhenBelowMinimumThenThrowsPageSizeOutOfRan $this->expectException(PageSizeOutOfRange::class); $this->expectExceptionMessage('Page size <0> must be greater than or equal to 1.'); - /** @When lowering the default page size below the minimum */ - $schema->withDefaultPerPage(defaultPerPage: 0); + /** @When lowering the maximum page size below the minimum */ + $schema->maxPerPage(maxPerPage: 0); } - public function testWithMaxPerPageWhenReplacedThenCopyCarriesItAndOriginalIsUnchanged(): void + public function testDefaultPerPageWhenAboveMaximumThenThrowsPageSizeOutOfRange(): void { /** @Given the default schema */ $schema = Schema::default(); - /** @When replacing the maximum page size */ - $copy = $schema->withMaxPerPage(maxPerPage: 250); - - /** @Then the copy carries the new maximum page size */ - self::assertSame(250, $copy->maxPerPage()); + /** @Then an exception indicating the page size is out of range is raised */ + $this->expectException(PageSizeOutOfRange::class); + $this->expectExceptionMessage('Page size <150> must be less than or equal to 100.'); - /** @And the original schema keeps the canonical maximum page size */ - self::assertSame(100, $schema->maxPerPage()); + /** @When raising the default page size above the maximum */ + $schema->defaultPerPage(defaultPerPage: 150); } - public function testWithDefaultPerPageWhenReplacedThenCopyCarriesItAndOriginalIsUnchanged(): void + public function testDefaultPerPageWhenBelowMinimumThenThrowsPageSizeOutOfRange(): void { /** @Given the default schema */ $schema = Schema::default(); - /** @When replacing the default page size */ - $copy = $schema->withDefaultPerPage(defaultPerPage: 50); - - /** @Then the copy carries the new default page size */ - self::assertSame(50, $copy->defaultPerPage()); + /** @Then an exception indicating the page size is out of range is raised */ + $this->expectException(PageSizeOutOfRange::class); + $this->expectExceptionMessage('Page size <0> must be greater than or equal to 1.'); - /** @And the original schema keeps the canonical default page size */ - self::assertSame(20, $schema->defaultPerPage()); + /** @When lowering the default page size below the minimum */ + $schema->defaultPerPage(defaultPerPage: 0); } } diff --git a/tests/Unit/ValueKindTest.php b/tests/Unit/ValueKindTest.php new file mode 100644 index 0000000..25ed951 --- /dev/null +++ b/tests/Unit/ValueKindTest.php @@ -0,0 +1,61 @@ +matches(value: $value); + + /** @Then it reports that the value matches the kind */ + self::assertTrue($matches); + } + + #[DataProvider('mismatchingValues')] + public function testMatchesWhenValueBreaksTheKindThenIsFalse(ValueKind $kind, string $value): void + { + /** @Given a value kind and a value that breaks it */ + + /** @When testing the value against the kind */ + $matches = $kind->matches(value: $value); + + /** @Then it reports that the value does not match the kind */ + self::assertFalse($matches); + } + + public static function matchingValues(): array + { + return [ + 'Non-empty string' => ['kind' => ValueKind::STRING, 'value' => 'paid'], + 'Positive integer' => ['kind' => ValueKind::INTEGER, 'value' => '42'], + 'Negative integer' => ['kind' => ValueKind::INTEGER, 'value' => '-7'], + 'Date only' => ['kind' => ValueKind::DATETIME, 'value' => '2023-01-15'], + 'Date-time with zone' => ['kind' => ValueKind::DATETIME, 'value' => '2023-01-15T10:30:00Z'], + 'Date-time offset' => ['kind' => ValueKind::DATETIME, 'value' => '2023-01-15T10:30:00+01:00'], + 'Date-time fraction' => ['kind' => ValueKind::DATETIME, 'value' => '2023-01-15T10:30:00.123Z'] + ]; + } + + public static function mismatchingValues(): array + { + return [ + 'Empty string' => ['kind' => ValueKind::STRING, 'value' => ''], + 'Non-numeric integer' => ['kind' => ValueKind::INTEGER, 'value' => 'abc'], + 'Decimal integer' => ['kind' => ValueKind::INTEGER, 'value' => '4.2'], + 'Free-form date' => ['kind' => ValueKind::DATETIME, 'value' => 'not-a-date'], + 'Single-digit month' => ['kind' => ValueKind::DATETIME, 'value' => '2023-1-15'], + 'Truncated date-time' => ['kind' => ValueKind::DATETIME, 'value' => '2023-01-15T99'] + ]; + } +} From a9aec0c305c074a32e6128066a349c69cd240bb1 Mon Sep 17 00:00:00 2001 From: Gustavo Freze Date: Tue, 9 Jun 2026 00:26:08 -0300 Subject: [PATCH 05/14] chore: Remove the .idea directory from version control. --- .idea/.gitignore | 10 ---------- .idea/misc.xml | 6 ------ 2 files changed, 16 deletions(-) delete mode 100644 .idea/.gitignore delete mode 100644 .idea/misc.xml diff --git a/.idea/.gitignore b/.idea/.gitignore deleted file mode 100644 index 30cf57e..0000000 --- a/.idea/.gitignore +++ /dev/null @@ -1,10 +0,0 @@ -# Default ignored files -/shelf/ -/workspace.xml -# Editor-based HTTP Client requests -/httpRequests/ -# Ignored default folder with query files -/queries/ -# Datasource local storage ignored files -/dataSources/ -/dataSources.local.xml diff --git a/.idea/misc.xml b/.idea/misc.xml deleted file mode 100644 index 13515d1..0000000 --- a/.idea/misc.xml +++ /dev/null @@ -1,6 +0,0 @@ - - - - - \ No newline at end of file From fae7eb67e03ec0b387c42e1e2491dde975d3af3a Mon Sep 17 00:00:00 2001 From: Gustavo Freze Date: Tue, 9 Jun 2026 07:36:15 -0300 Subject: [PATCH 06/14] refactor: Seal static-only internal classes with private constructors. Conjunction, SortKeys, and Iso8601 expose only static methods, so a private constructor blocks instantiation. CursorCodec's encode closures also gain explicit parameter and return types to follow the same code-style rules. --- src/Internal/Conjunction.php | 4 ++++ src/Internal/Cursor/CursorCodec.php | 4 ++-- src/Internal/Cursor/SortKeys.php | 4 ++++ src/Internal/Iso8601.php | 4 ++++ 4 files changed, 14 insertions(+), 2 deletions(-) diff --git a/src/Internal/Conjunction.php b/src/Internal/Conjunction.php index 6abc308..0ab37e5 100644 --- a/src/Internal/Conjunction.php +++ b/src/Internal/Conjunction.php @@ -12,6 +12,10 @@ final class Conjunction { + private function __construct() + { + } + public static function from(Filter $filter, string $expression): array { if ($filter instanceof Group) { diff --git a/src/Internal/Cursor/CursorCodec.php b/src/Internal/Cursor/CursorCodec.php index d04ecc5..2f2bf9b 100644 --- a/src/Internal/Cursor/CursorCodec.php +++ b/src/Internal/Cursor/CursorCodec.php @@ -35,7 +35,7 @@ public static function encode(array $keys): string return $payload |> base64_encode(...) - |> (fn($x) => strtr($x, '+/', '-_')) - |> (fn($x) => rtrim($x, '=')); + |> (static fn(string $encoded): string => strtr($encoded, '+/', '-_')) + |> (static fn(string $encoded): string => rtrim($encoded, '=')); } } diff --git a/src/Internal/Cursor/SortKeys.php b/src/Internal/Cursor/SortKeys.php index 51a91d3..8513a05 100644 --- a/src/Internal/Cursor/SortKeys.php +++ b/src/Internal/Cursor/SortKeys.php @@ -10,6 +10,10 @@ final class SortKeys { + private function __construct() + { + } + public static function from(Sort $sort): Closure { $orders = $sort->orders(); diff --git a/src/Internal/Iso8601.php b/src/Internal/Iso8601.php index 75ed31f..1203a13 100644 --- a/src/Internal/Iso8601.php +++ b/src/Internal/Iso8601.php @@ -6,6 +6,10 @@ final class Iso8601 { + private function __construct() + { + } + public static function isValid(string $value): bool { $pattern = '/^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?)?$/'; From 866a8679dd26281e75163b0160c03e891b39ad69 Mon Sep 17 00:00:00 2001 From: Gustavo Freze Date: Tue, 9 Jun 2026 07:36:21 -0300 Subject: [PATCH 07/14] test: Cover RSQL parsing edge cases and static-only constructors. Add filter tests for escaped quotes and backslashes and for parenthesized comparison and AND groups, with new malformed-expression cases. Cover the private constructors of the static-only Conjunction, SortKeys, Iso8601, and Renderer classes through reflection, and reorder the named arguments in the cursor tests to match the code-style rule. --- tests/Unit/Cursor/KeysetTest.php | 19 +++++++- tests/Unit/Cursor/PageTest.php | 20 ++++----- tests/Unit/Cursor/PaginationTest.php | 12 ++--- tests/Unit/FilterTest.php | 66 +++++++++++++++++++++++++++- tests/Unit/LinksTest.php | 13 ++++++ tests/Unit/SchemaTest.php | 15 +++++++ tests/Unit/ValueKindTest.php | 15 +++++++ 7 files changed, 140 insertions(+), 20 deletions(-) diff --git a/tests/Unit/Cursor/KeysetTest.php b/tests/Unit/Cursor/KeysetTest.php index cabd19c..0c319a1 100644 --- a/tests/Unit/Cursor/KeysetTest.php +++ b/tests/Unit/Cursor/KeysetTest.php @@ -5,12 +5,15 @@ namespace Test\TinyBlocks\HttpQuery\Unit\Cursor; use PHPUnit\Framework\TestCase; +use ReflectionClass; +use ReflectionMethod; use Test\TinyBlocks\HttpQuery\Models\Query; use TinyBlocks\HttpQuery\Cursor\Criteria; use TinyBlocks\HttpQuery\Cursor\Pagination; use TinyBlocks\HttpQuery\Cursor\Token; use TinyBlocks\HttpQuery\Direction; use TinyBlocks\HttpQuery\Exceptions\CursorIsInvalid; +use TinyBlocks\HttpQuery\Internal\Cursor\SortKeys; use TinyBlocks\HttpQuery\Order; use TinyBlocks\HttpQuery\Schema; @@ -66,7 +69,7 @@ public function testPageWhenKeysOfGivenThenUsesTheExtractor(): void self::assertSame([10, 20], $page->items()->toArray()); /** @And the next pagination anchors on the keys extracted from the last retained element */ - self::assertEquals(Pagination::from(perPage: 2, cursor: Token::fromKeys(keys: [20])), $page->next()); + self::assertEquals(Pagination::from(cursor: Token::fromKeys(keys: [20]), perPage: 2), $page->next()); } public function testPageWhenNoKeysOfGivenThenDerivesKeysFromTheSortFields(): void @@ -84,7 +87,7 @@ public function testPageWhenNoKeysOfGivenThenDerivesKeysFromTheSortFields(): voi self::assertSame([['id' => 10], ['id' => 20]], $page->items()->toArray()); /** @And the next pagination anchors on the sort-field keys of the last retained row */ - self::assertEquals(Pagination::from(perPage: 2, cursor: Token::fromKeys(keys: [20])), $page->next()); + self::assertEquals(Pagination::from(cursor: Token::fromKeys(keys: [20]), perPage: 2), $page->next()); } public function testCursorWhenNoIncomingCursorThenEverySortFieldIsNull(): void @@ -141,4 +144,16 @@ public function testCursorWhenDecodedCountMismatchesThenThrowsCursorIsInvalid(): /** @When reading the incoming cursor key values */ $keyset->cursor(); } + + public function testConstructorWhenInvokedThroughReflectionThenInstantiatesTheStaticOnlySortKeys(): void + { + /** @Given an uninitialized instance of the static-only sort-key extractor */ + $extractor = new ReflectionClass(SortKeys::class)->newInstanceWithoutConstructor(); + + /** @When invoking its otherwise-uncallable private constructor */ + new ReflectionMethod(SortKeys::class, '__construct')->invoke($extractor); + + /** @Then the static-only sort-key extractor is instantiated */ + self::assertInstanceOf(SortKeys::class, $extractor); + } } diff --git a/tests/Unit/Cursor/PageTest.php b/tests/Unit/Cursor/PageTest.php index eb894cd..bddd1ea 100644 --- a/tests/Unit/Cursor/PageTest.php +++ b/tests/Unit/Cursor/PageTest.php @@ -29,7 +29,7 @@ protected function setUp(): void public function testNavigationWhenNoExtraElementThenHasNoNextPage(): void { /** @Given a keyset pagination with an absent incoming cursor and a page size of two */ - $pagination = Pagination::from(perPage: 2, cursor: Token::none()); + $pagination = Pagination::from(cursor: Token::none(), perPage: 2); /** @And a cursor page built from items fetched within the page size */ $page = Page::from( @@ -64,7 +64,7 @@ public function testToResponseWhenCursorPageGivenThenRendersBodyAndLinkHeader(): filter: $this->filter, items: [10, 20, 30], keysOf: static fn(int $element): array => [$element], - pagination: Pagination::from(perPage: 2, cursor: Token::from(token: $token)) + pagination: Pagination::from(cursor: Token::from(token: $token), perPage: 2) ); /** @When rendering the cursor page as a JSON:API response over the orders base URI */ @@ -98,7 +98,7 @@ public function testToResponseWhenFirstCursorPageThenSelfLinkIsCursorStyle(): vo filter: $this->filter, items: [10, 20, 30], keysOf: static fn(int $element): array => [$element], - pagination: Pagination::from(perPage: 2, cursor: Token::none()) + pagination: Pagination::from(cursor: Token::none(), perPage: 2) ); /** @When rendering the first cursor page as a JSON:API response over the orders base URI */ @@ -126,7 +126,7 @@ public function testNavigationWhenExtraElementFetchedThenListsOnlyTheNextTarget( filter: $this->filter, items: [10, 20, 30], keysOf: static fn(int $element): array => [$element], - pagination: Pagination::from(perPage: 2, cursor: Token::none()) + pagination: Pagination::from(cursor: Token::none(), perPage: 2) ); /** @When reading the navigation targets */ @@ -138,7 +138,7 @@ public function testNavigationWhenExtraElementFetchedThenListsOnlyTheNextTarget( /** @And the only target is the next target anchored on the forward cursor */ self::assertEquals( NavigationTarget::to( - target: Pagination::from(perPage: 2, cursor: Token::fromKeys(keys: [20])), + target: Pagination::from(cursor: Token::fromKeys(keys: [20]), perPage: 2), relation: LinkRelation::NEXT ), $targets->first() @@ -153,7 +153,7 @@ public function testMapWhenTransformationGivenThenProjectsItemsAndPreservesTheCu filter: $this->filter, items: [10, 20, 30], keysOf: static fn(int $element): array => [$element], - pagination: Pagination::from(perPage: 2, cursor: Token::none()) + pagination: Pagination::from(cursor: Token::none(), perPage: 2) ); /** @When mapping the items through a projection */ @@ -166,7 +166,7 @@ public function testMapWhenTransformationGivenThenProjectsItemsAndPreservesTheCu self::assertTrue($mapped->hasNext()); /** @And the next pagination still anchors on the source keys */ - self::assertEquals(Pagination::from(perPage: 2, cursor: Token::fromKeys(keys: [20])), $mapped->next()); + self::assertEquals(Pagination::from(cursor: Token::fromKeys(keys: [20]), perPage: 2), $mapped->next()); /** @And the metadata is preserved in length-ascending key order */ self::assertSame(['has_next' => true, 'per_page' => 2], $mapped->metadata()); @@ -183,7 +183,7 @@ public function testToResponseWhenPageIsMappedThenRendersProjectedDataAndPreserv filter: $this->filter, items: [['id' => 10], ['id' => 20], ['id' => 30]], keysOf: static fn(array $row): array => [$row['id']], - pagination: Pagination::from(perPage: 2, cursor: Token::from(token: $token)) + pagination: Pagination::from(cursor: Token::from(token: $token), perPage: 2) )->map(transformation: static fn(array $row): int => (int)$row['id']); /** @When rendering the mapped cursor page as a JSON:API response over the orders base URI */ @@ -206,7 +206,7 @@ public function testToResponseWhenPageIsMappedThenRendersProjectedDataAndPreserv public function testNavigationWhenExtraElementFetchedThenHasNextAndNextCursorAnchorsLastItem(): void { /** @Given a keyset pagination with an absent incoming cursor and a page size of two */ - $pagination = Pagination::from(perPage: 2, cursor: Token::none()); + $pagination = Pagination::from(cursor: Token::none(), perPage: 2); /** @And a cursor page built over items fetched for the page size plus one */ $page = Page::from( @@ -224,7 +224,7 @@ public function testNavigationWhenExtraElementFetchedThenHasNextAndNextCursorAnc self::assertSame([10, 20], $page->items()->toArray()); /** @And the next pagination anchors on the last retained element with the page size */ - self::assertEquals(Pagination::from(perPage: 2, cursor: Token::fromKeys(keys: [20])), $page->next()); + self::assertEquals(Pagination::from(cursor: Token::fromKeys(keys: [20]), perPage: 2), $page->next()); /** @And the metadata carries the navigation flags in length-ascending key order */ self::assertSame(['has_next' => true, 'per_page' => 2], $page->metadata()); diff --git a/tests/Unit/Cursor/PaginationTest.php b/tests/Unit/Cursor/PaginationTest.php index fea673a..66d8208 100644 --- a/tests/Unit/Cursor/PaginationTest.php +++ b/tests/Unit/Cursor/PaginationTest.php @@ -14,7 +14,7 @@ final class PaginationTest extends TestCase public function testFromWhenPageSizeIsTheMinimumThenCarriesThatLimit(): void { /** @Given a cursor pagination built from an absent cursor and the minimum page size of 1 */ - $pagination = Pagination::from(perPage: 1, cursor: Token::none()); + $pagination = Pagination::from(cursor: Token::none(), perPage: 1); /** @When reading the page size limit */ $limit = $pagination->limit(); @@ -26,7 +26,7 @@ public function testFromWhenPageSizeIsTheMinimumThenCarriesThatLimit(): void public function testToQueryStringWhenCursorAbsentThenRendersOnlyTheSize(): void { /** @Given a cursor pagination carrying an absent cursor and a page size */ - $pagination = Pagination::from(perPage: 10, cursor: Token::none()); + $pagination = Pagination::from(cursor: Token::none(), perPage: 10); /** @When rendering it as a query string */ $queryString = $pagination->toQueryString(); @@ -38,7 +38,7 @@ public function testToQueryStringWhenCursorAbsentThenRendersOnlyTheSize(): void public function testFromWhenAbsentCursorGivenThenCarriesLimitAndAbsentCursor(): void { /** @Given a cursor pagination built from an absent cursor and a page size of 20 */ - $pagination = Pagination::from(perPage: 20, cursor: Token::none()); + $pagination = Pagination::from(cursor: Token::none(), perPage: 20); /** @When reading the page size limit */ $limit = $pagination->limit(); @@ -59,13 +59,13 @@ public function testFromWhenPageSizeBelowMinimumThenThrowsPageSizeOutOfRange(): $this->expectException(PageSizeOutOfRange::class); /** @When building a cursor pagination with a page size below the minimum */ - Pagination::from(perPage: 0, cursor: $cursor); + Pagination::from(cursor: $cursor, perPage: 0); } public function testToQueryStringWhenCursorPresentThenRendersCursorAndSize(): void { /** @Given a cursor pagination carrying an incoming cursor and a page size */ - $pagination = Pagination::from(perPage: 10, cursor: Token::from(token: 'abc')); + $pagination = Pagination::from(cursor: Token::from(token: 'abc'), perPage: 10); /** @When rendering it as a query string */ $queryString = $pagination->toQueryString(); @@ -77,7 +77,7 @@ public function testToQueryStringWhenCursorPresentThenRendersCursorAndSize(): vo public function testFromWhenIncomingCursorGivenThenCarriesLimitAndTheCursorToken(): void { /** @Given a cursor pagination built from an incoming cursor and a page size of 50 */ - $pagination = Pagination::from(perPage: 50, cursor: Token::from(token: 'abc')); + $pagination = Pagination::from(cursor: Token::from(token: 'abc'), perPage: 50); /** @When reading the page size limit */ $limit = $pagination->limit(); diff --git a/tests/Unit/FilterTest.php b/tests/Unit/FilterTest.php index b425a72..e81582f 100644 --- a/tests/Unit/FilterTest.php +++ b/tests/Unit/FilterTest.php @@ -135,6 +135,66 @@ public function testFromQueryWhenSingleQuotedValueThenComparisonStripsQuotes(): ); } + public function testFromQueryWhenEscapedQuoteInValueThenComparisonKeepsTheQuote(): void + { + /** @Given a query whose double-quoted value carries an escaped double quote */ + $query = Query::from(parameters: ['filter' => 'name=="a\\"b"']); + + /** @When reading the validated comparisons */ + $comparisons = Criteria::fromQuery(request: $query, schema: $this->schema)->comparisons(); + + /** @Then the comparison carries the value with the escaped quote unescaped */ + self::assertEquals( + [Comparison::of(field: 'name', values: ['a"b'], operator: Operator::EQUAL)], + $comparisons + ); + } + + public function testFromQueryWhenEscapedBackslashInValueThenComparisonKeepsTheBackslash(): void + { + /** @Given a query whose double-quoted value carries an escaped backslash */ + $query = Query::from(parameters: ['filter' => 'name=="a\\\\b"']); + + /** @When reading the validated comparisons */ + $comparisons = Criteria::fromQuery(request: $query, schema: $this->schema)->comparisons(); + + /** @Then the comparison carries the value with the escaped backslash unescaped */ + self::assertEquals( + [Comparison::of(field: 'name', values: ['a\\b'], operator: Operator::EQUAL)], + $comparisons + ); + } + + public function testFromQueryWhenParenthesizedComparisonThenComparisonIsReturned(): void + { + /** @Given a query wrapping a single comparison in parentheses */ + $query = Query::from(parameters: ['filter' => '(status==paid)']); + + /** @When reading the validated comparisons */ + $comparisons = Criteria::fromQuery(request: $query, schema: $this->schema)->comparisons(); + + /** @Then the only comparison is the unwrapped equality */ + self::assertEquals( + [Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL)], + $comparisons + ); + } + + public function testFromQueryWhenParenthesizedAndGroupThenComparisonsCarryEveryLeaf(): void + { + /** @Given a query wrapping an AND expression of two comparisons in parentheses */ + $query = Query::from(parameters: ['filter' => '(a==1;b==2)']); + + /** @When reading the validated comparisons */ + $comparisons = Criteria::fromQuery(request: $query, schema: $this->schema)->comparisons(); + + /** @Then the comparisons carry both leaves in order */ + self::assertEquals([ + Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), + Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) + ], $comparisons); + } + public function testFromQueryWhenDateTimeValueMatchesKindThenComparisonIsReturned(): void { /** @Given a schema allowing a date-time field under the greater-than operator */ @@ -334,12 +394,14 @@ public static function malformedExpressionCases(): array return [ 'No operator' => ['expression' => 'status'], 'Empty value' => ['expression' => 'status=='], + 'Backslash at the end' => ['expression' => 'name=="a\\'], 'Unclosed group' => ['expression' => '(status==paid'], 'Trailing semicolon' => ['expression' => 'status==paid;'], 'Unknown operator' => ['expression' => 'status=zz=paid'], - 'Group missing close mark' => ['expression' => '(a==1 '], + 'Whitespace after value' => ['expression' => 'a==b c'], 'Trailing close mark' => ['expression' => 'a==1)'], - 'Unclosed quoted value' => ['expression' => 'name=="x'] + 'Unclosed quoted value' => ['expression' => 'name=="x'], + 'Group missing close mark' => ['expression' => '(a==1 '] ]; } } diff --git a/tests/Unit/LinksTest.php b/tests/Unit/LinksTest.php index 8a145ef..7af9fe9 100644 --- a/tests/Unit/LinksTest.php +++ b/tests/Unit/LinksTest.php @@ -10,6 +10,7 @@ use Test\TinyBlocks\HttpQuery\Models\Query; use TinyBlocks\HttpQuery\Comparison; use TinyBlocks\HttpQuery\Group; +use TinyBlocks\HttpQuery\Internal\Rsql\Renderer; use TinyBlocks\HttpQuery\Internal\Uri; use TinyBlocks\HttpQuery\Links; use TinyBlocks\HttpQuery\LogicalOperator; @@ -359,4 +360,16 @@ public function testConstructorWhenInvokedThroughReflectionThenInstantiatesTheSt /** @Then the static-only URI assembler is instantiated */ self::assertInstanceOf(Uri::class, $uri); } + + public function testConstructorWhenInvokedThroughReflectionThenInstantiatesTheStaticOnlyRenderer(): void + { + /** @Given an uninitialized instance of the static-only RSQL renderer */ + $renderer = new ReflectionClass(Renderer::class)->newInstanceWithoutConstructor(); + + /** @When invoking its otherwise-uncallable private constructor */ + new ReflectionMethod(Renderer::class, '__construct')->invoke($renderer); + + /** @Then the static-only RSQL renderer is instantiated */ + self::assertInstanceOf(Renderer::class, $renderer); + } } diff --git a/tests/Unit/SchemaTest.php b/tests/Unit/SchemaTest.php index c3006ab..bbd5533 100644 --- a/tests/Unit/SchemaTest.php +++ b/tests/Unit/SchemaTest.php @@ -5,7 +5,10 @@ namespace Test\TinyBlocks\HttpQuery\Unit; use PHPUnit\Framework\TestCase; +use ReflectionClass; +use ReflectionMethod; use TinyBlocks\HttpQuery\Exceptions\PageSizeOutOfRange; +use TinyBlocks\HttpQuery\Internal\Conjunction; use TinyBlocks\HttpQuery\Schema; final class SchemaTest extends TestCase @@ -145,4 +148,16 @@ public function testDefaultPerPageWhenBelowMinimumThenThrowsPageSizeOutOfRange() /** @When lowering the default page size below the minimum */ $schema->defaultPerPage(defaultPerPage: 0); } + + public function testConstructorWhenInvokedThroughReflectionThenInstantiatesTheStaticOnlyConjunction(): void + { + /** @Given an uninitialized instance of the static-only conjunction flattener */ + $flattener = new ReflectionClass(Conjunction::class)->newInstanceWithoutConstructor(); + + /** @When invoking its otherwise-uncallable private constructor */ + new ReflectionMethod(Conjunction::class, '__construct')->invoke($flattener); + + /** @Then the static-only conjunction flattener is instantiated */ + self::assertInstanceOf(Conjunction::class, $flattener); + } } diff --git a/tests/Unit/ValueKindTest.php b/tests/Unit/ValueKindTest.php index 25ed951..eb30578 100644 --- a/tests/Unit/ValueKindTest.php +++ b/tests/Unit/ValueKindTest.php @@ -6,6 +6,9 @@ use PHPUnit\Framework\Attributes\DataProvider; use PHPUnit\Framework\TestCase; +use ReflectionClass; +use ReflectionMethod; +use TinyBlocks\HttpQuery\Internal\Iso8601; use TinyBlocks\HttpQuery\ValueKind; final class ValueKindTest extends TestCase @@ -34,6 +37,18 @@ public function testMatchesWhenValueBreaksTheKindThenIsFalse(ValueKind $kind, st self::assertFalse($matches); } + public function testConstructorWhenInvokedThroughReflectionThenInstantiatesTheStaticOnlyValidator(): void + { + /** @Given an uninitialized instance of the static-only ISO-8601 validator */ + $validator = new ReflectionClass(Iso8601::class)->newInstanceWithoutConstructor(); + + /** @When invoking its otherwise-uncallable private constructor */ + new ReflectionMethod(Iso8601::class, '__construct')->invoke($validator); + + /** @Then the static-only ISO-8601 validator is instantiated */ + self::assertInstanceOf(Iso8601::class, $validator); + } + public static function matchingValues(): array { return [ From 348b8894928a5c9ad0092d7feb9bac76a16e3a41 Mon Sep 17 00:00:00 2001 From: Gustavo Freze Date: Tue, 9 Jun 2026 07:36:27 -0300 Subject: [PATCH 08/14] docs: Clarify the schema vocabulary and expand the rendering examples. Align the README, package description, and exception docblocks on the "schema" terminology, expand the rendering section with the cursor response shape, and replace the prose em-dashes with the punctuation the style rules require. --- README.md | 40 ++++++++++++++++----- composer.json | 2 +- src/Exceptions/FilterFieldNotAllowed.php | 8 ++--- src/Exceptions/FilterOperatorNotAllowed.php | 4 +-- src/Exceptions/FilterShapeNotSupported.php | 2 +- src/Exceptions/SortFieldNotAllowed.php | 8 ++--- 6 files changed, 44 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 78d03c0..eca4078 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ ## Overview -A typed, framework- and database-agnostic toolkit for the query of an HTTP collection endpoint. The endpoint declares +A typed, framework-independent toolkit for querying an HTTP collection endpoint. The endpoint declares the query contract once on a `Schema`, the library parses an incoming request query string against it, and the consumer reads an already-validated result: a conjunction of comparisons for filtering, an effective sort, and a pagination view. The result renders as a JSON:API response carrying an RFC 8288 `Link` header and a body `links` object. @@ -289,7 +289,11 @@ $criteria = Criteria::fromQuery(request: $request, schema: $schema); $response = $criteria->page(total: 480, items: $items)->toResponse(baseUri: '/v1/orders'); ``` -The body carries the navigation with the filter and the sort preserved in every URI. +The body carries the data, the meta, and the links, with the filter and the sort preserved in every URI. The two +approaches return different shapes, shown below. + +An **offset** page exposes the full window (`total`, `total_pages`, `current_page`, `has_previous`) and a link for +every relation: ```json { @@ -312,8 +316,6 @@ The body carries the navigation with the filter and the sort preserved in every } ``` -The header folds the same relations into one RFC 8288 `Link` line. - ```text Link: ; rel="self", ; rel="first", @@ -322,9 +324,31 @@ Link: ; rel="last" ``` +A **cursor** page is forward-only: `meta` carries only `has_next` and `per_page`, and `links` only `self` and `next`. +For `GET /v1/orders?filter=status==paid&sort=-created_at,id&page[cursor]=BS3RvKY4LqEjYD19mQ0mCpJ&page[size]=20`: + +```json +{ + "data": [], + "meta": { + "has_next": true, + "per_page": 20 + }, + "links": { + "self": "/v1/orders?filter=status==paid&sort=-created_at,id&page[cursor]=BS3RvKY4LqEjYD19mQ0mCpJ&page[size]=20", + "next": "/v1/orders?filter=status==paid&sort=-created_at,id&page[cursor]=Pj9rZ0sB2xN7wK1dQmvY4La&page[size]=20" + } +} +``` + +```text +Link: ; rel="self", + ; rel="next" +``` + The `links` keys are the canonical JSON:API relations, in the semantic order below. Unavailable relations are omitted, -so the first page carries no `prev` and the last page carries no `next`. An `Offset\Slice` exposes `self`, `first`, -`prev`, and `next` (no `last`), and a `Cursor\Page` is forward-only, so it exposes only `self` and `next`. +so the first offset page carries no `prev` and the last carries no `next`, and an `Offset\Slice` omits `last` (it has +no total). | Relation | Meaning | |----------|--------------------| @@ -354,8 +378,8 @@ fails at the boundary with a dedicated `HttpQueryException`, never reaching the RSQL is a small, URI-safe grammar with a published reference, so the filter survives a query string without encoding and the same expression reads the same on the client and the server. The library is conjunction-only for the consumer: a -single comparison or an AND group of comparisons flattens into the `list` the consumer applies, -`AND` an `OR` or nested filter is rejected at parse. +single comparison or an AND group of comparisons flattens into the `list` the consumer applies. An OR +group, or a group nested inside another group, is rejected as an unsupported shape. > Zdenek Jirutka, *RSQL / FIQL parser* (https://github.com/jirutka/rsql-parser). diff --git a/composer.json b/composer.json index 6fa5abe..5f06ebe 100644 --- a/composer.json +++ b/composer.json @@ -1,6 +1,6 @@ { "name": "tiny-blocks/http-query", - "description": "Typed, framework and database-agnostic toolkit for HTTP collection queries with RSQL filtering, sorting, and offset and cursor pagination.", + "description": "Typed, framework-independent toolkit for HTTP collection queries (RSQL filtering, sorting, and offset and cursor pagination) that never touches a data store.", "license": "MIT", "type": "library", "keywords": [ diff --git a/src/Exceptions/FilterFieldNotAllowed.php b/src/Exceptions/FilterFieldNotAllowed.php index e3de168..2ee2659 100644 --- a/src/Exceptions/FilterFieldNotAllowed.php +++ b/src/Exceptions/FilterFieldNotAllowed.php @@ -7,10 +7,10 @@ use InvalidArgumentException; /** - * Raised when an incoming filter targets a field not declared through the filter rules. + * Raised when an incoming filter targets a field not declared filterable on the schema. * - * The consumer declares the filterable fields through the filter rules. A comparison whose field - * was never allowed cannot be applied to the store and is rejected. + * The consumer declares the filterable fields on the schema. A comparison whose field was never + * allowed cannot be applied to the store and is rejected. */ final class FilterFieldNotAllowed extends InvalidArgumentException implements HttpQueryException { @@ -26,7 +26,7 @@ private function __construct(string $field) /** * Creates a FilterFieldNotAllowed from the disallowed field. * - * @param string $field The field that was never declared through the filter rules. + * @param string $field The field the schema did not declare filterable. * @return FilterFieldNotAllowed The composed exception describing the disallowed field. */ public static function from(string $field): FilterFieldNotAllowed diff --git a/src/Exceptions/FilterOperatorNotAllowed.php b/src/Exceptions/FilterOperatorNotAllowed.php index f914627..0132597 100644 --- a/src/Exceptions/FilterOperatorNotAllowed.php +++ b/src/Exceptions/FilterOperatorNotAllowed.php @@ -10,8 +10,8 @@ /** * Raised when an incoming filter uses an operator not declared for the field. * - * The consumer declares the operators each field accepts through the filter rules. A comparison - * whose operator falls outside that set is rejected. + * The consumer declares the operators each field accepts on the schema. A comparison whose + * operator falls outside that set is rejected. */ final class FilterOperatorNotAllowed extends InvalidArgumentException implements HttpQueryException { diff --git a/src/Exceptions/FilterShapeNotSupported.php b/src/Exceptions/FilterShapeNotSupported.php index 267bd7d..41947ab 100644 --- a/src/Exceptions/FilterShapeNotSupported.php +++ b/src/Exceptions/FilterShapeNotSupported.php @@ -9,7 +9,7 @@ /** * Raised when an incoming filter is not a comparison or a flat AND group of comparisons. * - * The filter rules validate a conjunction of comparisons. An OR group, or a group nested inside + * The supported shape is a conjunction of comparisons. An OR group, or a group nested inside * another group, cannot be flattened into that shape and is rejected. */ final class FilterShapeNotSupported extends InvalidArgumentException implements HttpQueryException diff --git a/src/Exceptions/SortFieldNotAllowed.php b/src/Exceptions/SortFieldNotAllowed.php index 1f4396a..4531b08 100644 --- a/src/Exceptions/SortFieldNotAllowed.php +++ b/src/Exceptions/SortFieldNotAllowed.php @@ -7,10 +7,10 @@ use InvalidArgumentException; /** - * Raised when an incoming sort orders by a field not declared through the sort rules. + * Raised when an incoming sort orders by a field not declared sortable on the schema. * - * The consumer declares the sortable fields through the sort rules. A fixed rule allows none, so - * any client-provided sort is rejected. An order by an undeclared field is likewise rejected. + * The consumer declares the sortable fields on the schema. When the schema declares none, any + * client-provided sort is rejected, and an order by an undeclared field is likewise rejected. */ final class SortFieldNotAllowed extends InvalidArgumentException implements HttpQueryException { @@ -26,7 +26,7 @@ private function __construct(string $field) /** * Creates a SortFieldNotAllowed from the disallowed field. * - * @param string $field The field that was never declared through the sort rules. + * @param string $field The field the schema did not declare sortable. * @return SortFieldNotAllowed The composed exception describing the disallowed field. */ public static function from(string $field): SortFieldNotAllowed From b2fbf42ca5c271a19d8bbc27e36865e35225be36 Mon Sep 17 00:00:00 2001 From: Gustavo Freze Date: Tue, 9 Jun 2026 09:23:42 -0300 Subject: [PATCH 09/14] feat: Guard the query toolkit against malicious input. - Reject cursor tokens that do not decode to a flat list of scalars. - Bound RSQL filter parenthesis nesting at a maximum depth. - Percent-encode unsafe characters in rendered link URLs. --- README.md | 46 ++++++++++++++++++++++---- src/Cursor/Page.php | 4 +-- src/Internal/Cursor/CursorCodec.php | 10 ++++-- src/Internal/Rsql/FilterParser.php | 24 +++++++++----- src/Internal/Uri.php | 16 +++++++-- src/Offset/Page.php | 2 +- src/Offset/Slice.php | 2 +- tests/Unit/Cursor/PageTest.php | 18 +++++----- tests/Unit/Cursor/TokenTest.php | 26 +++++++++++++++ tests/Unit/EndToEndTest.php | 6 ++-- tests/Unit/FilterTest.php | 38 +++++++++++++++++++++ tests/Unit/LinksTest.php | 51 +++++++++++++++++++++++++---- tests/Unit/Offset/PageTest.php | 6 ++-- tests/Unit/Offset/SliceTest.php | 4 +-- 14 files changed, 207 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index eca4078..b2f5f0e 100644 --- a/README.md +++ b/README.md @@ -297,13 +297,26 @@ every relation: ```json { - "data": [], + "data": [ + { + "id": 4821, + "status": "paid", + "total": 12990, + "created_at": "2026-01-29T14:05:00Z" + }, + { + "id": 4820, + "status": "paid", + "total": 8400, + "created_at": "2026-01-29T13:51:00Z" + } + ], "meta": { "total": 480, - "has_next": true, "per_page": 20, "total_pages": 24, "current_page": 3, + "has_next": true, "has_previous": true }, "links": { @@ -329,10 +342,23 @@ For `GET /v1/orders?filter=status==paid&sort=-created_at,id&page[cursor]=BS3RvKY ```json { - "data": [], + "data": [ + { + "id": 4821, + "status": "paid", + "total": 12990, + "created_at": "2026-01-29T14:05:00Z" + }, + { + "id": 4820, + "status": "paid", + "total": 8400, + "created_at": "2026-01-29T13:51:00Z" + } + ], "meta": { - "has_next": true, - "per_page": 20 + "per_page": 20, + "has_next": true }, "links": { "self": "/v1/orders?filter=status==paid&sort=-created_at,id&page[cursor]=BS3RvKY4LqEjYD19mQ0mCpJ&page[size]=20", @@ -381,7 +407,7 @@ the same expression reads the same on the client and the server. The library is single comparison or an AND group of comparisons flattens into the `list` the consumer applies. An OR group, or a group nested inside another group, is rejected as an unsupported shape. -> Zdenek Jirutka, *RSQL / FIQL parser* (https://github.com/jirutka/rsql-parser). +> Zdenek Jirutka, *RSQL / FIQL parser*. ### 04. Why are the two pagination approaches split into separate contexts? @@ -391,6 +417,14 @@ offset-style `self` while its `next` is cursor-style. Splitting the API into a ` each complete and approach-only, with the common building blocks at the root, makes every `self` link consistent with the page's own approach. +### 05. How does the library help guard against injection? + +Field and operator names are validated against the `Schema` allowlist while parsing, so only declared identifiers ever +reach your store. Comparison and cursor values are returned as data for you to bind as parameters, and the library +builds no SQL. A cursor token is decoded only as a list of scalar values. Any unsafe character in the filter and sort +echoed into the `links` object and the `Link` header is percent-encoded. Binding the values is still your +responsibility. + ## License Http Query is licensed under [MIT](LICENSE). diff --git a/src/Cursor/Page.php b/src/Cursor/Page.php index b560340..1c06969 100644 --- a/src/Cursor/Page.php +++ b/src/Cursor/Page.php @@ -132,8 +132,8 @@ public function hasNext(): bool public function metadata(): array { return [ - 'has_next' => $this->hasNext, - 'per_page' => $this->pagination->limit() + 'per_page' => $this->pagination->limit(), + 'has_next' => $this->hasNext ]; } diff --git a/src/Internal/Cursor/CursorCodec.php b/src/Internal/Cursor/CursorCodec.php index 2f2bf9b..5da62d0 100644 --- a/src/Internal/Cursor/CursorCodec.php +++ b/src/Internal/Cursor/CursorCodec.php @@ -20,12 +20,18 @@ public static function decode(string $token): array throw CursorIsInvalid::from(token: $token); } - $keys = json_decode($decoded); + $keys = json_decode($decoded, true); - if (!is_array($keys)) { + if (!is_array($keys) || !array_is_list($keys)) { throw CursorIsInvalid::from(token: $token); } + foreach ($keys as $value) { + if (!is_scalar($value) && !is_null($value)) { + throw CursorIsInvalid::from(token: $token); + } + } + return $keys; } diff --git a/src/Internal/Rsql/FilterParser.php b/src/Internal/Rsql/FilterParser.php index 7cdaa8c..19d9d03 100644 --- a/src/Internal/Rsql/FilterParser.php +++ b/src/Internal/Rsql/FilterParser.php @@ -12,6 +12,8 @@ final readonly class FilterParser { + private const int MAX_DEPTH = 32; + private function __construct(private string $input, private Scanner $scanner) { } @@ -23,7 +25,7 @@ public static function from(string $input): FilterParser public function parse(): Filter { - $filter = $this->disjunction(); + $filter = $this->disjunction(depth: 0); if (!$this->scanner->isAtEnd()) { throw FilterExpressionIsInvalid::from(expression: $this->input); @@ -32,35 +34,39 @@ public function parse(): Filter return $filter; } - private function disjunction(): Filter + private function disjunction(int $depth): Filter { - $filters = [$this->conjunction()]; + $filters = [$this->conjunction(depth: $depth)]; while ($this->scanner->peek() === LogicalOperator::OR->value) { $this->scanner->expect(character: LogicalOperator::OR->value); - $filters[] = $this->conjunction(); + $filters[] = $this->conjunction(depth: $depth); } return count($filters) === 1 ? $filters[0] : Group::of(filters: $filters, operator: LogicalOperator::OR); } - private function conjunction(): Filter + private function conjunction(int $depth): Filter { - $filters = [$this->constraint()]; + $filters = [$this->constraint(depth: $depth)]; while ($this->scanner->peek() === LogicalOperator::AND->value) { $this->scanner->expect(character: LogicalOperator::AND->value); - $filters[] = $this->constraint(); + $filters[] = $this->constraint(depth: $depth); } return count($filters) === 1 ? $filters[0] : Group::of(filters: $filters, operator: LogicalOperator::AND); } - private function constraint(): Filter + private function constraint(int $depth): Filter { if ($this->scanner->peek() === '(') { + if ($depth >= FilterParser::MAX_DEPTH) { + throw FilterExpressionIsInvalid::from(expression: $this->input); + } + $this->scanner->expect(character: '('); - $group = $this->disjunction(); + $group = $this->disjunction(depth: $depth + 1); $this->scanner->expect(character: ')'); return $group; diff --git a/src/Internal/Uri.php b/src/Internal/Uri.php index cc07a68..230de55 100644 --- a/src/Internal/Uri.php +++ b/src/Internal/Uri.php @@ -21,12 +21,12 @@ public static function from(Sort $sort, Filter $filter, string $baseUri, Paginat if (!$filter->isEmpty()) { $template = 'filter=%s'; - $parameters[] = sprintf($template, Renderer::from(filter: $filter)); + $parameters[] = sprintf($template, Uri::encode(value: Renderer::from(filter: $filter))); } if (!$sort->isEmpty()) { $template = 'sort=%s'; - $parameters[] = sprintf($template, $sort->toExpression()); + $parameters[] = sprintf($template, Uri::encode(value: $sort->toExpression())); } $parameters[] = $pagination->toQueryString(); @@ -34,4 +34,16 @@ public static function from(Sort $sort, Filter $filter, string $baseUri, Paginat return sprintf($template, $baseUri, implode('&', $parameters)); } + + private static function encode(string $value): string + { + return strtr(rawurlencode($value), [ + '%3D' => '=', + '%3B' => ';', + '%2C' => ',', + '%28' => '(', + '%29' => ')', + '%21' => '!' + ]); + } } diff --git a/src/Offset/Page.php b/src/Offset/Page.php index 14de7c3..18e6bba 100644 --- a/src/Offset/Page.php +++ b/src/Offset/Page.php @@ -155,10 +155,10 @@ public function metadata(): array { return [ 'total' => $this->total->value(), - 'has_next' => $this->paging->hasNext(), 'per_page' => $this->paging->limit(), 'total_pages' => $this->pageCount->value(), 'current_page' => $this->paging->currentPage(), + 'has_next' => $this->paging->hasNext(), 'has_previous' => $this->paging->hasPrevious() ]; } diff --git a/src/Offset/Slice.php b/src/Offset/Slice.php index 3df8097..2ebfb8d 100644 --- a/src/Offset/Slice.php +++ b/src/Offset/Slice.php @@ -122,9 +122,9 @@ public function hasNext(): bool public function metadata(): array { return [ - 'has_next' => $this->paging->hasNext(), 'per_page' => $this->paging->limit(), 'current_page' => $this->paging->currentPage(), + 'has_next' => $this->paging->hasNext(), 'has_previous' => $this->paging->hasPrevious() ]; } diff --git a/tests/Unit/Cursor/PageTest.php b/tests/Unit/Cursor/PageTest.php index bddd1ea..3281ca9 100644 --- a/tests/Unit/Cursor/PageTest.php +++ b/tests/Unit/Cursor/PageTest.php @@ -50,7 +50,7 @@ public function testNavigationWhenNoExtraElementThenHasNoNextPage(): void self::assertCount(0, $page->navigation()->targets()->toArray()); /** @And the metadata reports no next page in length-ascending key order */ - self::assertSame(['has_next' => false, 'per_page' => 2], $page->metadata()); + self::assertSame(['per_page' => 2, 'has_next' => false], $page->metadata()); } public function testToResponseWhenCursorPageGivenThenRendersBodyAndLinkHeader(): void @@ -74,8 +74,8 @@ public function testToResponseWhenCursorPageGivenThenRendersBodyAndLinkHeader(): self::assertSame([ 'data' => [10, 20], 'meta' => [ - 'has_next' => true, - 'per_page' => 2 + 'per_page' => 2, + 'has_next' => true ], 'links' => [ 'self' => sprintf('/v1/orders?page[cursor]=%s&page[size]=2', $token), @@ -108,8 +108,8 @@ public function testToResponseWhenFirstCursorPageThenSelfLinkIsCursorStyle(): vo self::assertSame([ 'data' => [10, 20], 'meta' => [ - 'has_next' => true, - 'per_page' => 2 + 'per_page' => 2, + 'has_next' => true ], 'links' => [ 'self' => '/v1/orders?page[size]=2', @@ -169,7 +169,7 @@ public function testMapWhenTransformationGivenThenProjectsItemsAndPreservesTheCu self::assertEquals(Pagination::from(cursor: Token::fromKeys(keys: [20]), perPage: 2), $mapped->next()); /** @And the metadata is preserved in length-ascending key order */ - self::assertSame(['has_next' => true, 'per_page' => 2], $mapped->metadata()); + self::assertSame(['per_page' => 2, 'has_next' => true], $mapped->metadata()); } public function testToResponseWhenPageIsMappedThenRendersProjectedDataAndPreservedLinks(): void @@ -193,8 +193,8 @@ public function testToResponseWhenPageIsMappedThenRendersProjectedDataAndPreserv self::assertSame([ 'data' => [10, 20], 'meta' => [ - 'has_next' => true, - 'per_page' => 2 + 'per_page' => 2, + 'has_next' => true ], 'links' => [ 'self' => sprintf('/v1/orders?page[cursor]=%s&page[size]=2', $token), @@ -227,6 +227,6 @@ public function testNavigationWhenExtraElementFetchedThenHasNextAndNextCursorAnc self::assertEquals(Pagination::from(cursor: Token::fromKeys(keys: [20]), perPage: 2), $page->next()); /** @And the metadata carries the navigation flags in length-ascending key order */ - self::assertSame(['has_next' => true, 'per_page' => 2], $page->metadata()); + self::assertSame(['per_page' => 2, 'has_next' => true], $page->metadata()); } } diff --git a/tests/Unit/Cursor/TokenTest.php b/tests/Unit/Cursor/TokenTest.php index 875e322..e295307 100644 --- a/tests/Unit/Cursor/TokenTest.php +++ b/tests/Unit/Cursor/TokenTest.php @@ -153,6 +153,32 @@ public function testToArrayWhenTokenDecodesToScalarThenThrowsCursorIsInvalid(): $token->toArray(); } + public function testToArrayWhenTokenDecodesToObjectThenThrowsCursorIsInvalid(): void + { + /** @Given a base64url token whose decoded payload is a JSON object rather than a list */ + $token = Token::from(token: rtrim(strtr(base64_encode('{"a":1}'), '+/', '-_'), '=')); + + /** @Then an exception indicating the cursor token is invalid is raised */ + $this->expectException(CursorIsInvalid::class); + $this->expectExceptionMessage('could not be decoded'); + + /** @When decoding the token into key values */ + $token->toArray(); + } + + public function testToArrayWhenTokenDecodesToListWithNestedStructureThenThrowsCursorIsInvalid(): void + { + /** @Given a base64url token whose decoded list carries a nested array and object */ + $token = Token::from(token: rtrim(strtr(base64_encode('[["x"],{"a":1}]'), '+/', '-_'), '=')); + + /** @Then an exception indicating the cursor token is invalid is raised */ + $this->expectException(CursorIsInvalid::class); + $this->expectExceptionMessage('could not be decoded'); + + /** @When decoding the token into key values */ + $token->toArray(); + } + public function testFromKeysWhenRoundTrippedThroughTokenThenYieldsTheOriginalKeys(): void { /** @Given the opaque token produced from ordering key values */ diff --git a/tests/Unit/EndToEndTest.php b/tests/Unit/EndToEndTest.php index d709242..64f5902 100644 --- a/tests/Unit/EndToEndTest.php +++ b/tests/Unit/EndToEndTest.php @@ -46,10 +46,10 @@ public function testPipelineWhenOffsetRequestGivenThenPageRendersTheResponse(): 'data' => ['a', 'b'], 'meta' => [ 'total' => 480, - 'has_next' => true, 'per_page' => 20, 'total_pages' => 24, 'current_page' => 3, + 'has_next' => true, 'has_previous' => true ], 'links' => [ @@ -125,8 +125,8 @@ public function testPipelineWhenCursorRequestGivenThenCursorPageRendersTheRespon self::assertSame([ 'data' => [['id' => 10], ['id' => 20]], 'meta' => [ - 'has_next' => true, - 'per_page' => 2 + 'per_page' => 2, + 'has_next' => true ], 'links' => [ 'self' => sprintf('%s&page[cursor]=%s&page[size]=2', $base, $token), diff --git a/tests/Unit/FilterTest.php b/tests/Unit/FilterTest.php index e81582f..9642926 100644 --- a/tests/Unit/FilterTest.php +++ b/tests/Unit/FilterTest.php @@ -195,6 +195,44 @@ public function testFromQueryWhenParenthesizedAndGroupThenComparisonsCarryEveryL ], $comparisons); } + public function testFromQueryWhenFilterNestedToTheMaximumDepthThenComparisonIsReturned(): void + { + /** @Given a filter template wrapping a comparison in placeholders */ + $template = '%sa==1%s'; + + /** @And a query whose filter nests parentheses up to the maximum depth */ + $query = Query::from(parameters: [ + 'filter' => sprintf($template, str_repeat('(', 32), str_repeat(')', 32)) + ]); + + /** @When reading the validated comparisons */ + $comparisons = Criteria::fromQuery(request: $query, schema: $this->schema)->comparisons(); + + /** @Then the deeply nested parentheses collapse to the single unwrapped comparison */ + self::assertEquals( + [Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL)], + $comparisons + ); + } + + public function testFromQueryWhenFilterNestedBeyondTheMaximumDepthThenThrowsFilterExpressionIsInvalid(): void + { + /** @Given a filter template wrapping a comparison in placeholders */ + $template = '%sa==1%s'; + + /** @And a query whose filter nests parentheses one level beyond the maximum depth */ + $query = Query::from(parameters: [ + 'filter' => sprintf($template, str_repeat('(', 33), str_repeat(')', 33)) + ]); + + /** @Then an exception indicating the filter expression is invalid is raised */ + $this->expectException(FilterExpressionIsInvalid::class); + $this->expectExceptionMessage('could not be parsed'); + + /** @When building the criteria from the query */ + Criteria::fromQuery(request: $query, schema: $this->schema); + } + public function testFromQueryWhenDateTimeValueMatchesKindThenComparisonIsReturned(): void { /** @Given a schema allowing a date-time field under the greater-than operator */ diff --git a/tests/Unit/LinksTest.php b/tests/Unit/LinksTest.php index 7af9fe9..551b3c4 100644 --- a/tests/Unit/LinksTest.php +++ b/tests/Unit/LinksTest.php @@ -59,7 +59,7 @@ public function testToArrayWhenReservedCharacterInValueThenQuotesIt(): void /** @Then the self link renders the value within double quotes */ self::assertSame( - '/v1/orders?filter=name=="John Doe"&page[number]=1&page[size]=20', + '/v1/orders?filter=name==%22John%20Doe%22&page[number]=1&page[size]=20', $links->toArray()['self'] ); } @@ -80,11 +80,38 @@ public function testToArrayWhenQuoteAndBackslashInValueThenEscapesBoth(): void /** @Then the self link escapes the quote and the backslash within the double-quoted value */ self::assertSame( - '/v1/orders?filter=name=="a\\"b\\\\c"&page[number]=1&page[size]=20', + '/v1/orders?filter=name==%22a%5C%22b%5C%5Cc%22&page[number]=1&page[size]=20', $links->toArray()['self'] ); } + public function testToArrayWhenValueCarriesUnsafeAndStructuralCharactersThenEncodesOnlyTheUnsafeOnes(): void + { + /** @Given a comparison whose value carries query-unsafe and RSQL-structural characters */ + $filter = Comparison::of(field: 'name', values: ["a&b#c%d=e;f,g(h)i!j k\r\n"], operator: Operator::EQUAL); + + /** @And the readable link the decoded query is expected to round-trip to */ + $template = '/v1/orders?filter=%s&page[number]=1&page[size]=20'; + + /** @When rendering the self link for a page carrying that filter */ + $self = Links::from( + sort: Sort::fromExpression(expression: ''), + filter: $filter, + baseUri: '/v1/orders', + self: Pagination::fromPage(page: 1, perPage: 20), + navigation: Navigation::empty() + )->toArray()['self']; + + /** @Then the unsafe characters stay percent-encoded while the structural and unreserved ones stay readable */ + self::assertSame( + '/v1/orders?filter=name==%22a%26b%23c%25d=e;f,g(h)i!j%20k%0D%0A%22&page[number]=1&page[size]=20', + $self + ); + + /** @And URL-decoding the link recovers the readable form carrying the rendered RSQL */ + self::assertSame(sprintf($template, Renderer::from(filter: $filter)), rawurldecode($self)); + } + public function testToArrayWhenAndGroupFilterThenJoinsChildrenWithTheAndToken(): void { /** @Given an AND group of two comparisons */ @@ -103,7 +130,10 @@ public function testToArrayWhenAndGroupFilterThenJoinsChildrenWithTheAndToken(): ); /** @Then the self link joins the children with the AND token */ - self::assertSame('/v1/orders?filter=a==1;b==2&page[number]=1&page[size]=20', $links->toArray()['self']); + self::assertSame( + '/v1/orders?filter=a==1;b==2&page[number]=1&page[size]=20', + $links->toArray()['self'] + ); } public function testToArrayWhenOrGroupFilterThenJoinsChildrenWithTheOrToken(): void @@ -124,7 +154,10 @@ public function testToArrayWhenOrGroupFilterThenJoinsChildrenWithTheOrToken(): v ); /** @Then the self link joins the children with the OR token */ - self::assertSame('/v1/orders?filter=a==1,b==2&page[number]=1&page[size]=20', $links->toArray()['self']); + self::assertSame( + '/v1/orders?filter=a==1,b==2&page[number]=1&page[size]=20', + $links->toArray()['self'] + ); } public function testToArrayWhenOrGroupNestedInAndThenWrapsItInParentheses(): void @@ -148,7 +181,10 @@ public function testToArrayWhenOrGroupNestedInAndThenWrapsItInParentheses(): voi ); /** @Then the self link wraps the tighter-binding OR group in parentheses */ - self::assertSame('/v1/orders?filter=(a==1,b==2);c==3&page[number]=1&page[size]=20', $links->toArray()['self']); + self::assertSame( + '/v1/orders?filter=(a==1,b==2);c==3&page[number]=1&page[size]=20', + $links->toArray()['self'] + ); } public function testToArrayWhenAndGroupNestedInOrThenLeavesItUnwrapped(): void @@ -172,7 +208,10 @@ public function testToArrayWhenAndGroupNestedInOrThenLeavesItUnwrapped(): void ); /** @Then the self link leaves the tighter-binding AND group unwrapped */ - self::assertSame('/v1/orders?filter=a==1;b==2,c==3&page[number]=1&page[size]=20', $links->toArray()['self']); + self::assertSame( + '/v1/orders?filter=a==1;b==2,c==3&page[number]=1&page[size]=20', + $links->toArray()['self'] + ); } public function testToArrayWhenPageIsTheLastThenOmitsTheNextRelation(): void diff --git a/tests/Unit/Offset/PageTest.php b/tests/Unit/Offset/PageTest.php index 288d9b4..567bdab 100644 --- a/tests/Unit/Offset/PageTest.php +++ b/tests/Unit/Offset/PageTest.php @@ -83,10 +83,10 @@ public function testNavigationWhenTotalIsZeroThenThereIsNoPage(): void /** @And the metadata carries a zero total and zero total pages */ self::assertSame([ 'total' => 0, - 'has_next' => false, 'per_page' => 20, 'total_pages' => 0, 'current_page' => 1, + 'has_next' => false, 'has_previous' => false ], $page->metadata()); } @@ -170,10 +170,10 @@ public function testMetadataWhenMiddlePageGivenThenCarriesEveryFlagAndCount(): v /** @Then the metadata carries every navigation flag and count in length-ascending key order */ self::assertSame([ 'total' => 480, - 'has_next' => true, 'per_page' => 20, 'total_pages' => 24, 'current_page' => 3, + 'has_next' => true, 'has_previous' => true ], $page->metadata()); } @@ -215,10 +215,10 @@ public function testToResponseWhenMiddlePageGivenThenRendersBodyAndLinkHeader(): 'data' => ['a', 'b'], 'meta' => [ 'total' => 480, - 'has_next' => true, 'per_page' => 20, 'total_pages' => 24, 'current_page' => 3, + 'has_next' => true, 'has_previous' => true ], 'links' => [ diff --git a/tests/Unit/Offset/SliceTest.php b/tests/Unit/Offset/SliceTest.php index 626b347..f62753e 100644 --- a/tests/Unit/Offset/SliceTest.php +++ b/tests/Unit/Offset/SliceTest.php @@ -41,9 +41,9 @@ public function testToResponseWhenSliceGivenThenRendersBodyAndLinkHeader(): void self::assertSame([ 'data' => ['a', 'b', 'c'], 'meta' => [ - 'has_next' => true, 'per_page' => 3, 'current_page' => 2, + 'has_next' => true, 'has_previous' => true ], 'links' => [ @@ -94,9 +94,9 @@ public function testNavigationWhenExtraElementFetchedThenHasNextAndTrimsItems(): /** @And the metadata carries every navigation flag and count in length-ascending key order */ self::assertSame([ - 'has_next' => true, 'per_page' => 3, 'current_page' => 2, + 'has_next' => true, 'has_previous' => true ], $slice->metadata()); } From 3efab130c46a51244f6c31d7c5fa4c0e8eba3fce Mon Sep 17 00:00:00 2001 From: Gustavo Freze Date: Tue, 9 Jun 2026 09:41:50 -0300 Subject: [PATCH 10/14] docs: Update metadata documentation to clarify key ordering in JSON:API responses. --- src/Cursor/Page.php | 3 ++- src/Offset/Page.php | 3 ++- src/Offset/Slice.php | 3 ++- tests/Unit/Cursor/PageTest.php | 6 +++--- tests/Unit/Offset/PageTest.php | 2 +- tests/Unit/Offset/SliceTest.php | 2 +- 6 files changed, 11 insertions(+), 8 deletions(-) diff --git a/src/Cursor/Page.php b/src/Cursor/Page.php index 1c06969..1f196fe 100644 --- a/src/Cursor/Page.php +++ b/src/Cursor/Page.php @@ -127,7 +127,8 @@ public function hasNext(): bool /** * Returns the cursor page as the JSON:API meta contents. * - * @return array The meta contents keyed in length-ascending order. + * @return array The meta contents, counts and sizes first, then the boolean + * flags, each by ascending key-name length. */ public function metadata(): array { diff --git a/src/Offset/Page.php b/src/Offset/Page.php index 18e6bba..c1edd64 100644 --- a/src/Offset/Page.php +++ b/src/Offset/Page.php @@ -149,7 +149,8 @@ public function hasNext(): bool /** * Returns the page as the JSON:API meta contents. * - * @return array The meta contents keyed in length-ascending order. + * @return array The meta contents, counts and sizes first, then the boolean + * flags, each by ascending key-name length. */ public function metadata(): array { diff --git a/src/Offset/Slice.php b/src/Offset/Slice.php index 2ebfb8d..f4eb8ac 100644 --- a/src/Offset/Slice.php +++ b/src/Offset/Slice.php @@ -117,7 +117,8 @@ public function hasNext(): bool /** * Returns the slice as the JSON:API meta contents. * - * @return array The meta contents keyed in length-ascending order. + * @return array The meta contents, counts and sizes first, then the boolean + * flags, each by ascending key-name length. */ public function metadata(): array { diff --git a/tests/Unit/Cursor/PageTest.php b/tests/Unit/Cursor/PageTest.php index 3281ca9..500839d 100644 --- a/tests/Unit/Cursor/PageTest.php +++ b/tests/Unit/Cursor/PageTest.php @@ -49,7 +49,7 @@ public function testNavigationWhenNoExtraElementThenHasNoNextPage(): void /** @And the navigation lists no target */ self::assertCount(0, $page->navigation()->targets()->toArray()); - /** @And the metadata reports no next page in length-ascending key order */ + /** @And the metadata reports no next page in grouped key order (counts and sizes, then the boolean flags) */ self::assertSame(['per_page' => 2, 'has_next' => false], $page->metadata()); } @@ -168,7 +168,7 @@ public function testMapWhenTransformationGivenThenProjectsItemsAndPreservesTheCu /** @And the next pagination still anchors on the source keys */ self::assertEquals(Pagination::from(cursor: Token::fromKeys(keys: [20]), perPage: 2), $mapped->next()); - /** @And the metadata is preserved in length-ascending key order */ + /** @And the metadata is preserved in grouped key order (counts and sizes, then the boolean flags) */ self::assertSame(['per_page' => 2, 'has_next' => true], $mapped->metadata()); } @@ -226,7 +226,7 @@ public function testNavigationWhenExtraElementFetchedThenHasNextAndNextCursorAnc /** @And the next pagination anchors on the last retained element with the page size */ self::assertEquals(Pagination::from(cursor: Token::fromKeys(keys: [20]), perPage: 2), $page->next()); - /** @And the metadata carries the navigation flags in length-ascending key order */ + /** @And the metadata carries every entry in grouped key order (counts and sizes, then the boolean flags) */ self::assertSame(['per_page' => 2, 'has_next' => true], $page->metadata()); } } diff --git a/tests/Unit/Offset/PageTest.php b/tests/Unit/Offset/PageTest.php index 567bdab..dc84904 100644 --- a/tests/Unit/Offset/PageTest.php +++ b/tests/Unit/Offset/PageTest.php @@ -167,7 +167,7 @@ public function testMetadataWhenMiddlePageGivenThenCarriesEveryFlagAndCount(): v /** @When building the page from the total element count */ $page = $criteria->page(total: 480, items: ['a', 'b']); - /** @Then the metadata carries every navigation flag and count in length-ascending key order */ + /** @Then the metadata carries every entry in grouped key order (counts and sizes, then the boolean flags) */ self::assertSame([ 'total' => 480, 'per_page' => 20, diff --git a/tests/Unit/Offset/SliceTest.php b/tests/Unit/Offset/SliceTest.php index f62753e..7e652f1 100644 --- a/tests/Unit/Offset/SliceTest.php +++ b/tests/Unit/Offset/SliceTest.php @@ -92,7 +92,7 @@ public function testNavigationWhenExtraElementFetchedThenHasNextAndTrimsItems(): /** @And the previous pagination points at the first page */ self::assertSame(1, $slice->previous()?->page()); - /** @And the metadata carries every navigation flag and count in length-ascending key order */ + /** @And the metadata carries every entry in grouped key order (counts and sizes, then the boolean flags) */ self::assertSame([ 'per_page' => 3, 'current_page' => 2, From fdb0f05dec1c9ac0cf042e8da35dc6787dd6f7e8 Mon Sep 17 00:00:00 2001 From: Gustavo Freze Date: Mon, 15 Jun 2026 12:59:57 -0300 Subject: [PATCH 11/14] refactor: Order members, parameters, and named arguments by name length. --- src/Cursor/Page.php | 4 +- src/Internal/AllowedField.php | 10 +- src/Internal/Conjunction.php | 18 +- src/Internal/Cursor/Seek.php | 8 +- src/Internal/Offset/OffsetNavigation.php | 8 +- src/Internal/Offset/PageCount.php | 2 +- src/Internal/Offset/Total.php | 2 +- src/Internal/Rendering.php | 4 +- src/Internal/Rsql/FilterParser.php | 56 ++--- src/Internal/Rsql/Renderer.php | 16 +- src/Internal/Window.php | 2 +- src/Links.php | 10 +- src/Offset/Criteria.php | 4 +- src/Offset/Page.php | 8 +- src/Offset/Slice.php | 4 +- tests/Models/Query.php | 2 +- tests/Unit/ComparisonTest.php | 84 +++---- tests/Unit/Cursor/CriteriaTest.php | 70 +++--- tests/Unit/Cursor/KeysetTest.php | 30 +-- tests/Unit/Cursor/PageTest.php | 56 ++--- tests/Unit/Cursor/PaginationTest.php | 24 +- tests/Unit/Cursor/TokenTest.php | 108 ++++---- tests/Unit/DirectionTest.php | 8 +- tests/Unit/EndToEndTest.php | 76 +++--- tests/Unit/FilterTest.php | 304 +++++++++++------------ tests/Unit/LinksTest.php | 294 +++++++++++----------- tests/Unit/LogicalOperatorTest.php | 8 +- tests/Unit/Offset/CriteriaTest.php | 154 ++++++------ tests/Unit/Offset/PageTest.php | 136 +++++----- tests/Unit/Offset/PaginationTest.php | 24 +- tests/Unit/Offset/SliceTest.php | 24 +- tests/Unit/OperatorTest.php | 4 +- tests/Unit/SchemaTest.php | 66 ++--- 33 files changed, 814 insertions(+), 814 deletions(-) diff --git a/src/Cursor/Page.php b/src/Cursor/Page.php index 1f196fe..14c8c54 100644 --- a/src/Cursor/Page.php +++ b/src/Cursor/Page.php @@ -58,7 +58,7 @@ public static function from( ): Page { /** @var Collection $collection */ $collection = Collection::createFrom(elements: $items); - $seek = Seek::from(limit: $pagination->limit(), items: $collection, keysOf: $keysOf); + $seek = Seek::from(items: $collection, limit: $pagination->limit(), keysOf: $keysOf); return new Page( sort: $sort, @@ -157,8 +157,8 @@ public function navigation(): Navigation public function toResponse(string $baseUri): ResponseInterface { return Rendering::of( - sort: $this->sort, self: $this->pagination, + sort: $this->sort, items: $this->items, filter: $this->filter, baseUri: $baseUri, diff --git a/src/Internal/AllowedField.php b/src/Internal/AllowedField.php index 84fec09..9e87a06 100644 --- a/src/Internal/AllowedField.php +++ b/src/Internal/AllowedField.php @@ -24,11 +24,6 @@ public static function from(?ValueKind $kind, string $field, ?array $values, arr return new AllowedField(kind: $kind, field: $field, values: $values, operators: $operators); } - public function hasField(string $field): bool - { - return $this->field === $field; - } - public function permit(Comparison $comparison): Comparison { if (!in_array($comparison->operator(), $this->operators, true)) { @@ -47,4 +42,9 @@ public function permit(Comparison $comparison): Comparison return $comparison; } + + public function hasField(string $field): bool + { + return $this->field === $field; + } } diff --git a/src/Internal/Conjunction.php b/src/Internal/Conjunction.php index 0ab37e5..799fcf2 100644 --- a/src/Internal/Conjunction.php +++ b/src/Internal/Conjunction.php @@ -25,6 +25,15 @@ public static function from(Filter $filter, string $expression): array return [$filter]; } + private static function leaf(Filter $filter, string $expression): Comparison + { + if ($filter instanceof Comparison) { + return $filter; + } + + throw FilterShapeNotSupported::from(expression: $expression); + } + private static function flatten(Group $group, string $expression): array { if ($group->operator() !== LogicalOperator::AND) { @@ -36,13 +45,4 @@ private static function flatten(Group $group, string $expression): array $group->filters() ); } - - private static function leaf(Filter $filter, string $expression): Comparison - { - if ($filter instanceof Comparison) { - return $filter; - } - - throw FilterShapeNotSupported::from(expression: $expression); - } } diff --git a/src/Internal/Cursor/Seek.php b/src/Internal/Cursor/Seek.php index ee996bb..186a868 100644 --- a/src/Internal/Cursor/Seek.php +++ b/src/Internal/Cursor/Seek.php @@ -18,7 +18,7 @@ * @param Window $window * @param Closure(TValue): list $keysOf */ - private function __construct(private Window $window, private Closure $keysOf) + private function __construct(private Closure $keysOf, private Window $window) { } @@ -28,12 +28,12 @@ private function __construct(private Window $window, private Closure $keysOf) * @param Closure(TElement): list $keysOf * @return Seek */ - public static function from(int $limit, Collection $items, Closure $keysOf): Seek + public static function from(Collection $items, int $limit, Closure $keysOf): Seek { /** @var Window $window */ - $window = Window::from(limit: $limit, items: $items); + $window = Window::from(items: $items, limit: $limit); - return new Seek(window: $window, keysOf: $keysOf); + return new Seek(keysOf: $keysOf, window: $window); } public function next(): Token diff --git a/src/Internal/Offset/OffsetNavigation.php b/src/Internal/Offset/OffsetNavigation.php index a966cd6..5340b6d 100644 --- a/src/Internal/Offset/OffsetNavigation.php +++ b/src/Internal/Offset/OffsetNavigation.php @@ -11,8 +11,8 @@ { private function __construct( private bool $hasNext, - private Pagination $pagination, - private PageNumber $pageNumber + private PageNumber $pageNumber, + private Pagination $pagination ) { } @@ -23,8 +23,8 @@ public static function from(bool $hasNext, Pagination $pagination): OffsetNaviga return new OffsetNavigation( hasNext: $hasNext, - pagination: $pagination, - pageNumber: PageNumber::fromOffset(limit: $limit, offset: $offset) + pageNumber: PageNumber::fromOffset(limit: $limit, offset: $offset), + pagination: $pagination ); } diff --git a/src/Internal/Offset/PageCount.php b/src/Internal/Offset/PageCount.php index 0d1f544..0681787 100644 --- a/src/Internal/Offset/PageCount.php +++ b/src/Internal/Offset/PageCount.php @@ -12,7 +12,7 @@ private function __construct(private int $value) { } - public static function from(Total $total, Limit $limit): PageCount + public static function from(Limit $limit, Total $total): PageCount { return new PageCount(value: (int)ceil($total->value() / $limit->value())); } diff --git a/src/Internal/Offset/Total.php b/src/Internal/Offset/Total.php index 558e6cc..ee0e73b 100644 --- a/src/Internal/Offset/Total.php +++ b/src/Internal/Offset/Total.php @@ -29,6 +29,6 @@ public function value(): int public function pageCount(Limit $limit): PageCount { - return PageCount::from(total: $this, limit: $limit); + return PageCount::from(limit: $limit, total: $this); } } diff --git a/src/Internal/Rendering.php b/src/Internal/Rendering.php index 1a46ddf..273197d 100644 --- a/src/Internal/Rendering.php +++ b/src/Internal/Rendering.php @@ -20,15 +20,15 @@ private function __construct() } public static function of( - Sort $sort, Pagination $self, + Sort $sort, Collection $items, Filter $filter, string $baseUri, array $metadata, Navigation $navigation ): ResponseInterface { - $links = Links::from(sort: $sort, self: $self, filter: $filter, baseUri: $baseUri, navigation: $navigation); + $links = Links::from(self: $self, sort: $sort, filter: $filter, baseUri: $baseUri, navigation: $navigation); return Response::ok([ 'data' => $items->toArray(), diff --git a/src/Internal/Rsql/FilterParser.php b/src/Internal/Rsql/FilterParser.php index 19d9d03..7484727 100644 --- a/src/Internal/Rsql/FilterParser.php +++ b/src/Internal/Rsql/FilterParser.php @@ -34,28 +34,26 @@ public function parse(): Filter return $filter; } - private function disjunction(int $depth): Filter + private function comparison(): Comparison { - $filters = [$this->conjunction(depth: $depth)]; + $field = $this->scanner->unreserved(); + $operator = $this->scanner->operator(); - while ($this->scanner->peek() === LogicalOperator::OR->value) { - $this->scanner->expect(character: LogicalOperator::OR->value); - $filters[] = $this->conjunction(depth: $depth); + if ($this->scanner->peek() !== '(') { + return Comparison::of(field: $field, values: [$this->scanner->value()], operator: $operator); } - return count($filters) === 1 ? $filters[0] : Group::of(filters: $filters, operator: LogicalOperator::OR); - } - - private function conjunction(int $depth): Filter - { - $filters = [$this->constraint(depth: $depth)]; + $this->scanner->expect(character: '('); + $values = [$this->scanner->value()]; - while ($this->scanner->peek() === LogicalOperator::AND->value) { - $this->scanner->expect(character: LogicalOperator::AND->value); - $filters[] = $this->constraint(depth: $depth); + while ($this->scanner->peek() === ',') { + $this->scanner->expect(character: ','); + $values[] = $this->scanner->value(); } - return count($filters) === 1 ? $filters[0] : Group::of(filters: $filters, operator: LogicalOperator::AND); + $this->scanner->expect(character: ')'); + + return Comparison::of(field: $field, values: $values, operator: $operator); } private function constraint(int $depth): Filter @@ -75,25 +73,27 @@ private function constraint(int $depth): Filter return $this->comparison(); } - private function comparison(): Comparison + private function conjunction(int $depth): Filter { - $field = $this->scanner->unreserved(); - $operator = $this->scanner->operator(); + $filters = [$this->constraint(depth: $depth)]; - if ($this->scanner->peek() !== '(') { - return Comparison::of(field: $field, values: [$this->scanner->value()], operator: $operator); + while ($this->scanner->peek() === LogicalOperator::AND->value) { + $this->scanner->expect(character: LogicalOperator::AND->value); + $filters[] = $this->constraint(depth: $depth); } - $this->scanner->expect(character: '('); - $values = [$this->scanner->value()]; + return count($filters) === 1 ? $filters[0] : Group::of(filters: $filters, operator: LogicalOperator::AND); + } - while ($this->scanner->peek() === ',') { - $this->scanner->expect(character: ','); - $values[] = $this->scanner->value(); - } + private function disjunction(int $depth): Filter + { + $filters = [$this->conjunction(depth: $depth)]; - $this->scanner->expect(character: ')'); + while ($this->scanner->peek() === LogicalOperator::OR->value) { + $this->scanner->expect(character: LogicalOperator::OR->value); + $filters[] = $this->conjunction(depth: $depth); + } - return Comparison::of(field: $field, values: $values, operator: $operator); + return count($filters) === 1 ? $filters[0] : Group::of(filters: $filters, operator: LogicalOperator::OR); } } diff --git a/src/Internal/Rsql/Renderer.php b/src/Internal/Rsql/Renderer.php index 1168590..65f9f49 100644 --- a/src/Internal/Rsql/Renderer.php +++ b/src/Internal/Rsql/Renderer.php @@ -20,14 +20,6 @@ public static function from(Filter $filter): string return Renderer::expressionOf(filter: $filter)->value(); } - private static function expressionOf(Filter $filter): Expression - { - return match (true) { - $filter instanceof Group => Renderer::grouped(group: $filter), - $filter instanceof Comparison => Renderer::atomic(comparison: $filter) - }; - } - private static function atomic(Comparison $comparison): Expression { /** @var Collection $values */ @@ -67,4 +59,12 @@ private static function grouped(Group $group): Expression return Expression::grouped(value: $value, connective: $operator); } + + private static function expressionOf(Filter $filter): Expression + { + return match (true) { + $filter instanceof Group => Renderer::grouped(group: $filter), + $filter instanceof Comparison => Renderer::atomic(comparison: $filter) + }; + } } diff --git a/src/Internal/Window.php b/src/Internal/Window.php index d9f68ed..961783c 100644 --- a/src/Internal/Window.php +++ b/src/Internal/Window.php @@ -22,7 +22,7 @@ private function __construct(private Collection $items, private bool $hasNext) * @param Collection $items * @return Window */ - public static function from(int $limit, Collection $items): Window + public static function from(Collection $items, int $limit): Window { $elements = [...$items]; $hasNext = count($elements) > $limit; diff --git a/src/Links.php b/src/Links.php index 4997038..880d0e6 100644 --- a/src/Links.php +++ b/src/Links.php @@ -38,8 +38,8 @@ private function __construct(private WebLink $self, private Collection $links) * @return Links The navigation for the result. */ public static function from( - Sort $sort, Pagination $self, + Sort $sort, Filter $filter, string $baseUri, Navigation $navigation @@ -72,11 +72,11 @@ public static function from( public function toArray(): array { return $this->links->reduce( + initial: [$this->self->relation->value => $this->self->uri], accumulator: static fn(array $body, WebLink $link): array => [ ...$body, $link->relation->value => $link->uri - ], - initial: [$this->self->relation->value => $this->self->uri] + ] ); } @@ -88,11 +88,11 @@ public function toArray(): array public function toHeader(): Link { return $this->links->reduce( + initial: Link::to(uri: $this->self->uri, relation: $this->self->relation), accumulator: static fn(Link $carry, WebLink $link): Link => $carry->and( uri: $link->uri, relation: $link->relation - ), - initial: Link::to(uri: $this->self->uri, relation: $this->self->relation) + ) ); } } diff --git a/src/Offset/Criteria.php b/src/Offset/Criteria.php index 876cc96..b18bef1 100644 --- a/src/Offset/Criteria.php +++ b/src/Offset/Criteria.php @@ -82,12 +82,12 @@ public static function fromQuery(ServerRequestInterface $request, ?Schema $schem * @return Page The offset page carrying the items, the total, and the navigation. * @throws TotalIsNegative If the total is less than 0. */ - public function page(int $total, iterable $items): Page + public function page(iterable $items, int $total): Page { return Page::from( sort: $this->submittedSort, - total: $total, items: $items, + total: $total, filter: $this->filter, pagination: $this->pagination ); diff --git a/src/Offset/Page.php b/src/Offset/Page.php index c1edd64..5af16c3 100644 --- a/src/Offset/Page.php +++ b/src/Offset/Page.php @@ -31,8 +31,8 @@ */ private function __construct( private Sort $sort, - private Total $total, private Collection $items, + private Total $total, private Filter $filter, private OffsetNavigation $paging, private PageCount $pageCount, @@ -52,7 +52,7 @@ private function __construct( * @return Page The page carrying the items, the total, and the navigation. * @throws TotalIsNegative If the total is less than 0. */ - public static function from(Sort $sort, int $total, iterable $items, Filter $filter, Pagination $pagination): Page + public static function from(Sort $sort, iterable $items, int $total, Filter $filter, Pagination $pagination): Page { $count = Total::from(value: $total); $limit = Limit::from(value: $pagination->limit()); @@ -64,8 +64,8 @@ public static function from(Sort $sort, int $total, iterable $items, Filter $fil return new Page( sort: $sort, - total: $count, items: $collection, + total: $count, filter: $filter, paging: OffsetNavigation::from( hasNext: $pageCount->hasPageAfter(page: $pageNumber), @@ -197,8 +197,8 @@ public function navigation(): Navigation public function toResponse(string $baseUri): ResponseInterface { return Rendering::of( - sort: $this->sort, self: $this->pagination, + sort: $this->sort, items: $this->items, filter: $this->filter, baseUri: $baseUri, diff --git a/src/Offset/Slice.php b/src/Offset/Slice.php index f4eb8ac..9817395 100644 --- a/src/Offset/Slice.php +++ b/src/Offset/Slice.php @@ -50,7 +50,7 @@ public static function from(Sort $sort, iterable $items, Filter $filter, Paginat { /** @var Collection $collection */ $collection = Collection::createFrom(elements: $items); - $window = Window::from(limit: $pagination->limit(), items: $collection); + $window = Window::from(items: $collection, limit: $pagination->limit()); /** @var Collection $trimmed */ $trimmed = $window->items(); @@ -162,8 +162,8 @@ public function navigation(): Navigation public function toResponse(string $baseUri): ResponseInterface { return Rendering::of( - sort: $this->sort, self: $this->pagination, + sort: $this->sort, items: $this->items, filter: $this->filter, baseUri: $baseUri, diff --git a/tests/Models/Query.php b/tests/Models/Query.php index 6abb2af..196f159 100644 --- a/tests/Models/Query.php +++ b/tests/Models/Query.php @@ -15,6 +15,6 @@ private function __construct() public static function from(array $parameters): ServerRequestInterface { - return new ServerRequest(method: 'GET', uri: '/')->withQueryParams($parameters); + return new ServerRequest(uri: '/', method: 'GET')->withQueryParams($parameters); } } diff --git a/tests/Unit/ComparisonTest.php b/tests/Unit/ComparisonTest.php index a438c0e..e00906e 100644 --- a/tests/Unit/ComparisonTest.php +++ b/tests/Unit/ComparisonTest.php @@ -10,30 +10,6 @@ final class ComparisonTest extends TestCase { - public function testFieldThenReturnsTheComparedField(): void - { - /** @Given an equality comparison on a field */ - $comparison = Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL); - - /** @When reading the compared field */ - $field = $comparison->field(); - - /** @Then it returns the field being compared */ - self::assertSame('status', $field); - } - - public function testValuesThenReturnsTheComparedValues(): void - { - /** @Given an IN comparison carrying several values */ - $comparison = Comparison::of(field: 'role', values: ['admin', 'user'], operator: Operator::IN); - - /** @When reading the compared values */ - $values = $comparison->values(); - - /** @Then it returns the values compared against the field in order */ - self::assertSame(['admin', 'user'], $values); - } - public function testIsEmptyThenReportsItIsNotEmpty(): void { /** @Given an equality comparison */ @@ -46,16 +22,16 @@ public function testIsEmptyThenReportsItIsNotEmpty(): void self::assertFalse($isEmpty); } - public function testOperatorThenReturnsTheComparisonOperator(): void + public function testFieldThenReturnsTheComparedField(): void { - /** @Given an equality comparison */ + /** @Given an equality comparison on a field */ $comparison = Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL); - /** @When reading the comparison operator */ - $operator = $comparison->operator(); + /** @When reading the compared field */ + $field = $comparison->field(); - /** @Then it returns the operator the comparison carries */ - self::assertSame(Operator::EQUAL, $operator); + /** @Then it returns the field being compared */ + self::assertSame('status', $field); } public function testHasFieldWhenFieldMatchesThenIsTrue(): void @@ -70,6 +46,18 @@ public function testHasFieldWhenFieldMatchesThenIsTrue(): void self::assertTrue($hasField); } + public function testValuesThenReturnsTheComparedValues(): void + { + /** @Given an IN comparison carrying several values */ + $comparison = Comparison::of(field: 'role', values: ['admin', 'user'], operator: Operator::IN); + + /** @When reading the compared values */ + $values = $comparison->values(); + + /** @Then it returns the values compared against the field in order */ + self::assertSame(['admin', 'user'], $values); + } + public function testHasFieldWhenFieldDiffersThenIsFalse(): void { /** @Given an equality comparison on a field */ @@ -82,18 +70,6 @@ public function testHasFieldWhenFieldDiffersThenIsFalse(): void self::assertFalse($hasField); } - public function testFirstValueWhenMultipleValuesThenReturnsTheFirst(): void - { - /** @Given an IN comparison carrying several values */ - $comparison = Comparison::of(field: 'role', values: ['admin', 'user'], operator: Operator::IN); - - /** @When reading the first compared value */ - $firstValue = $comparison->firstValue(); - - /** @Then it returns the first of the compared values */ - self::assertSame('admin', $firstValue); - } - public function testHasOperatorWhenOperatorMatchesThenIsTrue(): void { /** @Given an equality comparison */ @@ -106,6 +82,18 @@ public function testHasOperatorWhenOperatorMatchesThenIsTrue(): void self::assertTrue($hasOperator); } + public function testOperatorThenReturnsTheComparisonOperator(): void + { + /** @Given an equality comparison */ + $comparison = Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL); + + /** @When reading the comparison operator */ + $operator = $comparison->operator(); + + /** @Then it returns the operator the comparison carries */ + self::assertSame(Operator::EQUAL, $operator); + } + public function testHasOperatorWhenOperatorDiffersThenIsFalse(): void { /** @Given an equality comparison */ @@ -117,4 +105,16 @@ public function testHasOperatorWhenOperatorDiffersThenIsFalse(): void /** @Then it reports that it does not carry the operator */ self::assertFalse($hasOperator); } + + public function testFirstValueWhenMultipleValuesThenReturnsTheFirst(): void + { + /** @Given an IN comparison carrying several values */ + $comparison = Comparison::of(field: 'role', values: ['admin', 'user'], operator: Operator::IN); + + /** @When reading the first compared value */ + $firstValue = $comparison->firstValue(); + + /** @Then it returns the first of the compared values */ + self::assertSame('admin', $firstValue); + } } diff --git a/tests/Unit/Cursor/CriteriaTest.php b/tests/Unit/Cursor/CriteriaTest.php index 7eba9fe..91b7e58 100644 --- a/tests/Unit/Cursor/CriteriaTest.php +++ b/tests/Unit/Cursor/CriteriaTest.php @@ -42,19 +42,6 @@ public function testFromQueryWhenEmptyThenComparisonsAreEmpty(): void self::assertSame([], $criteria->comparisons()); } - public function testKeysetWhenEffectiveSortIsEmptyThenThrowsSortIsRequired(): void - { - /** @Given a criteria parsed from a request carrying no sort and no schema default */ - $criteria = Criteria::fromQuery(request: Query::from(parameters: [])); - - /** @Then an exception indicating a deterministic order is required is raised */ - $this->expectException(SortIsRequired::class); - $this->expectExceptionMessage('A keyset requires a deterministic order, but the effective sort is empty.'); - - /** @When building the keyset view */ - $criteria->keyset(); - } - public function testKeysetWhenBuiltWithoutCursorThenBuildsCursorPage(): void { /** @Given a schema declaring a default sort over the identifier */ @@ -97,6 +84,33 @@ public function testKeysetWhenIncomingCursorPresentThenBuildsCursorPage(): void self::assertSame([10, 20], $page->items()->toArray()); } + public function testKeysetWhenEffectiveSortIsEmptyThenThrowsSortIsRequired(): void + { + /** @Given a criteria parsed from a request carrying no sort and no schema default */ + $criteria = Criteria::fromQuery(request: Query::from(parameters: [])); + + /** @Then an exception indicating a deterministic order is required is raised */ + $this->expectException(SortIsRequired::class); + $this->expectExceptionMessage('A keyset requires a deterministic order, but the effective sort is empty.'); + + /** @When building the keyset view */ + $criteria->keyset(); + } + + public function testFromQueryWhenCustomSchemaGivenThenAppliesItsDefaultPageSize(): void + { + /** @Given a schema lowering the default page size and declaring a default sort */ + $schema = Schema::create() + ->defaultPerPage(defaultPerPage: 5) + ->defaultSort(sort: Sort::fromExpression(expression: 'id')); + + /** @When building the keyset view from a query carrying no page size and the schema */ + $keyset = Criteria::fromQuery(request: Query::from(parameters: []), schema: $schema)->keyset(); + + /** @Then the keyset carries the schema default page size */ + self::assertSame(5, $keyset->limit()); + } + public function testFromQueryWhenCursorPresentThenKeysetCarriesPageSizeAndCursor(): void { /** @Given an opaque token produced from a single ordering key value */ @@ -121,18 +135,17 @@ public function testFromQueryWhenCursorPresentThenKeysetCarriesPageSizeAndCursor self::assertSame(['id' => 5], $keyset->cursor()); } - public function testFromQueryWhenCustomSchemaGivenThenAppliesItsDefaultPageSize(): void + public function testFromQueryWhenPerPageAboveMaximumThenThrowsPageSizeOutOfRange(): void { - /** @Given a schema lowering the default page size and declaring a default sort */ - $schema = Schema::create() - ->defaultPerPage(defaultPerPage: 5) - ->defaultSort(sort: Sort::fromExpression(expression: 'id')); + /** @Given query parameters carrying a page size above the default maximum */ + $query = Query::from(parameters: ['page' => ['size' => '500']]); - /** @When building the keyset view from a query carrying no page size and the schema */ - $keyset = Criteria::fromQuery(request: Query::from(parameters: []), schema: $schema)->keyset(); + /** @Then an exception indicating the page size is out of range is raised */ + $this->expectException(PageSizeOutOfRange::class); + $this->expectExceptionMessage('Page size'); - /** @Then the keyset carries the schema default page size */ - self::assertSame(5, $keyset->limit()); + /** @When building the criteria from the query */ + Criteria::fromQuery(request: $query); } public function testFromQueryWhenFilterAndSortGivenThenEachSpecificationIsValidated(): void @@ -157,17 +170,4 @@ public function testFromQueryWhenFilterAndSortGivenThenEachSpecificationIsValida /** @And the effective sort is the client sort */ self::assertEquals(Sort::fromExpression(expression: '-created_at'), $criteria->sort()); } - - public function testFromQueryWhenPerPageAboveMaximumThenThrowsPageSizeOutOfRange(): void - { - /** @Given query parameters carrying a page size above the default maximum */ - $query = Query::from(parameters: ['page' => ['size' => '500']]); - - /** @Then an exception indicating the page size is out of range is raised */ - $this->expectException(PageSizeOutOfRange::class); - $this->expectExceptionMessage('Page size'); - - /** @When building the criteria from the query */ - Criteria::fromQuery(request: $query); - } } diff --git a/tests/Unit/Cursor/KeysetTest.php b/tests/Unit/Cursor/KeysetTest.php index 0c319a1..3655d17 100644 --- a/tests/Unit/Cursor/KeysetTest.php +++ b/tests/Unit/Cursor/KeysetTest.php @@ -72,6 +72,21 @@ public function testPageWhenKeysOfGivenThenUsesTheExtractor(): void self::assertEquals(Pagination::from(cursor: Token::fromKeys(keys: [20]), perPage: 2), $page->next()); } + public function testCursorWhenNoIncomingCursorThenEverySortFieldIsNull(): void + { + /** @Given a keyset view built from a request carrying a sort over two fields */ + $keyset = Criteria::fromQuery( + request: Query::from(parameters: ['sort' => 'created_at,id', 'page' => ['size' => '2']]), + schema: $this->schema + )->keyset(); + + /** @When reading the incoming cursor key values */ + $cursor = $keyset->cursor(); + + /** @Then every sort field is present with a null value */ + self::assertSame(['created_at' => null, 'id' => null], $cursor); + } + public function testPageWhenNoKeysOfGivenThenDerivesKeysFromTheSortFields(): void { /** @Given a keyset view built from a request carrying a sort and a page size of two */ @@ -90,21 +105,6 @@ public function testPageWhenNoKeysOfGivenThenDerivesKeysFromTheSortFields(): voi self::assertEquals(Pagination::from(cursor: Token::fromKeys(keys: [20]), perPage: 2), $page->next()); } - public function testCursorWhenNoIncomingCursorThenEverySortFieldIsNull(): void - { - /** @Given a keyset view built from a request carrying a sort over two fields */ - $keyset = Criteria::fromQuery( - request: Query::from(parameters: ['sort' => 'created_at,id', 'page' => ['size' => '2']]), - schema: $this->schema - )->keyset(); - - /** @When reading the incoming cursor key values */ - $cursor = $keyset->cursor(); - - /** @Then every sort field is present with a null value */ - self::assertSame(['created_at' => null, 'id' => null], $cursor); - } - public function testCursorWhenIncomingCursorGivenThenKeysValuesBySortField(): void { /** @Given an opaque token produced from the ordering key values */ diff --git a/tests/Unit/Cursor/PageTest.php b/tests/Unit/Cursor/PageTest.php index 500839d..6eb7283 100644 --- a/tests/Unit/Cursor/PageTest.php +++ b/tests/Unit/Cursor/PageTest.php @@ -34,8 +34,8 @@ public function testNavigationWhenNoExtraElementThenHasNoNextPage(): void /** @And a cursor page built from items fetched within the page size */ $page = Page::from( sort: $this->sort, - filter: $this->filter, items: [10, 20], + filter: $this->filter, keysOf: static fn(int $element): array => [$element], pagination: $pagination ); @@ -53,24 +53,21 @@ public function testNavigationWhenNoExtraElementThenHasNoNextPage(): void self::assertSame(['per_page' => 2, 'has_next' => false], $page->metadata()); } - public function testToResponseWhenCursorPageGivenThenRendersBodyAndLinkHeader(): void + public function testToResponseWhenFirstCursorPageThenSelfLinkIsCursorStyle(): void { - /** @Given an opaque token produced from ordering key values */ - $token = Token::fromKeys(keys: [5])->toString(); - - /** @And a cursor page built over items fetched for the page size plus one */ + /** @Given a cursor page on the first page with no incoming cursor */ $page = Page::from( sort: $this->sort, - filter: $this->filter, items: [10, 20, 30], + filter: $this->filter, keysOf: static fn(int $element): array => [$element], - pagination: Pagination::from(cursor: Token::from(token: $token), perPage: 2) + pagination: Pagination::from(cursor: Token::none(), perPage: 2) ); - /** @When rendering the cursor page as a JSON:API response over the orders base URI */ + /** @When rendering the first cursor page as a JSON:API response over the orders base URI */ $response = $page->toResponse(baseUri: '/v1/orders'); - /** @Then the response body carries the trimmed data, the meta, and the forward-only links */ + /** @Then the self link is cursor-style, carrying only the page size and never an offset page number */ self::assertSame([ 'data' => [10, 20], 'meta' => [ @@ -78,33 +75,30 @@ public function testToResponseWhenCursorPageGivenThenRendersBodyAndLinkHeader(): 'has_next' => true ], 'links' => [ - 'self' => sprintf('/v1/orders?page[cursor]=%s&page[size]=2', $token), + 'self' => '/v1/orders?page[size]=2', 'next' => sprintf('/v1/orders?page[cursor]=%s&page[size]=2', Token::fromKeys(keys: [20])->toString()) ] ], json_decode($response->getBody()->getContents(), true)); - - /** @And the Link header folds the self and next relations */ - self::assertSame(implode(', ', [ - sprintf('; rel="self"', $token), - sprintf('; rel="next"', Token::fromKeys(keys: [20])->toString()) - ]), $response->getHeaderLine('Link')); } - public function testToResponseWhenFirstCursorPageThenSelfLinkIsCursorStyle(): void + public function testToResponseWhenCursorPageGivenThenRendersBodyAndLinkHeader(): void { - /** @Given a cursor page on the first page with no incoming cursor */ + /** @Given an opaque token produced from ordering key values */ + $token = Token::fromKeys(keys: [5])->toString(); + + /** @And a cursor page built over items fetched for the page size plus one */ $page = Page::from( sort: $this->sort, - filter: $this->filter, items: [10, 20, 30], + filter: $this->filter, keysOf: static fn(int $element): array => [$element], - pagination: Pagination::from(cursor: Token::none(), perPage: 2) + pagination: Pagination::from(cursor: Token::from(token: $token), perPage: 2) ); - /** @When rendering the first cursor page as a JSON:API response over the orders base URI */ + /** @When rendering the cursor page as a JSON:API response over the orders base URI */ $response = $page->toResponse(baseUri: '/v1/orders'); - /** @Then the self link is cursor-style, carrying only the page size and never an offset page number */ + /** @Then the response body carries the trimmed data, the meta, and the forward-only links */ self::assertSame([ 'data' => [10, 20], 'meta' => [ @@ -112,10 +106,16 @@ public function testToResponseWhenFirstCursorPageThenSelfLinkIsCursorStyle(): vo 'has_next' => true ], 'links' => [ - 'self' => '/v1/orders?page[size]=2', + 'self' => sprintf('/v1/orders?page[cursor]=%s&page[size]=2', $token), 'next' => sprintf('/v1/orders?page[cursor]=%s&page[size]=2', Token::fromKeys(keys: [20])->toString()) ] ], json_decode($response->getBody()->getContents(), true)); + + /** @And the Link header folds the self and next relations */ + self::assertSame(implode(', ', [ + sprintf('; rel="self"', $token), + sprintf('; rel="next"', Token::fromKeys(keys: [20])->toString()) + ]), $response->getHeaderLine('Link')); } public function testNavigationWhenExtraElementFetchedThenListsOnlyTheNextTarget(): void @@ -123,8 +123,8 @@ public function testNavigationWhenExtraElementFetchedThenListsOnlyTheNextTarget( /** @Given a keyset page fetched for the page size plus one with an absent incoming cursor */ $page = Page::from( sort: $this->sort, - filter: $this->filter, items: [10, 20, 30], + filter: $this->filter, keysOf: static fn(int $element): array => [$element], pagination: Pagination::from(cursor: Token::none(), perPage: 2) ); @@ -150,8 +150,8 @@ public function testMapWhenTransformationGivenThenProjectsItemsAndPreservesTheCu /** @Given a cursor page built over items fetched for the page size plus one */ $page = Page::from( sort: $this->sort, - filter: $this->filter, items: [10, 20, 30], + filter: $this->filter, keysOf: static fn(int $element): array => [$element], pagination: Pagination::from(cursor: Token::none(), perPage: 2) ); @@ -180,8 +180,8 @@ public function testToResponseWhenPageIsMappedThenRendersProjectedDataAndPreserv /** @And a cursor page built over array rows then projected to their identifiers */ $page = Page::from( sort: $this->sort, - filter: $this->filter, items: [['id' => 10], ['id' => 20], ['id' => 30]], + filter: $this->filter, keysOf: static fn(array $row): array => [$row['id']], pagination: Pagination::from(cursor: Token::from(token: $token), perPage: 2) )->map(transformation: static fn(array $row): int => (int)$row['id']); @@ -211,8 +211,8 @@ public function testNavigationWhenExtraElementFetchedThenHasNextAndNextCursorAnc /** @And a cursor page built over items fetched for the page size plus one */ $page = Page::from( sort: $this->sort, - filter: $this->filter, items: [10, 20, 30], + filter: $this->filter, keysOf: static fn(int $element): array => [$element], pagination: $pagination ); diff --git a/tests/Unit/Cursor/PaginationTest.php b/tests/Unit/Cursor/PaginationTest.php index 66d8208..382da0b 100644 --- a/tests/Unit/Cursor/PaginationTest.php +++ b/tests/Unit/Cursor/PaginationTest.php @@ -35,6 +35,18 @@ public function testToQueryStringWhenCursorAbsentThenRendersOnlyTheSize(): void self::assertSame('page[size]=10', $queryString); } + public function testToQueryStringWhenCursorPresentThenRendersCursorAndSize(): void + { + /** @Given a cursor pagination carrying an incoming cursor and a page size */ + $pagination = Pagination::from(cursor: Token::from(token: 'abc'), perPage: 10); + + /** @When rendering it as a query string */ + $queryString = $pagination->toQueryString(); + + /** @Then it renders the cursor token followed by the page size in the JSON:API page family */ + self::assertSame('page[cursor]=abc&page[size]=10', $queryString); + } + public function testFromWhenAbsentCursorGivenThenCarriesLimitAndAbsentCursor(): void { /** @Given a cursor pagination built from an absent cursor and a page size of 20 */ @@ -62,18 +74,6 @@ public function testFromWhenPageSizeBelowMinimumThenThrowsPageSizeOutOfRange(): Pagination::from(cursor: $cursor, perPage: 0); } - public function testToQueryStringWhenCursorPresentThenRendersCursorAndSize(): void - { - /** @Given a cursor pagination carrying an incoming cursor and a page size */ - $pagination = Pagination::from(cursor: Token::from(token: 'abc'), perPage: 10); - - /** @When rendering it as a query string */ - $queryString = $pagination->toQueryString(); - - /** @Then it renders the cursor token followed by the page size in the JSON:API page family */ - self::assertSame('page[cursor]=abc&page[size]=10', $queryString); - } - public function testFromWhenIncomingCursorGivenThenCarriesLimitAndTheCursorToken(): void { /** @Given a cursor pagination built from an incoming cursor and a page size of 50 */ diff --git a/tests/Unit/Cursor/TokenTest.php b/tests/Unit/Cursor/TokenTest.php index e295307..dfead4d 100644 --- a/tests/Unit/Cursor/TokenTest.php +++ b/tests/Unit/Cursor/TokenTest.php @@ -67,30 +67,6 @@ public function testNoneThenAbsentWithEmptyKeysAndEmptyToken(): void self::assertSame('', $token->toString()); } - public function testFromKeysWhenKeysGivenThenDecodesToTheSameKeys(): void - { - /** @Given a token backed by ordering key values */ - $token = Token::fromKeys(keys: ['2024-01-01', 42]); - - /** @When decoding the token into key values */ - $keys = $token->toArray(); - - /** @Then it yields the original key values */ - self::assertSame(['2024-01-01', 42], $keys); - } - - public function testFromKeysWhenKeysAreGappedThenDecodesToAReindexedList(): void - { - /** @Given a token backed by ordering key values held under gapped integer keys */ - $token = Token::fromKeys(keys: [5 => 'x', 9 => 'y']); - - /** @When decoding the token into key values */ - $keys = $token->toArray(); - - /** @Then it yields the values as a zero-based list */ - self::assertSame(['x', 'y'], $keys); - } - public function testKeyedByWhenTokenAbsentThenEveryFieldIsNull(): void { /** @Given an absent token */ @@ -103,6 +79,18 @@ public function testKeyedByWhenTokenAbsentThenEveryFieldIsNull(): void self::assertSame(['created_at' => null, 'id' => null], $keyed); } + public function testFromKeysWhenKeysGivenThenDecodesToTheSameKeys(): void + { + /** @Given a token backed by ordering key values */ + $token = Token::fromKeys(keys: ['2024-01-01', 42]); + + /** @When decoding the token into key values */ + $keys = $token->toArray(); + + /** @Then it yields the original key values */ + self::assertSame(['2024-01-01', 42], $keys); + } + public function testKeyedByWhenKeysPresentThenValuesAreKeyedByField(): void { /** @Given a token backed by ordering key values */ @@ -115,6 +103,18 @@ public function testKeyedByWhenKeysPresentThenValuesAreKeyedByField(): void self::assertSame(['created_at' => '2024-01-01', 'id' => 42], $keyed); } + public function testFromKeysWhenEncodedThenTokenIsUrlSafeAndUnpadded(): void + { + /** @Given a token backed by key values whose base64 payload carries plus, slash, and padding */ + $token = Token::fromKeys(keys: ['>>>???']); + + /** @When rendering the opaque token */ + $rendered = $token->toString(); + + /** @Then it renders the base64url form, translating plus and slash and dropping the padding */ + self::assertSame('WyI-Pj4_Pz8iXQ', $rendered); + } + public function testKeyedByWhenCountMismatchesThenThrowsCursorIsInvalid(): void { /** @Given a token backed by a single key value */ @@ -127,30 +127,16 @@ public function testKeyedByWhenCountMismatchesThenThrowsCursorIsInvalid(): void $token->keyedBy(fields: ['created_at', 'id']); } - public function testToArrayWhenTokenCarriesInvalidCharacterThenThrowsCursorIsInvalid(): void + public function testFromKeysWhenKeysAreGappedThenDecodesToAReindexedList(): void { - /** @Given a token carrying a character outside the base64url alphabet */ - $token = Token::from(token: 'WzEsMl0!'); - - /** @Then an exception indicating the cursor token is invalid is raised */ - $this->expectException(CursorIsInvalid::class); - $this->expectExceptionMessage('could not be decoded'); + /** @Given a token backed by ordering key values held under gapped integer keys */ + $token = Token::fromKeys(keys: [5 => 'x', 9 => 'y']); /** @When decoding the token into key values */ - $token->toArray(); - } - - public function testToArrayWhenTokenDecodesToScalarThenThrowsCursorIsInvalid(): void - { - /** @Given a base64url token whose decoded payload is the JSON scalar 5 */ - $token = Token::from(token: rtrim(strtr(base64_encode('5'), '+/', '-_'), '=')); - - /** @Then an exception indicating the cursor token is invalid is raised */ - $this->expectException(CursorIsInvalid::class); - $this->expectExceptionMessage('could not be decoded'); + $keys = $token->toArray(); - /** @When decoding the token into key values */ - $token->toArray(); + /** @Then it yields the values as a zero-based list */ + self::assertSame(['x', 'y'], $keys); } public function testToArrayWhenTokenDecodesToObjectThenThrowsCursorIsInvalid(): void @@ -166,10 +152,10 @@ public function testToArrayWhenTokenDecodesToObjectThenThrowsCursorIsInvalid(): $token->toArray(); } - public function testToArrayWhenTokenDecodesToListWithNestedStructureThenThrowsCursorIsInvalid(): void + public function testToArrayWhenTokenDecodesToScalarThenThrowsCursorIsInvalid(): void { - /** @Given a base64url token whose decoded list carries a nested array and object */ - $token = Token::from(token: rtrim(strtr(base64_encode('[["x"],{"a":1}]'), '+/', '-_'), '=')); + /** @Given a base64url token whose decoded payload is the JSON scalar 5 */ + $token = Token::from(token: rtrim(strtr(base64_encode('5'), '+/', '-_'), '=')); /** @Then an exception indicating the cursor token is invalid is raised */ $this->expectException(CursorIsInvalid::class); @@ -194,16 +180,17 @@ public function testFromKeysWhenRoundTrippedThroughTokenThenYieldsTheOriginalKey self::assertSame(['2024-01-01', 42], $keys); } - public function testFromKeysWhenEncodedThenTokenIsUrlSafeAndUnpadded(): void + public function testToArrayWhenTokenCarriesInvalidCharacterThenThrowsCursorIsInvalid(): void { - /** @Given a token backed by key values whose base64 payload carries plus, slash, and padding */ - $token = Token::fromKeys(keys: ['>>>???']); + /** @Given a token carrying a character outside the base64url alphabet */ + $token = Token::from(token: 'WzEsMl0!'); - /** @When rendering the opaque token */ - $rendered = $token->toString(); + /** @Then an exception indicating the cursor token is invalid is raised */ + $this->expectException(CursorIsInvalid::class); + $this->expectExceptionMessage('could not be decoded'); - /** @Then it renders the base64url form, translating plus and slash and dropping the padding */ - self::assertSame('WyI-Pj4_Pz8iXQ', $rendered); + /** @When decoding the token into key values */ + $token->toArray(); } public function testFromKeysWhenRoundTrippedThroughUrlSafeTokenThenYieldsTheOriginalKeys(): void @@ -229,4 +216,17 @@ public function testConstructorWhenInvokedThroughReflectionThenInstantiatesTheSt /** @Then the static-only cursor codec is instantiated */ self::assertInstanceOf(CursorCodec::class, $codec); } + + public function testToArrayWhenTokenDecodesToListWithNestedStructureThenThrowsCursorIsInvalid(): void + { + /** @Given a base64url token whose decoded list carries a nested array and object */ + $token = Token::from(token: rtrim(strtr(base64_encode('[["x"],{"a":1}]'), '+/', '-_'), '=')); + + /** @Then an exception indicating the cursor token is invalid is raised */ + $this->expectException(CursorIsInvalid::class); + $this->expectExceptionMessage('could not be decoded'); + + /** @When decoding the token into key values */ + $token->toArray(); + } } diff --git a/tests/Unit/DirectionTest.php b/tests/Unit/DirectionTest.php index a75d95c..58c9ddc 100644 --- a/tests/Unit/DirectionTest.php +++ b/tests/Unit/DirectionTest.php @@ -11,7 +11,7 @@ final class DirectionTest extends TestCase { #[DataProvider('directionCases')] - public function testFromWhenTokenGivenThenResolvesToCase(Direction $direction, string $token): void + public function testFromWhenTokenGivenThenResolvesToCase(string $token, Direction $direction): void { /** @Given a canonical token and the direction it maps to */ @@ -23,7 +23,7 @@ public function testFromWhenTokenGivenThenResolvesToCase(Direction $direction, s } #[DataProvider('directionCases')] - public function testValueWhenCaseGivenThenExposesCanonicalToken(Direction $direction, string $token): void + public function testValueWhenCaseGivenThenExposesCanonicalToken(string $token, Direction $direction): void { /** @Given a sort direction and its canonical token */ @@ -36,8 +36,8 @@ public function testValueWhenCaseGivenThenExposesCanonicalToken(Direction $direc #[DataProvider('prefixCases')] public function testPrefixWhenCaseGivenThenReturnsTheSortExpressionPrefix( - Direction $direction, - string $prefix + string $prefix, + Direction $direction ): void { /** @Given a sort direction and its sort-expression prefix */ diff --git a/tests/Unit/EndToEndTest.php b/tests/Unit/EndToEndTest.php index 64f5902..ab5a113 100644 --- a/tests/Unit/EndToEndTest.php +++ b/tests/Unit/EndToEndTest.php @@ -36,7 +36,7 @@ public function testPipelineWhenOffsetRequestGivenThenPageRendersTheResponse(): $base = '/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id'; /** @And the third page of a 480-element result built from the criteria */ - $page = $criteria->page(total: 480, items: ['a', 'b']); + $page = $criteria->page(items: ['a', 'b'], total: 480); /** @When rendering the page as a JSON:API response over the orders base URI */ $response = $page->toResponse(baseUri: '/v1/orders'); @@ -62,43 +62,6 @@ public function testPipelineWhenOffsetRequestGivenThenPageRendersTheResponse(): ], json_decode($response->getBody()->getContents(), true)); } - public function testPipelineWhenOffsetRequestGivenThenLinkHeaderFoldsEveryRelation(): void - { - /** @Given the query contract of the orders endpoint */ - $schema = Schema::create() - ->sortable(fields: ['created_at', 'id']) - ->filterable(field: 'total', operators: [Operator::GREATER_THAN_OR_EQUAL]) - ->filterable(field: 'status', operators: [Operator::EQUAL]); - - /** @And the canonical request query parameters */ - $query = Query::from(parameters: [ - 'filter' => 'status==paid;total=ge=100', - 'sort' => '-created_at,id', - 'page' => ['number' => '3', 'size' => '20'] - ]); - - /** @And the criteria parsed from those parameters */ - $criteria = OffsetCriteria::fromQuery(request: $query, schema: $schema); - - /** @And the base URI the relations render against */ - $base = '/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id'; - - /** @And the Link header template rendered per relation */ - $template = '<%s&page[number]=%d&page[size]=20>; rel="%s"'; - - /** @When rendering the page as a JSON:API response and reading its RFC 8288 Link header line */ - $header = $criteria->page(total: 480, items: [])->toResponse(baseUri: '/v1/orders')->getHeaderLine('Link'); - - /** @Then the line folds the five relations in navigation order */ - self::assertSame(implode(', ', [ - sprintf($template, $base, 3, 'self'), - sprintf($template, $base, 1, 'first'), - sprintf($template, $base, 2, 'prev'), - sprintf($template, $base, 4, 'next'), - sprintf($template, $base, 24, 'last') - ]), $header); - } - public function testPipelineWhenCursorRequestGivenThenCursorPageRendersTheResponse(): void { /** @Given the query contract of the orders endpoint */ @@ -134,4 +97,41 @@ public function testPipelineWhenCursorRequestGivenThenCursorPageRendersTheRespon ] ], json_decode($response->getBody()->getContents(), true)); } + + public function testPipelineWhenOffsetRequestGivenThenLinkHeaderFoldsEveryRelation(): void + { + /** @Given the query contract of the orders endpoint */ + $schema = Schema::create() + ->sortable(fields: ['created_at', 'id']) + ->filterable(field: 'total', operators: [Operator::GREATER_THAN_OR_EQUAL]) + ->filterable(field: 'status', operators: [Operator::EQUAL]); + + /** @And the canonical request query parameters */ + $query = Query::from(parameters: [ + 'filter' => 'status==paid;total=ge=100', + 'sort' => '-created_at,id', + 'page' => ['number' => '3', 'size' => '20'] + ]); + + /** @And the criteria parsed from those parameters */ + $criteria = OffsetCriteria::fromQuery(request: $query, schema: $schema); + + /** @And the base URI the relations render against */ + $base = '/v1/orders?filter=status==paid;total=ge=100&sort=-created_at,id'; + + /** @And the Link header template rendered per relation */ + $template = '<%s&page[number]=%d&page[size]=20>; rel="%s"'; + + /** @When rendering the page as a JSON:API response and reading its RFC 8288 Link header line */ + $header = $criteria->page(items: [], total: 480)->toResponse(baseUri: '/v1/orders')->getHeaderLine('Link'); + + /** @Then the line folds the five relations in navigation order */ + self::assertSame(implode(', ', [ + sprintf($template, $base, 3, 'self'), + sprintf($template, $base, 1, 'first'), + sprintf($template, $base, 2, 'prev'), + sprintf($template, $base, 4, 'next'), + sprintf($template, $base, 24, 'last') + ]), $header); + } } diff --git a/tests/Unit/FilterTest.php b/tests/Unit/FilterTest.php index 9642926..2b4f088 100644 --- a/tests/Unit/FilterTest.php +++ b/tests/Unit/FilterTest.php @@ -45,21 +45,6 @@ public function testFromQueryWhenNoFilterThenComparisonsAreEmpty(): void self::assertSame([], $comparisons); } - public function testFromQueryWhenSingleComparisonThenComparisonCarriesFieldAndValue(): void - { - /** @Given a query carrying a single equality comparison */ - $query = Query::from(parameters: ['filter' => 'status==paid']); - - /** @When reading the validated comparisons */ - $comparisons = Criteria::fromQuery(request: $query, schema: $this->schema)->comparisons(); - - /** @Then the only comparison is an equality on the named field with its value */ - self::assertEquals( - [Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL)], - $comparisons - ); - } - public function testFromQueryWhenAndGroupThenComparisonsCarryEveryLeaf(): void { /** @Given a query carrying an AND expression of two comparisons */ @@ -105,6 +90,19 @@ public function testFromQueryWhenNotInListThenComparisonCarriesEveryValue(): voi ); } + public function testFromQueryWhenOrGroupThenThrowsFilterShapeNotSupported(): void + { + /** @Given a query carrying an OR expression of two comparisons */ + $query = Query::from(parameters: ['filter' => 'a==1,b==2']); + + /** @Then an exception carrying the raw filter query string is raised */ + $this->expectException(FilterShapeNotSupported::class); + $this->expectExceptionMessage('Filter shape is not supported.'); + + /** @When building the criteria from the query */ + Criteria::fromQuery(request: $query, schema: $this->schema); + } + public function testFromQueryWhenDoubleQuotedValueThenComparisonStripsQuotes(): void { /** @Given a query carrying a double-quoted value with whitespace */ @@ -135,6 +133,19 @@ public function testFromQueryWhenSingleQuotedValueThenComparisonStripsQuotes(): ); } + public function testFromQueryWhenNestedGroupThenThrowsFilterShapeNotSupported(): void + { + /** @Given a query whose parentheses nest an OR group inside an AND group */ + $query = Query::from(parameters: ['filter' => '(a==1,b==2);c==3']); + + /** @Then an exception carrying the raw filter query string is raised */ + $this->expectException(FilterShapeNotSupported::class); + $this->expectExceptionMessage('Filter shape <(a==1,b==2);c==3> is not supported.'); + + /** @When building the criteria from the query */ + Criteria::fromQuery(request: $query, schema: $this->schema); + } + public function testFromQueryWhenEscapedQuoteInValueThenComparisonKeepsTheQuote(): void { /** @Given a query whose double-quoted value carries an escaped double quote */ @@ -150,89 +161,57 @@ public function testFromQueryWhenEscapedQuoteInValueThenComparisonKeepsTheQuote( ); } - public function testFromQueryWhenEscapedBackslashInValueThenComparisonKeepsTheBackslash(): void + public function testFromQueryWhenFieldNotAllowedThenThrowsFilterFieldNotAllowed(): void { - /** @Given a query whose double-quoted value carries an escaped backslash */ - $query = Query::from(parameters: ['filter' => 'name=="a\\\\b"']); + /** @Given a schema allowing only the status field */ + $schema = Schema::create()->filterable(field: 'status', operators: [Operator::EQUAL]); - /** @When reading the validated comparisons */ - $comparisons = Criteria::fromQuery(request: $query, schema: $this->schema)->comparisons(); + /** @And a query filtering by a field that was never allowed */ + $query = Query::from(parameters: ['filter' => 'discount==10']); - /** @Then the comparison carries the value with the escaped backslash unescaped */ - self::assertEquals( - [Comparison::of(field: 'name', values: ['a\\b'], operator: Operator::EQUAL)], - $comparisons - ); + /** @Then an exception indicating the filter field is not allowed is raised */ + $this->expectException(FilterFieldNotAllowed::class); + $this->expectExceptionMessage('Filter field is not allowed.'); + + /** @When building the criteria from the query */ + Criteria::fromQuery(request: $query, schema: $schema); } - public function testFromQueryWhenParenthesizedComparisonThenComparisonIsReturned(): void + public function testFromQueryWhenValueBreaksKindThenThrowsFilterValueNotAllowed(): void { - /** @Given a query wrapping a single comparison in parentheses */ - $query = Query::from(parameters: ['filter' => '(status==paid)']); - - /** @When reading the validated comparisons */ - $comparisons = Criteria::fromQuery(request: $query, schema: $this->schema)->comparisons(); - - /** @Then the only comparison is the unwrapped equality */ - self::assertEquals( - [Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL)], - $comparisons + /** @Given a schema expecting a date-time kind on the created_at field */ + $schema = Schema::create()->filterable( + field: 'created_at', + operators: [Operator::GREATER_THAN], + kind: ValueKind::DATETIME ); - } - public function testFromQueryWhenParenthesizedAndGroupThenComparisonsCarryEveryLeaf(): void - { - /** @Given a query wrapping an AND expression of two comparisons in parentheses */ - $query = Query::from(parameters: ['filter' => '(a==1;b==2)']); + /** @And a query whose value is not a valid date-time */ + $query = Query::from(parameters: ['filter' => 'created_at=gt=not-a-date']); - /** @When reading the validated comparisons */ - $comparisons = Criteria::fromQuery(request: $query, schema: $this->schema)->comparisons(); + /** @Then an exception indicating the value does not match the expected kind is raised */ + $this->expectException(FilterValueNotAllowed::class); + $this->expectExceptionMessage('does not match the datetime kind'); - /** @Then the comparisons carry both leaves in order */ - self::assertEquals([ - Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), - Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) - ], $comparisons); + /** @When building the criteria from the query */ + Criteria::fromQuery(request: $query, schema: $schema); } - public function testFromQueryWhenFilterNestedToTheMaximumDepthThenComparisonIsReturned(): void + public function testFromQueryWhenParenthesizedComparisonThenComparisonIsReturned(): void { - /** @Given a filter template wrapping a comparison in placeholders */ - $template = '%sa==1%s'; - - /** @And a query whose filter nests parentheses up to the maximum depth */ - $query = Query::from(parameters: [ - 'filter' => sprintf($template, str_repeat('(', 32), str_repeat(')', 32)) - ]); + /** @Given a query wrapping a single comparison in parentheses */ + $query = Query::from(parameters: ['filter' => '(status==paid)']); /** @When reading the validated comparisons */ $comparisons = Criteria::fromQuery(request: $query, schema: $this->schema)->comparisons(); - /** @Then the deeply nested parentheses collapse to the single unwrapped comparison */ + /** @Then the only comparison is the unwrapped equality */ self::assertEquals( - [Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL)], + [Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL)], $comparisons ); } - public function testFromQueryWhenFilterNestedBeyondTheMaximumDepthThenThrowsFilterExpressionIsInvalid(): void - { - /** @Given a filter template wrapping a comparison in placeholders */ - $template = '%sa==1%s'; - - /** @And a query whose filter nests parentheses one level beyond the maximum depth */ - $query = Query::from(parameters: [ - 'filter' => sprintf($template, str_repeat('(', 33), str_repeat(')', 33)) - ]); - - /** @Then an exception indicating the filter expression is invalid is raised */ - $this->expectException(FilterExpressionIsInvalid::class); - $this->expectExceptionMessage('could not be parsed'); - - /** @When building the criteria from the query */ - Criteria::fromQuery(request: $query, schema: $this->schema); - } - public function testFromQueryWhenDateTimeValueMatchesKindThenComparisonIsReturned(): void { /** @Given a schema allowing a date-time field under the greater-than operator */ @@ -256,19 +235,6 @@ public function testFromQueryWhenDateTimeValueMatchesKindThenComparisonIsReturne )], $comparisons); } - public function testFromQueryWhenOrGroupThenThrowsFilterShapeNotSupported(): void - { - /** @Given a query carrying an OR expression of two comparisons */ - $query = Query::from(parameters: ['filter' => 'a==1,b==2']); - - /** @Then an exception carrying the raw filter query string is raised */ - $this->expectException(FilterShapeNotSupported::class); - $this->expectExceptionMessage('Filter shape is not supported.'); - - /** @When building the criteria from the query */ - Criteria::fromQuery(request: $query, schema: $this->schema); - } - public function testFromQueryWhenMixedPrecedenceThenThrowsFilterShapeNotSupported(): void { /** @Given a query mixing AND and OR connectives so the top filter is an OR group */ @@ -282,33 +248,69 @@ public function testFromQueryWhenMixedPrecedenceThenThrowsFilterShapeNotSupporte Criteria::fromQuery(request: $query, schema: $this->schema); } - public function testFromQueryWhenNestedGroupThenThrowsFilterShapeNotSupported(): void + public function testFromQueryWhenValueNotPermittedThenThrowsFilterValueNotAllowed(): void { - /** @Given a query whose parentheses nest an OR group inside an AND group */ - $query = Query::from(parameters: ['filter' => '(a==1,b==2);c==3']); + /** @Given a schema permitting only a fixed set of status values */ + $schema = Schema::create()->filterable( + field: 'status', + operators: [Operator::EQUAL], + values: ['paid', 'pending'] + ); - /** @Then an exception carrying the raw filter query string is raised */ - $this->expectException(FilterShapeNotSupported::class); - $this->expectExceptionMessage('Filter shape <(a==1,b==2);c==3> is not supported.'); + /** @And a query filtering by a value outside the permitted set */ + $query = Query::from(parameters: ['filter' => 'status==shipped']); + + /** @Then an exception indicating the value is not permitted is raised */ + $this->expectException(FilterValueNotAllowed::class); + $this->expectExceptionMessage('Value is not permitted for filter field .'); /** @When building the criteria from the query */ - Criteria::fromQuery(request: $query, schema: $this->schema); + Criteria::fromQuery(request: $query, schema: $schema); } - public function testFromQueryWhenFieldNotAllowedThenThrowsFilterFieldNotAllowed(): void + public function testFromQueryWhenParenthesizedAndGroupThenComparisonsCarryEveryLeaf(): void { - /** @Given a schema allowing only the status field */ - $schema = Schema::create()->filterable(field: 'status', operators: [Operator::EQUAL]); + /** @Given a query wrapping an AND expression of two comparisons in parentheses */ + $query = Query::from(parameters: ['filter' => '(a==1;b==2)']); - /** @And a query filtering by a field that was never allowed */ - $query = Query::from(parameters: ['filter' => 'discount==10']); + /** @When reading the validated comparisons */ + $comparisons = Criteria::fromQuery(request: $query, schema: $this->schema)->comparisons(); - /** @Then an exception indicating the filter field is not allowed is raised */ - $this->expectException(FilterFieldNotAllowed::class); - $this->expectExceptionMessage('Filter field is not allowed.'); + /** @Then the comparisons carry both leaves in order */ + self::assertEquals([ + Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), + Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) + ], $comparisons); + } - /** @When building the criteria from the query */ - Criteria::fromQuery(request: $query, schema: $schema); + public function testFromQueryWhenSingleComparisonThenComparisonCarriesFieldAndValue(): void + { + /** @Given a query carrying a single equality comparison */ + $query = Query::from(parameters: ['filter' => 'status==paid']); + + /** @When reading the validated comparisons */ + $comparisons = Criteria::fromQuery(request: $query, schema: $this->schema)->comparisons(); + + /** @Then the only comparison is an equality on the named field with its value */ + self::assertEquals( + [Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL)], + $comparisons + ); + } + + #[DataProvider('comparisonOperatorCases')] + public function testFromQueryWhenComparisonOperatorThenComparisonCarriesThatOperator( + string $expression, + Operator $expected + ): void { + /** @Given a query carrying a binary comparison using one RSQL operator */ + $query = Query::from(parameters: ['filter' => $expression]); + + /** @When reading the validated comparisons */ + $comparisons = Criteria::fromQuery(request: $query, schema: $this->schema)->comparisons(); + + /** @Then the only comparison carries the expected operator */ + self::assertEquals([Comparison::of(field: 'a', values: ['b'], operator: $expected)], $comparisons); } public function testFromQueryWhenOperatorNotAllowedThenThrowsFilterOperatorNotAllowed(): void @@ -327,44 +329,54 @@ public function testFromQueryWhenOperatorNotAllowedThenThrowsFilterOperatorNotAl Criteria::fromQuery(request: $query, schema: $schema); } - public function testFromQueryWhenValueNotPermittedThenThrowsFilterValueNotAllowed(): void + public function testFromQueryWhenFilterNestedToTheMaximumDepthThenComparisonIsReturned(): void { - /** @Given a schema permitting only a fixed set of status values */ - $schema = Schema::create()->filterable( - field: 'status', - operators: [Operator::EQUAL], - values: ['paid', 'pending'] - ); + /** @Given a filter template wrapping a comparison in placeholders */ + $template = '%sa==1%s'; - /** @And a query filtering by a value outside the permitted set */ - $query = Query::from(parameters: ['filter' => 'status==shipped']); + /** @And a query whose filter nests parentheses up to the maximum depth */ + $query = Query::from(parameters: [ + 'filter' => sprintf($template, str_repeat('(', 32), str_repeat(')', 32)) + ]); - /** @Then an exception indicating the value is not permitted is raised */ - $this->expectException(FilterValueNotAllowed::class); - $this->expectExceptionMessage('Value is not permitted for filter field .'); + /** @When reading the validated comparisons */ + $comparisons = Criteria::fromQuery(request: $query, schema: $this->schema)->comparisons(); - /** @When building the criteria from the query */ - Criteria::fromQuery(request: $query, schema: $schema); + /** @Then the deeply nested parentheses collapse to the single unwrapped comparison */ + self::assertEquals( + [Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL)], + $comparisons + ); } - public function testFromQueryWhenValueBreaksKindThenThrowsFilterValueNotAllowed(): void + public function testFromQueryWhenEscapedBackslashInValueThenComparisonKeepsTheBackslash(): void { - /** @Given a schema expecting a date-time kind on the created_at field */ - $schema = Schema::create()->filterable( - field: 'created_at', - operators: [Operator::GREATER_THAN], - kind: ValueKind::DATETIME + /** @Given a query whose double-quoted value carries an escaped backslash */ + $query = Query::from(parameters: ['filter' => 'name=="a\\\\b"']); + + /** @When reading the validated comparisons */ + $comparisons = Criteria::fromQuery(request: $query, schema: $this->schema)->comparisons(); + + /** @Then the comparison carries the value with the escaped backslash unescaped */ + self::assertEquals( + [Comparison::of(field: 'name', values: ['a\\b'], operator: Operator::EQUAL)], + $comparisons ); + } - /** @And a query whose value is not a valid date-time */ - $query = Query::from(parameters: ['filter' => 'created_at=gt=not-a-date']); + #[DataProvider('malformedExpressionCases')] + public function testFromQueryWhenMalformedExpressionThenThrowsFilterExpressionIsInvalid( + string $expression + ): void { + /** @Given a query carrying a filter expression that breaks the RSQL grammar */ + $query = Query::from(parameters: ['filter' => $expression]); - /** @Then an exception indicating the value does not match the expected kind is raised */ - $this->expectException(FilterValueNotAllowed::class); - $this->expectExceptionMessage('does not match the datetime kind'); + /** @Then an exception indicating the filter expression is invalid is raised */ + $this->expectException(FilterExpressionIsInvalid::class); + $this->expectExceptionMessage('could not be parsed'); /** @When building the criteria from the query */ - Criteria::fromQuery(request: $query, schema: $schema); + Criteria::fromQuery(request: $query, schema: $this->schema); } public function testFromQueryWhenInListHasDisallowedValueThenThrowsFilterValueNotAllowed(): void @@ -386,27 +398,15 @@ public function testFromQueryWhenInListHasDisallowedValueThenThrowsFilterValueNo Criteria::fromQuery(request: $query, schema: $schema); } - #[DataProvider('comparisonOperatorCases')] - public function testFromQueryWhenComparisonOperatorThenComparisonCarriesThatOperator( - string $expression, - Operator $expected - ): void { - /** @Given a query carrying a binary comparison using one RSQL operator */ - $query = Query::from(parameters: ['filter' => $expression]); - - /** @When reading the validated comparisons */ - $comparisons = Criteria::fromQuery(request: $query, schema: $this->schema)->comparisons(); - - /** @Then the only comparison carries the expected operator */ - self::assertEquals([Comparison::of(field: 'a', values: ['b'], operator: $expected)], $comparisons); - } + public function testFromQueryWhenFilterNestedBeyondTheMaximumDepthThenThrowsFilterExpressionIsInvalid(): void + { + /** @Given a filter template wrapping a comparison in placeholders */ + $template = '%sa==1%s'; - #[DataProvider('malformedExpressionCases')] - public function testFromQueryWhenMalformedExpressionThenThrowsFilterExpressionIsInvalid( - string $expression - ): void { - /** @Given a query carrying a filter expression that breaks the RSQL grammar */ - $query = Query::from(parameters: ['filter' => $expression]); + /** @And a query whose filter nests parentheses one level beyond the maximum depth */ + $query = Query::from(parameters: [ + 'filter' => sprintf($template, str_repeat('(', 33), str_repeat(')', 33)) + ]); /** @Then an exception indicating the filter expression is invalid is raised */ $this->expectException(FilterExpressionIsInvalid::class); diff --git a/tests/Unit/LinksTest.php b/tests/Unit/LinksTest.php index 551b3c4..8c943f6 100644 --- a/tests/Unit/LinksTest.php +++ b/tests/Unit/LinksTest.php @@ -22,27 +22,6 @@ final class LinksTest extends TestCase { - public function testToArrayWhenInListFilterThenRendersParenthesizedValues(): void - { - /** @Given an IN comparison carrying several values */ - $filter = Comparison::of(field: 'role', values: ['admin', 'user'], operator: Operator::IN); - - /** @When rendering the navigation for a page carrying that filter */ - $links = Links::from( - sort: Sort::fromExpression(expression: ''), - filter: $filter, - baseUri: '/v1/orders', - self: Pagination::fromPage(page: 1, perPage: 20), - navigation: Navigation::empty() - ); - - /** @Then the self link wraps the comma-joined values in parentheses */ - self::assertSame( - '/v1/orders?filter=role=in=(admin,user)&page[number]=1&page[size]=20', - $links->toArray()['self'] - ); - } - public function testToArrayWhenReservedCharacterInValueThenQuotesIt(): void { /** @Given a comparison whose value carries a space */ @@ -50,10 +29,10 @@ public function testToArrayWhenReservedCharacterInValueThenQuotesIt(): void /** @When rendering the navigation for a page carrying that filter */ $links = Links::from( + self: Pagination::fromPage(page: 1, perPage: 20), sort: Sort::fromExpression(expression: ''), filter: $filter, baseUri: '/v1/orders', - self: Pagination::fromPage(page: 1, perPage: 20), navigation: Navigation::empty() ); @@ -64,185 +43,162 @@ public function testToArrayWhenReservedCharacterInValueThenQuotesIt(): void ); } - public function testToArrayWhenQuoteAndBackslashInValueThenEscapesBoth(): void + public function testToArrayWhenPageIsTheLastThenOmitsTheNextRelation(): void { - /** @Given a comparison whose value carries a double quote and a backslash */ - $filter = Comparison::of(field: 'name', values: ['a"b\\c'], operator: Operator::EQUAL); - - /** @When rendering the navigation for a page carrying that filter */ - $links = Links::from( - sort: Sort::fromExpression(expression: ''), - filter: $filter, - baseUri: '/v1/orders', - self: Pagination::fromPage(page: 1, perPage: 20), - navigation: Navigation::empty() - ); - - /** @Then the self link escapes the quote and the backslash within the double-quoted value */ - self::assertSame( - '/v1/orders?filter=name==%22a%5C%22b%5C%5Cc%22&page[number]=1&page[size]=20', - $links->toArray()['self'] + /** @Given a criteria pointing at the twenty-fourth page */ + $criteria = Criteria::fromQuery( + request: Query::from(parameters: ['page' => ['number' => '24', 'size' => '20']]) ); - } - public function testToArrayWhenValueCarriesUnsafeAndStructuralCharactersThenEncodesOnlyTheUnsafeOnes(): void - { - /** @Given a comparison whose value carries query-unsafe and RSQL-structural characters */ - $filter = Comparison::of(field: 'name', values: ["a&b#c%d=e;f,g(h)i!j k\r\n"], operator: Operator::EQUAL); - - /** @And the readable link the decoded query is expected to round-trip to */ - $template = '/v1/orders?filter=%s&page[number]=1&page[size]=20'; + /** @And a page carrying a total spanning twenty-four pages */ + $result = $criteria->page(items: range(1, 20), total: 480); - /** @When rendering the self link for a page carrying that filter */ - $self = Links::from( + /** @When rendering the navigation for the last page from its own pagination */ + $links = Links::from( + self: Pagination::fromPage(page: 24, perPage: 20), sort: Sort::fromExpression(expression: ''), - filter: $filter, + filter: Group::none(), baseUri: '/v1/orders', - self: Pagination::fromPage(page: 1, perPage: 20), - navigation: Navigation::empty() - )->toArray()['self']; - - /** @Then the unsafe characters stay percent-encoded while the structural and unreserved ones stay readable */ - self::assertSame( - '/v1/orders?filter=name==%22a%26b%23c%25d=e;f,g(h)i!j%20k%0D%0A%22&page[number]=1&page[size]=20', - $self + navigation: $result->navigation() ); - /** @And URL-decoding the link recovers the readable form carrying the rendered RSQL */ - self::assertSame(sprintf($template, Renderer::from(filter: $filter)), rawurldecode($self)); + /** @Then the navigation exposes the self, first, previous, and last relations in that order */ + self::assertSame([ + 'self' => '/v1/orders?page[number]=24&page[size]=20', + 'first' => '/v1/orders?page[number]=1&page[size]=20', + 'prev' => '/v1/orders?page[number]=23&page[size]=20', + 'last' => '/v1/orders?page[number]=24&page[size]=20' + ], $links->toArray()); + + /** @And the navigation carries no next relation */ + self::assertArrayNotHasKey('next', $links->toArray()); } - public function testToArrayWhenAndGroupFilterThenJoinsChildrenWithTheAndToken(): void + public function testToArrayWhenAndGroupNestedInOrThenLeavesItUnwrapped(): void { - /** @Given an AND group of two comparisons */ + /** @Given an OR group whose first child is an AND group */ $filter = Group::of(filters: [ - Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), - Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) - ], operator: LogicalOperator::AND); + Group::of(filters: [ + Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), + Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) + ], operator: LogicalOperator::AND), + Comparison::of(field: 'c', values: ['3'], operator: Operator::EQUAL) + ], operator: LogicalOperator::OR); /** @When rendering the navigation for a page carrying that filter */ $links = Links::from( + self: Pagination::fromPage(page: 1, perPage: 20), sort: Sort::fromExpression(expression: ''), filter: $filter, baseUri: '/v1/orders', - self: Pagination::fromPage(page: 1, perPage: 20), navigation: Navigation::empty() ); - /** @Then the self link joins the children with the AND token */ + /** @Then the self link leaves the tighter-binding AND group unwrapped */ self::assertSame( - '/v1/orders?filter=a==1;b==2&page[number]=1&page[size]=20', + '/v1/orders?filter=a==1;b==2,c==3&page[number]=1&page[size]=20', $links->toArray()['self'] ); } - public function testToArrayWhenOrGroupFilterThenJoinsChildrenWithTheOrToken(): void + public function testToArrayWhenQuoteAndBackslashInValueThenEscapesBoth(): void { - /** @Given an OR group of two comparisons */ - $filter = Group::of(filters: [ - Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), - Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) - ], operator: LogicalOperator::OR); + /** @Given a comparison whose value carries a double quote and a backslash */ + $filter = Comparison::of(field: 'name', values: ['a"b\\c'], operator: Operator::EQUAL); /** @When rendering the navigation for a page carrying that filter */ $links = Links::from( + self: Pagination::fromPage(page: 1, perPage: 20), sort: Sort::fromExpression(expression: ''), filter: $filter, baseUri: '/v1/orders', - self: Pagination::fromPage(page: 1, perPage: 20), navigation: Navigation::empty() ); - /** @Then the self link joins the children with the OR token */ + /** @Then the self link escapes the quote and the backslash within the double-quoted value */ self::assertSame( - '/v1/orders?filter=a==1,b==2&page[number]=1&page[size]=20', + '/v1/orders?filter=name==%22a%5C%22b%5C%5Cc%22&page[number]=1&page[size]=20', $links->toArray()['self'] ); } - public function testToArrayWhenOrGroupNestedInAndThenWrapsItInParentheses(): void + public function testToArrayWhenInListFilterThenRendersParenthesizedValues(): void { - /** @Given an AND group whose first child is an OR group */ - $filter = Group::of(filters: [ - Group::of(filters: [ - Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), - Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) - ], operator: LogicalOperator::OR), - Comparison::of(field: 'c', values: ['3'], operator: Operator::EQUAL) - ], operator: LogicalOperator::AND); + /** @Given an IN comparison carrying several values */ + $filter = Comparison::of(field: 'role', values: ['admin', 'user'], operator: Operator::IN); /** @When rendering the navigation for a page carrying that filter */ $links = Links::from( + self: Pagination::fromPage(page: 1, perPage: 20), sort: Sort::fromExpression(expression: ''), filter: $filter, baseUri: '/v1/orders', - self: Pagination::fromPage(page: 1, perPage: 20), navigation: Navigation::empty() ); - /** @Then the self link wraps the tighter-binding OR group in parentheses */ + /** @Then the self link wraps the comma-joined values in parentheses */ self::assertSame( - '/v1/orders?filter=(a==1,b==2);c==3&page[number]=1&page[size]=20', + '/v1/orders?filter=role=in=(admin,user)&page[number]=1&page[size]=20', $links->toArray()['self'] ); } - public function testToArrayWhenAndGroupNestedInOrThenLeavesItUnwrapped(): void + public function testToArrayWhenOrGroupNestedInAndThenWrapsItInParentheses(): void { - /** @Given an OR group whose first child is an AND group */ + /** @Given an AND group whose first child is an OR group */ $filter = Group::of(filters: [ Group::of(filters: [ Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) - ], operator: LogicalOperator::AND), + ], operator: LogicalOperator::OR), Comparison::of(field: 'c', values: ['3'], operator: Operator::EQUAL) - ], operator: LogicalOperator::OR); + ], operator: LogicalOperator::AND); /** @When rendering the navigation for a page carrying that filter */ $links = Links::from( + self: Pagination::fromPage(page: 1, perPage: 20), sort: Sort::fromExpression(expression: ''), filter: $filter, baseUri: '/v1/orders', - self: Pagination::fromPage(page: 1, perPage: 20), navigation: Navigation::empty() ); - /** @Then the self link leaves the tighter-binding AND group unwrapped */ + /** @Then the self link wraps the tighter-binding OR group in parentheses */ self::assertSame( - '/v1/orders?filter=a==1;b==2,c==3&page[number]=1&page[size]=20', + '/v1/orders?filter=(a==1,b==2);c==3&page[number]=1&page[size]=20', $links->toArray()['self'] ); } - public function testToArrayWhenPageIsTheLastThenOmitsTheNextRelation(): void + public function testToArrayWhenPageIsTheFirstThenOmitsThePreviousRelation(): void { - /** @Given a criteria pointing at the twenty-fourth page */ + /** @Given a criteria pointing at the first page */ $criteria = Criteria::fromQuery( - request: Query::from(parameters: ['page' => ['number' => '24', 'size' => '20']]) + request: Query::from(parameters: ['page' => ['number' => '1', 'size' => '20']]) ); /** @And a page carrying a total spanning twenty-four pages */ - $result = $criteria->page(total: 480, items: range(1, 20)); + $result = $criteria->page(items: range(1, 20), total: 480); - /** @When rendering the navigation for the last page from its own pagination */ + /** @When rendering the navigation for the first page from its own pagination */ $links = Links::from( + self: Pagination::fromPage(page: 1, perPage: 20), sort: Sort::fromExpression(expression: ''), filter: Group::none(), baseUri: '/v1/orders', - self: Pagination::fromPage(page: 24, perPage: 20), navigation: $result->navigation() ); - /** @Then the navigation exposes the self, first, previous, and last relations in that order */ + /** @Then the navigation exposes the self, first, next, and last relations in that order */ self::assertSame([ - 'self' => '/v1/orders?page[number]=24&page[size]=20', + 'self' => '/v1/orders?page[number]=1&page[size]=20', 'first' => '/v1/orders?page[number]=1&page[size]=20', - 'prev' => '/v1/orders?page[number]=23&page[size]=20', + 'next' => '/v1/orders?page[number]=2&page[size]=20', 'last' => '/v1/orders?page[number]=24&page[size]=20' ], $links->toArray()); - /** @And the navigation carries no next relation */ - self::assertArrayNotHasKey('next', $links->toArray()); + /** @And the navigation carries no previous relation */ + self::assertArrayNotHasKey('prev', $links->toArray()); } public function testToArrayWhenSliceMiddleThenExposesSelfFirstPrevAndNext(): void @@ -257,10 +213,10 @@ public function testToArrayWhenSliceMiddleThenExposesSelfFirstPrevAndNext(): voi /** @When rendering the navigation preserving a filter and a sort */ $links = Links::from( + self: Pagination::fromPage(page: 3, perPage: 20), sort: Sort::fromExpression(expression: '-created_at,id'), filter: Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL), baseUri: '/v1/orders', - self: Pagination::fromPage(page: 3, perPage: 20), navigation: $result->navigation() ); @@ -273,35 +229,28 @@ public function testToArrayWhenSliceMiddleThenExposesSelfFirstPrevAndNext(): voi ], $links->toArray()); } - public function testToArrayWhenPageIsTheFirstThenOmitsThePreviousRelation(): void + public function testToArrayWhenOrGroupFilterThenJoinsChildrenWithTheOrToken(): void { - /** @Given a criteria pointing at the first page */ - $criteria = Criteria::fromQuery( - request: Query::from(parameters: ['page' => ['number' => '1', 'size' => '20']]) - ); - - /** @And a page carrying a total spanning twenty-four pages */ - $result = $criteria->page(total: 480, items: range(1, 20)); + /** @Given an OR group of two comparisons */ + $filter = Group::of(filters: [ + Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), + Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) + ], operator: LogicalOperator::OR); - /** @When rendering the navigation for the first page from its own pagination */ + /** @When rendering the navigation for a page carrying that filter */ $links = Links::from( + self: Pagination::fromPage(page: 1, perPage: 20), sort: Sort::fromExpression(expression: ''), - filter: Group::none(), + filter: $filter, baseUri: '/v1/orders', - self: Pagination::fromPage(page: 1, perPage: 20), - navigation: $result->navigation() + navigation: Navigation::empty() ); - /** @Then the navigation exposes the self, first, next, and last relations in that order */ - self::assertSame([ - 'self' => '/v1/orders?page[number]=1&page[size]=20', - 'first' => '/v1/orders?page[number]=1&page[size]=20', - 'next' => '/v1/orders?page[number]=2&page[size]=20', - 'last' => '/v1/orders?page[number]=24&page[size]=20' - ], $links->toArray()); - - /** @And the navigation carries no previous relation */ - self::assertArrayNotHasKey('prev', $links->toArray()); + /** @Then the self link joins the children with the OR token */ + self::assertSame( + '/v1/orders?filter=a==1,b==2&page[number]=1&page[size]=20', + $links->toArray()['self'] + ); } public function testToArrayWhenSliceMiddleThenCarriesAFirstButNoLastRelation(): void @@ -316,10 +265,10 @@ public function testToArrayWhenSliceMiddleThenCarriesAFirstButNoLastRelation(): /** @When rendering the navigation for the slice from its own pagination */ $links = Links::from( + self: Pagination::fromPage(page: 3, perPage: 20), sort: Sort::fromExpression(expression: ''), filter: Group::none(), baseUri: '/v1/orders', - self: Pagination::fromPage(page: 3, perPage: 20), navigation: $result->navigation() ); @@ -330,6 +279,42 @@ public function testToArrayWhenSliceMiddleThenCarriesAFirstButNoLastRelation(): self::assertArrayNotHasKey('last', $links->toArray()); } + public function testToArrayWhenAndGroupFilterThenJoinsChildrenWithTheAndToken(): void + { + /** @Given an AND group of two comparisons */ + $filter = Group::of(filters: [ + Comparison::of(field: 'a', values: ['1'], operator: Operator::EQUAL), + Comparison::of(field: 'b', values: ['2'], operator: Operator::EQUAL) + ], operator: LogicalOperator::AND); + + /** @When rendering the navigation for a page carrying that filter */ + $links = Links::from( + self: Pagination::fromPage(page: 1, perPage: 20), + sort: Sort::fromExpression(expression: ''), + filter: $filter, + baseUri: '/v1/orders', + navigation: Navigation::empty() + ); + + /** @Then the self link joins the children with the AND token */ + self::assertSame( + '/v1/orders?filter=a==1;b==2&page[number]=1&page[size]=20', + $links->toArray()['self'] + ); + } + + public function testConstructorWhenInvokedThroughReflectionThenInstantiatesTheStaticOnlyUri(): void + { + /** @Given an uninitialized instance of the static-only URI assembler */ + $uri = new ReflectionClass(Uri::class)->newInstanceWithoutConstructor(); + + /** @When invoking its otherwise-uncallable private constructor */ + new ReflectionMethod(Uri::class, '__construct')->invoke($uri); + + /** @Then the static-only URI assembler is instantiated */ + self::assertInstanceOf(Uri::class, $uri); + } + public function testToHeaderWhenPageInTheMiddleThenFoldsEveryRelationIntoOneCommaJoinedValue(): void { /** @Given a criteria at a middle page */ @@ -338,14 +323,14 @@ public function testToHeaderWhenPageInTheMiddleThenFoldsEveryRelationIntoOneComm ); /** @And a page carrying a total spanning twenty-four pages */ - $result = $criteria->page(total: 480, items: range(1, 20)); + $result = $criteria->page(items: range(1, 20), total: 480); /** @When rendering the navigation as an RFC 8288 Link header preserving a filter and a sort */ $header = Links::from( + self: Pagination::fromPage(page: 3, perPage: 20), sort: Sort::fromExpression(expression: '-created_at,id'), filter: Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL), baseUri: '/v1/orders', - self: Pagination::fromPage(page: 3, perPage: 20), navigation: $result->navigation() )->toHeader(); @@ -367,14 +352,14 @@ public function testToArrayWhenPageInTheMiddleThenExposesEveryRelationPreserving ); /** @And a page carrying a total spanning twenty-four pages */ - $result = $criteria->page(total: 480, items: range(1, 20)); + $result = $criteria->page(items: range(1, 20), total: 480); /** @When rendering the navigation preserving a filter and a sort */ $links = Links::from( + self: Pagination::fromPage(page: 3, perPage: 20), sort: Sort::fromExpression(expression: '-created_at,id'), filter: Comparison::of(field: 'status', values: ['paid'], operator: Operator::EQUAL), baseUri: '/v1/orders', - self: Pagination::fromPage(page: 3, perPage: 20), navigation: $result->navigation() ); @@ -388,18 +373,6 @@ public function testToArrayWhenPageInTheMiddleThenExposesEveryRelationPreserving ], $links->toArray()); } - public function testConstructorWhenInvokedThroughReflectionThenInstantiatesTheStaticOnlyUri(): void - { - /** @Given an uninitialized instance of the static-only URI assembler */ - $uri = new ReflectionClass(Uri::class)->newInstanceWithoutConstructor(); - - /** @When invoking its otherwise-uncallable private constructor */ - new ReflectionMethod(Uri::class, '__construct')->invoke($uri); - - /** @Then the static-only URI assembler is instantiated */ - self::assertInstanceOf(Uri::class, $uri); - } - public function testConstructorWhenInvokedThroughReflectionThenInstantiatesTheStaticOnlyRenderer(): void { /** @Given an uninitialized instance of the static-only RSQL renderer */ @@ -411,4 +384,31 @@ public function testConstructorWhenInvokedThroughReflectionThenInstantiatesTheSt /** @Then the static-only RSQL renderer is instantiated */ self::assertInstanceOf(Renderer::class, $renderer); } + + public function testToArrayWhenValueCarriesUnsafeAndStructuralCharactersThenEncodesOnlyTheUnsafeOnes(): void + { + /** @Given a comparison whose value carries query-unsafe and RSQL-structural characters */ + $filter = Comparison::of(field: 'name', values: ["a&b#c%d=e;f,g(h)i!j k\r\n"], operator: Operator::EQUAL); + + /** @And the readable link the decoded query is expected to round-trip to */ + $template = '/v1/orders?filter=%s&page[number]=1&page[size]=20'; + + /** @When rendering the self link for a page carrying that filter */ + $self = Links::from( + self: Pagination::fromPage(page: 1, perPage: 20), + sort: Sort::fromExpression(expression: ''), + filter: $filter, + baseUri: '/v1/orders', + navigation: Navigation::empty() + )->toArray()['self']; + + /** @Then the unsafe characters stay percent-encoded while the structural and unreserved ones stay readable */ + self::assertSame( + '/v1/orders?filter=name==%22a%26b%23c%25d=e;f,g(h)i!j%20k%0D%0A%22&page[number]=1&page[size]=20', + $self + ); + + /** @And URL-decoding the link recovers the readable form carrying the rendered RSQL */ + self::assertSame(sprintf($template, Renderer::from(filter: $filter)), rawurldecode($self)); + } } diff --git a/tests/Unit/LogicalOperatorTest.php b/tests/Unit/LogicalOperatorTest.php index 9c846e5..593df5c 100644 --- a/tests/Unit/LogicalOperatorTest.php +++ b/tests/Unit/LogicalOperatorTest.php @@ -11,7 +11,7 @@ final class LogicalOperatorTest extends TestCase { #[DataProvider('logicalOperatorCases')] - public function testFromWhenTokenGivenThenResolvesToCase(LogicalOperator $operator, string $token): void + public function testFromWhenTokenGivenThenResolvesToCase(string $token, LogicalOperator $operator): void { /** @Given a canonical token and the connective it maps to */ @@ -23,7 +23,7 @@ public function testFromWhenTokenGivenThenResolvesToCase(LogicalOperator $operat } #[DataProvider('logicalOperatorCases')] - public function testValueWhenCaseGivenThenExposesCanonicalToken(LogicalOperator $operator, string $token): void + public function testValueWhenCaseGivenThenExposesCanonicalToken(string $token, LogicalOperator $operator): void { /** @Given a logical connective and its canonical token */ @@ -36,9 +36,9 @@ public function testValueWhenCaseGivenThenExposesCanonicalToken(LogicalOperator #[DataProvider('precedenceCases')] public function testBindsTighterThanWhenComparedToOtherThenReflectsPrecedence( - LogicalOperator $operator, LogicalOperator $other, - bool $expected + bool $expected, + LogicalOperator $operator ): void { /** @Given a connective and another connective to compare against */ diff --git a/tests/Unit/Offset/CriteriaTest.php b/tests/Unit/Offset/CriteriaTest.php index ce5beb1..6bb0a75 100644 --- a/tests/Unit/Offset/CriteriaTest.php +++ b/tests/Unit/Offset/CriteriaTest.php @@ -18,6 +18,33 @@ final class CriteriaTest extends TestCase { + public function testSortWhenNoClientSortAndNoDefaultThenIsEmpty(): void + { + /** @Given a schema declaring no sortable field and no default sort */ + $schema = Schema::create(); + + /** @When reading the effective sort from a query carrying no sort */ + $sort = Criteria::fromQuery(request: Query::from(parameters: []), schema: $schema)->sort(); + + /** @Then the effective sort is empty */ + self::assertTrue($sort->isEmpty()); + } + + public function testPageWhenBuiltFromRequestThenReturnsOffsetPage(): void + { + /** @Given a criteria parsed from a request carrying a page size of three */ + $criteria = Criteria::fromQuery(request: Query::from(parameters: ['page' => ['size' => '3']])); + + /** @When building an offset page from the total element count and the items */ + $page = $criteria->page(items: ['a', 'b', 'c'], total: 30); + + /** @Then the result is an offset page */ + self::assertInstanceOf(Page::class, $page); + + /** @And it carries the total element count */ + self::assertSame(30, $page->total()); + } + public function testFromQueryWhenEmptyThenOffsetAndLimitAreDefaults(): void { /** @Given empty query parameters */ @@ -33,6 +60,21 @@ public function testFromQueryWhenEmptyThenOffsetAndLimitAreDefaults(): void self::assertSame(20, $criteria->limit()); } + public function testSliceWhenBuiltFromRequestThenReturnsOffsetSlice(): void + { + /** @Given a criteria parsed from a request carrying a page size of three */ + $criteria = Criteria::fromQuery(request: Query::from(parameters: ['page' => ['size' => '3']])); + + /** @When building an offset slice from the items fetched for the page size plus one */ + $slice = $criteria->slice(items: ['a', 'b', 'c', 'd']); + + /** @Then the result is an offset slice */ + self::assertInstanceOf(Slice::class, $slice); + + /** @And it reports a next page from the trimmed extra element */ + self::assertTrue($slice->hasNext()); + } + public function testFromQueryWhenPerPageAtMaximumThenLimitIsAccepted(): void { /** @Given query parameters carrying a page size at the default maximum */ @@ -70,97 +112,53 @@ public function testSortWhenNoClientSortAndDefaultGivenThenReturnsTheDefault(): self::assertEquals(Sort::fromExpression(expression: '-created_at'), $sort); } - public function testSortWhenNoClientSortAndNoDefaultThenIsEmpty(): void + public function testFromQueryWhenCustomSchemaGivenThenAppliesItsDefaultPageSize(): void { - /** @Given a schema declaring no sortable field and no default sort */ - $schema = Schema::create(); + /** @Given query parameters carrying a page number without a page size */ + $query = Query::from(parameters: ['page' => ['number' => '2']]); - /** @When reading the effective sort from a query carrying no sort */ - $sort = Criteria::fromQuery(request: Query::from(parameters: []), schema: $schema)->sort(); + /** @And a schema lowering the default page size */ + $schema = Schema::create()->defaultPerPage(defaultPerPage: 5); - /** @Then the effective sort is empty */ - self::assertTrue($sort->isEmpty()); + /** @When building the criteria from the query and the schema */ + $criteria = Criteria::fromQuery(request: $query, schema: $schema); + + /** @Then the offset is derived from the requested page and the schema default page size */ + self::assertSame(5, $criteria->offset()); + + /** @And the limit carries the schema default page size */ + self::assertSame(5, $criteria->limit()); } - public function testSortWhenClientSortsDisallowedFieldThenThrowsSortFieldNotAllowed(): void + public function testFromQueryWhenPerPageAboveMaximumThenThrowsPageSizeOutOfRange(): void { - /** @Given a schema allowing the client to sort by a single field */ - $schema = Schema::create()->sortable(fields: ['id']); - - /** @And a query sorting by a field that was never declared sortable */ - $query = Query::from(parameters: ['sort' => 'name']); + /** @Given query parameters carrying a page size above the default maximum */ + $query = Query::from(parameters: ['page' => ['size' => '500']]); - /** @Then an exception indicating the sort field is not allowed is raised */ - $this->expectException(SortFieldNotAllowed::class); - $this->expectExceptionMessage('Sort field is not allowed.'); + /** @Then an exception indicating the page size is out of range is raised */ + $this->expectException(PageSizeOutOfRange::class); + $this->expectExceptionMessage('Page size'); /** @When building the criteria from the query */ - Criteria::fromQuery(request: $query, schema: $schema); + Criteria::fromQuery(request: $query); } - public function testSortWhenServerControlledAndClientSortsThenThrowsSortFieldNotAllowed(): void + public function testSortWhenClientSortsDisallowedFieldThenThrowsSortFieldNotAllowed(): void { - /** @Given a schema with a server-controlled default and no client-sortable field */ - $schema = Schema::create()->defaultSort(sort: Sort::fromExpression(expression: '-created_at')); + /** @Given a schema allowing the client to sort by a single field */ + $schema = Schema::create()->sortable(fields: ['id']); - /** @And a query carrying a client sort */ - $query = Query::from(parameters: ['sort' => 'id']); + /** @And a query sorting by a field that was never declared sortable */ + $query = Query::from(parameters: ['sort' => 'name']); /** @Then an exception indicating the sort field is not allowed is raised */ $this->expectException(SortFieldNotAllowed::class); + $this->expectExceptionMessage('Sort field is not allowed.'); /** @When building the criteria from the query */ Criteria::fromQuery(request: $query, schema: $schema); } - public function testPageWhenBuiltFromRequestThenReturnsOffsetPage(): void - { - /** @Given a criteria parsed from a request carrying a page size of three */ - $criteria = Criteria::fromQuery(request: Query::from(parameters: ['page' => ['size' => '3']])); - - /** @When building an offset page from the total element count and the items */ - $page = $criteria->page(total: 30, items: ['a', 'b', 'c']); - - /** @Then the result is an offset page */ - self::assertInstanceOf(Page::class, $page); - - /** @And it carries the total element count */ - self::assertSame(30, $page->total()); - } - - public function testSliceWhenBuiltFromRequestThenReturnsOffsetSlice(): void - { - /** @Given a criteria parsed from a request carrying a page size of three */ - $criteria = Criteria::fromQuery(request: Query::from(parameters: ['page' => ['size' => '3']])); - - /** @When building an offset slice from the items fetched for the page size plus one */ - $slice = $criteria->slice(items: ['a', 'b', 'c', 'd']); - - /** @Then the result is an offset slice */ - self::assertInstanceOf(Slice::class, $slice); - - /** @And it reports a next page from the trimmed extra element */ - self::assertTrue($slice->hasNext()); - } - - public function testFromQueryWhenCustomSchemaGivenThenAppliesItsDefaultPageSize(): void - { - /** @Given query parameters carrying a page number without a page size */ - $query = Query::from(parameters: ['page' => ['number' => '2']]); - - /** @And a schema lowering the default page size */ - $schema = Schema::create()->defaultPerPage(defaultPerPage: 5); - - /** @When building the criteria from the query and the schema */ - $criteria = Criteria::fromQuery(request: $query, schema: $schema); - - /** @Then the offset is derived from the requested page and the schema default page size */ - self::assertSame(5, $criteria->offset()); - - /** @And the limit carries the schema default page size */ - self::assertSame(5, $criteria->limit()); - } - public function testFromQueryWhenFilterSortAndPageGivenThenEachSpecificationIsValidated(): void { /** @Given a schema allowing the filtered and sorted fields */ @@ -194,16 +192,18 @@ public function testFromQueryWhenFilterSortAndPageGivenThenEachSpecificationIsVa self::assertSame(15, $criteria->limit()); } - public function testFromQueryWhenPerPageAboveMaximumThenThrowsPageSizeOutOfRange(): void + public function testSortWhenServerControlledAndClientSortsThenThrowsSortFieldNotAllowed(): void { - /** @Given query parameters carrying a page size above the default maximum */ - $query = Query::from(parameters: ['page' => ['size' => '500']]); + /** @Given a schema with a server-controlled default and no client-sortable field */ + $schema = Schema::create()->defaultSort(sort: Sort::fromExpression(expression: '-created_at')); - /** @Then an exception indicating the page size is out of range is raised */ - $this->expectException(PageSizeOutOfRange::class); - $this->expectExceptionMessage('Page size'); + /** @And a query carrying a client sort */ + $query = Query::from(parameters: ['sort' => 'id']); + + /** @Then an exception indicating the sort field is not allowed is raised */ + $this->expectException(SortFieldNotAllowed::class); /** @When building the criteria from the query */ - Criteria::fromQuery(request: $query); + Criteria::fromQuery(request: $query, schema: $schema); } } diff --git a/tests/Unit/Offset/PageTest.php b/tests/Unit/Offset/PageTest.php index dc84904..e4eb121 100644 --- a/tests/Unit/Offset/PageTest.php +++ b/tests/Unit/Offset/PageTest.php @@ -15,49 +15,6 @@ final class PageTest extends TestCase { - public function testTotalWhenPageGivenThenReturnsTheTotalElementCount(): void - { - /** @Given a criteria on the first page with a page size of twenty */ - $criteria = Criteria::fromQuery( - request: Query::from(parameters: ['page' => ['number' => '1', 'size' => '20']]) - ); - - /** @When building the page from the total element count */ - $page = $criteria->page(total: 480, items: ['a', 'b']); - - /** @Then the total is the count provided across every page */ - self::assertSame(480, $page->total()); - } - - public function testItemsWhenPageGivenThenCarriesTheProvidedItems(): void - { - /** @Given a criteria on the third page with a page size of twenty */ - $criteria = Criteria::fromQuery( - request: Query::from(parameters: ['page' => ['number' => '3', 'size' => '20']]) - ); - - /** @When building the page and reading its items */ - $page = $criteria->page(total: 480, items: ['a', 'b']); - - /** @Then the items carry the provided elements */ - self::assertSame(['a', 'b'], $page->items()->toArray(keyPreservation: KeyPreservation::DISCARD)); - } - - public function testFromWhenTotalIsNegativeThenThrowsTotalIsNegative(): void - { - /** @Given a criteria on the first page */ - $criteria = Criteria::fromQuery( - request: Query::from(parameters: ['page' => ['number' => '1', 'size' => '20']]) - ); - - /** @Then an exception indicating the total is negative is raised */ - $this->expectException(TotalIsNegative::class); - $this->expectExceptionMessage('Total'); - - /** @When building a page from a negative total */ - $criteria->page(total: -1, items: []); - } - public function testNavigationWhenTotalIsZeroThenThereIsNoPage(): void { /** @Given a criteria on the first page */ @@ -66,7 +23,7 @@ public function testNavigationWhenTotalIsZeroThenThereIsNoPage(): void ); /** @When building the page from a total of zero */ - $page = $criteria->page(total: 0, items: []); + $page = $criteria->page(items: [], total: 0); /** @Then there are no pages */ self::assertSame(0, $page->totalPages()); @@ -99,7 +56,7 @@ public function testNavigationWhenLastPageGivenThenHasNoNextPage(): void ); /** @When building the page from the total element count */ - $page = $criteria->page(total: 480, items: ['a', 'b']); + $page = $criteria->page(items: ['a', 'b'], total: 480); /** @Then the page reports no next page */ self::assertFalse($page->hasNext()); @@ -114,6 +71,35 @@ public function testNavigationWhenLastPageGivenThenHasNoNextPage(): void self::assertSame(24, $page->last()?->page()); } + public function testItemsWhenPageGivenThenCarriesTheProvidedItems(): void + { + /** @Given a criteria on the third page with a page size of twenty */ + $criteria = Criteria::fromQuery( + request: Query::from(parameters: ['page' => ['number' => '3', 'size' => '20']]) + ); + + /** @When building the page and reading its items */ + $page = $criteria->page(items: ['a', 'b'], total: 480); + + /** @Then the items carry the provided elements */ + self::assertSame(['a', 'b'], $page->items()->toArray(keyPreservation: KeyPreservation::DISCARD)); + } + + public function testFromWhenTotalIsNegativeThenThrowsTotalIsNegative(): void + { + /** @Given a criteria on the first page */ + $criteria = Criteria::fromQuery( + request: Query::from(parameters: ['page' => ['number' => '1', 'size' => '20']]) + ); + + /** @Then an exception indicating the total is negative is raised */ + $this->expectException(TotalIsNegative::class); + $this->expectExceptionMessage('Total'); + + /** @When building a page from a negative total */ + $criteria->page(items: [], total: -1); + } + public function testNavigationWhenFirstPageGivenThenHasNoPreviousPage(): void { /** @Given a criteria on the first page */ @@ -122,7 +108,7 @@ public function testNavigationWhenFirstPageGivenThenHasNoPreviousPage(): void ); /** @When building the page from the total element count */ - $page = $criteria->page(total: 480, items: ['a', 'b']); + $page = $criteria->page(items: ['a', 'b'], total: 480); /** @Then the page reports no previous page */ self::assertFalse($page->hasPrevious()); @@ -143,6 +129,20 @@ public function testNavigationWhenFirstPageGivenThenHasNoPreviousPage(): void self::assertSame(24, $page->last()?->page()); } + public function testTotalWhenPageGivenThenReturnsTheTotalElementCount(): void + { + /** @Given a criteria on the first page with a page size of twenty */ + $criteria = Criteria::fromQuery( + request: Query::from(parameters: ['page' => ['number' => '1', 'size' => '20']]) + ); + + /** @When building the page from the total element count */ + $page = $criteria->page(items: ['a', 'b'], total: 480); + + /** @Then the total is the count provided across every page */ + self::assertSame(480, $page->total()); + } + public function testTotalPagesWhenTotalIsNotAMultipleOfPerPageThenRoundsUp(): void { /** @Given a criteria on the first page with a page size of twenty */ @@ -151,7 +151,7 @@ public function testTotalPagesWhenTotalIsNotAMultipleOfPerPageThenRoundsUp(): vo ); /** @When building the page from a total that is not a multiple of the page size */ - $page = $criteria->page(total: 21, items: ['a', 'b']); + $page = $criteria->page(items: ['a', 'b'], total: 21); /** @Then the total number of pages rounds the division up */ self::assertSame(2, $page->totalPages()); @@ -165,7 +165,7 @@ public function testMetadataWhenMiddlePageGivenThenCarriesEveryFlagAndCount(): v ); /** @When building the page from the total element count */ - $page = $criteria->page(total: 480, items: ['a', 'b']); + $page = $criteria->page(items: ['a', 'b'], total: 480); /** @Then the metadata carries every entry in grouped key order (counts and sizes, then the boolean flags) */ self::assertSame([ @@ -186,7 +186,7 @@ public function testNavigationWhenFirstPageGivenThenOmitsThePreviousRelation(): ); /** @And a page on that first page */ - $page = $criteria->page(total: 480, items: []); + $page = $criteria->page(items: [], total: 480); /** @When reading the relations of the navigation targets */ $relations = $page->navigation()->targets() @@ -205,7 +205,7 @@ public function testToResponseWhenMiddlePageGivenThenRendersBodyAndLinkHeader(): ); /** @And a page built over items keyed by their positions */ - $page = $criteria->page(total: 480, items: [5 => 'a', 9 => 'b']); + $page = $criteria->page(items: [5 => 'a', 9 => 'b'], total: 480); /** @When rendering the page as a JSON:API response over the orders base URI */ $response = $page->toResponse(baseUri: '/v1/orders'); @@ -248,7 +248,7 @@ public function testNavigationWhenMiddlePageGivenThenExposesEverySurroundingPage ); /** @When building the page from the total element count */ - $page = $criteria->page(total: 480, items: ['a', 'b']); + $page = $criteria->page(items: ['a', 'b'], total: 480); /** @Then the current page number is preserved */ self::assertSame(3, $page->currentPage()); @@ -272,7 +272,7 @@ public function testNavigationWhenMiddlePageGivenThenExposesEverySurroundingPage self::assertSame(24, $page->last()?->page()); } - public function testNavigationWhenMiddlePageGivenThenListsFirstPreviousNextAndLastTargets(): void + public function testNavigationWhenMiddlePageGivenThenTheFirstTargetPointsAtTheFirstPage(): void { /** @Given a criteria on a middle page of a multi-page result */ $criteria = Criteria::fromQuery( @@ -280,18 +280,19 @@ public function testNavigationWhenMiddlePageGivenThenListsFirstPreviousNextAndLa ); /** @And a page on that middle page */ - $page = $criteria->page(total: 480, items: []); + $page = $criteria->page(items: [], total: 480); - /** @When reading the relations of the navigation targets */ - $relations = $page->navigation()->targets() - ->map(transformations: static fn(NavigationTarget $target): string => $target->relation()->value) - ->toArray(keyPreservation: KeyPreservation::DISCARD); + /** @When reading the first navigation target */ + $target = $page->navigation()->targets()->first(); - /** @Then it lists the first, previous, next, and last relations in semantic order */ - self::assertSame(['first', 'prev', 'next', 'last'], $relations); + /** @Then the first target is the first page reached through the first relation */ + self::assertEquals( + NavigationTarget::to(target: Pagination::fromPage(page: 1, perPage: 20), relation: LinkRelation::FIRST), + $target + ); } - public function testNavigationWhenMiddlePageGivenThenTheFirstTargetPointsAtTheFirstPage(): void + public function testNavigationWhenMiddlePageGivenThenListsFirstPreviousNextAndLastTargets(): void { /** @Given a criteria on a middle page of a multi-page result */ $criteria = Criteria::fromQuery( @@ -299,15 +300,14 @@ public function testNavigationWhenMiddlePageGivenThenTheFirstTargetPointsAtTheFi ); /** @And a page on that middle page */ - $page = $criteria->page(total: 480, items: []); + $page = $criteria->page(items: [], total: 480); - /** @When reading the first navigation target */ - $target = $page->navigation()->targets()->first(); + /** @When reading the relations of the navigation targets */ + $relations = $page->navigation()->targets() + ->map(transformations: static fn(NavigationTarget $target): string => $target->relation()->value) + ->toArray(keyPreservation: KeyPreservation::DISCARD); - /** @Then the first target is the first page reached through the first relation */ - self::assertEquals( - NavigationTarget::to(target: Pagination::fromPage(page: 1, perPage: 20), relation: LinkRelation::FIRST), - $target - ); + /** @Then it lists the first, previous, next, and last relations in semantic order */ + self::assertSame(['first', 'prev', 'next', 'last'], $relations); } } diff --git a/tests/Unit/Offset/PaginationTest.php b/tests/Unit/Offset/PaginationTest.php index f7e9b8b..756247f 100644 --- a/tests/Unit/Offset/PaginationTest.php +++ b/tests/Unit/Offset/PaginationTest.php @@ -105,18 +105,6 @@ public function testFromOffsetWhenUnalignedOffsetGivenThenPageIsFloored(): void self::assertSame(20, $pagination->limit()); } - public function testToQueryStringWhenPageGivenThenRendersPageNumberAndSize(): void - { - /** @Given an offset pagination on the third page */ - $pagination = Pagination::fromPage(page: 3, perPage: 20); - - /** @When rendering it as a query string */ - $queryString = $pagination->toQueryString(); - - /** @Then it renders the page number and the page size in the JSON:API page family */ - self::assertSame('page[number]=3&page[size]=20', $queryString); - } - public function testFromPageWhenPageBelowOneGivenThenPageNumberOutOfRange(): void { /** @Then an exception indicating the page number is out of range is raised */ @@ -156,4 +144,16 @@ public function testFromPageWhenPerPageBelowOneGivenThenPageSizeOutOfRange(): vo /** @When building a pagination from a page size below one */ Pagination::fromPage(page: 1, perPage: 0); } + + public function testToQueryStringWhenPageGivenThenRendersPageNumberAndSize(): void + { + /** @Given an offset pagination on the third page */ + $pagination = Pagination::fromPage(page: 3, perPage: 20); + + /** @When rendering it as a query string */ + $queryString = $pagination->toQueryString(); + + /** @Then it renders the page number and the page size in the JSON:API page family */ + self::assertSame('page[number]=3&page[size]=20', $queryString); + } } diff --git a/tests/Unit/Offset/SliceTest.php b/tests/Unit/Offset/SliceTest.php index 7e652f1..0dca7a2 100644 --- a/tests/Unit/Offset/SliceTest.php +++ b/tests/Unit/Offset/SliceTest.php @@ -14,18 +14,6 @@ final class SliceTest extends TestCase { - public function testOffsetWhenSecondPageGivenThenReturnsTheZeroBasedOffset(): void - { - /** @Given a criteria on the second page with a page size of three */ - $criteria = Criteria::fromQuery(request: Query::from(parameters: ['page' => ['number' => '2', 'size' => '3']])); - - /** @When building the slice from the items fetched for the page size plus one */ - $slice = $criteria->slice(items: ['a', 'b', 'c', 'd']); - - /** @Then the offset is derived from the page and the page size */ - self::assertSame(3, $slice->offset()); - } - public function testToResponseWhenSliceGivenThenRendersBodyAndLinkHeader(): void { /** @Given a criteria on the second page with a page size of three */ @@ -63,6 +51,18 @@ public function testToResponseWhenSliceGivenThenRendersBodyAndLinkHeader(): void ]), $response->getHeaderLine('Link')); } + public function testOffsetWhenSecondPageGivenThenReturnsTheZeroBasedOffset(): void + { + /** @Given a criteria on the second page with a page size of three */ + $criteria = Criteria::fromQuery(request: Query::from(parameters: ['page' => ['number' => '2', 'size' => '3']])); + + /** @When building the slice from the items fetched for the page size plus one */ + $slice = $criteria->slice(items: ['a', 'b', 'c', 'd']); + + /** @Then the offset is derived from the page and the page size */ + self::assertSame(3, $slice->offset()); + } + public function testNavigationWhenExtraElementFetchedThenHasNextAndTrimsItems(): void { /** @Given a criteria on the second page with a page size of three */ diff --git a/tests/Unit/OperatorTest.php b/tests/Unit/OperatorTest.php index 0259842..0664efc 100644 --- a/tests/Unit/OperatorTest.php +++ b/tests/Unit/OperatorTest.php @@ -11,7 +11,7 @@ final class OperatorTest extends TestCase { #[DataProvider('operatorCases')] - public function testFromWhenTokenGivenThenResolvesToCase(Operator $operator, string $token): void + public function testFromWhenTokenGivenThenResolvesToCase(string $token, Operator $operator): void { /** @Given a canonical token and the operator it maps to */ @@ -23,7 +23,7 @@ public function testFromWhenTokenGivenThenResolvesToCase(Operator $operator, str } #[DataProvider('operatorCases')] - public function testValueWhenCaseGivenThenExposesCanonicalToken(Operator $operator, string $token): void + public function testValueWhenCaseGivenThenExposesCanonicalToken(string $token, Operator $operator): void { /** @Given a comparison operator and its canonical token */ diff --git a/tests/Unit/SchemaTest.php b/tests/Unit/SchemaTest.php index bbd5533..2511ab8 100644 --- a/tests/Unit/SchemaTest.php +++ b/tests/Unit/SchemaTest.php @@ -37,28 +37,40 @@ public function testDefaultThenAppliesTheDefaultPageSize(): void self::assertSame(20, $actual); } - public function testPageSizeForWhenAtMaximumThenReturnsTheMaximumSize(): void + public function testDefaultPerPageWhenLoweredThenTheCopyAppliesIt(): void { /** @Given the default schema */ $schema = Schema::default(); - /** @When asking for a page size equal to the maximum */ - $actual = $schema->pageSizeFor(requested: 100); + /** @When lowering the default page size and asking with no requested value */ + $actual = $schema->defaultPerPage(defaultPerPage: 5)->pageSizeFor(requested: null); - /** @Then it returns the maximum page size */ - self::assertSame(100, $actual); + /** @Then the lowered default page size is applied */ + self::assertSame(5, $actual); } - public function testPageSizeForWhenWithinMaximumThenReturnsTheRequestedSize(): void + public function testBoundsWhenBothAtMinimumThenAcceptsTheMinimumSize(): void + { + /** @Given a schema with the default and maximum page sizes lowered to the minimum */ + $schema = Schema::create()->defaultPerPage(defaultPerPage: 1)->maxPerPage(maxPerPage: 1); + + /** @When asking for a page size of one */ + $actual = $schema->pageSizeFor(requested: 1); + + /** @Then the minimum page size is accepted */ + self::assertSame(1, $actual); + } + + public function testPageSizeForWhenAtMaximumThenReturnsTheMaximumSize(): void { /** @Given the default schema */ $schema = Schema::default(); - /** @When asking for a page size within the maximum */ - $actual = $schema->pageSizeFor(requested: 50); + /** @When asking for a page size equal to the maximum */ + $actual = $schema->pageSizeFor(requested: 100); - /** @Then it returns the requested page size */ - self::assertSame(50, $actual); + /** @Then it returns the maximum page size */ + self::assertSame(100, $actual); } public function testMaxPerPageWhenRaisedThenTheCopyAcceptsTheLargerSize(): void @@ -73,28 +85,17 @@ public function testMaxPerPageWhenRaisedThenTheCopyAcceptsTheLargerSize(): void self::assertSame(250, $actual); } - public function testDefaultPerPageWhenLoweredThenTheCopyAppliesIt(): void + public function testMaxPerPageWhenBelowMinimumThenThrowsPageSizeOutOfRange(): void { /** @Given the default schema */ $schema = Schema::default(); - /** @When lowering the default page size and asking with no requested value */ - $actual = $schema->defaultPerPage(defaultPerPage: 5)->pageSizeFor(requested: null); - - /** @Then the lowered default page size is applied */ - self::assertSame(5, $actual); - } - - public function testBoundsWhenBothAtMinimumThenAcceptsTheMinimumSize(): void - { - /** @Given a schema with the default and maximum page sizes lowered to the minimum */ - $schema = Schema::create()->defaultPerPage(defaultPerPage: 1)->maxPerPage(maxPerPage: 1); - - /** @When asking for a page size of one */ - $actual = $schema->pageSizeFor(requested: 1); + /** @Then an exception indicating the page size is out of range is raised */ + $this->expectException(PageSizeOutOfRange::class); + $this->expectExceptionMessage('Page size <0> must be greater than or equal to 1.'); - /** @Then the minimum page size is accepted */ - self::assertSame(1, $actual); + /** @When lowering the maximum page size below the minimum */ + $schema->maxPerPage(maxPerPage: 0); } public function testPageSizeForWhenAboveMaximumThenThrowsPageSizeOutOfRange(): void @@ -110,17 +111,16 @@ public function testPageSizeForWhenAboveMaximumThenThrowsPageSizeOutOfRange(): v $schema->pageSizeFor(requested: 101); } - public function testMaxPerPageWhenBelowMinimumThenThrowsPageSizeOutOfRange(): void + public function testPageSizeForWhenWithinMaximumThenReturnsTheRequestedSize(): void { /** @Given the default schema */ $schema = Schema::default(); - /** @Then an exception indicating the page size is out of range is raised */ - $this->expectException(PageSizeOutOfRange::class); - $this->expectExceptionMessage('Page size <0> must be greater than or equal to 1.'); + /** @When asking for a page size within the maximum */ + $actual = $schema->pageSizeFor(requested: 50); - /** @When lowering the maximum page size below the minimum */ - $schema->maxPerPage(maxPerPage: 0); + /** @Then it returns the requested page size */ + self::assertSame(50, $actual); } public function testDefaultPerPageWhenAboveMaximumThenThrowsPageSizeOutOfRange(): void From ab975f328fb25d78acdd54219e9a92f33831a3d8 Mon Sep 17 00:00:00 2001 From: Gustavo Freze Date: Mon, 15 Jun 2026 13:01:14 -0300 Subject: [PATCH 12/14] feat: Add PHP ordering and prose punctuation conformance hooks. --- .claude/hooks/php-ordering-conformance.py | 537 ++++++++++++++++++ .../php-prose-punctuation-conformance.py | 176 ++++++ .claude/settings.json | 17 + 3 files changed, 730 insertions(+) create mode 100644 .claude/hooks/php-ordering-conformance.py create mode 100644 .claude/hooks/php-prose-punctuation-conformance.py diff --git a/.claude/hooks/php-ordering-conformance.py b/.claude/hooks/php-ordering-conformance.py new file mode 100644 index 0000000..0076512 --- /dev/null +++ b/.claude/hooks/php-ordering-conformance.py @@ -0,0 +1,537 @@ +#!/usr/bin/env python3 +"""PHP ordering conformance hook for tiny-blocks PHP libraries. + +Self-contained PostToolUse hook on Edit|Write|MultiEdit. Verifies the deterministic +ordering conventions for PHP declarations: + +- Parameter ordering: declaration parameters (constructors, factories, methods, + property promotion) ordered by identifier length ascending, alphabetical + tie-breaker, semantic pairs preserved. +- Parameter ordering: named arguments at call sites, same comparator. +- Member ordering: constants, enum cases, constructor, static methods, instance + methods, in that group order, each group length-ascending with alphabetical + tie-breaker. + +The analysis is pure (FileUnit in, Violation out) and runs in three passes over +well-formed PHP: a lexical pass blanks every comment, string, and heredoc/nowdoc +body (LITERALS), a structural pass maps every bracket to its pair (bracket_spans); +extraction assigns tokens of interest to their containers by flat walks. Control +flow uses guard clauses only and nesting never exceeds two levels. Reports +violations to stderr and exits 2 to prompt Claude, exits 0 silently if no violations +or the file is out of scope. +""" + +import json +import re +import sys +from dataclasses import dataclass +from enum import Enum +from functools import cached_property +from pathlib import Path +from typing import Final + +# --- Configuration ---------------------------------------------------------- + +# In-scope files: PHP sources under src/ or tests/. +SCOPE_PATTERN: Final = re.compile(r"(^|/)(src|tests)/.+\.php$") + +# Semantic pairs (exhaustive). Natural order wins between +# the two members when both appear in the same parameter list. +SEMANTIC_PAIRS: Final = ( + ("start", "end"), + ("from", "to"), + ("startAt", "endAt"), + ("createdAt", "updatedAt"), + ("before", "after"), + ("min", "max"), +) + +# Each member maps to (first, second, position). Both members keep their natural +# order only when both are present, sorting as a unit at the lead member's key. +PAIR_MEMBER: Final = { + member: (first, second, position) + for first, second in SEMANTIC_PAIRS + for position, member in enumerate((first, second)) +} + +MODIFIERS: Final = ("abstract", "final", "private", "protected", "public", "static") + +# The lexical grammar: every PHP construct that must not be scanned as code. +# Alternatives are ordered, the heredoc label closes via backreference. +LITERALS: Final = re.compile( + r""" + /\*.*?\*/ # block comment + | //[^\n]* # line comment + | \#(?!\[)[^\n]* # hash comment, never a #[ attribute + | <<<[ \t]*(?P['"]?)(?P