Mcbumpface Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require --dev malukenho/mcbumpface
   

   Add the package as a dev dependency to avoid bloating production builds.

2. First Use Case: Run the command after composer update to sync composer.json versions with composer.lock:

   ./vendor/bin/mcbumpface
   

   This updates composer.json to reflect the exact versions installed in composer.lock.

3. Where to Look First:

   • Check the README for core functionality.
   • Review the configuration options in composer.json under extra.mc-bumpface.

Implementation Patterns

Usage Patterns

1. Post-Update Workflow: Integrate mcbumpface into your CI/CD pipeline after composer update to ensure composer.json stays aligned with composer.lock:

   # Example GitHub Actions step
   - run: composer update
   - run: ./vendor/bin/mcbumpface
   - run: git add composer.json && git commit -m "Update package versions"
   

2. Selective Bumping: Use the --package flag to target specific packages:

   ./vendor/bin/mcbumpface --package="laravel/framework"
   

3. Dry Run: Test changes without modifying files:

   ./vendor/bin/mcbumpface --dry-run
   

Integration Tips

• Pre-Commit Hooks: Add to .git/hooks/pre-commit to auto-bump versions before commits:

  #!/bin/sh
  ./vendor/bin/mcbumpface
  git add composer.json
  

  (Ensure the hook is executable: chmod +x .git/hooks/pre-commit.)

• Laravel Artisan Command: Create a custom Artisan command to wrap mcbumpface for consistency:

  // app/Console/Commands/BumpPackages.php
  namespace App\Console\Commands;
  use Illuminate\Console\Command;
  class BumpPackages extends Command {
      protected $signature = 'packages:bump';
      public function handle() {
          $this->call('vendor:mcbumpface');
      }
  }
  

  Register in app/Console/Kernel.php and run with:

  php artisan packages:bump
  

• Monorepo Support: For monorepos, use --path to target specific project directories:

  ./vendor/bin/mcbumpface --path="path/to/project"
  

Gotchas and Tips

Pitfalls

1. Version Constraint Conflicts:

   • If composer.lock contains a version incompatible with composer.json constraints (e.g., lock has 1.0.0 but json requires ^2.0), mcbumpface will fail silently. Verify constraints manually or use --force (if available in future versions).

2. Git Conflicts:

   • Running mcbumpface on uncommitted composer.json changes may cause merge conflicts. Commit or stash changes before running:

     git stash
     ./vendor/bin/mcbumpface
     git stash pop
     

3. CI/CD Pitfalls:

   • Avoid running mcbumpface in CI unless necessary (e.g., for dependency updates). Use sparingly to prevent unnecessary composer.json commits.

4. Version Parsing Issues:

   • Custom version formats (e.g., +build.metadata) may break parsing. Test thoroughly with edge cases.

Debugging

• Verbose Output: Use --verbose to debug parsing issues:

  ./vendor/bin/mcbumpface --verbose
  

• Log File: Redirect output to a log for troubleshooting:

  ./vendor/bin/mcbumpface > mcbumpface.log 2>&1
  

Configuration Quirks

1. stripVersionPrefixes:

   • Enabling this may break semantic versioning tools (e.g., semver) that expect v1.0.0. Use cautiously in projects relying on strict versioning.

2. keepVersionConstraintPrefix:

   • When enabled, ^1.0.0 → ^1.0.2 (instead of 1.0.2). Test compatibility with downstream dependencies.

3. Default Behavior:

   • Without config, mcbumpface preserves constraints (e.g., ^1.0.0 → ^1.0.2). Explicitly configure if you need stricter control.

Extension Points

1. Custom Version Rules: Override version parsing by extending the package’s VersionParser class (check src/VersionParser.php). Example:

   // app/Providers/McBumpfaceServiceProvider.php
   use Malukenho\McBumpface\VersionParser;
   class CustomVersionParser extends VersionParser {
       protected function parseVersion(string $version): string {
           // Custom logic here
           return parent::parseVersion($version);
       }
   }
   

   Bind the custom parser in the service provider.

2. Pre/Post-Bump Hooks: Use Laravel’s events to trigger actions before/after bumping:

   // app/Providers/EventServiceProvider.php
   protected $listen = [
       'mcbumpface.before-bump' => [YourListener::class],
       'mcbumpface.after-bump' => [YourLogger::class],
   ];
   

3. Git Integration: Extend the package to auto-commit changes by hooking into mcbumpface.after-bump:

   // app/Listeners/CommitBump.php
   public function handle() {
       shell_exec('git add composer.json && git commit -m "Bump packages"');
   }