Phpcsutils Laravel Package

Getting Started

Start by installing the package via Composer to complement PHP_CodeSniffer (PHPCS) in your custom sniffs or scripts:

composer require phpcsstandards/phpcsutils --dev  

The primary entry point is the PHP_CodeSniffer\Util\Tokens and PHP_CodeSniffer\Files\File utilities—explore src/ in the repository for classes like Common, Tokens, and Variables. The first use case is typically writing custom sniffs: use Tokens::getCondition() to analyze token context, or Common::isAssignment() to detect variable assignments in code. Check the examples/ directory if available for quick sniff templates.

Implementation Patterns

• Custom Sniff Development: Leverage utilities like Tokens::getPropertyDecorators() to extract PHP 8 attributes or Common::isReference() for by-reference checks—saving time over raw token traversal.
• Token Navigation: Use Tokens::getNext() and Tokens::findPrevious() with chained filters (e.g., Tokens::emptyTokens) to skip whitespace/comments robustly.
• Variable Context Analysis: In sniff logic, combine Variables::get declaredVariable() and Variables::getCondition() to track variable scope and usage across blocks.
• Integration with CI/CD: Drop in custom sniffs using these utilities into phpcs.xml or phpcs.xml.dist; they integrate directly with PHPCS’ command-line interface without extra setup.

Gotchas and Tips

• Version Locking: This package aligns tightly with PHPCS versions (e.g., v1.x for PHPCS 3.x); mismatches cause class/interface errors. Confirm compatibility via composer require phpcsstandards/phpcsutils:^1.0 per PHPCS version.
• Whitespace Pitfalls: Avoid hardcoding T_WHITESPACE checks; use Tokens::emptyTokens (includes comments, newlines, etc.) to ensure portable sniff logic.
• Scope Traversal: When working with closures or anonymous classes, Tokens::getCondition() may require passing the current file pointer explicitly—don’t rely on implicit state.
• Debugging: Enable PHPCS’ verbose mode (-vv) to inspect actual token sequences when utilities like Variables::getMemberVar SCOPE() behave unexpectedly.
• Extension Point: Extend Sniff from PHPCS and utility classes directly (e.g., use PHP_CodeSniffer\Util\Tokens;) rather than wrapping them—minimize abstraction unless adding project-specific helpers.