/php-standards

name: php-standards
description: Use when setting up PHP-package autoloading, coding style, or PSR interfaces — PSR-4, PER Coding Style 3.1, composer.json. Do NOT use for syntax or Laravel.
versions:
  per-coding-style: "3.1"
  psr-4: "accepted"
  composer: "2"
user-invocable: false
references: references/per-coding-style.md, references/psr-catalog.md, references/psr4-autoloading.md, references/templates/composer-json.md, references/templates/project-structure.md
related-skills: php-language-modern

<objective> Covers the standards that shape a framework-agnostic PHP package: PSR-4 autoloading (and why PSR-0 is deprecated), PER Coding Style 3.1 versus the still-Accepted PSR-12, and the current PSR catalog to depend on for logging (PSR-3), caching (PSR-6/16), HTTP (PSR-7/15/17/18), DI containers (PSR-11), events (PSR-14), and time (PSR-20).

Includes composer.json and project-structure templates (src/ for library code, tests/ wired via autoload-dev, PSR-4 namespace mapping), and the core PER/PSR-1 file rules (4 spaces, LF endings, no closing ?>).

Do NOT use this skill for language syntax or feature questions — that is php-language-modern. Do NOT use it for Laravel-specific conventions, which live in the Laravel plugin. </objective>

PHP Standards (PSR / PER / Composer)

Agent Workflow (MANDATORY)

Before applying a standard, spawn 3 agents in parallel, one `Agent` call each with a `name`:

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.1 | "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](references/psr4-autoloading.md). 2. **PER Coding Style 3.1 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](references/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](references/templates/project-structure.md) for the full layout

---

Reference Guide

Concepts

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

Templates

| Template | When to Use | |----------|-------------| | [composer-json.md](references/templates/composer-json.md) | Starting or modernizing a package | | [project-structure.md](references/templates/project-structure.md) | Laying out directories |

---

Best Practices

DO

• Use PSR-4 with `src/` mapped to the vendor namespace
• Follow PER Coding Style 3.1 (run php-cs-fixer with the `@PER-CS` ruleset — it currently enforces the 3.0 rules; apply the 3.1 additions by review)
• 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