App Lock Composer Plugin Laravel Package

Getting Started

Minimal Setup

1. Installation Add the plugin to your project’s composer.json under config.extra.plugins:

   {
       "config": {
           "extra": {
               "plugins": {
                   "ebitkov/app-lock-composer-plugin": {
                       "enabled": true
                   }
               }
           }
       }
   }
   

   Then run:

   composer require ebitkov/app-lock-composer-plugin --dev
   

2. First Use Case After installation, the plugin will automatically:

   • Create a .composer/app-lock file when running composer update or composer install.
   • Prevent manual edits to composer.lock unless the .composer/app-lock file is removed.

   Verify it works:

   composer update
   # Check if `.composer/app-lock` exists
   ls -la .composer/
   

Implementation Patterns

Workflow Integration

1. Team Collaboration

   • Use .composer/app-lock as a team agreement to avoid accidental composer.lock modifications.
   • Add .composer/app-lock to .gitignore if you want to enforce lock consistency only locally.

2. CI/CD Pipelines

   • Enforce Lock Stability: Add a pre-commit or pre-push hook to check for .composer/app-lock presence before allowing composer.lock changes.

     # Example Git hook (pre-commit)
     if [ -f ".composer/app-lock" ] && ! git diff --name-only HEAD | grep -q "composer.lock"; then
         echo "✅ Lockfile unchanged or intentionally updated."
     else
         echo "❌ composer.lock modified without app-lock. Aborting."
         exit 1
     fi
     

   • CI Check: Fail builds if composer.lock is modified without .composer/app-lock:

     if [ -f ".composer/app-lock" ] && ! git diff --name-only origin/main composer.lock > /dev/null; then
         echo "::error::composer.lock was modified without app-lock. Remove .composer/app-lock to allow changes."
         exit 1
     fi
     

3. Local Development

   • Temporarily Disable Lock: Remove .composer/app-lock to allow composer.lock edits (e.g., for dependency tweaks):

     rm .composer/app-lock
     composer update package-name
     # Re-enable later
     touch .composer/app-lock
     

4. Custom Scripts

   • Automate Lock Management: Add a script to package.json or composer.json to toggle the lock:

     {
         "scripts": {
             "lock:allow": "rm -f .composer/app-lock",
             "lock:enforce": "touch .composer/app-lock"
         }
     }
     

Gotchas and Tips

Pitfalls

1. False Positives

   • The plugin only prevents composer.lock modifications when .composer/app-lock exists.
   • Gotcha: If you delete .composer/app-lock and then run composer update, the plugin won’t block future composer.lock changes unless you recreate the file.
   • Fix: Re-add .composer/app-lock after intentional updates to re-enforce protection.

2. Merge Conflicts

   • If .composer/app-lock is committed to version control, merging branches may cause conflicts.
   • Tip: Exclude it from Git (add to .gitignore) and regenerate it locally as needed.

3. Composer Version Compatibility

   • Updated: The plugin now supports older Composer versions (downgraded requirements in v1.0.1) to avoid conflicts with some applications.
   • Test: Verify compatibility by running:

     composer update --dry-run
     

   • Note: While the plugin now works with older versions, ensure your project’s Composer version aligns with your team’s workflow (e.g., avoid mixing v1 and v2 behaviors).

4. Overriding Default Behavior

   • The plugin does not block composer install or composer update—it only prevents manual composer.lock edits.
   • Misconception: Some may expect it to lock the app entirely (like a deployment lock). Clarify this with your team.

Debugging

1. Plugin Not Triggering

   • Ensure the plugin is enabled in composer.json:

     "extra": {
         "plugins": {
             "ebitkov/app-lock-composer-plugin": { "enabled": true }
         }
     }
     

   • Debug: Run with -vvv to see plugin logs:

     composer update -vvv
     

2. Permission Issues

   • If .composer/app-lock can’t be created, check directory permissions:

     mkdir -p .composer && chmod -R 777 .composer
     

3. Composer Version Conflicts

   • If you encounter issues after updating, pin the plugin version to avoid unintended upgrades:

     composer require ebitkov/app-lock-composer-plugin:^1.0.1 --dev
     

Extension Points

1. Custom Lock Files

   • The plugin uses .composer/app-lock by default. To change the filename:
     • Fork the plugin and modify src/AppLockPlugin.php (line ~30).
     • Override the getLockFilePath() method.

2. Integrate with Other Tools

   • Git Hooks: Combine with pre-commit tools like Husky or pre-commit to enforce lock rules.
   • Laravel Artisan: Create a custom command to toggle the lock:

     // app/Console/Commands/ToggleAppLock.php
     public function handle() {
         $lockFile = base_path('.composer/app-lock');
         if (file_exists($lockFile)) {
             unlink($lockFile);
             $this->info('App lock removed. composer.lock can now be modified.');
         } else {
             file_put_contents($lockFile, '');
             $this->info('App lock enforced. composer.lock changes will be blocked.');
         }
     }
     

3. Visual Feedback

   • Add a .gitattributes rule to highlight the lock file:

     .composer/app-lock diff=composerlock
     

   • Create a custom diff driver in .git/config for better visibility in Git clients.