Coding Standard Laravel Package

Getting Started

Minimal Steps

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

   composer require --dev phpmyadmin/coding-standard
   

   Register the standard in your project’s phpcs.xml or phpcs.xml.dist:

   <config name="standard" value="PhpMyAdmin"/>
   

2. First Use Case Run CodeSniffer on a Laravel controller or model:

   vendor/bin/phpcs app/Http/Controllers/ --standard=PhpMyAdmin
   

   Focus on files where you suspect violations (e.g., new or modified files).

3. Where to Look First

   • Ruleset: Review vendor/phpmyadmin/coding-standard/PhpMyAdmin.ruleset.xml for custom rules.
   • Documentation: Check the phpMyAdmin Coding Guidelines for context (if available).
   • Laravel-Specific Adjustments: Override rules in your project’s phpcs.xml (e.g., relax PSR12 conflicts).

Implementation Patterns

Usage Patterns

1. Integrate into CI/CD Add to composer.json scripts:

   "scripts": {
       "test": [
           "phpcs --standard=PhpMyAdmin --report=full app/"
       ]
   }
   

   Trigger via GitHub Actions or GitLab CI:

   - name: Run PHP CodeSniffer
     run: composer test
   

2. Laravel-Specific Workflows

   • Migrations: Run on database/migrations/ to enforce consistency:

     phpcs database/migrations/ --standard=PhpMyAdmin --warning-severity=3
     

   • Service Providers: Useful for detecting underused classes or circular dependencies (if rules support it).

3. Pair with PHPStan/Laravel-Pint Combine with static analysis tools for broader coverage:

   composer require --dev phpstan/phpstan laravel/pint
   vendor/bin/phpstan analyse --level=5
   vendor/bin/pint --test
   vendor/bin/phpcs app/
   

Integration Tips

• IDE Setup: Configure PHPStorm/VSCode to auto-fix on save using phpcbf:

  vendor/bin/phpcbf app/Http/Controllers/UserController.php
  

• Custom Rules: Extend the standard by creating a local ruleset file (e.g., phpcs-local.ruleset.xml) and reference it:

  <config name="standard" value="PhpMyAdmin,phpcs-local"/>
  

• Team Onboarding: Document the standard in CONTRIBUTING.md with examples of compliant/non-compliant code.

Gotchas and Tips

Pitfalls

1. Rule Conflicts with PSR12

   • Issue: Some rules may conflict with Laravel’s default PSR12 (e.g., line length, method ordering).
   • Fix: Override in phpcs.xml:

     <rule ref="PhpMyAdmin">
         <exclude name="PSR12.Classes.ClassDeclaration.MissingDocblock"/>
         <arg name="lineLength" value="120"/>
     </rule>
     

2. False Positives in Legacy Code

   • Issue: Strict rules may flag legacy code (e.g., mysql_* functions, old Laravel versions).
   • Fix: Use <exclude-pattern> in phpcs.xml:

     <file>app/OldLegacyCode/</file>
     

3. Performance on Large Codebases

   • Issue: Running on app/ can be slow.
   • Fix: Target specific directories or use --ignore:

     phpcs app/Http app/Models --ignore=app/Jobs/*
     

Debugging

• Verbose Output: Use --report=full to debug rule violations:

  phpcs app/ --standard=PhpMyAdmin --report=full --verbose
  

• Rule-Specific Help: Check individual rule docs (e.g., vendor/bin/phpcs --help for generic tips).

Extension Points

1. Custom Sniffs Add project-specific sniffs to phpcs.xml:

   <rule ref="PhpMyAdmin">
       <config name="customSniffs" value="app/CodeSniffer/"/>
   </rule>
   

   Example: Create app/CodeSniffer/LaravelSniff.php to enforce Laravel-specific patterns.

2. Severity Adjustments Lower severity for non-critical rules (e.g., docblocks):

   <rule ref="PhpMyAdmin">
       <severity name="PSR12.Classes.ClassDeclaration.MissingDocblock" value="2"/>
   </rule>
   

3. Autofix Limitations

   • Note: Not all rules support --fix. Test phpcbf on a backup first:

     cp -r app/ app.bak && vendor/bin/phpcbf app/