Author Validation Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: The package serves as a compliance guardrail for copyright attribution, aligning with Laravel projects requiring strict adherence to open-source licenses (e.g., MIT, GPL) or internal IP policies. It complements Laravel’s existing tooling (e.g., phpunit, pint) by addressing a non-functional but critical requirement.
• Modularity: Operates independently of Laravel’s core, making it ideal for monorepos or projects with mixed PHP stacks (e.g., Laravel + Symfony). Avoids tight coupling with framework-specific components (e.g., Eloquent, Blade).
• Extensibility Gaps: Lacks native Laravel integrations (e.g., Artisan commands, service providers), requiring wrapper logic for deep integration. Could be extended via a custom facade or console command (see Integration Approach).

Integration Feasibility

• Low-Coupling Design: No Laravel dependencies; integrates via Composer and CLI. Feasible for:
  • Pre-commit hooks (e.g., Husky).
  • CI/CD pipelines (e.g., GitHub Actions, Laravel Forge).
  • Scheduled tasks (e.g., Laravel’s schedule).
• Path Limitations:
  • Blade Templates: Ignores .blade.php files by default. Requires custom config (e.g., include: ["resources/views/**/*.blade.php"]) or post-processing (e.g., sed to convert Blade to PHP for validation).
  • Vendor Files: Exclude vendor/ by default (recommended) but may need inclusion for custom packages.
• Git Dependency: Relies on Git history for author detection. Projects using GitHub/GitLab templates or squashed commits may require manual config tweaks.

Technical Risk

• False Positives/Negatives:
  • Case Sensitivity: Author names like "John Doe" vs. "john doe" may fail. Mitigate with config normalization (e.g., .check-author.yml mapping).
  • Incomplete Git Logs: Shallow clones or missing git fetch may cause missing author data. Enforce git fetch --unshallow in CI.
• Configuration Complexity:
  • Author Aliasing: Requires manual maintenance for renamed contributors or team mergers. Automate with a script (e.g., git log --format='%aN <%aE>' | sort | uniq).
  • Path Exclusions: Risk of over/under-inclusion if include/exclude rules are misconfigured. Document defaults in README.md.
• Performance:
  • Linear Scaling: Time complexity grows with file count. For repos >50K files, parallelize checks (e.g., GitHub Actions matrix).
  • CI Bottleneck: May slow pipelines if run on every commit. Optimize with path filtering (e.g., ./vendor/bin/check-author.php app/).

Key Questions

1. Validation Scope:
   • Should Blade templates (.blade.php) be validated? If yes, how to handle dynamic content (e.g., @include)?
   • Should third-party packages (e.g., vendor/) be excluded or validated?
2. Error Handling:
   • Should failures block builds (fail-fast) or log warnings (allow-list exceptions)?
   • How to notify stakeholders (e.g., Slack, email) on CI failures?
3. Laravel-Specific Needs:
   • Can it integrate with Laravel Mix (e.g., package.json authors)?
   • Should it validate config files (e.g., config/app.php copyright headers)?
4. Git Workflow:
   • How to handle new contributors (e.g., auto-update config via PR template)?
   • Should it skip initial commit (e.g., git init) or validate all history?
5. Configuration Management:
   • Should .check-author.yml be auto-generated from Git logs?
   • How to version-control the config (e.g., .gitignore vs. committed)?

Integration Approach

Stack Fit

• PHP/Laravel Compatibility:
  • PHP 8.0+ required (Laravel 8+). Verify compatibility with your Laravel version.
  • No Framework Lock-in: Works with any PHP project, including non-Laravel codebases.
• Tooling Synergy:
  • Composer: Native integration via require-dev.
  • CI/CD: Seamless with:
    • GitHub Actions (e.g., on: [push]).
    • GitLab CI (e.g., before_script).
    • Laravel Forge/Envoyer (as a deploy hook).
  • Static Analysis: Complements tools like:
    • PHPStan (type safety).
    • Psalm (static analysis).
    • PHPMD (code metrics).
• Laravel-Specific Tools:
  • Artisan: Can wrap the CLI tool in a custom command (see Sequencing).
  • Laravel Mix: Extend to validate package.json authors if using frontend assets.

Migration Path

1. Phase 1: CI-Only Validation (Low Risk)

   • Steps:
     1. Add to composer.json:

        "require-dev": {
          "phpcq/author-validation": "^1.0"
        }
        

     2. Run in CI (GitHub Actions example):

        - name: Validate Authors
          run: ./vendor/bin/check-author.php --path=app/
        

   • Pros: Zero local setup; fails builds early.
   • Cons: No pre-commit feedback.

2. Phase 2: Pre-Commit Hook (Medium Risk)

   • Steps:
     1. Install Husky and add to package.json:

        "scripts": {
          "prepare": "husky install",
          "check-authors": "./vendor/bin/check-author.php --path=app/"
        }
        

     2. Configure Husky to run on pre-commit:

        echo 'node scripts/check-authors.js' >> .husky/pre-commit
        

   • Pros: Immediate feedback for developers.
   • Cons: Local dependency; may slow commits for large repos.

3. Phase 3: Laravel Artisan Command (High Customization)

   • Steps:
     1. Publish a config file:

        ./vendor/bin/check-author.php --publish-config
        

     2. Create a custom Artisan command:

        php artisan make:command ValidateAuthors
        

     3. Implement wrapper logic (e.g., path filtering, Laravel-specific exclusions):

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

   • Pros: Deep Laravel integration; reusable across projects.
   • Cons: Requires maintenance for config updates.

Compatibility

• Path Handling:
  • Supports glob patterns (e.g., app/**/*.php) and relative/absolute paths.
  • Default Behavior: Scans entire repo. Override with --path or .check-author.yml.
• Configuration:
  • .check-author.yml: Must exist or be auto-generated. Example:

    include:
      - app/
      - config/
    exclude:
      - vendor/
      - tests/
    mapping:
      "Old Name <old@example.com>": "New Name <new@example.com>"
    

  • Author Metadata: Use metadata key to add roles/homepages (e.g., for diff output).
• Edge Cases:
  • Submodules: Use --recursive or manual path inclusion.
  • Monorepos: Scope to Laravel directories (e.g., --path=laravel-app/).
  • Blade Templates: Add to include or pre-process files (e.g., php artisan view:clear + custom script).

Sequencing

1. CI Pipeline Order:
   • Run after composer install but before tests/deploy:

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

2. Dependency on Git:
   • Ensure full Git history is available:

     - run: git fetch --unshallow
     

   • For fresh clones, avoid shallow