Coding standards

By Rafael Duarte · created 4 May 2020, 08:00 UTC · last updated 30 Sep 2026, 12:30 UTC · version 13

standardsphptypescriptreviews

Rules we hold each other to in review. The tools enforce what they can; this page is for the rest.

Everywhere

Never hard-code a region. Read the client's region ($client->region, a Region, in identity-service; client.region in notifier). Code that assumes Frankfurt is a data residency bug.
No personal data in logs. Log ids, not emails, names or phone numbers. The logger masks emails and numbers it recognises; don't rely on it.
Events go through the outbox. Never publish to the queue from application code (Events and the outbox).
Behaviour customers see ships behind a flag per client.
Tests come with the change. A bug fix starts with a test that fails.
Name things after what they mean to a customer: depot, approver, access request, home depot. Not "location", "validator", "ticket".

PHP 8.3, Laravel conventions, declare(strict_types=1), typed properties and return types.
Pest for tests. Laravel Pint for formatting; PHPStan at level 6.
Policies decide who may do what. Controllers don't check roles by hand.
Anything in src/Approvals or src/Policies needs a test for who may not do the thing, too.
Migrations: reversible, one concern each, no data changes mixed with schema changes.
Jobs are idempotent: running one twice changes nothing the second time.

strict on. No any without a comment saying why.
ESLint and Prettier as configured in each repository.
Portal: function components, data through the API client in src/api, strings in src/i18n/locales/en/. Every screen works with the keyboard alone.
notifier: every consumer handles the same event twice without sending twice.

Review within one working day. If you can't, say so.
Ask questions in the review, not in Slack, so the next reader sees them.
Two approvals for src/Saml, src/Approvals and region code.
Merge requests from agents (Codex, Claude Code) are reviewed like anyone's; the person who ran the agent is the author.

Version	Date	Who	What
11	19 Jan 2026	Rafael	Never hard-code a region (US region)
12	10 Aug 2026	Aiko	Keyboard rule for portal screens
13	30 Sep 2026	Lukas	Merge requests from agents