Hidev Scrutinizer Laravel Package

Getting Started

Minimal Setup

1. Install the Package Add to your Laravel project via Composer:

   composer require hiqdev/hidev-scrutinizer
   

   Ensure your project uses HiDev (this package is a HiDev plugin).

2. Configure HiDev Ensure your hidev.json includes the Scrutinizer plugin:

   {
       "plugins": [
           "hiqdev/hidev-scrutinizer"
       ]
   }
   

3. Define .scrutinizer.yml Create a .scrutinizer.yml file in your project root with basic Scrutinizer CI configuration:

   tools:
       php:
           coverage:
               enabled: true
               target: 80%
   

4. First Use Case: Auto-Generate Scrutinizer Config Run HiDev to auto-generate/update the Scrutinizer config:

   hidev scrutinizer:generate
   

   This ensures .scrutinizer.yml is synced with HiDev’s expectations.

Implementation Patterns

Workflow Integration

1. CI Pipeline Hook Integrate with your CI (e.g., GitHub Actions, GitLab CI) to run Scrutinizer checks post-tests:

   # Example GitHub Actions step
   - name: Run Scrutinizer
     run: |
       hidev scrutinizer:upload-coverage
       hidev scrutinizer:check
   

2. Dynamic Configuration Use HiDev’s hidev.json to dynamically configure Scrutinizer:

   {
       "scrutinizer": {
           "tools": {
               "php": {
                   "coverage": {
                       "target": "{{ env('SCRUTINIZER_TARGET') ?: '80' }}"
                   }
               }
           }
       }
   }
   

   HiDev will merge this with .scrutinizer.yml during generation.

3. Coverage Uploading Upload test coverage (PHP/Python) to Scrutinizer CI:

   hidev scrutinizer:upload-coverage
   

   Requires ocular.phar (for PHP) or equivalent tools for other languages.

4. Badge Generation Auto-generate badges for your README.md:

   hidev scrutinizer:badges
   

   Outputs Shields.io-compatible badge snippets (e.g., coverage, quality).

Laravel-Specific Tips

1. Artisan Command Integration Create a custom Artisan command to trigger Scrutinizer checks:

   // app/Console/Commands/ScrutinizerCheck.php
   namespace App\Console\Commands;
   use Illuminate\Console\Command;
   class ScrutinizerCheck extends Command
   {
       protected $signature = 'scrutinizer:check';
       public function handle()
       {
           $this->call('hidev.scrutinizer.check');
       }
   }
   

2. Environment-Specific Config Use Laravel’s .env to override Scrutinizer settings:

   SCRUTINIZER_TARGET=90
   

   Reference in hidev.json as shown above.

3. Testing with Laravel Forge/Laravel Vapor For cloud deployments, ensure Scrutinizer’s ocular.phar is available in your deployment scripts:

   # In deploy script
   wget https://scrutinizer-ci.com/ocular.phar
   chmod +x ocular.phar
   ./ocular.phar code-coverage:upload --format=php-clover coverage.clover
   

Gotchas and Tips

Pitfalls

1. HiDev Dependency

   • Issue: This package only works with HiDev. Without HiDev installed (hiqdev/hidev), commands will fail.
   • Fix: Install HiDev first:

     composer require hiqdev/hidev
     

2. Outdated Package

   • Issue: Last release was in 2017. May not support newer Scrutinizer CI APIs or HiDev versions.
   • Fix:
     • Fork the repo and update dependencies (e.g., hiqdev/composer-extension-plugin).
     • Check compatibility with your HiDev version (e.g., hidev-config changes in v0.6.0).

3. Coverage Upload Failures

   • Issue: hidev scrutinizer:upload-coverage may fail if:
     • ocular.phar is missing.
     • Coverage files (e.g., coverage.clover) are not generated.
   • Fix:
     • Install ocular.phar manually:

       wget https://scrutinizer-ci.com/ocular.phar
       

     • Ensure your test suite generates coverage (e.g., PHPUnit with --coverage-clover).

4. YAML Merge Conflicts

   • Issue: HiDev’s auto-generation may overwrite manual .scrutinizer.yml changes.
   • Fix: Use HiDev’s hidev.json for dynamic settings and keep static configs in .scrutinizer.yml:

     # .scrutinizer.yml
     tools:
         php:
             environment:
                 php:
                     version: "8.1"
     

Debugging Tips

1. Verbose Mode Run HiDev commands with -v for debug output:

   hidev scrutinizer:generate -v
   

2. Dry Run Preview changes before applying:

   hidev scrutinizer:generate --dry-run
   

3. Check HiDev Logs HiDev logs are stored in ~/.cache/hidev/logs/. Inspect for errors:

   tail -f ~/.cache/hidev/logs/hidev.log
   

Extension Points

1. Custom Controllers Extend Scrutinizer’s "controllers" (formerly "goals") in hidev.json:

   {
       "scrutinizer": {
           "controllers": {
               "php": {
                   "checks": ["CodeRating", "DuplicateCode"]
               }
           }
       }
   }
   

2. Post-Processing Badges Hook into badge generation to customize output:

   // In a HiDev plugin
   use HiQDev\Hidev\Plugin\Scrutinizer\BadgeGenerator;
   class CustomBadgeGenerator extends BadgeGenerator
   {
       protected function getBadgeUrl(): string
       {
           return "https://custom-badge-service.com/...";
       }
   }
   

3. Multi-Language Support The package supports Python coverage uploads. For other languages (e.g., JavaScript), extend the ConfigFile class to handle new formats:

   namespace HiQDev\Hidev\Plugin\Scrutinizer;
   class ExtendedConfigFile extends ConfigFile
   {
       public function uploadCoverage(string $language): void
       {
           if ($language === 'javascript') {
               // Custom logic for JS coverage (e.g., using istanbul)
           }
       }
   }