Contributing

​

Getting Started

​

1. Fork and Clone

1. Click Fork on github.com/apivalk/apivalk.
2. Clone your fork locally:

git clone git@github.com:<your-username>/apivalk.git
cd apivalk

3. Add the upstream remote so you can stay in sync:

git remote add upstream git@github.com:apivalk/apivalk.git

​

2. Create a Branch

git checkout -b feat/2312-cursor-pagination-metadata
git checkout -b fix/2315-jwt-expiry-validation
git checkout -b docs/add-rate-limit-example   # no issue → description only

​

3. Set Up the Development Environment

docker compose build
docker compose run --rm php72 composer install

​

4. Make Your Changes

​

5. Run the Test Suite and Static Analysis

# Unit tests
docker compose run --rm php72 composer test

# Static analysis (PHPStan level 6)
docker compose run --rm php72 composer phpstan

​

6. Open a Pull Request

git push origin feat/cursor-pagination-metadata

• Tests pass (composer test)
• PHPStan passes (composer phpstan)
• Commit messages follow Conventional Commits
• Breaking changes are flagged with BREAKING CHANGE: in the commit footer
• New public APIs have corresponding test coverage
• Docs updated if behaviour changed

​

Commit Messages

​

Format

<type>(<optional scope>): <short summary>

[optional body]

[optional footer(s)]

​

Types

​

Examples

feat(pagination): add cursor-based paginator
docs(routing): add caching example to router guide

fix(jwt): handle expired tokens without throwing uncaught exception

Issue: #2315

test(validation): cover missing required body property case

Issue: #2318

​

Breaking Changes

feat(request)!: remove deprecated getBody() alias

BREAKING CHANGE: getBody() was removed. Use body() instead.
Issue: #2312

​

Issues

​

Reporting a Bug

• PHP version and Apivalk version (composer show apivalk/apivalk)
• A minimal reproducible example
• What you expected vs. what happened
• Stack trace if applicable

​

Proposing a Feature

​

Standards

​

Coding Standards

• declare(strict_types=1) on every file.
• PSR-1 / PSR-12 formatting.
• PHPStan level 6 — no new violations.
• Single Responsibility: one controller per route/method, one request per endpoint, one validator per property type.
• Fail fast: validation happens in middleware, never inside controllers.
• No raw $_POST / $_GET / $_SERVER in framework code — go through the request abstraction.
• Type hints on all method signatures, including return types.

​

OpenAPI & REST Standards

• REST Design and Naming — resource-oriented URLs, correct HTTP verbs, noun-based naming.
• Versioning and Structure — /v1/ prefix, no breaking changes within a version.
• Pagination, Filtering, Sorting — use Apivalk’s built-in strategies; don’t invent custom query param conventions.
• Responses, Errors, Status Codes — use the correct HTTP status code and the built-in typed error responses.
• Localization / i18n — Accept-Language / Content-Language via LocalizationConfiguration.

​

Test Coverage

• New features need tests. Follow the existing structure: Tests/PhpUnit/ mirrors the source tree.
• Tests must be runnable with vendor/bin/phpunit and pass on PHP 7.2.
• Unit test individual classes; integration tests go through the full Apivalk::run() lifecycle where relevant.

​

Questions