php-standards

PHP Standards (PSR / PER / Composer)

Agent Workflow (MANDATORY)

Before applying a standard, use TeamCreate to spawn 3 agents:

1. fuse-ai-pilot:explore-codebase - Detect existing style config (.php-cs-fixer.php, phpcs.xml), composer.json autoload
2. fuse-ai-pilot:research-expert - Verify a PSR's current status on php-fig.org before recommending it
3. mcp__context7__query-docs - Cross-check composer.json schema

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

---

Overview

Concern	Standard	Notes
Autoloading	PSR-4	Recommended; PSR-0 is deprecated
Coding style	PER Coding Style 3.0	"Extends, expands and replaces PSR-12"; PSR-12 remains the Accepted PSR
Logging	PSR-3	LoggerInterface
Caching	PSR-6 / PSR-16	Pool vs Simple Cache
HTTP	PSR-7 / 15 / 17 / 18	Message / Handlers / Factories / Client
DI container	PSR-11	ContainerInterface
Events	PSR-14	Event Dispatcher
Time	PSR-20	ClockInterface — testable "now"

---

Critical Rules

1. PSR-4 for autoloading, never PSR-0 - PSR-0 and target-dir are deprecated. See psr4-autoloading.md.
2. PER Coding Style 3.0 is the current style spec - It supersedes PSR-12 in practice while requiring PSR-1. PSR-12 is still the officially Accepted PSR — document the nuance, don't pretend PSR-12 was withdrawn. See per-coding-style.md.
3. Depend on PSR interfaces, not implementations - Type-hint Psr\Log\LoggerInterface, not a concrete logger.
4. 4 spaces, no tabs; LF line endings; omit closing ?> - Core PER/PSR-1 file rules.
5. src/ for library code, tests/ for tests - Wire tests/ via autoload-dev, never autoload.

---

Architecture

my-package/
├── composer.json           # PSR-4 autoload + autoload-dev + scripts
├── src/                    # Namespace root (Vendor\Package\)
│   └── Service.php
├── tests/                  # PSR-4 dev namespace (Vendor\Package\Tests\)
│   └── ServiceTest.php
└── bin/                    # CLI entry points (composer "bin")

→ See project-structure.md for the full layout

---

Reference Guide

Concepts

Topic	Reference	When to Consult
PER Coding Style	per-coding-style.md	Formatting rules, PER vs PSR-12
PSR catalog	psr-catalog.md	Which PSR to depend on / avoid
PSR-4 autoloading	psr4-autoloading.md	Namespace-to-path mapping

Templates

Template	When to Use
composer-json.md	Starting or modernizing a package
project-structure.md	Laying out directories

---

Best Practices

DO

• Use PSR-4 with src/ mapped to the vendor namespace
• Follow PER Coding Style 3.0 (run php-cs-fixer with the @PER-CS ruleset)
• Depend on PSR interface packages (psr/log, psr/http-message, …)
• Put test-only classes under autoload-dev

DON'T

• Use PSR-0 autoloading or target-dir (deprecated)
• Claim PER "replaced" PSR-12 as the official standard — PSR-12 is still Accepted
• Depend on PSR-2/PSR-0 (deprecated) or PSR-8/9/10 (abandoned)
• Hardcode a concrete logger/cache when a PSR interface exists