Coding Standards - WordPress Developer Showcase

Maintaining consistent coding standards ensures code quality, readability, and maintainability across the project.

PHP Coding Standards

This project follows WordPress Coding Standards for PHP code.

Tools and Configuration

The project uses PHP_CodeSniffer (PHPCS) with the following rulesets:

WordPress Coding Standards (wp-coding-standards/wpcs)
PHP Compatibility (phpcompatibility/phpcompatibility-wp)

These tools are automatically configured when you run composer dev in a theme or plugin directory.

Running Code Linting

Install dev dependencies

cd themes/bifrost-noise  # or plugins/bifrost-music
composer dev

Run the linter

composer lint:php

This runs:

./vendor/bin/phpcs -d error_reporting=E_ALL^E_DEPRECATED -s --colors .

Fix issues

Review the output and fix any coding standard violations before committing.

PHP Version Requirements

Minimum PHP version: 8.0+
Project standard: PHP 8.1+

Ensure your code is compatible with PHP 8.1 and above. The PHP Compatibility checker will catch incompatible syntax.

PSR-4 Autoloading

Both themes and plugins use PSR-4 autoloading: Theme (bifrost-noise):

"autoload": {
  "psr-4": {
    "Bifrost\\Noise\\": "src/"
  }
}

Plugin (bifrost-music):

"autoload": {
  "psr-4": {
    "Bifrost\\Music\\": "inc/"
  }
}

Class naming and file structure

Follow PSR-4 conventions:

Class Bifrost\Noise\Admin\Settings → src/Admin/Settings.php
Class Bifrost\Music\API\Endpoint → inc/API/Endpoint.php
Use UpperCamelCase for class names
One class per file

WordPress-Specific Standards

Follow WordPress best practices:

Naming Conventions

Functions: snake_case
Classes: PascalCase
Constants: UPPERCASE_SNAKE_CASE
Hooks: prefix_hook_name

Security

Escape output: esc_html(), esc_attr(), esc_url()
Sanitize input: sanitize_text_field(), etc.
Validate and sanitize all user input
Use nonces for forms

Database

Use $wpdb->prepare() for queries
Never concatenate user input into SQL
Use WordPress functions when available

Internationalization

Wrap strings in __(), _e(), _n()
Use text domain consistently
Make all user-facing strings translatable

JavaScript Standards

For JavaScript and React code:

Use modern ES6+ syntax
Follow WordPress Gutenberg coding standards for block development
Use @wordpress/scripts for build tooling when applicable
Ensure code is linted before committing

CSS/SCSS Standards

Follow WordPress CSS Coding Standards
Use BEM methodology for class naming when appropriate
Prefer CSS custom properties for theming
Ensure responsive design principles are followed

Commit Message Format

This project follows Conventional Commits specification.

Format

<type>: <short description>

[optional body]

[optional footer]

Types

Type	Description	Example
`feat`	New feature	`feat: add user registration endpoint`
`fix`	Bug fix	`fix: resolve null pointer in auth service`
`docs`	Documentation changes	`docs: update API documentation`
`style`	Code style changes (formatting, etc.)	`style: format code with phpcs`
`refactor`	Code refactoring	`refactor: extract authentication logic`
`test`	Adding or updating tests	`test: add unit tests for user model`
`chore`	Maintenance tasks	`chore: update composer dependencies`

Examples

Good commit messages

feat: add REST API endpoints for custom post types

fix: resolve navigation menu alignment on mobile devices

docs: add contributing guidelines for new developers

refactor: extract block registration into separate files

chore: update WordPress coding standards to 3.0

Commit message best practices

Use the imperative mood: “add feature” not “added feature”
Be concise: Keep the summary line under 72 characters
Explain why, not what: The diff shows what changed; explain why
Reference issues: Include issue numbers when applicable: fix: #123 resolve login bug
Separate subject from body: Use a blank line between summary and detailed description

Writing Good Commit Messages

Write a clear summary

Start with a type prefix and a concise description:

feat: add block editor integration

Add a detailed body (if needed)

Explain the reasoning and context:

feat: add block editor integration

Implements custom blocks for the music player functionality.
This allows users to embed music players directly in posts
and pages using the block editor.

Includes:
- Music player block
- Playlist block
- Album cover block

Reference related issues

Link to relevant issues or pull requests:

fix: resolve mobile navigation menu issues

Fixes #42
Related to #38

Testing

Before Committing

Run these checks before committing:

# PHP linting
composer lint:php

# Build assets (if applicable)
npm run build

# Test in local WordPress installation

Testing in Staging

All changes must be tested in the staging environment before merging to trunk.

After merging to staging, verify:

Functionality works as expected
No PHP errors or warnings
No JavaScript console errors
Responsive design works across devices
No performance regressions
WordPress admin area remains functional

Code Review Guidelines

When reviewing pull requests:

Code Quality

Follows WordPress coding standards
No obvious bugs or security issues
Proper error handling
Code is readable and maintainable

Functionality

Meets requirements
Works in staging environment
No breaking changes (or properly documented)
Edge cases are handled

Documentation

Code is properly commented
DocBlocks for functions and classes
README updated if needed
Inline comments for complex logic

Testing

Tested in staging
QA approval obtained
No regressions introduced
Performance impact considered

Documentation Standards

PHP Documentation

Use PHPDoc format for all functions and classes:

/**
 * Register custom post types for the music plugin.
 *
 * @since 1.0.0
 *
 * @return void
 */
function register_music_post_types() {
    // Implementation
}

Inline Comments

Add comments for complex logic:

// Check if user has permission before showing admin menu
if ( current_user_can( 'manage_options' ) ) {
    add_menu_page( /* ... */ );
}

README Files

Keep README files up to date:

Installation instructions
Configuration options
Usage examples
API documentation

Build and Deployment

Composer Scripts

Available composer scripts:

Script	Purpose	Command
`build`	Production build	`composer build`
`dev`	Development dependencies	`composer dev`
`lint:php`	Run PHP linting	`composer lint:php`
`zip`	Create distribution archive	`composer zip`

Vendor Folder Management

Never commit the vendor/ folder to the repository. It’s automatically deployed via GitHub Actions.

The deployment workflow:

Runs on push to trunk or staging
Executes composer install --no-dev
Uploads vendor folder to the appropriate environment
Uses GitHub Environments for credentials

Resources

WordPress Coding Standards

Official WordPress coding standards documentation

Conventional Commits

Learn more about the Conventional Commits specification

PHP_CodeSniffer

PHP_CodeSniffer documentation and usage

WordPress Developer Resources

Comprehensive WordPress development documentation

Questions?

If you have questions about coding standards:

Open an issue with the question label
Ask in code review comments
Reach out to maintainers

Get Started

Plugin Development

Theme Development

Contributing

​PHP Coding Standards

​Tools and Configuration

​Running Code Linting

​PHP Version Requirements

​PSR-4 Autoloading

​WordPress-Specific Standards

Naming Conventions

Security

Database

Internationalization

​JavaScript Standards

​CSS/SCSS Standards

​Commit Message Format

​Format

​Types

​Examples

​Writing Good Commit Messages

​Testing

​Before Committing

​Testing in Staging

​Code Review Guidelines

Code Quality

Functionality

Documentation

Testing

​Documentation Standards

​PHP Documentation

​Inline Comments

​README Files

​Build and Deployment

​Composer Scripts

​Vendor Folder Management

​Resources

WordPress Coding Standards

Conventional Commits

PHP_CodeSniffer

WordPress Developer Resources

​Questions?

Build docs developers (and LLMs) love

PHP Coding Standards

Tools and Configuration

Running Code Linting

PHP Version Requirements

PSR-4 Autoloading

WordPress-Specific Standards

JavaScript Standards

CSS/SCSS Standards

Commit Message Format

Format

Types

Examples

Writing Good Commit Messages

Testing

Before Committing

Testing in Staging

Code Review Guidelines

Documentation Standards

PHP Documentation

Inline Comments

README Files

Build and Deployment

Composer Scripts

Vendor Folder Management

Resources

Questions?