Peck Laravel Package

Getting Started

1. Installation:

   • Ensure GNU Aspell is installed on your system (see README for OS-specific instructions).
   • Add Peck to your Laravel project:

     composer require --dev peckphp/peck
     

   • Initialize the config file (creates peck.json in project root):

     ./vendor/bin/peck --init
     

2. First Run:

   • Scan the entire project for spelling errors:

     ./vendor/bin/peck
     

   • For Laravel projects, use the built-in laravel preset (auto-applied via --init):

     {
       "preset": "laravel"
     }
     

3. Quick Use Case:

   • Fix a typo in a method name (e.g., getUserData → getUserDatas). Peck will flag it during development or CI runs.

Implementation Patterns

1. Daily Development Workflow

• Pre-commit Hook: Add to composer.json to run Peck before commits:

  "scripts": {
    "lint:peck": "peck --quiet"
  }
  

  Run via:

  composer lint:peck
  

• IDE Integration: Use --text to validate strings on-the-fly (e.g., commit messages or docblocks):

  ./vendor/bin/peck --text "This is a test string with a typo"
  

2. CI/CD Integration

• GitHub Actions Example:

  - name: Spell Check
    run: |
      if [ "$RUNNER_OS" = "Linux" ]; then
        sudo apt-get install -y aspell aspell-en
      fi
      composer require --dev peckphp/peck
      ./vendor/bin/peck --report=checkstyle > spelling-report.xml
  

  • Upload spelling-report.xml as an artifact for review.

3. Configuration Tuning

• Project-Specific Ignores: Extend peck.json to ignore Laravel-specific terms or paths:

  {
    "preset": "laravel",
    "ignore": {
      "words": ["eloquent", "blade", "facade"],
      "paths": ["storage/*", "tests/Feature/*"]
    }
  }
  

• Language Support: Switch to a non-US English dictionary (e.g., en_GB) for UK-based projects:

  {
    "language": "en_GB"
  }
  

4. Team Collaboration

• Shared Config: Commit peck.json to version control to enforce consistent spelling across the team.
• Ad-Hoc Ignores: Use --ignore-all sparingly (e.g., during initial setup):

  ./vendor/bin/peck --ignore-all
  

  Then manually curate peck.json afterward.

Gotchas and Tips

Pitfalls

1. False Positives:

   • Peck may flag camelCase identifiers (e.g., userId) or acronyms (e.g., API, HTML).
   • Fix: Add to ignored_words or use inline comments:

     // @peck-skip
     public function getUserId() { ... }
     

2. Aspell Dependency:

   • Windows: Use WSL or Scoop; native Windows support is untested.
   • CI Environments: Explicitly install Aspell in workflows (see README).

3. Performance:

   • Scanning large projects (e.g., monorepos) can be slow.
   • Fix: Limit paths in peck.json or use --path:

     ./vendor/bin/peck --path=app/Http
     

4. Config Overrides:

   • Command-line flags (e.g., --ignore-all) temporarily override peck.json.
   • Tip: Use --config to test changes without modifying the shared file:

     ./vendor/bin/peck --config custom-peck.json
     

Debugging Tips

• Verbose Output: Use --verbose to debug file exclusions or Aspell interactions:

  ./vendor/bin/peck --verbose
  

• Suggestion Rejection: If Peck suggests incorrect replacements (e.g., configArray → configurationArray), add the original term to ignored_words.

Extension Points

1. Custom Presets:

   • Extend the laravel preset by copying its rules to a new config file and modifying ignored_words.

2. Plugin Development:

   • Peck’s modular design allows adding processors for custom file types (e.g., Blade templates). Example:

     // Extend Peck\Peck\Processors\AbstractProcessor
     class BladeProcessor extends AbstractProcessor { ... }
     

3. Reporting Formats:

   • Generate custom reports by extending the Report classes (e.g., for Slack notifications or Jira tickets).

Laravel-Specific Quirks

• Blade Files: Peck skips Blade files by default. To include them, add to peck.json:

  {
    "include": ["*.blade.php"]
  }
  

• Database Migrations: Ignore migration files if they contain raw SQL with non-standard terms:

  {
    "ignore": {
      "paths": ["database/migrations/*"]
    }
  }
  

• Artisan Commands: Use --text to validate command descriptions in app/Console/Kernel.php:

  ./vendor/bin/peck --text "This command does something useful"