Php Parallel Lint Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev jakub-onderka/php-parallel-lint
   composer require --dev jakub-onderka/php-console-highlighter  # For colored output
   

2. Basic Usage: Run in your project root to check all PHP files:

   vendor/bin/parallel-lint .
   

   • Defaults to checking php,php3,php4,php5,phtml,phpt files.
   • Uses 10 parallel jobs by default (-j 10).

3. First Use Case: Integrate into your CI pipeline (e.g., GitHub Actions, GitLab CI) to catch syntax errors early:

   # Example GitHub Actions step
   - name: Run PHP Parallel Lint
     run: vendor/bin/parallel-lint --exclude vendor --exclude tests .
   

Implementation Patterns

Workflows

1. Local Development:

   • Run in watch mode (via inotifywait or nodemon) to auto-check files on save:

     # Linux (requires inotify-tools)
     inotifywait -m -e modify -e create -e delete src/ | while read -r event; do vendor/bin/parallel-lint src/; done
     

   • Use --json for programmatic integration:

     vendor/bin/parallel-lint --json . > lint-results.json
     

2. CI/CD Integration:

   • Fail the build on syntax errors (default behavior). Add --ignore-fails to treat warnings as non-fatal:

     vendor/bin/parallel-lint --ignore-fails --exclude vendor .
     

   • Output Checkstyle XML for IDE integration:

     vendor/bin/parallel-lint --checkstyle . > lint-results.xml
     

3. Symfony-Specific:

   • Exclude app/ and vendor/ directories:

     vendor/bin/parallel-lint --exclude app --exclude vendor .
     

   • Combine with php-cs-fixer for linting + formatting:

     vendor/bin/parallel-lint . && vendor/bin/php-cs-fixer fix --dry-run
     

4. Git Hooks:

   • Add to pre-commit hook to block syntax errors:

     # .git/hooks/pre-commit
     #!/bin/sh
     vendor/bin/parallel-lint --exclude vendor .
     

Integration Tips

• Parallelism: Adjust -j based on your machine’s CPU cores (e.g., -j 8 for 8 cores).
• PHP Version: Specify a custom PHP binary if needed (e.g., --php /usr/bin/php8.1).
• Git Blame: Use --blame to pinpoint who introduced syntax errors:

  vendor/bin/parallel-lint --blame --git /usr/bin/git .
  

• Stdin Input: Pipe file lists for dynamic analysis:

  find src/ -name "*.php" | vendor/bin/parallel-lint --stdin
  

Gotchas and Tips

Pitfalls

1. Abandoned Package:

   • The original repo is archived. Use the fork for updates.
   • Mitigation: Pin the version in composer.json to avoid breaking changes:

     "jakub-onderka/php-parallel-lint": "dev-master"
     

2. HHVM Support:

   • Auto-detects HHVM but may behave unpredictably. Test thoroughly if using HHVM.

3. False Positives:

   • Dynamic file generation (e.g., eval(), create_function()) may trigger false errors.
   • Fix: Exclude problematic directories or use --ignore-fails.

4. Memory Usage:

   • High parallelism (-j) can spike memory. Monitor with htop and adjust -j if needed.

5. Windows Paths:

   • Use forward slashes (/) or escape backslashes (\\) in --exclude paths.

Debugging

• Verbose Output: Add -vvv for debug logs (not officially documented but works in some versions).
• Checkstyle XML: Parse errors programmatically:

  $xml = simplexml_load_file('lint-results.xml');
  foreach ($xml->file as $file) {
      echo "Errors in {$file['name']}: " . $file->error->count() . "\n";
  }
  

• JSON Output: Validate with jq:

  vendor/bin/parallel-lint --json . | jq '.[] | select(.errors | length > 0)'
  

Extension Points

1. Custom PHP.ini: Override settings via environment variables (e.g., PHP_INI_SCAN_DIR for custom php.ini paths).

2. Pre/Post-Processing: Chain with other tools (e.g., parallel-lint | grep "ERROR" for quick checks).

3. GitHub Actions: Cache results to avoid re-linting unchanged files:

   - name: Cache Parallel Lint
     uses: actions/cache@v2
     with:
       path: ~/.parallel-lint-cache
       key: ${{ runner.os }}-lint-${{ hashFiles('**/*.php') }}
   

4. Docker: Use in CI containers to ensure consistency:

   RUN composer require jakub-onderka/php-parallel-lint --dev
   CMD ["vendor/bin/parallel-lint", "--exclude vendor", "."]
   

Config Quirks

• Short Open Tags: Enable with -s if your project uses <? syntax.
• ASP Tags: Enable with --asp for legacy <?php ... ?>-like tags.
• Progress Bar: Disable with --no-progress for CI environments where it adds noise.