coding-standards_skill

Overview

This skill defines language-level PHP coding standards covering PSR-12, PHPDoc, and PHP 8+ type hints for any PHP project. It enforces consistent file structure, naming, formatting, and error-handling practices to improve readability and maintainability. The guidance is framework-agnostic and intended to be applied across CakePHP, Laravel, Symfony, and plain PHP codebases.

How this skill works

The skill inspects source files for PSR-12 compliance (file headers, namespaces, alphabetical imports, and class naming) and checks method signatures for parameter and return type hints. It requires comprehensive PHPDoc for public methods and properties, documents thrown exceptions, and enforces consistent formatting: 4-space indentation, <=120 character line length, and blank-line placement. It also recommends static analysis (PHPStan) and automated formatting (PHP-CS-Fixer) for continuous validation.

When to use it

• When establishing a project-wide PHP style guide for a new or existing codebase
• During code review to ensure consistent documentation, type safety, and formatting
• Before running CI checks to catch missing type hints or PHPDoc annotations
• When onboarding developers to ensure uniform naming and error-handling practices
• When integrating static analysis and automatic code formatting into pipelines

Best practices

• Always declare strict_types at the top of PHP files
• Require parameter and return type hints for all methods, using unions and nullable types where appropriate
• Write a one-line short description in PHPDoc plus longer details and @param/@return/@throws tags for public methods
• Keep indentation to 4 spaces, limit lines to 120 characters, and place blank lines between logical sections
• Use specific exception types, document them with @throws, and handle predictable exceptions with targeted catch blocks
• Run PHPStan (recommended level 7+) and PHP-CS-Fixer in CI to automate checks and fixes

Example use cases

• Enforcing consistent method signatures and PHPDoc in a monorepo shared by multiple teams
• Adding a pre-commit or CI check to fail builds on missing type hints or PSR-12 violations
• Migrating a legacy codebase to PHP 8+ by progressively adding return types and union types
• Standardizing error handling across services by documenting thrown exceptions and using targeted catches
• Configuring PHP-CS-Fixer and PHPStan with these rules to provide automated fixes and type validation