# Contributing

Thanks for considering a contribution to the Openstatus PHP SDK.

## Development setup

Requires PHP 8.4+ and Composer.

```bash
composer install
composer test       # phpunit
composer analyse    # phpstan level 8
composer fmt        # php-cs-fixer
```

## Bumping the pinned schema version

The PHP message classes under `src/Gen/` are generated from the pinned Buf
archive listed in `scripts/regen.sh`. Never edit `src/Gen/` by hand.

1. Find the latest archive version at
   <https://buf.build/openstatus/api/sdks/main:protocolbuffers/php>.
2. Edit `BUF_PHP_VERSION` in `scripts/regen.sh`.
3. Run `composer regen`.
4. Commit both `scripts/regen.sh` and the resulting `src/Gen/` diff in a single PR.

The weekly `regen.yml` workflow does this automatically when a new version is
published; you only need to do it manually if you want to ship a schema change
before the next cron run.

## Adding a new RPC

When the schema gains a new RPC, add a single dispatch method to the relevant
file under `src/Services/`. The method takes the typed request message and an
optional `array $headers = []`, and returns the typed response message. Match
the existing pattern; one method per RPC, no abstractions.

## Code style

- PSR-12 plus `declare(strict_types=1);` on every file.
- All hand-written public classes are `final`.
- No `mixed` types in `src/` (PHPStan level 8 enforces this).
- Run `composer fmt` before opening a PR.

## Tests

- Unit tests under `tests/Unit/` run on every PR. They use a PSR-18 mock client
  and never touch the real API.
- Integration tests under `tests/Integration/` are gated on `OPENSTATUS_API_KEY`
  and run locally before tagging a release. They are not wired into CI.