php-language-modern

Modern PHP Language (8.1 → 8.5)

Agent Workflow (MANDATORY)

Before writing PHP, use TeamCreate to spawn 3 agents:

1. fuse-ai-pilot:explore-codebase - Detect the project's minimum PHP version (composer.json require.php, CI matrix)
2. fuse-ai-pilot:research-expert - Verify a feature's version + syntax on php.net before using it
3. mcp__context7__query-docs - Cross-check idiomatic usage

After writing, run fuse-ai-pilot:sniper for validation.

---

Overview

Feature	Since	Use it for
Enums (backed + methods/interfaces)	8.1	Closed sets of values with behavior
First-class callable syntax f(...)	8.1	Passing callables without strings
readonly properties / classes	8.1 / 8.2	Immutable value objects / DTOs
#[\Override]	8.3	Fail-fast on broken inheritance
Property hooks get/set	8.4	Computed/validated properties, no getter/setter boilerplate
Asymmetric visibility public private(set)	8.4 (static: 8.5)	Public read, restricted write
Lazy objects newLazyGhost()	8.4	Deferred initialization in DI containers
Pipe operator |>	8.5	Left-to-right data transformation chains
clone() function + $withProperties	8.5	Immutable "with" updates, incl. readonly
#[\NoDiscard]	8.5	Enforce return-value consumption

---

Critical Rules

1. Attributes, never docblock annotations - Native #[Attribute] replaces @annotation docblocks for routing, ORM, DI, validation. This is the #1 LLM mistake — see attributes-over-docblocks.md.
2. Check the target PHP version first - Never emit 8.5 syntax on an 8.1 project. Read composer.json require.php before choosing a feature.
3. Prefer enums over class constants for closed value sets — they carry type safety and methods.
4. Prefer readonly + property hooks over hand-written getters/setters — less boilerplate, enforced immutability.
5. declare(strict_types=1); at the top of every file.

---

Architecture

src/
├── Enum/
│   └── Status.php          # backed enum + interface + methods
├── ValueObject/
│   └── Money.php           # readonly class, clone() with $withProperties
└── Model/
    └── User.php            # property hooks, asymmetric visibility

→ See modern-class.md for complete working code

---

Reference Guide

Concepts

Topic	Reference	When to Consult
PHP 8.5 features	php-85-features.md	Pipe operator, clone(), #[\NoDiscard], static aviz
PHP 8.4 features	php-84-features.md	Property hooks, aviz, lazy objects, #[\Deprecated]
8.1–8.3 baseline	php-81-83-baseline.md	Enums, readonly, fibers, #[\Override]
Attributes vs docblocks	attributes-over-docblocks.md	Any metadata: routing, ORM, DI, validation

Templates

Template	When to Use
modern-class.md	Writing a new class the modern way

---

Best Practices

DO

• Read require.php before picking a feature version
• Use enums with interfaces + methods for stateful value sets
• Use property hooks for validation/computation instead of magic __get
• Use the pipe operator to flatten nested calls (8.5+)

DON'T

• Write @Route/@ORM\Column docblock annotations — use attributes
• Emit 8.4/8.5 syntax without confirming the project supports it
• Hand-roll getters/setters when hooks or readonly fit
• Guess a feature's version — verify on php.net