Coding Standard Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer in your Laravel project:

   composer require --dev dosfarma/coding-standard
   

2. First Use Case Run PHP_CodeSniffer against your project to enforce the DosFarma coding standard:

   ./vendor/bin/phpcs -s --standard=./vendor/dosfarma/coding-standard/src/DosFarma ./app
   

3. Where to Look First

   • Standard Ruleset: Check ./vendor/dosfarma/coding-standard/src/DosFarma for the ruleset file.
   • Documentation: Review the PHP_CodeSniffer documentation for general usage.
   • Laravel Integration: Look for .phpcs.xml or .phpcs.xml.dist in your project root for configuration.

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline Add a step in your GitHub Actions, GitLab CI, or Jenkins pipeline to run the coding standard checks:

   # Example GitHub Actions step
   - name: Run PHP_CodeSniffer
     run: ./vendor/bin/phpcs -s --standard=./vendor/dosfarma/coding-standard/src/DosFarma ./app --report=checkstyle | tee phpcs.xml
   

2. Pre-Commit Hook Use tools like Husky or Pre-Commit to run checks before commits:

   echo 'vendor/bin/phpcs -s --standard=./vendor/dosfarma/coding-standard/src/DosFarma ./app' >> .git/hooks/pre-commit
   

3. IDE Integration Configure your IDE (PHPStorm, VSCode) to use this standard for real-time feedback:

   • PHPStorm: Go to Settings > Editor > Inspections > PHP > PHP_CodeSniffer and set the standard path.
   • VSCode: Use the PHP_CodeSniffer extension and configure it to use the DosFarma standard.

4. Custom Configuration Extend the standard by creating a custom .phpcs.xml file:

   <?xml version="1.0"?>
   <ruleset name="Project Coding Standard">
       <config name="installed_paths" value="./vendor/dosfarma/coding-standard/src/DosFarma"/>
       <arg name="extensions" value="php"/>
       <arg name="tab-width" value="4"/>
       <arg name="encoding" value="utf-8"/>
       <file>./app</file>
   </ruleset>
   

5. Fixing Issues Automatically Use PHP_CodeSniffer’s auto-fixer to correct minor issues:

   ./vendor/bin/phpcbf -s --standard=./vendor/dosfarma/coding-standard/src/DosFarma ./app
   

Gotchas and Tips

Pitfalls

1. Rule Conflicts

   • The DosFarma standard may conflict with other standards (e.g., PSR12, Laravel). Ensure your .phpcs.xml overrides conflicting rules explicitly.
   • Example:

     <rule ref="DosFarma">
         <exclude name="Generic.Files.LineEndings"/>
     </rule>
     

2. Performance

   • Running phpcs on large codebases can be slow. Use --parallel (if supported) or limit the scope:

     ./vendor/bin/phpcs ./app/Http/Controllers --standard=./vendor/dosfarma/coding-standard/src/DosFarma
     

3. False Positives

   • Some rules may flag legitimate code (e.g., legacy code or framework-specific patterns). Use <exclude> or <ignore> in your config:

     <exclude-pattern>*/vendor/*</exclude-pattern>
     <exclude-pattern>*/tests/*</exclude-pattern>
     

4. Outdated Rules

   • If the package is unmaintained, rules may not align with modern PHP/Laravel practices. Audit the ruleset against PSR standards or Laravel’s own rules.

Debugging

1. Verbose Output Use -v or --verbose to debug rule application:

   ./vendor/bin/phpcs -v --standard=./vendor/dosfarma/coding-standard/src/DosFarma ./app
   

2. Dry Run Test changes without modifying files:

   ./vendor/bin/phpcbf --dry-run --standard=./vendor/dosfarma/coding-standard/src/DosFarma ./app
   

3. Rule-Specific Help Check which rules are being applied:

   ./vendor/bin/phpcs --list-targets --standard=./vendor/dosfarma/coding-standard/src/DosFarma
   

Tips

1. Custom Rules Extend the standard by adding custom rules in a separate file and including it:

   <rule ref="./custom-ruleset.xml"/>
   

2. Team Alignment

   • Document the coding standard in your team’s CONTRIBUTING.md or README.md.
   • Example:

     ## Coding Standards
     We enforce the [DosFarma PHP Coding Standard](https://github.com/dosfarma/coding-standard).
     Run `./vendor/bin/phpcs ./app` before submitting PRs.
     

3. Partial Adoption Start with critical paths (e.g., ./app/Http/Controllers) before enforcing it project-wide.

4. Integration with Laravel Tools

   • Use laravel-shift/laravel-coding-standard as a fallback if DosFarma’s rules are too restrictive.
   • Combine standards in your config:

     <config name="installed_paths">
         ./vendor/dosfarma/coding-standard/src/DosFarma,
         ./vendor/laravel-shift/laravel-coding-standard
     </config>
     

5. Automated Reporting Generate reports for stakeholders (e.g., Jira, Slack) using --report=json or --report=xml.