PHP Guidelines

Overview

Modern PHP guidelines based on the PHP Manual covering PHP 8.x idioms. PHP has evolved dramatically — write modern, type-safe PHP, not legacy PHP 5 patterns.

Core Principles

Always use declare(strict_types=1) — first line of every file
Type everything — parameters, returns, properties, constants
Use === not == — loose comparison causes security bugs
Errors are exceptions — catch them, don't suppress with @
Composition over inheritance — interfaces + traits over deep hierarchies

Strict Types

<?php
declare(strict_types=1);  // MUST be first statement

function add(int $a, int $b): int {
    return $a + $b;
}
add("1", "2"); // TypeError in strict mode, silently coerces without it

Mode	Behavior
Coercive (default)	`"123"` silently becomes `123`, truncates floats
Strict (`strict_types=1`)	TypeError on any mismatch (except `int` to `float`)
Scope	Per-file — each file must declare independently

Type System

Scalar Types

Type	Falsy values	Gotchas
`bool`	`false`	`-1` is truthy; `"0"` is falsy but `"false"` is truthy
`int`	`0`	Overflow silently becomes `float`; use `PHP_INT_MAX`
`float`	`0.0`, `-0.0`	Never compare for equality — use epsilon; `NAN != NAN`
`string`	`""`, `"0"`	No native Unicode — use `mbstring`; `"0"` is falsy
`null`	`null`	`isset()` returns false for null; use `?Type` or `Type\|null`

Type Declarations

// Union types (PHP 8.0+)
function handle(int|string $value): string|false { }

// Intersection types (PHP 8.1+)
function process(Countable&ArrayAccess $data): void { }

// DNF types (PHP 8.2+)
function route((Logger&Handler)|NullHandler $h): void { }

// Nullable shorthand
function get(?int $id): ?string { }  // same as int|null

// Special return types
function loop(): never { while(true) {} }   // never returns
function fire(): void { }                    // returns nothing

Type	Use for
`mixed`	Accepts anything (avoid — be specific)
`void`	Function returns nothing visible
`never`	Function never returns (exit, throw, infinite loop)
`iterable`	`array\|Traversable`
`callable`	Parameters/returns only — cannot type properties
`self`, `static`, `parent`	Class context references

Type Juggling Pitfalls

// BAD: loose comparison — security holes
0 == "a"       // false in PHP 8 (was TRUE in PHP 7!)
"0" == false   // true — "0" is falsy
"" == null     // true
"0" == null    // false (inconsistent!)
"123" == "123.0" // true — numeric string comparison

// GOOD: always strict
0 === "a"      // false
"0" === false  // false

// Float precision trap
0.1 + 0.7 == 0.8   // FALSE — binary representation
floor((0.1 + 0.7) * 10) // 7, not 8!
// Use: abs($a - $b) < PHP_FLOAT_EPSILON

OOP

Rules Summary

Rule	Detail
Always declare property types	Untyped properties are error-prone
Use `readonly` for immutable data	Can only be set once (PHP 8.1+)
Constructor promotion	Reduces boilerplate — use for simple DTOs
`private(set)`	Read public, write private (PHP 8.4+)
Dynamic properties deprecated	PHP 8.2+ — declare all properties explicitly
Reading uninitialized typed property	Throws Error
Interface methods must be public	All of them
Small interfaces	1-3 methods — compose larger ones
Abstract for shared behavior	Interfaces for contracts
`final` prevents extension	Use when inheritance isn't intended
`final` class constants (8.1+)	Prevent override in children
Use enums over class constants	Type-safe, exhaustive matching (PHP 8.1+)
`from()` throws on invalid	`tryFrom()` returns null
Enums can have methods and interfaces	But no state (properties)

Detailed OOP code examples (classes, interfaces, traits, enums, visibility, magic methods): see resources/oop-patterns.md

Dependency Injection & SOLID

Principle	Rule
S — Single Responsibility	One class = one reason to change
O — Open/Closed	Open for extension, closed for modification — use interfaces
L — Liskov Substitution	Subtypes must be substitutable for their base types
I — Interface Segregation	Many small interfaces > one large interface
D — Dependency Inversion	Depend on abstractions (interfaces), not concretions

Rule	Detail
Constructor injection	Preferred — makes dependencies explicit
Type-hint interfaces	Not concrete classes — enables swapping
DI container ≠ DI	Containers are optional convenience; DI is the pattern
Avoid Service Locator	Hiding dependencies inside a container = anti-pattern
`final` by default	Mark classes `final` unless designed for extension

DI code examples and namespace patterns: see resources/oop-patterns.md

PSR Standards & Composer

PSR Standards

Standard	Purpose
PSR-1	Basic coding standard — `<?php` tag, UTF-8, class naming
PSR-4	Autoloading — namespace maps to directory structure
PSR-12 / PER	Extended coding style — indentation, braces, spacing
PSR-3	Logger interface (`Psr\Log\LoggerInterface`)
PSR-7	HTTP message interfaces (request/response)
PSR-11	Container interface (`Psr\Container\ContainerInterface`)
PSR-15	HTTP handlers and middleware

Composer

# Initialize project
composer init

# Add dependency
composer require monolog/monolog

# Install from lock file (deployment — deterministic)
composer install --no-dev --optimize-autoloader

# Update to latest compatible versions (development)
composer update

# Autoload — include once at entry point
require 'vendor/autoload.php';

Rule	Detail
Commit `composer.lock`	Ensures identical versions across team/environments
`composer install` in production	Never `composer update` — use lock file
`--no-dev` in production	Exclude dev dependencies
`--optimize-autoloader` / `-o`	Converts PSR-4/PSR-0 to classmap for speed
PSR-4 autoloading	Namespace `App\` -> directory `src/`
`composer dump-autoload -o`	Regenerate optimized autoload after changes
Security auditing	`composer audit` checks for known vulnerabilities

Modern PHP 8.x Patterns

Key features by version:

Version	Key Features
8.0	Match, named args, union types, constructor promotion, nullsafe `?->`, attributes
8.1	Enums, readonly, fibers, intersection types, `never`, first-class callables
8.2	Readonly classes, DNF types, `true`/`false`/`null` types, trait constants
8.3	Typed class constants, `#[Override]`, `json_validate()`
8.4	Property hooks, asymmetric visibility, `#[Deprecated]`, lazy objects
8.5	Pipe operator `\|>`, `#[NoDiscard]`, `(void)` cast

Detailed code examples for all features, functions, generators, fibers, and attributes: see resources/modern-php.md

Error Handling

try {
    $result = riskyOperation();
} catch (NotFoundException $e) {
    return defaultValue();
} catch (ValidationException | AuthException $e) {
    log($e->getMessage());
    throw $e;
} finally {
    cleanup();  // always runs
}

Rule	Detail
Catch `\Throwable` for everything	`Exception` + `Error`
Use union catches	`catch (TypeA \| TypeB $e)` (PHP 8.0+)
Catch without variable	`catch (SpecificException)` (PHP 8.0+)
Call `parent::__construct()`	In custom exception classes
Log exceptions, don't display	Never show stack traces to users
`throw` is an expression (8.0+)	`$x ?? throw new Exception()`
Never use `@` suppression	Hides real problems; custom handlers still fire
PHP 7+ throws `Error`	Not `Exception` — use `\Throwable`

Error Configuration

Setting	Development	Production
`error_reporting`	`E_ALL`	`E_ALL`
`display_errors`	`On`	`Off`
`log_errors`	`On`	`On`
`error_log`	stderr	syslog or file

Arrays & Strings

Arrays

$map = ['key' => 'value', 'other' => 42];
$list = [1, 2, 3];

// Destructuring
['name' => $name, 'age' => $age] = $userData;
[$first, , $third] = $list;  // skip second

// Spread (PHP 7.4+ for numeric, 8.1+ for string keys)
$merged = [...$array1, ...$array2];

Rule	Detail
Null coalescing	`$map['key'] ?? $default`
Keys are `int\|string` only	Objects/arrays cannot be keys
Iteration order preserved	Arrays are ordered maps
Empty array is falsy	`if ($arr)` checks non-empty

Strings

// Interpolation — use braces for clarity
$msg = "Hello {$user->name}, you have {$count} items";

// Heredoc (indented, PHP 7.3+)
$html = <<<HTML
    <div class="card">
        <h1>{$title}</h1>
    </div>
    HTML;

// Nowdoc — no interpolation
$sql = <<<'SQL'
    SELECT * FROM users WHERE id = :id
    SQL;

Rule	Detail
Use `{$var}` in double-quoted	Not `${var}` (deprecated PHP 8.2)
Single-byte encoding	Use `mb_strlen()`, `mb_substr()` for Unicode
`===` for string comparison	`==` does numeric coercion on numeric strings
Negative offset (7.1+)	`$str[-1]` for last character

JSON

// Encode — always use JSON_THROW_ON_ERROR (PHP 7.3+)
$json = json_encode($data, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);

// Decode — assoc arrays are faster than objects for data access
$data = json_decode($json, true, 512, JSON_THROW_ON_ERROR);

// Validate without decoding (PHP 8.3+)
if (json_validate($json)) { /* valid */ }

// Large integers — prevent precision loss
$data = json_decode($json, true, 512, JSON_BIGINT_AS_STRING);

Flag	Effect
`JSON_THROW_ON_ERROR`	Throw `JsonException` instead of returning `false`/`null`
`JSON_UNESCAPED_UNICODE`	Don't escape UTF-8 chars — smaller output
`JSON_UNESCAPED_SLASHES`	Don't escape `/` — cleaner URLs
`JSON_PRESERVE_ZERO_FRACTION`	Keep `10.0` instead of `10`
`JSON_BIGINT_AS_STRING`	Decode large ints as strings (prevent precision loss)
`JSON_NUMERIC_CHECK`	Convert numeric strings to numbers — use cautiously (phone numbers!)
`JSON_INVALID_UTF8_SUBSTITUTE`	Replace broken UTF-8 with `U+FFFD` (PHP 7.2+)
`JSON_PRETTY_PRINT`	Human-readable output — dev/debug only

Rule	Detail
Always `JSON_THROW_ON_ERROR`	Never check `json_last_error()` manually
Input must be UTF-8	`mb_convert_encoding()` first if unsure
`json_validate()` (8.3+)	Faster than decode when you just need validity
Assoc arrays over objects	`json_decode($json, true)` — faster property access

Testing

Rule	Detail
`assertSame()` over `assertEquals()`	Strict comparison (type + value)
Data providers for table-driven tests	`#[DataProvider('method')]` attribute
`expectException()` before the call	Not after
Test naming	`Test.php`, method `test`
PHPStan	Levels 0-9 strictness; start low, increase per sprint
Psalm	Adds taint analysis for security
CI gate	Fail build on any new error — never ignore regressions

Full testing examples, static analysis setup, and version migration reference: see resources/testing-migration.md

Build & Deploy

Always Use Makefile

Before running composer install or any build command, check if a Makefile exists. If it does, use it.

Situation	Action
Makefile exists with relevant target	`make deploy`, `make build`, `make test`
Makefile exists, no matching target	List targets, pick closest
No Makefile	`composer install`, `php artisan`, etc.

Permissions & Ownership

stat -c '%U:%G' * | sort | uniq -c | sort -rn | head -5
chown -R <user>:<group> .

Temporary Files

File type	Location
Build intermediates	`/tmp` — never the project directory
Dependencies	`vendor/` (Composer standard)

Test File Placement

Test type	Location
Temporary	`/tmp`
Permanent, dir exists	`tests/` (follow existing structure)
Permanent, no dir	Create `tests/` at project root

Anti-Pattern Quick Reference

Anti-Pattern	Better Alternative
No `strict_types`	`declare(strict_types=1)` in every file
`==` comparison	`===` everywhere
`@` error suppression	Try-catch or proper validation
No type declarations	Type params, returns, properties, constants
`catch (Exception)` only	`catch (\Throwable)` for `Error` too
Dynamic properties	Declare explicitly (`#[AllowDynamicProperties]` if must)
Class constants for finite sets	`enum` (PHP 8.1+)
Deep inheritance	Interfaces + traits composition
`__sleep()` / `__wakeup()`	`__serialize()` / `__unserialize()`
`${var}` interpolation	`{$var}`
`get_class()` no arg	`$obj::class`
`switch` fall-through	`match` expression
Manual null chain	Nullsafe `?->`
`array_key_exists` + access	`??` null coalescing
String constants	Backed enums
Float `==`	Epsilon: `abs($a - $b) < PHP_FLOAT_EPSILON`
`global $var`	Dependency injection
`extract()`	Explicit assignment
Implicit nullable param	Explicit `?Type`
`(boolean)` cast	`(bool)`
`json_last_error()` checking	`JSON_THROW_ON_ERROR` flag

Resources

Detailed code examples and extended references are organized in resource files:

resources/oop-patterns.md — OOP detailed code (classes, interfaces, traits, enums, visibility, magic methods), dependency injection examples, and namespace patterns
resources/modern-php.md — Modern PHP 8.x feature code (match, named args, readonly, pipe operator, deprecated/nodiscard), functions (arrow functions, closures, variadic, generators, fibers), and attributes
resources/testing-migration.md — Testing examples with PHPUnit and data providers, static analysis setup (PHPStan, Psalm), and PHP version migration reference (8.0-8.5)

php-guidelines