Qa Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require ninjify/qa
   

   Add to composer.json scripts:

   "scripts": {
       "qa": [
           "linter src app tests",
           "codesniffer src app tests"
       ]
   }
   

2. First Run:

   composer qa
   

   • Runs PHP linting (php-parallel-lint) and code sniffing (phpcs) on src/, app/, and tests/ by default.

3. Fix Issues Automatically:

   vendor/bin/codefixer src app tests
   

   • Uses php-cs-fixer to auto-correct PSR-12 violations.

Where to Look First

• Default Config: Check ruleset.xml in your project root (or use the package’s strict default).
• Excluded Folders: Modify .qa.php (if created) or pass custom paths:

  composer qa -- --exclude="database/"
  

• CI Integration: Add to .github/workflows/laravel.yml:

  - run: composer qa
  

First Use Case

Pre-commit Hook:

# Add to .git/hooks/pre-commit
#!/bin/sh
composer qa || exit 1

• Blocks non-compliant code before merging, reducing CI failures.

Implementation Patterns

Usage Patterns

1. Project-Wide QA:

   composer qa
   

   • Runs linting and sniffing on default folders (src/, app/, tests/).

2. Targeted Checks:

   composer qa app/Http
   

   • Focus on specific directories (e.g., controllers).

3. Fix-and-Commit Workflow:

   composer qa && vendor/bin/codefixer && git add -u && git commit -m "Fix QA issues"
   

   • Auto-fix and commit style violations in one go.

4. Custom Rulesets:

   • Place a ruleset.xml in your project root to override defaults:

     <rule ref="PSR12">
         <exclude name="PSR12.Classes.ClassDeclaration.MissingTraitUses"/>
     </rule>
     

5. CI/CD Integration:

   # GitHub Actions example
   jobs:
     qa:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - run: composer install
         - run: composer qa
   

Workflows

1. Developer Workflow:

   • Run composer qa before pushing to catch issues early.
   • Use codefixer to resolve warnings interactively.

2. Pull Request Workflow:

   • Add a GitHub Actions step to fail PRs with QA violations:

     - name: Run QA Checks
       run: composer qa
     

3. Release Workflow:

   • Combine with phpstan and pest in CI:

     "scripts": {
         "test": "pest",
         "qa": ["linter", "codesniffer"],
         "ci": ["test", "qa"]
     }
     

Integration Tips

• Laravel-Specific:

  • Exclude vendor/ and bootstrap/cache/ from checks:

    composer qa -- --exclude="vendor/ bootstrap/cache/"
    

  • Add resources/ if using Blade templates:

    composer qa -- --include="resources/views/"
    

• Team Onboarding:

  • Document the composer qa command in your CONTRIBUTING.md.
  • Use codefixer in CI to auto-fix common issues for new contributors.

• Performance:

  • Parallelize linting for large projects:

    composer qa -- --parallel
    

Gotchas and Tips

Pitfalls

1. False Positives:

   • Issue: php-parallel-lint may flag legacy PHP files (e.g., php4).
   • Fix: Exclude old files:

     composer qa -- --exclude="*/legacy/"
     

2. Ruleset Conflicts:

   • Issue: Custom ruleset.xml may override Laravel’s PSR-12 defaults.
   • Fix: Merge rulesets or use the package’s default:

     vendor/bin/codesniffer --standard=PSR12
     

3. CI Failures:

   • Issue: codefixer modifies files, causing git diff noise.
   • Fix: Run codefixer locally and commit fixes separately.

4. PHP Version Mismatch:

   • Issue: Package requires PHP 7.2+, but your project uses 8.2+.
   • Fix: Update dependencies:

     composer require --dev php-parallel-lint/php-parallel-lint:^1.3
     

Debugging

• Verbose Output:

  composer qa -- --verbose
  

  • Shows detailed linting errors and paths.

• Dry Run:

  vendor/bin/codefixer --dry-run
  

  • Preview fixes without modifying files.

• Custom Exit Codes:

  • The package exits with 1 on failures. Use in CI:

    - run: composer qa || exit 1
    

Config Quirks

1. Default Folders:

   • Override in .qa.php:

     return [
         'folders' => ['src', 'app', 'tests', 'routes'],
         'exclude' => ['*/migrations/*', '*/temp/*'],
     ];
     

2. Ruleset Path:

   • Specify a custom path:

     vendor/bin/codesniffer --standard=/path/to/ruleset.xml
     

3. EditorConfig:

   • The package respects .editorconfig. Ensure consistency:

     [*.php]
     indent_style = space
     indent_size = 4
     

Extension Points

1. Custom Sniffs:

   • Add Laravel-specific sniffs to ruleset.xml:

     <rule ref="SlevomatCodingStandard"/>
     <rule ref="Contributte\CodingStandard\Sniffs"/>
     

2. Pre/Post-QA Hooks:

   • Extend composer.json scripts:

     "scripts": {
         "qa": [
             "@pre-qa",
             "linter",
             "codesniffer",
             "@post-qa"
         ]
     }
     

3. Artisan Command:

   • Create a custom command for Laravel:

     // app/Console/Commands/QaCheck.php
     public function handle() {
         $this->call('vendor:publish', ['--provider' => 'Ninjify\Qa\QaServiceProvider']);
         Artisan::call('qa');
     }
     

Tips

• Auto-Fix in CI:

  • Use codefixer in a separate CI job to auto-correct:

    - name: Auto-fix QA issues
      if: github.event_name == 'pull_request'
      run: vendor/bin/codefixer
    

• Exclude Tests:

  • Skip tests in CI but enforce in local dev:

    # CI
    composer qa -- --exclude="tests/"
    
    # Local
    composer qa
    

• Monitor Trends:

  • Track QA violations over time using GitHub’s "Insights" or a custom script:

    composer qa -- --format=json > qa-results.json