Phpcsdevtools Laravel Package

Getting Started

This package is a collection of utilities aimed at developers writing custom sniffs for PHP_CodeSniffer (PHPCS). If you're already using PHPCS and need to create or extend custom sniffs, this is your toolkit. Start by installing it via Composer in your project’s dev requirements:

composer require --dev phpcsstandards/phpcsdevtools

The main entry point is the phpcs-dev CLI tool. After installation, run vendor/bin/phpcs-dev to see available commands. Your first use case is likely generating a new sniff skeleton using phpcs-dev generate:sniff, which scaffolds boilerplate code, test stubs, and documentation templates—accelerating the creation of custom sniffs.

Implementation Patterns

• Sniff scaffolding: Use phpcs-dev generate:sniff <Vendor> <SniffName> to create a class with standard methods (register(), process()) and ready-to-edit inline documentation.
• Sniff testing: The tool includes phpcs-dev generate:test, which generates skeleton test files using PHPCS’s built-in test suite system, following best practices for assertion coverage.
• Documentation generation: Run phpcs-dev generate:docblock to auto-generate standardized docblocks from your sniff’s PHPCS annotations (e.g., @phpcs:license, @phpcs:since).
• Integration workflows: Add these commands to your CI pipeline—e.g., generate sniffs in Docker layers or embed generation in Composer scripts ("phpcs:sniff": "phpcs-dev generate:sniff MyVendor MySniff").

Gotchas and Tips

• Path assumptions: phpcs-dev assumes your project’s phpcs.xml or phpcs.ruleset.xml is in the root. If your ruleset lives elsewhere, pass --config-file explicitly.
• Autoloading quirks: Ensure your sniff’s namespace is registered in composer.json ("autoload": { "psr-4": { "YourNamespace\\": "src/" } }) or PHPCS won’t load it—even after generation.
• PHPCS version skew: The tool requires PHPCS 3.7+; older versions lack required reflection-based APIs. Check compatibility via phpcs --version.
• Template extensibility: Overwrite generated stubs by providing custom templates via --template-dir. Useful for enforcing team conventions (e.g., custom logging in process()).
• Debugging sniffs: After generation, use phpcs -s path/to/file.php to see which sniff triggered each error—critical for verifying your generated sniff integrates cleanly.