coding-standards
PHP coding standards (PSR-12, PHPDoc, type hints) for any PHP project
When & Why to Use This Skill
This Claude skill automates the enforcement of professional PHP coding standards, focusing on PSR-12 compliance, comprehensive PHPDoc documentation, and strict type hinting. It ensures that PHP codebases remain consistent, readable, and maintainable by applying modern best practices across any framework, including Laravel, Symfony, and CakePHP.
Use Cases
- Automating PSR-12 formatting and structural compliance during the development of new PHP modules.
- Generating standardized PHPDoc blocks for classes, methods, and properties to improve IDE autocompletion and technical documentation.
- Enforcing strict type hints and union types (PHP 8.0+) to enhance type safety and reduce runtime errors in complex applications.
- Standardizing naming conventions (PascalCase for classes, camelCase for methods) and file structures across large-scale or legacy PHP projects.
- Performing pre-commit quality checks to ensure all public methods have appropriate visibility modifiers and exception documentation.
| name | coding-standards |
|---|---|
| description | PHP coding standards (PSR-12, PHPDoc, type hints) for any PHP project |
| - type | command |
| command | | |
| - matcher | "Edit|Write" |
| FILE="${TOOL_INPUT_FILE_PATH | -}" |
PHP Coding Standards
Language-level coding standards for PHP, applicable to any PHP project regardless of framework.
PSR-12 Compliance
File Structure
<?php
declare(strict_types=1); // Required at file top
namespace App\Controller\User; // PSR-4 autoloading
use Cake\Controller\Controller; // Alphabetical imports
use Cake\Http\Response;
/**
* User Controller
*
* Handles user management operations
*
* @property \App\Model\Table\UsersTable $Users
*/
class UserController extends Controller // PascalCase for classes
{
// Class body
}
Method Documentation (PHPDoc)
/**
* Display user list
*
* Retrieves and displays paginated list of users for the current company.
*
* @return \Cake\Http\Response|null Renders user list view
* @throws \Cake\Http\Exception\NotFoundException When user not found
*/
public function index(): ?Response
{
// Method implementation
}
Type Hints (PHP 8.2+)
Required for all methods:
// Parameter type hints
public function findUser(int $id): ?User
{
return $this->Users->get($id);
}
// Return type hints
public function getStatus(): string
{
return 'active';
}
// Union types (PHP 8.0+)
public function process(string|int $value): bool
{
return is_numeric($value);
}
// Nullable types
public function findOptional(int $id): ?User
{
try {
return $this->Users->get($id);
} catch (RecordNotFoundException $e) {
return null;
}
}
Naming Conventions
// Classes: PascalCase
class UserManagementService {}
// Methods: camelCase
public function getUserById(int $id): ?User {}
// Constants: UPPER_SNAKE_CASE
const MAX_LOGIN_ATTEMPTS = 5;
// Properties: camelCase
private string $userName;
// Local variables: camelCase
$userData = $this->fetchData();
Code Formatting
// Indentation: 4 spaces (not tabs)
public function example(): void
{
if ($condition) {
// 4 space indent
$this->doSomething();
}
}
// Line length: <= 120 characters
public function methodWithLongName(
string $firstParameter,
int $secondParameter,
bool $thirdParameter
): array {
return [];
}
// Blank lines
class Example
{
private string $property; // Property declaration
// Blank line before methods
public function method(): void
{
// Method body
}
// Blank line between methods
public function anotherMethod(): void
{
// Method body
}
}
PHPDoc Standards
Required Elements
/**
* Short description (one line)
*
* Long description if needed.
* Can span multiple lines.
*
* @param string $name User name
* @param int $age User age
* @return bool Success status
* @throws \InvalidArgumentException When age is negative
*/
public function validateUser(string $name, int $age): bool
{
if ($age < 0) {
throw new \InvalidArgumentException('Age cannot be negative');
}
return true;
}
Optional Elements
/**
* Process user data
*
* @param array $data User data
* @return User Processed user entity
* @see UserValidator::validate() Related validation
* @deprecated 2.0.0 Use processUserEntity() instead
* @todo Add email validation
*/
public function processUser(array $data): User
{
// Implementation
}
Property Documentation
/**
* @var \App\Model\Table\UsersTable Users table instance
*/
public $Users;
/**
* @var array<string, mixed> Configuration options
*/
private array $config;
Error Handling
Exception Types
// Use specific exception types
throw new \InvalidArgumentException('Invalid user ID');
throw new \RuntimeException('Database connection failed');
throw new \LogicException('Method called in wrong state');
// Document all thrown exceptions
/**
* @throws \InvalidArgumentException When ID is invalid
* @throws \RuntimeException When database fails
*/
public function getUser(int $id): User {}
Try-Catch Blocks
try {
$user = $this->Users->get($id);
$this->processUser($user);
} catch (RecordNotFoundException $e) {
// Handle specific exception
Log::error('User not found: ' . $id);
throw new NotFoundException('User not found');
} catch (\Exception $e) {
// Handle general exception
Log::error('Unexpected error: ' . $e->getMessage());
throw $e;
}
Code Quality Standards
Validation Rules
Check these in code review:
- All public methods have PHPDoc comments
- All parameters have type hints
- Return types are declared
- Exceptions are documented with @throws
- PSR-12 formatting applied (indentation, spacing, line length)
- No unused imports
- Properties have visibility modifiers
- No PHP short tags (
<?=)
Static Analysis
Use PHPStan for type checking:
vendor/bin/phpstan analyse src tests --level 7
Code Style
Use PHP-CS-Fixer for automatic formatting:
vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.dist.php
Framework-Agnostic
These standards apply to:
- CakePHP projects
- Laravel projects
- Symfony projects
- Plain PHP projects
- Any PHP codebase
Framework-specific conventions should be defined in framework-level skills (e.g., php-cakephp/framework-conventions).