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

• .gitkeep 1 KB
• SKILL.md 5 KB
• references/per-coding-style.md 4 KB
• references/psr-catalog.md 3 KB
• references/psr4-autoloading.md 3 KB
• references/templates/composer-json.md 3 KB
• references/templates/project-structure.md 2 KB