Branch Alias Validation Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: The package addresses a critical gap in Laravel/PHP CI/CD pipelines—enforcing branch-tag alignment to prevent version skew and release chaos. It fits seamlessly into:
  • Pre-merge validation (e.g., GitHub Actions/GitLab CI).
  • Laravel-specific workflows where branches (e.g., feature/, release/) must logically progress with tags (e.g., v1.0.0).
  • Semantic Versioning (SemVer) compliance, a priority for Laravel monorepos or enterprise apps.
• Laravel Synergy:
  • Artisan Integration: Can be wrapped in a custom command (e.g., php artisan validate:branches) for developer workflows.
  • Envoyer/Forge: Validates branches before deployments tied to tagged releases.
  • Laravel Mix/Vite: Extend to block builds if branch validation fails (e.g., via postcss or webpack hooks).
• Limitation: Not a "Laravel package" per se—its value depends on Git tagging discipline, which may not exist in all PHP projects (e.g., trunk-based development).

Integration Feasibility

• Composer-First Design:
  • Zero Laravel dependencies; integrates via require-dev and a CLI binary.
  • Pros: No bloated dependencies, easy to add/remove.
  • Cons: Requires manual invocation (mitigated by CI/Laravel wrappers).
• Git Dependency:
  • Hard Requirement: Git must be installed on all execution environments (CI, local dev, servers).
  • Laravel-Specific: No impact on backend logic, but CI/CD (e.g., GitHub Actions) must support Git.
• Output Flexibility:
  • Currently CLI-only (exit codes + console output).
  • Extension Opportunity: Modify to output JSON for Laravel API integration (e.g., frontend branch validation).

Technical Risk

• Rule Rigidity:
  • Default Behavior: Fails if any branch is behind the latest tag.
  • Risk: Overly strict for teams with:
    • Long-lived release/ branches (e.g., release/2.x may lag v2.0.0 during stabilization).
    • main/develop branches that intentionally diverge from tags.
  • Mitigation: Extend the package to support:
    • Configurable branch whitelists (e.g., ["main", "develop"]).
    • Tag pattern exclusions (e.g., ignore alpha-* tags).
• Performance in CI:
  • Git operations (e.g., git tag, git merge-base) can add 5–30 seconds to CI pipelines for large repos.
  • Mitigation:
    • Cache Git metadata (e.g., git fetch --tags once per job).
    • Run only on relevant branches (e.g., feature/*, release/*).
• Maintenance Risk:
  • Unproven: 0 stars, 0 dependents, minimal documentation.
  • Mitigation:
    • Treat as a temporary solution until a more robust tool emerges.
    • Fork and extend for critical use cases (e.g., add Laravel-specific logging).

Key Questions

1. Branch/Tag Strategy:
   • Are branches named consistently (e.g., feature/, hotfix/)? If not, validation may fail unpredictably.
   • How are tags created? (e.g., manual, automated via CI, or tied to Laravel releases?)
2. Integration Depth:
   • Should validation block merges (CI failure) or warn (e.g., Slack alert)?
   • Should Laravel expose this as an API (e.g., GET /api/branch-validation) for frontend checks?
3. Customization Needs:
   • Are default rules sufficient, or needed to:
     • Whitelist branches (e.g., main can lag tags)?
     • Ignore specific tag patterns (e.g., v*.*.*-rc.*)?
4. Error Handling:
   • How should failures be surfaced?
     • CI: Fail the pipeline.
     • Laravel: Log to storage/logs/laravel.log or show in admin panel.
     • Git Hook: Block git push locally.
5. Alternatives:
   • Could this be replaced by:
     • Git Hooks (e.g., pre-push script)?
     • GitHub API (e.g., check branch/tag state via REST)?
     • Laravel Policy (e.g., BranchValidationPolicy for authorization)?

Integration Approach

Stack Fit

• PHP/Laravel Compatibility:
  • 100% Compatible: No Laravel dependencies; works with any PHP 7.4+ project.
  • Laravel-Specific Enhancements:
    • Artisan Command: Wrap the binary for php artisan validate:branches.
    • Service Provider: Hook into Laravel events (e.g., git:pre-push, deploy).
    • Testing: Integrate with Pest/Laravel tests (e.g., fail tests if branches are invalid).
• CI/CD Tools:
  • GitHub Actions: Add as a step in workflows (e.g., feature/* branches).
  • GitLab CI: Use before_script to install Git and run validation.
  • CircleCI: Execute via run command with Git preinstalled.
• Local Development:
  • Pre-commit Hook: Add to .git/hooks/pre-push to block stale branches.
  • Laravel Valet/Homestead: Run manually or via custom Artisan command.

Migration Path

1. Phase 1: Composer Integration (1 hour)

   • Add to composer.json:

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

   • Run composer install.
   • Test locally:

     ./vendor/bin/validate-branch-alias.php
     

2. Phase 2: CI Validation (2 hours)

   • GitHub Actions Example:

     - name: Validate branch alias
       if: contains(github.ref, 'feature/') || contains(github.ref, 'release/')
       run: ./vendor/bin/validate-branch-alias.php
     

   • GitLab CI Example:

     validate_branch:
       script:
         - ./vendor/bin/validate-branch-alias.php
       rules:
         - if: $CI_COMMIT_REF_NAME =~ /^feature\/|release\//
     

3. Phase 3: Laravel Integration (Optional, 4 hours)

   • Artisan Command:

     php artisan make:command ValidateBranches
     

     // app/Console/Commands/ValidateBranches.php
     public function handle() {
         $exitCode = shell_exec('php ' . base_path('vendor/bin/validate-branch-alias.php'));
         if ($exitCode !== 0) {
             $this->error('Branch validation failed! Fix before merging.');
             exit(1);
         }
     }
     

   • Register Command:

     // app/Console/Kernel.php
     protected $commands = [
         Commands\ValidateBranches::class,
     ];
     

   • Run via Artisan:

     php artisan validate:branches
     

4. Phase 4: Customization (If Needed, 8 hours)

   • Extend the Package:
     • Fork and modify validate-branch-alias.php to:
       • Read a config file (e.g., .branch-validation.json).
       • Support whitelisted branches.
       • Output JSON for API use.
     • Example config:

       {
         "whitelist": ["main", "develop"],
         "ignoreTags": ["v*.*.*-rc.*"]
       }
       

   • Laravel-Specific:
     • Publish config via php artisan vendor:publish.
     • Add a BranchValidationService to reuse logic in policies/controllers.

Compatibility

• Git Version: Requires Git ≥2.0 (for git merge-base). 99% of modern setups (2018+) are compatible.
• PHP Version: Assumes PHP 7.4+ (check Laravel’s php-version support).
  • Laravel 8.x: PHP 7.4–8.1.
  • Laravel 9.x: PHP 8.0–8.2.
• Operating System: Cross-platform (Linux/macOS/Windows with Git installed).
• Laravel Version: No direct dependency, but must align with PHP version (e.g., Laravel 8+ for PHP 8.0+).

Sequencing