Grumphp License Task Laravel Package

Getting Started

Minimal Steps

1. Install the Package:

   composer require loophp/grumphp-license-task --dev
   

   Ensure it’s added to require-dev in composer.json for CI/CD environments.

2. Register the Extension: Add the extension to your grumphp.yml:

   grumphp:
     extensions:
       - loophp\GrumphpLicenseTask\Extension
   

3. Configure the Task: Define the license task in grumphp.yml with required fields:

   tasks:
     license:
       name: MIT          # Required: OSI license name (e.g., MIT, LGPL-3.0)
       holder: "Your Name" # Required: License holder
       date_from: 2023     # Optional: Year for dynamic date placeholders
   

4. Run GrumPHP: Execute locally or in CI:

   ./vendor/bin/grumphp run
   

   • If no LICENSE file exists, it will be auto-generated.
   • If invalid, GrumPHP will suggest fixes.

First Use Case

Onboarding New Developers:

• Add the task to your team’s grumphp.yml to enforce license compliance during PR reviews.
• Example workflow:

  tasks:
    license:
      name: MIT
      holder: "Acme Corp"
      date_from: 2023
  

  • Outcome: New contributors cannot commit without a valid LICENSE file, reducing legal risks.

Implementation Patterns

Workflows

1. CI/CD Integration:

   • Place the task in your CI pipeline (e.g., GitHub Actions) to block merges without a valid license:

     # .github/workflows/ci.yml
     jobs:
       test:
         runs-on: ubuntu-latest
         steps:
           - uses: actions/checkout@v4
           - run: composer install
           - run: ./vendor/bin/grumphp run --strict
     

2. Dynamic License Updates:

   • Use date_from to auto-update the year in the license file:

     tasks:
       license:
         name: MIT
         holder: "Acme Corp"
         date_from: 2023  # Updates annually via CI script
     

   • Tip: Combine with a script to update date_from in grumphp.yml yearly.

3. Custom License Files:

   • Use input/output to validate or generate licenses from templates:

     tasks:
       license:
         input: ./templates/CUSTOM_LICENSE.txt
         output: LICENSE
     

4. Multi-Repository Consistency:

   • Standardize licenses across repositories by reusing the same grumphp.yml snippet.

Integration Tips

• Combine with Other Tasks: Pair with grumphp/phpunit or grumphp/git_blacklist to enforce licenses alongside code quality:

  tasks:
    license:
      name: MIT
    phpunit:
      test_class_regex: ".*Test"
  

• Exclude Directories: Use GrumPHP’s paths to skip specific folders (e.g., vendor/):

  grumphp:
    paths:
      - src/
      - tests/
    ignore:
      - vendor/
  

• Custom Error Handling: Override GrumPHP’s failure messages via grumphp.yml:

  grumphp:
    tasks:
      license:
        name: MIT
        failure_message: "LICENSE file is missing or invalid. Run `grumphp fix` to auto-fix."
  

Gotchas and Tips

Pitfalls

1. License Name Mismatch:

   • Issue: Using an unsupported license (e.g., GPL-3.0) will fail silently.
   • Fix: Check supported licenses or submit a PR to add yours.

2. File Permission Errors:

   • Issue: GrumPHP may fail to write LICENSE if permissions are restricted.
   • Fix: Ensure the CI user has write access to the project root:

     # GitHub Actions example
     - run: chmod -R a+w .
     

3. Dynamic date_from Quirks:

   • Issue: If date_from is set to a future year, the license may appear invalid.
   • Fix: Use a script to update date_from annually or set it to the current year.

4. Custom Templates:

   • Issue: The input/output feature may not handle complex templates (e.g., with placeholders).
   • Workaround: Pre-process templates with a script before running GrumPHP.

Debugging

1. Dry Runs: Use --dry-run to preview changes without modifying files:

   ./vendor/bin/grumphp run --dry-run
   

2. Verbose Output: Enable debug mode for detailed logs:

   ./vendor/bin/grumphp run -v
   

3. Fix Mode: Auto-correct issues with:

   ./vendor/bin/grumphp fix
   

Extension Points

1. Custom Licenses: Extend the package by adding new licenses via a PR or fork. The source shows how licenses are defined.

2. Pre/Post-Task Hooks: Use GrumPHP’s on-failure or on-success hooks to trigger additional actions:

   grumphp:
     hooks:
       on-failure:
         - ./scripts/notify-slack.sh "License check failed!"
   

3. Environment Variables: Dynamically set holder or date_from via environment variables (requires custom scripting):

   tasks:
     license:
       name: MIT
       holder: "%env(HOLDER_NAME)%"  # Requires interpolation (not natively supported)
   

Pro Tips

1. Template Inheritance: Store license templates in a shared repo and symlink them across projects to maintain consistency.

2. CI Caching: Cache the LICENSE file in CI to avoid regenerating it on every run (if using input/output):

   # GitHub Actions example
   - uses: actions/cache@v3
     with:
       path: LICENSE
       key: ${{ runner.os }}-license
   

3. Git Ignore: Add LICENSE to .gitignore if using input/output to avoid conflicts:

   # .gitignore
   LICENSE
   

4. Team Onboarding: Document the license task in your CONTRIBUTING.md to educate contributors:

   ## License Requirements
   All commits must pass the `grumphp license` task. Run `composer install && ./vendor/bin/grumphp run` locally before submitting PRs.