Download the PHP package ncac/phpcs-standard without Composer

NCAC PHPCS Standard

An opinionated PHP coding standard focused on type safety and consistency

NCAC is a comprehensive PHP_CodeSniffer standard that enforces strict typing, consistent naming conventions, and 2-space indentation. Built on top of proven standards like Slevomat, it adds custom rules designed for modern PHP development practices.

🎯 Key Features

Strict Type Safety

Enforces explicit type declarations for all parameters, return values, and properties to catch errors early and improve code clarity.

2-Space Indentation with Smart Array Handling

Uses 2-space indentation with context-aware formatting for arrays and function arguments.

Consistent Naming Conventions

Enforces context-appropriate naming: snake_case for variables and functions, camelCase for class properties and methods, PascalCase for classes.

🏗️ What Makes NCAC Different?

This is an opinionated standard that makes specific choices about code formatting and structure. While these choices work well for many teams, they may not suit every project or preference.

Built on Proven Foundations

• Extends Slevomat Coding Standard for type safety and structural rules
• Adds 7 custom sniffs for specific formatting requirements
• Requires PHP 8.0+ for modern type safety features (union types, named arguments, etc.)
• Designed for auto-fixing to minimize manual formatting work

Note: For PHP 7.4 support, use version ^1.2.0. See BREAKING_CHANGES.md for migration details.

Opinionated Choices

• 2-space indentation instead of the more common 4-space
• Strict type hints required everywhere (may be challenging for legacy code)
• Specific naming conventions that mix snake_case and camelCase based on context
• Minimal class spacing for compact, readable code structure

When to Consider NCAC

✅ Good fit for:

• New projects starting fresh
• Teams that prefer strict typing and consistent formatting
• Projects that can adopt 2-space indentation
• Codebases that can enforce type hints everywhere

⚠️ Consider carefully for:

• Large legacy codebases (strict typing requirements)
• Teams strongly preferring 4-space indentation
• Projects with existing PSR-12 compliance requirements
• Mixed coding style preferences within the team

📊 Quality Assurance

Continuous Integration (PHP 8.0 - 8.2)

⚡ Quick Start

Requirements

• PHP 8.0+ (for PHP 7.4 support, use version ^1.2.0)
• Composer

Installation

Basic Usage

Quick Start: One-Line Command

The easiest way to apply the full NCAC formatting workflow:

This automatically runs the complete 3-step formatting workflow for you (PHP-CS-Fixer → PHPCBF → PHPCS validation).

💡 Pro Tip: Add a script to your project's composer.json for easy access:

Then run: composer format or composer format:dry

Manual: Full Workflow (Advanced)

If you prefer running each step manually:

Why this workflow? PHP-CS-Fixer handles ~95% of complex formatting (alternate syntax, spacing), while PHPCBF handles NCAC-specific rules. This combination achieves the best conformity to the standard.

Alternative: PHPCS/PHPCBF Only

If you prefer to use only PHPCS tools (without PHP-CS-Fixer):

Note: Using PHPCBF alone may leave some violations unfixed (~60% auto-fix rate vs ~95% with the full workflow). See docs/WORKFLOW_STRATEGY.md for details.

Project Configuration

Create a phpcs.xml in your project root:

📚 Documentation

• 📖 Complete Rules Reference - Detailed examples for all 21 rules
• ⚙️ Workflow Strategy - PHP-CS-Fixer + PHPCBF integration and migration plan
• 🔄 Code Quality Workflow - Auto-fixing and CI/CD integration
• 🛠️ Development Setup Guide - VS Code Dev Container setup
• 🤝 Contributing Guidelines - How to contribute to the project

🎨 Code Examples

Before (Inconsistent formatting)

After (NCAC compliant)

🔧 Advanced Configuration

Custom Rulesets

Disable specific rules for legacy codebases:

Customize Slevomat spacing rules (built-in configurability):

Drupal Compatibility

Enable support for Drupal hook naming conventions:

Why this is needed: Drupal uses double underscores (__) in hook function names to target specific template suggestions. For example:

Without these options enabled, PHPCBF would incorrectly transform:

• mymodule_preprocess_node__homepage → mymodule_preprocess_node_homepage ❌ (breaks Drupal hooks!)
• _internal_helper → internal_helper ❌ (loses private function convention)

Configuration options:

• allowDoubleUnderscore (default: false): When enabled, allows __ in function names for Drupal preprocess hooks and theme suggestions
• allowLeadingUnderscore (default: false): When enabled, allows _ prefix for marking internal/private functions

Note: NCAC custom sniffs (like NCAC.Formatting.ClassClosingSpacing, NCAC.WhiteSpace.TwoSpacesIndent) are not yet configurable. This is planned for future releases.

🛠️ Development & Contributing

Development Setup

VS Code Dev Container (Recommended)

1. Clone the repository:

2. Generate environment (before opening in VS Code):

3. Open in VS Code: The Dev Container will automatically configure everything.

Manual Setup

🔧 Tool Strategy: PHPCS vs PHP-CS-Fixer

NCAC uses a strategic separation between detection and correction to avoid conflicts and ensure reliable results:

Current Implementation (v1.0)

Why Some Rules Are Detection-Only

Certain rules like NoAlternateControlStructureSniff intentionally provide no automatic fixes due to PHP_CodeSniffer's token processing limitations:

• Token conflicts: Sequential sniffs can overwrite each other's modifications
• Invalid syntax: Complex transformations can generate broken PHP code
• Execution order: Later sniffs (like indentation) may undo earlier fixes

Example issue:

Planned Evolution (v4.x)

📖 Learn more: See docs/PHPCS_VS_PHPCSFIXER_STRATEGY.md for technical details.

Contributing

We welcome contributions! Please see our Contributing Guidelines for:

• 🐛 Bug reports with reproducible examples
• ✨ Feature requests with clear use cases
• 🔧 Pull requests with comprehensive tests
• 📖 Documentation improvements

🏆 Acknowledgments

NCAC is built upon two excellent foundational projects:

• PHP_CodeSniffer by Squiz Labs - provides the tokenization engine and auto-fixing capabilities
• Slevomat Coding Standard - provides many of the type safety and structural rules

NCAC adds 7 custom sniffs for specific formatting and naming requirements:

• 2-space indentation with context-aware array handling
• Mixed naming conventions (snake_case variables, camelCase properties, PascalCase classes)
• Minimal class spacing and structure rules
• Modern PHP pattern enforcement

License Compliance: NCAC operates under the MIT license and respects all incorporated project licenses. See LICENSE for details.

🚀 Requirements & Compatibility

• PHP: 7.4, 8.0, 8.1, 8.2, 8.3
• PHP_CodeSniffer: 3.7.0 or higher
• Composer: 2.0 or higher

✨ Features At a Glance

• ✅ 21 comprehensive rules covering all aspects of PHP code quality
• ✅ Auto-fixable formatting for seamless workflow integration
• ✅ Type safety enforcement with mandatory type hints
• ✅ Modern PHP support including enums and typed properties
• ✅ IDE integration for VS Code, PhpStorm, and others
• ✅ Performance optimized for large codebases
• ✅ Extensive test coverage ensuring reliability
• ✅ Rich documentation with practical examples

📞 Support & Community

• 📚 Documentation Hub - Comprehensive guides and references
• 🐛 Issue Tracker - Bug reports and feature requests
• 💬 Discussions - Community Q&A and ideas
• 📊 Releases - Version history and changelogs

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Get started: