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: Navigate to your Laravel project root and run:

   lean-package-validator validate
   

   This checks if your .gitattributes file correctly excludes common repository artifacts (e.g., tests/, vendor/, .env) from release assets.

3. Quick Fix: If validation fails, use the create command to auto-generate a compliant .gitattributes:

   lean-package-validator create
   

First Use Case: Pre-Release Check

Before tagging a Laravel package (e.g., a service provider or API library), run:

composer validate-gitattributes

Add this to your composer.json scripts:

"scripts": {
    "validate-gitattributes": "lean-package-validator validate --validate-git-archive"
}

This ensures no unwanted files (e.g., node_modules/, .idea/) leak into your dist package.

Implementation Patterns

Workflows

1. CI/CD Integration: Add to .github/workflows/ci.yml:

   - name: Validate Lean Package
     run: composer validate-gitattributes
   

   Fail the build if validation fails, enforcing lean releases.

2. Composer Script Hooks: Use in post-update-cmd to auto-fix .gitattributes:

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

3. Custom Presets: For Laravel-specific packages, create a custom .lpv file:

   lean-package-validator init --preset=PHP
   

   Then edit .lpv to include Laravel-specific paths (e.g., config/, database/).

Integration Tips

• Laravel Artisan Commands: Extend your package’s CLI with a custom command:

  // app/Console/Commands/ValidateLeanPackage.php
  use Stolt\LeanPackageValidator\Validator;
  
  protected $signature = 'package:validate-lean';
  public function handle(Validator $validator) {
      $validator->validate(__DIR__.'/../../');
  }
  

• Git Hooks: Add to .git/hooks/pre-commit:

  #!/bin/sh
  composer validate-gitattributes || exit 1
  

• Monorepos: Use --glob-pattern to exclude project-specific paths:

  lean-package-validator validate --glob-pattern '{tests/**,vendor/**,node_modules/**,.env}'
  

Gotchas and Tips

Pitfalls

1. False Positives:

   • The validator may flag config/ as ignored if not explicitly allowed. Use --keep-glob-pattern '{config/}' to override.

2. Negated Patterns:

   • Avoid mixing export-ignore and -export-ignore for the same path. Stick to one style (prefer classic for Laravel).

3. Git Archive Validation:

   • --validate-git-archive creates a temporary archive. On CI, ensure Git is initialized (git init if needed).

4. Case Sensitivity:

   • .gitattributes is case-sensitive. Ensure paths match exactly (e.g., README.md vs readme.md).

Debugging

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

  lean-package-validator update --dry-run
  

• Diff Output: Compare current vs expected .gitattributes:

  lean-package-validator validate --diff
  

• Stale Entries: Detect unused export-ignore rules:

  lean-package-validator validate --report-stale-export-ignores
  

Extension Points

1. Custom Validators: Extend the Validator class to add Laravel-specific rules:

   // app/Providers/LeanPackageValidatorServiceProvider.php
   use Stolt\LeanPackageValidator\Validator;
   
   public function boot() {
       Validator::extend(function ($attributes, $path) {
           return !str_starts_with($path, 'storage/') || file_exists($path);
       });
   }
   

2. Preset Overrides: Override the PHP preset in config/lpv.php:

   'patterns' => [
       '{tests/**,vendor/**,node_modules/**,storage/**,bootstrap/cache/**,*.env}',
   ],
   

3. GitHub Action: Use the dedicated action for CI:

   - uses: raphaelstolt/lean-package-validator-action@v1
     with:
       directory: '.'
   

Laravel-Specific Tips

• Exclude Laravel Cache: Add to .gitattributes:

  bootstrap/cache/ export-ignore
  

• Keep Config Files: Use --keep-glob-pattern to retain config/:

  lean-package-validator validate --keep-glob-pattern '{config/**,*.env.example}'
  

• PHAR Packages: For PHAR builds, exclude vendor/ and bootstrap/:

  lean-package-validator validate --glob-pattern '{vendor/**,bootstrap/**,tests/**}'