[armanist]

Refs #612. This pull request targets 3.1.x, so it does not close the issue; the merge of 3.1.x into master does.

What changed

Converts the constant classes that can become enums on PHP 8.1:

• ReservedKeys, AuthKeys, Pagination and the database Type, Key and Relation are string-backed enums with the same case names and values.
• Table::CREATE, ALTER, DROP and RENAME move to a new int-backed TableAction enum.
• Pagination keeps its four names. The numbers FIRST_PAGE_NUMBER, MINIMUM_PAGE_ITEMS_COUNT and EDGE_PADDING move to PaginationLimit, an enum that holds them as constants: a backed enum cannot hold them, because two of them are both 3.
• Table::addColumn(), modifyColumn(), Column::__construct(), Table::addIndex() and Table::setAction() take the enum only.
• AuthTrait::verifySchema() reads AuthKeys::cases() instead of ReflectionClass::getConstants(), and Table::addIndex() chooses the method with a match over Key.
• ModelException::unsupportedRelationType() accepts a Relation or text.

Why

An enum gives a closed set of values that PHP and PHPStan check, instead of free strings and integers. The adapter types, StatusCode, ContentType, Env, ExitCode and the ExceptionMessages classes stay constant classes (see #620).

Breaking changes

Yes, listed in CHANGELOG.md with the migration note:

• A case is not its value: array keys, comparisons with text and string parameters need ->value.
• A text value passed to addColumn(), modifyColumn(), new Column(), addIndex() or setAction() throws a TypeError.
• Table::CREATE, ALTER, DROP and RENAME are removed.
• A model relation type must be a Relation case.
• A subclass of Table or Column that overrides the changed methods must declare the enum types.

Relation::BELONGS_TO, Type::INT and Key::INDEX are written as before, so the module templates and migrations that use them need no change.

Testing

• One new test class per enum (case names and values). The enum tests fail before the conversion.
• Tests that reject a text value (addColumn, modifyColumn, Column, addIndex, setAction), a test for every Key through addIndex() and the generated SQL, and tests that belongsToMany is reported as unsupported by both join adapters.
• A test for the reserved-key check in Request::set() and one for a user schema with a missing key in SessionAuthAdapter, which had no coverage.

Notes for reviewers

• The starter project and the docs examples are not changed here; they follow in their own pull requests.
• PaginationLimit is a new name for the three numbers.

Summary by CodeRabbit

• Breaking Changes
  • Authentication, reserved-key, pagination, database type, key, and relation values are now accessed through enums; use each case’s string value where a string is required.
  • Table actions now use dedicated action cases. The former action constants on Table are no longer available.
  • Table column types, index types, and actions now require their corresponding enum cases. Passing text or numeric values may raise a TypeError.
  • Pagination limit constants are now available separately from pagination presentation values.

[coderabbitai]

No actionable comments were generated in the recent review.

Recent review info

Run configuration

• Source mode: Auto
• Repository: quantum-php/framework
• Branch: 3.1.x
• File: .coderabbit.yaml
• Commit: 99e3baf
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Advanced
• Run ID: d88279dd-9e0a-4ed3-b37b-19e39c3afc96

Commits

Reviewing files that changed from the base of the PR and between 99e3baf and a4bd53a.

Files selected for processing: 36

• CHANGELOG.md
• src/App/Enums/ReservedKeys.php
• src/Auth/Adapters/JwtAuthAdapter.php
• src/Auth/Adapters/SessionAuthAdapter.php
• src/Auth/Enums/AuthKeys.php
• src/Auth/Traits/AuthTrait.php
• src/Database/Enums/Key.php
• src/Database/Enums/Relation.php
• src/Database/Enums/TableAction.php
• src/Database/Enums/Type.php
• src/Database/Factories/TableFactory.php
• src/Database/Schemas/Column.php
• src/Database/Schemas/Table.php
• src/Database/Traits/TableTrait.php
• src/Http/Helpers/http.php
• src/Http/Traits/Request/Body.php
• src/Http/Traits/Response/Body.php
• src/Http/Traits/Response/Header.php
• src/Model/Exceptions/ModelException.php
• src/Paginator/Enums/Pagination.php
• src/Paginator/Enums/PaginationLimit.php
• src/Paginator/Traits/PaginatorTrait.php
• tests/Unit/App/Enums/ReservedKeysTest.php
• tests/Unit/Auth/Adapters/SessionAuthAdapterTest.php
• tests/Unit/Auth/Enums/AuthKeysTest.php
• tests/Unit/Database/Adapters/Idiorm/Statements/JoinIdiormTest.php
• tests/Unit/Database/Adapters/Sleekdb/Statements/JoinSleekTest.php
• tests/Unit/Database/Enums/KeyTest.php
• tests/Unit/Database/Enums/RelationTest.php
• tests/Unit/Database/Enums/TableActionTest.php
• tests/Unit/Database/Enums/TypeTest.php
• tests/Unit/Database/Schema/ColumnTest.php
• tests/Unit/Database/Schema/TableTest.php
• tests/Unit/Http/RequestTest.php
• tests/Unit/Paginator/Enums/PaginationLimitTest.php
• tests/Unit/Paginator/Enums/PaginationTest.php

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

Walkthrough

This PR converts several constant classes to backed enums and updates their callers. It also changes database schema method parameter types, moves pagination limits to PaginationLimit, adds relation-validation coverage, and documents the breaking API changes.

Changes: Backed enum conversions

Layer / File(s)	Summary
Authentication enum migration src/Auth/Enums/AuthKeys.php, src/Auth/Adapters/*, src/Auth/Traits/AuthTrait.php, tests/Unit/Auth/*, CHANGELOG.md	AuthKeys is now a string-backed enum. Authentication code uses case values, and tests cover enum values and rejection of a missing user-schema field.
Database enum contracts and schema operations src/Database/Enums/{Key,Type,TableAction}.php, src/Database/Schemas/*, src/Database/Factories/TableFactory.php, src/Database/Traits/TableTrait.php, tests/Unit/Database/Enums/*, tests/Unit/Database/Schema/*	Key and Type are string-backed enums, and TableAction is an integer-backed enum. Schema APIs accept enum types, table action constants were removed, and tests cover type errors and SQL output.
Relation enum and unsupported-relation handling src/Database/Enums/Relation.php, src/Model/Exceptions/ModelException.php, tests/Unit/Database/Adapters/*/Statements/Join*Test.php, tests/Unit/Database/Enums/RelationTest.php	Relation is now a string-backed enum. unsupportedRelationType accepts a Relation or string, and adapter tests cover unsupported belongs-to-many joins.
Reserved HTTP keys src/App/Enums/ReservedKeys.php, src/Http/Helpers/http.php, src/Http/Traits/{Request,Response}/*, tests/Unit/App/Enums/ReservedKeysTest.php, tests/Unit/Http/RequestTest.php	ReservedKeys is now a string-backed enum. HTTP code uses its backed values for request, response, and session keys.
Pagination enum values and limits src/Paginator/Enums/*, src/Paginator/Traits/PaginatorTrait.php, tests/Unit/Paginator/Enums/*	Pagination is now a string-backed enum. The numeric pagination limits moved to PaginationLimit, and the paginator uses both definitions.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Possibly related PRs

• quantum-php/framework#600: This PR uses native PHP enums, while #600 sets the package and CI PHP version requirements to PHP 8.1 or later.
• quantum-php/framework#621: Both PRs change how Header::back() stores previous-request data using ReservedKeys::PREV_REQUEST.

Suggested labels: enhancement

Suggested reviewers: andrey-smaelov, grigoryanmartin20

Merge Risk: Minimal · up to a4bd5

The enum migration has no identified issue that needs correction before merge; the documented API changes still require normal compatibility checks.

Pre-merge checks: 5

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title 'Issue/612 Convert the first batch of Enums classes to PHP enums' matches the main change. The PR converts ReservedKeys, AuthKeys, Pagination, Type, Key, and Relation from constant classes t…
Docstring Coverage		Docstring coverage is 95.45% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentati…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Title check

Explanation

The title 'Issue/612 Convert the first batch of Enums classes to PHP enums' matches the main change. The PR converts ReservedKeys, AuthKeys, Pagination, Type, Key, and Relation from constant classes to string-backed PHP enums, and adds TableAction and PaginationLimit. The title names the issue and the core change, but does not name the specific classes. It is specific enough for a teammate scanning history.

Full details: Docstring Coverage

Explanation

Docstring coverage is 95.45% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 44 functions across 35 files. (1 skipped: 1 unsupported.)

Finishing Touches

Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

• X
• Mastodon
• Reddit
• LinkedIn

[codecov]

Codecov Report

❌ Patch coverage is 97.50000% with 3 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/Auth/Adapters/JwtAuthAdapter.php	80.00%	3 Missing ⚠️

📢 Thoughts on this report? Let us know!