home / skills / hoangnguyen0403 / agent-skills-standard / best-practices

best-practices skill

safe

This skill helps you implement PHP best practices with PSR-12, autoloading, SOLID design, and clean code structure for maintainable apps.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill best-practices

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.3 KB

---
name: PHP Best Practices
description: PHP best practices, PSR standards, and code quality guidelines.
metadata:
  labels: [php, psr, best-practices]
  triggers:
    files: ['**/*.php']
    keywords: [psr-12, camelCase, PascalCase, dry, solid]
---

# PHP Best Practices

## **Priority: P1 (HIGH)**

## Structure

```text
src/
├── {Domain}/             # e.g., Services, Repositories
└── Helpers/              # Pure functions/Traits
```

## Implementation Guidelines

- **PSR-12**: Follow PSR-12 for coding style (indent, braces, space).
- **Autoloading**: Use PSR-4 via Composer.
- **Namespacing**: Map namespaces to directory structure.
- **PascalCase**: Use for all class names.
- **camelCase**: Use for methods and variables.
- **SNAKE_CASE**: Use for class constants.
- **DRY Logic**: Extract repetitive logic into traits/methods.
- **SOLID**: Use interfaces for decoupling and SRP adherence.

## Anti-Patterns

- **God Classes**: **No Monoliths**: Avoid classes with multiple responsibilities.
- **Magic Numbers**: **No Hardcoding**: Use class constants for config values.
- **Deep Nesting**: **No Nesting**: Guard clauses over nested if/else.
- **Direct Output**: **No Echo**: Return data; let controller handle response.

## References

- [Clean Code Patterns](references/implementation.md)

Overview

This skill codifies PHP best practices, PSR standards, and code quality guidelines to help agents produce clean, maintainable PHP code. It focuses on project structure, naming conventions, autoloading, and design principles that reduce technical debt and improve readability. The guidance is practical and aimed at real-world PHP projects following modern standards.

How this skill works

The skill inspects code and project layout against PSR-12 and PSR-4 conventions, checks naming and casing rules, and flags anti-patterns such as god classes, magic numbers, deep nesting, and direct output in business logic. It recommends extracting reusable logic into helpers or traits and using interfaces to enforce SOLID design. It outputs concrete remediation steps and examples for quick fixes.

When to use it

When scaffolding a new PHP service or package to ensure consistent structure and autoloading.
During code reviews to catch style violations and architecture anti-patterns early.
When refactoring legacy code to improve separation of concerns and reduce coupling.
Before release to verify adherence to PSR-12 and PSR-4 standards.
When onboarding engineers to align team conventions and naming rules.

Best practices

Organize source under src/ with domain folders (Services, Repositories) and Helpers for pure functions or traits.
Follow PSR-12 for formatting and use Composer with PSR-4 autoloading and namespace-to-directory mapping.
Name classes in PascalCase, methods and variables in camelCase, and class constants in SNAKE_CASE.
Prefer small single-responsibility classes and use interfaces to decouple implementations (SOLID principles).
Replace repeated code with traits or helper methods and centralize configuration values as class constants.
Avoid direct output (echo/print) inside logic; return data and let controllers or responders handle responses.

Example use cases

Validate a new repository structure and suggest PSR-4 namespace mappings for Composer.
Review a controller that echoes content and recommend returning DTOs or response objects instead.
Refactor a large service into smaller classes and interfaces to eliminate a god class.
Convert hardcoded numeric values to named class constants and update references.
Simplify deeply nested conditional logic by introducing guard clauses and early returns.

FAQ

Do I have to follow PSR-12 and PSR-4 exactly?

Aim to follow PSR-12 and PSR-4 for consistency; minor deviations can be tolerated for legacy constraints, but document exceptions and migrate when feasible.

When should I use traits versus standalone helpers?

Use traits for reusable behavior that logically belongs to an object; use pure helper functions for stateless utilities that don't fit an object context.