fusengine/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