Lean Package Validator Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer global require stolt/lean-package-validator
   

   Add to PATH or create an alias (e.g., alias lpv='~/.config/composer/vendor/bin/lean-package-validator').

2. First Use Case: Validate your Laravel project’s .gitattributes for lean releases:

   lpv validate
   

   Run in your project root (or specify a directory). If missing, it suggests creating one.

Implementation Patterns

Workflows

1. Pre-Release Validation: Integrate into Laravel’s composer.json scripts:

   {
       "scripts": {
           "pre-release": [
               "lean-package-validator validate",
               "@php artisan package:discover"
           ]
       }
   }
   

   Run with composer pre-release.

2. CI/CD Pipeline: Use in GitHub Actions (e.g., stolt/lean-package-validator-action) or GitLab CI:

   # .github/workflows/validate.yml
   - name: Validate Lean Package
     run: composer run lean-package-validator validate
   

3. Agentic Workflows: For AI/automation pipelines, use --agentic-run for structured JSON output:

   lpv validate --agentic-run | jq '.valid'
   

Integration Tips

• Custom Patterns: Override defaults with --glob-pattern or a .lpv file:

  lpv validate --glob-pattern '{*.env,node_modules/,tests/}'
  

• Presets: Use language-specific presets (e.g., PHP, JavaScript):

  lpv validate --preset=PHP
  

• Git Archive Validation: Ensure no artifacts slip into releases:

  lpv validate --validate-git-archive
  

Gotchas and Tips

Pitfalls

1. Deprecated Flags: Avoid --create/--overwrite (deprecated in v5.0). Use create/update commands instead:

   lpv create  # Replaces --create
   lpv update  # Replaces --overwrite
   

2. Strict Order Enforcement: --enforce-strict-order fails if export-ignore entries are not in the exact expected order. Use sparingly.

3. False Positives: --validate-git-archive may flag LICENSE/README if not explicitly kept:

   lpv validate --keep-license --keep-readme
   

Debugging

• Diff Mode: Compare actual vs. expected .gitattributes:

  lpv validate --diff
  

• Dry Runs: Test changes without modifying files:

  lpv update --dry-run
  

Extension Points

1. Custom .lpv Files: Define project-specific patterns (e.g., for Laravel’s storage/):

   lpv init --preset=PHP
   # Edit `.lpv` to add:
   # storage/* export-ignore
   

2. Preset Extensions: Extend presets by copying PhpPreset.php and overriding patterns.

3. GitHub Action: Use the action for automated validation in PRs:

   - uses: raphaelstolt/lean-package-validator-action@v1
   

Laravel-Specific Tips

• Artisan Integration: Create a custom command to validate before vendor:publish:

  // app/Console/Commands/ValidateLeanPackage.php
  public function handle() {
      $this->call('lean-package-validator', ['command' => 'validate']);
  }
  

  Register in app/Console/Kernel.php:

  protected $commands = [
      \App\Console\Commands\ValidateLeanPackage::class,
  ];