PHP Guidelines

by Convext

Official

Public

PHP best practices

php laravel

Rules (20)

Config

high Use environment variables for configuration

Config in env vars, not code. Never commit .env. Commit .env.example. Never hardcode secrets.

Database

critical Never store sensitive data in plain text

Passwords: bcrypt. API keys: encrypt. PII: field-level encryption. Never log sensitive data.

Dependencies

critical Always use latest dependency versions

Use latest stable versions. Fix breaking changes—don't avoid upgrades. Check official registries.

Git

medium Atomic commits with Conventional Commits

Small, focused commits. Use: feat/fix/refactor/test/docs/chore. Each commit independently deployable.

Llm Behavior

critical User defines success

User and tests define done. Don't redefine scope or declare partial progress as complete.

critical No rationalizations

No excuses: 'pre-existing', 'unrelated', 'tedious', 'for now'. Recognize and continue working.

critical Own all code in the repository

You wrote every line. No 'pre-existing issues'—only issues you haven't fixed yet.

Rails

critical Use Rails credentials for secrets

Rails.application.credentials for secrets. `rails credentials:edit`. Environment-specific credentials. Never commit master.key.

Security

critical Use HTTPS everywhere

Force SSL, redirect HTTP→HTTPS, secure cookies (Secure/HttpOnly/SameSite), HSTS headers.

critical Implement proper authentication and authorization

Auth: bcrypt/argon2 for passwords, rate limiting, secure sessions/tokens. Authz: check permissions on every request, use policy objects or middleware.

critical Validate and sanitize all user input

Allowlists, not denylists. Validate type/length/format. Sanitize HTML. Parameterized queries only.

Testing

critical No mocking the class under test

Test real instances. Mocking the class under test hides bugs.

critical Never ignore failing tests

Fix failures immediately. No skipping, no "pre-existing issues." Own the codebase state—a test suite with ignored tests can't be trusted.

high TDD: Red -> Green -> Refactor

1) Write failing test 2) Minimum code to pass 3) Refactor. Every line has a reason.

high Test behavior, not implementation

Test public interfaces, inputs/outputs. Tests must survive refactoring. Don't test private methods.

high Mock only at external boundaries

Mock only: external HTTP APIs, time, filesystem side effects, third-party services. Use real implementations for internal services, database, and business logic.

medium One assertion per test (conceptually)

One logical concept per test. Multiple asserts OK if same concept. Clear test names describing behavior.

medium Use fixtures or factories for test data

Use consistent test data setup: fixtures for stable reference data, factories for dynamic scenarios. Avoid inline object creation scattered throughout tests.

Workflow

critical Code must work locally before pushing

Verify changes locally: run app, run tests, check for errors. CI catches environment issues, not basic bugs.

high Run formatter, linter, and tests before commit

Format → Lint → Test before every commit. Never rely on CI for basic checks.

Language Standards (1)

php

Framework: laravel Linter: phpstan Formatter: php-cs-fixer

Use this Ruleset

Statistics

Rules: 20
Standards: 1
Projects using: 0
Created: Jan 15, 2026