Lean Package Validator Laravel Package

Technical Evaluation

Architecture Fit

• Lean Package Philosophy: Aligns perfectly with modern PHP/Laravel package development, where minimizing release artifacts (e.g., dev files, IDE configs, tests) is critical for performance and security.
• Git Integration: Leverages .gitattributes (a native Git feature), reducing dependency on custom tooling. Works seamlessly with Laravel’s existing Git workflows (e.g., git archive).
• Preset-Based Validation: Predefined presets (PHP, Python, etc.) ensure consistency across projects, reducing manual configuration. Laravel-specific presets (e.g., for vendor/, bootstrap/) could be added via custom .lpv files.
• CLI + Programmatic Use: Can be invoked via CLI (for CI/CD) or embedded in Laravel’s composer.json scripts, enabling automated validation during builds/deploys.

Integration Feasibility

• Low Friction: No Laravel-specific dependencies; integrates via Composer. Can be added to any Laravel project as a dev dependency (composer require --dev stolt/lean-package-validator).
• Git Hooks: Can be tied to pre-commit or pre-push hooks (via composer.json scripts) to enforce lean releases before code is merged or deployed.
• CI/CD Pipelines: Ideal for GitHub Actions, GitLab CI, or Laravel Forge deployments to validate releases pre-publish. Example:

  # GitHub Actions
  - name: Validate Lean Package
    run: composer validate-gitattributes
  

• Laravel Artisan Integration: Could be wrapped in a custom Artisan command for tighter integration with Laravel’s ecosystem (e.g., php artisan lpv:validate).

Technical Risk

• False Positives/Negatives: Custom .gitattributes rules might conflict with Laravel’s default ignored files (e.g., node_modules/, storage/). Requires careful tuning of glob patterns.
• Performance Overhead: --validate-git-archive creates temporary archives, which could slow down CI pipelines for large repos. Mitigate by running only in critical paths (e.g., main branch).
• Tooling Dependency: Relies on Git’s export-ignore feature; teams unfamiliar with .gitattributes may need training. Document usage clearly in the project’s CONTRIBUTING.md.
• Laravel-Specific Edge Cases: Laravel’s vendor/ directory is auto-generated and often excluded, but custom vendor paths (e.g., in monorepos) might need explicit handling.

Key Questions

1. Scope of Validation:
   • Should Laravel-specific files (e.g., bootstrap/cache/, config/) be explicitly allowed or excluded?
   • How to handle dynamically generated files (e.g., compiled Blade templates in storage/framework/views)?
2. CI/CD Strategy:
   • Should validation run on every commit (potentially noisy) or gated to release branches?
   • How to handle failures in CI (block vs. warn)?
3. Customization:
   • Should the team create a custom .lpv preset for Laravel (e.g., including routes/, app/Providers)?
   • How to balance strictness (e.g., blocking README.md in releases) with practicality (e.g., allowing CHANGELOG.md)?
4. Tooling Integration:
   • Should the package be integrated into Laravel’s make:package or make:command scaffolding?
   • Could it be extended to validate composer.json for lean dependencies (e.g., no require-dev in production)?

Integration Approach

Stack Fit

• Laravel Compatibility: Fully compatible with Laravel 10+ (PHP 8.2+) and modern Composer workflows. No framework-specific code required.
• Ecosystem Synergy:
  • Works with Laravel’s composer.json scripts, GitHub Actions, and Forge deployments.
  • Complements tools like phpunit, phpstan, and pest by ensuring their configs (e.g., phpunit.xml.dist) are excluded from releases.
• Monorepo Support: Can validate individual Laravel packages within a monorepo by targeting specific directories.

Migration Path

1. Pilot Phase:
   • Install as a dev dependency in a non-critical Laravel package:

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

   • Add to composer.json:

     "scripts": {
       "validate-lean": "lean-package-validator validate"
     }
     

   • Test locally with composer validate-lean and adjust .gitattributes as needed.
2. CI/CD Integration:
   • Add to GitHub Actions/GitLab CI:

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

   • Start with warnings (non-blocking) to avoid disrupting workflows.
3. Enforcement:
   • Gradually enforce in critical paths (e.g., release branches) by making the script fail CI.
   • Document exceptions (e.g., CHANGELOG.md allowed in releases) in the project’s CONTRIBUTING.md.

Compatibility

• Laravel-Specific Files:
  • Default PHP preset excludes common Laravel files (e.g., vendor/, node_modules/), but may need tweaks for:
    • Custom storage paths (e.g., storage/app/public).
    • Environment-specific configs (e.g., .env.example vs. .env).
  • Use --keep-glob-pattern to whitelist exceptions:

    lean-package-validator validate --keep-glob-pattern '{CHANGELOG.md,.env.example}'
    

• Existing .gitattributes:
  • The update command can migrate existing files to the lean format:

    lean-package-validator update --dry-run
    

  • Use --diff to preview changes:

    lean-package-validator validate --diff
    

• Multi-Package Repos:
  • Validate each package directory separately:

    lean-package-validator validate packages/auth
    

Sequencing

1. Initial Setup:
   • Run lean-package-validator init to create a .lpv file with Laravel-specific patterns.
   • Customize the .lpv file or use --preset=PHP as a starting point.
2. Validation:
   • Start with --validate-git-archive to catch accidental inclusions in releases.
   • Use --report-stale-export-ignores to clean up unused rules.
3. Automation:
   • Integrate into composer.json scripts and CI pipelines.
   • Add to pre-release hooks to validate before publishing to Packagist.
4. Iteration:
   • Refine glob patterns based on false positives/negatives.
   • Consider creating a Laravel-specific preset PR to the package.

Operational Impact

Maintenance

• Low Ongoing Effort:
  • Minimal maintenance required after initial setup. Updates to the validator can be handled via Composer.
  • Presets (e.g., PHP) are maintained by the package authors, reducing local upkeep.
• Dependency Updates:
  • Monitor for breaking changes in the validator (e.g., new PHP version requirements).
  • Test updates in a staging environment before rolling out to production packages.
• Documentation:
  • Maintain a LEAN_PACKAGE_GUIDE.md in the repo explaining:
    • Why leanness matters (e.g., smaller release sizes, security).
    • How to customize .gitattributes for Laravel.
    • Common exceptions (e.g., CHANGELOG.md).

Support

• Troubleshooting:
  • Common issues:
    • False positives for Laravel-specific files (e.g., bootstrap/cache/).
    • Conflicts with existing .gitattributes rules (e.g., from IDEs like PHPStorm).
  • Solutions:
    • Use --diff to debug discrepancies.
    • Adjust glob patterns or use --keep-glob-pattern.
• Team Adoption:
  • Provide a workshop or runbook for contributors on:
    • How to run lean-package-validator.
    • What to do when validation fails.
  • Example workflow:

    # Fix a validation failure
    lean-package-validator update --dry-run  # Preview changes
    lean-package-validator update            # Apply changes
    git add .gitattributes
    git commit -m "Fix lean package validation"
    

• Escalation Path:
  • For complex issues (e.g., custom Laravel setups), escalate to the validator’s GitHub issues or create a feature request for Laravel-specific presets.

Scaling

• Performance:
  • --validate-git-archive is the most resource-intensive operation. Mitigate by:
    • Running only on release branches or tags.
    • Caching results for frequent runs (e.g., in CI).
  • For large repos, consider parallelizing validation across subdirectories.
• Team Growth:
  • As the team grows, enforce validation in onboarding (e.g., "All new packages must pass lean validation").
  • Use the GitHub Action to automate checks for all PRs targeting main.
• Multi-Repo Workflows:
  • Centralize `.lp