Lean Package Validator Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require --dev stolt/lean-package-validator
   

   or globally:

   composer global require stolt/lean-package-validator
   

2. First Validation: Run in your project root:

   vendor/bin/lean-package-validator validate
   

   This checks if .gitattributes excludes common non-release files (e.g., .github/, vendor/).

3. Quick Fix: Auto-generate a compliant .gitattributes:

   vendor/bin/lean-package-validator create
   

Where to Look First

• Presets: Use --preset=PHP (default) or others (Python, Rust, etc.) for language-specific rules.
• CLI Help: Run vendor/bin/lean-package-validator validate --help for options.
• GitHub Action: For CI/CD integration, see lean-package-validator-action.

Implementation Patterns

Core Workflows

1. Pre-Release Validation: Add to composer.json:

   "scripts": {
     "pre-release": [
       "@validate-gitattributes",
       "phpunit"
     ],
     "validate-gitattributes": "lean-package-validator validate --validate-git-archive"
   }
   

   Ensures no unwanted files slip into releases.

2. CI/CD Integration: Use the GitHub Action in .github/workflows/validate.yml:

   - name: Validate Lean Package
     uses: raphaelstolt/lean-package-validator-action@v1
     with:
       directory: '.'
   

3. Custom Patterns: Create a .lpv file in your project root:

   lean-package-validator init --preset=PHP
   

   Edit to add custom glob patterns (e.g., *.env).

Laravel-Specific Use Cases

1. Artisan Command: Publish the CLI as an Artisan command:

   php artisan vendor:publish --provider="Stolt\LeanPackageValidator\LeanPackageValidatorServiceProvider"
   

   Then call via:

   php artisan lean-package-validator:validate
   

2. Package Development: For Laravel packages, enforce lean releases by:

   lean-package-validator validate --preset=PHP --keep-glob-pattern '{LICENSE,README.md}'
   

3. Testing: Validate in PHPUnit tests:

   use Stolt\LeanPackageValidator\Validator;
   
   public function testGitAttributes()
   {
       $validator = new Validator();
       $this->assertTrue($validator->validate(__DIR__.'/../'));
   }
   

Integration Tips

• Composer Scripts: Use post-update-cmd to auto-fix .gitattributes:

  "scripts": {
    "post-update-cmd": "lean-package-validator update"
  }
  

• Monorepos: Run in subdirectories:

  find packages -name "composer.json" -exec dirname {} \; | xargs -I{} lean-package-validator validate {}
  

• PHAR Deployment: For standalone PHARs, exclude build artifacts:

  lean-package-validator validate --glob-pattern '{*.phar,build/}'
  

Gotchas and Tips

Pitfalls

1. False Positives:

   • Issue: --validate-git-archive may fail if composer.lock is excluded but needed for testing.
   • Fix: Use --keep-glob-pattern '{composer.lock}' or adjust presets.

2. Order Sensitivity:

   • Issue: --enforce-strict-order fails if .gitattributes entries are reordered.
   • Fix: Use --sort-from-directories-to-files to standardize order.

3. PHAR Conflicts:

   • Issue: PHAR files may be excluded by default, breaking deployments.
   • Fix: Add to .lpv:

     *.phar !export-ignore
     

4. Case Sensitivity:

   • Issue: Git attributes are case-sensitive on Linux/macOS but not Windows.
   • Fix: Use lowercase globs (e.g., *.php) for cross-platform compatibility.

5. Nested Directories:

   • Issue: Deeply nested .gitattributes files may not be detected.
   • Fix: Run lean-package-validator validate from the project root.

Debugging

1. Dry Runs: Use --dry-run with update or reformat to preview changes:

   lean-package-validator update --dry-run
   

2. Diff Output: Compare current vs. expected .gitattributes:

   lean-package-validator validate --diff
   

3. Tree Inspection: Debug what’s excluded:

   lean-package-validator tree --src --dist-package
   

Extension Points

1. Custom Presets: Extend Stolt\LeanPackageValidator\Presets\PresetInterface to add language support (e.g., LaravelPreset).

2. Agentic Mode: Use --agentic-run for programmatic output (JSON):

   lean-package-validator validate --agentic-run | jq '.valid'
   

3. Git Hooks: Integrate with pre-push to block non-lean commits:

   lean-package-validator validate || exit 1
   

Laravel-Specific Quirks

1. Vendor Exclusions: Laravel’s vendor/ is already excluded by default, but ensure:

   vendor/ export-ignore
   

2. Configuration Caching: If using config:cache, exclude:

   bootstrap/cache/ export-ignore
   

3. Artisan Commands: For custom commands, exclude:

   app/Console/Commands/ export-ignore
   

Performance Tips

• Cache Results: Store validation output in bootstrap/cache/lean-package-validator.json for repeated runs.
• Parallel Validation: Use parallel-lint or pest to validate multiple packages simultaneously.