Peck Laravel Package

Getting Started

Minimal Steps

1. Install Dependencies: Ensure GNU Aspell is installed on your system (see README for OS-specific instructions).

   # Debian/Ubuntu
   sudo apt-get install aspell aspell-en
   

2. Install Peck: Add Peck to your project via Composer:

   composer require peckphp/peck --dev
   

3. Initialize Configuration: Generate a peck.json file with default settings (Laravel preset included):

   ./vendor/bin/peck --init
   

4. Run First Check: Execute Peck in your project root to scan for spelling issues:

   ./vendor/bin/peck
   

First Use Case: Pre-Commit Hook

Add Peck to your pre-commit workflow to catch naming inconsistencies early:

# Example: Using Laravel Git Hooks
./vendor/bin/peck --path=app/Http/Controllers --text="Commit message here"

Implementation Patterns

Workflows

1. Daily Local Development:

   • Run Peck on specific directories (e.g., app/, config/) to catch typos in class/method names:

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

   • Use --text to validate commit messages or docblocks:

     ./vendor/bin/peck --text="Fix the user auth flow"
     

2. CI/CD Integration:

   • Add Peck to your GitHub Actions workflow (see README for setup):

     - name: Run Peck
       run: ./vendor/bin/peck --ignore-all  # Temporarily ignore all to avoid false positives
     

   • Pro Tip: Use --ignore-all initially to baseline your codebase, then refine peck.json to exclude false positives.

3. Team Onboarding:

   • Configure peck.json with project-specific ignores (e.g., app/Helpers, config/) and share it in your repo.
   • Example:

     {
       "preset": "laravel",
       "ignore": {
         "words": ["laravel", "eloquent"],
         "paths": ["app/Helpers/*"]
       }
     }
     

Integration Tips

• Combine with PHPStan/Pest: Use Peck to catch lexical issues (e.g., UsrModel vs. UserModel) while PHPStan handles logical errors. Example workflow:

  ./vendor/bin/peck && ./vendor/bin/phpstan analyse
  

• Custom Dictionaries: Extend Aspell’s dictionary by adding domain-specific terms to peck.json:

  {
    "ignore": {
      "words": ["acme", "customer360"]
    }
  }
  

• IDE Shortcuts: Create a shell alias for quick checks:

  alias peck-check='./vendor/bin/peck --path=app'
  

Gotchas and Tips

Pitfalls

1. False Positives in Laravel:

   • Issue: Peck may flag Laravel-specific terms (e.g., Route, ServiceProvider) as misspellings.
   • Fix: Use the laravel preset or manually ignore words in peck.json:

     "ignore": { "words": ["Route", "ServiceProvider", "Eloquent"] }
     

2. GNU Aspell Dependency:

   • Issue: Windows users may struggle with Aspell installation (WSL recommended).
   • Fix: Document setup steps in your CONTRIBUTING.md or use Docker for CI:

     RUN apt-get update && apt-get install -y aspell aspell-en
     

3. Performance on Large Codebases:

   • Issue: Initial runs may be slow due to Aspell’s dictionary checks.
   • Fix: Cache results or run Peck incrementally:

     ./vendor/bin/peck --path=app/Models  # Target specific directories
     

4. Case Sensitivity:

   • Issue: Aspell may not distinguish between User and user in filenames.
   • Fix: Normalize paths in peck.json or use --ignore-all for case variants.

Debugging

• Verbose Output: Enable debug mode to inspect Aspell’s suggestions:

  ./vendor/bin/peck --verbose
  

• Check Aspell Dictionaries: List available languages to troubleshoot language-specific issues:

  aspell dump dicts
  

Extension Points

1. Custom Presets: Extend the laravel preset by creating a peck-custom.json with project-specific rules:

   {
     "preset": "laravel",
     "ignore": {
       "words": ["acme", "legacy"],
       "paths": ["app/OldCode/*"]
     }
   }
   

2. Hook into Laravel Events: Trigger Peck automatically on artisan commands (e.g., make:model):

   // app/Console/Kernel.php
   protected function commands()
   {
       $this->commands([
           \Peck\Console\PeckCommand::class,
       ]);
   }
   

3. GitHub Actions Caching: Cache Aspell dictionaries between runs to speed up CI:

   - name: Cache Aspell
     uses: actions/cache@v3
     with:
       path: /usr/share/aspell
       key: ${{ runner.os }}-aspell
   

Pro Tips

• Exclude Vendors: Always ignore vendor/ in peck.json to avoid false positives:

  "ignore": { "paths": ["vendor/*"] }
  

• Pair with pint: Run Peck after pint to ensure formatted code is also spell-checked:

  ./vendor/bin/pint && ./vendor/bin/peck
  

• Document Ignored Terms: Maintain a PECK_IGNORES.md file in your repo to explain why certain words/path are excluded (e.g., legacy terms, domain-specific abbreviations).