Author Validation Laravel Package

Getting Started

Minimal Steps

1. Installation: Add to composer.json under require-dev:

   "phpcq/author-validation": "^1.0"
   

   Run composer update.

2. First Run: Execute the CLI tool in your project root:

   ./vendor/bin/check-author.php
   

   This checks all PHP files, composer.json, and package files against Git authorship.

3. Basic Configuration: Create a .check-author.yml file in your project root with minimal settings:

   ignore:
     - "Build Bot <bot@example.com>"
   exclude:
     - "vendor/"
     - "tests/"
   

First Use Case

Pre-CI Validation: Integrate into a GitHub Actions workflow to block merges with mismatched authors:

# .github/workflows/author-validation.yml
name: Author Validation
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: composer install
      - run: ./vendor/bin/check-author.php

Implementation Patterns

Usage Patterns

1. Path Scoping: Limit checks to specific directories (e.g., Laravel’s app/):

   ./vendor/bin/check-author.php app/
   

   Or via config:

   include:
     - "app/"
     - "config/"
   

2. Author Aliasing: Map historical authors to current names (e.g., after renames):

   mapping:
     "Old Name <old@example.com>": "New Name <new@example.com>"
   

3. Copy-Left Enforcement: Enforce specific authors for certain files/directories:

   copy-left:
     "Lead Developer <dev@example.com>": "src/"
   

Workflows

1. Pre-Commit Hook: Use with Husky to fail locally:

   # package.json
   "husky": {
     "hooks": {
       "pre-commit": "./vendor/bin/check-author.php --quiet"
     }
   }
   

2. CI/CD Pipeline: Run as a build step with path filtering:

   # GitLab CI example
   test:
     script:
       - ./vendor/bin/check-author.php --path=app/
   

3. Laravel Artisan Integration: Create a custom command to wrap the tool:

   // app/Console/Commands/ValidateAuthors.php
   public function handle() {
       $command = base_path('vendor/bin/check-author.php');
       $exitCode = shell_exec("$command app/ 2>&1");
       if ($exitCode !== 0) {
           $this->error('Author validation failed!');
           exit(1);
       }
   }
   

Integration Tips

• Laravel-Specific: Exclude Blade templates by default (they’re not PHP files):

  exclude:
    - "resources/views/**/*.blade.php"
  

• Monorepos: Use --path to scope to Laravel directories:

  ./vendor/bin/check-author.php packages/laravel-app/
  

• Git Workflow: Ensure CI runs git fetch --unshallow if using shallow clones to avoid missing history.

Gotchas and Tips

Pitfalls

1. Git History Dependencies:

   • Issue: Missing Git history (e.g., shallow clones) causes false negatives.
   • Fix: Add to CI:

     - run: git fetch --unshallow
     

2. Case Sensitivity:

   • Issue: Author names like "John Doe" vs. "john doe" may not match.
   • Fix: Normalize in config or use exact matches.

3. Blade Template Exclusions:

   • Issue: .blade.php files are PHP but often excluded.
   • Fix: Explicitly include if needed:

     include:
       - "resources/views/**/*.blade.php"
     

4. Vendor Directory Conflicts:

   • Issue: Third-party authors in vendor/ may trigger false positives.
   • Fix: Always exclude vendor/ in config.

Debugging

• Verbose Output: Use --verbose to see detailed mismatches:

  ./vendor/bin/check-author.php --verbose
  

• Dry Runs: Test without failing builds:

  ./vendor/bin/check-author.php --dry-run
  

• Config Validation: Validate YAML syntax with:

  ./vendor/bin/check-author.php --config=.check-author.yml --dry-run
  

Config Quirks

1. Path Resolution:

   • Relative paths in include/exclude are resolved from the config file’s directory.
   • Use absolute paths for reliability in CI.

2. Author Mapping:

   • One-to-Many: Use arrays for multiple aliases:

     mapping:
       "Old Name <old@example.com>":
         - "New Name <new@example.com>"
         - "Team Alias <team@example.com>"
     

3. Copy-Left Overrides:

   • Directory vs. File: Directories take precedence over files.
   • Glob Patterns: Use **/ for deep paths:

     copy-left:
       "Lead <lead@example.com>": "src/**/*.php"
     

Extension Points

1. Custom Comparators: Extend the tool by implementing a custom comparator (advanced). See source.

2. Laravel Service Provider: Register the tool as a Laravel service for dynamic config:

   // config/check-author.php
   return [
       'ignore' => env('AUTHOR_VALIDATION_IGNORE', []),
   ];
   

3. CI Notifications: Parse output in CI to send Slack alerts on failures:

   - name: Slack Notification
     if: failure()
     run: |
       curl -X POST -H 'Content-type: application/json' \
       --data '{"text":"Author validation failed!"}' \
       $SLACK_WEBHOOK