Update Lock Bundle Laravel Package

Getting Started

Install the package via Composer:

composer require vendor/package-name

Publish the package's configuration (if needed) and assets:

php artisan vendor:publish --provider="Vendor\PackageName\PackageServiceProvider"

First Use Case

Enable the package in config/app.php under providers:

Vendor\PackageName\PackageServiceProvider::class,

The package will now automatically intercept requests during Composer operations (install/update) and display a blocking "app updating" page with auto-refresh functionality. No additional setup is required for basic usage.

Implementation Patterns

Core Workflow

1. Automatic Detection: The package hooks into Composer's lifecycle events (via post-install-cmd/post-update-cmd) and blocks HTTP requests during package installation/updates.
2. Request Interception: Uses Laravel's middleware to detect ongoing Composer processes and redirect users to a dedicated "updating" page.
3. Auto-Refresh: The updating page includes JavaScript to auto-refresh every 2 seconds (configurable) until Composer completes.

Customization Points

• Refresh Interval: Modify the refresh_interval in the config file (default: 2000ms).
• Custom View: Override the default updating page by publishing the view and modifying resources/views/vendor/package-name/updating.blade.php.
• Excluded Routes: Whitelist specific routes (e.g., health checks) in config/package-name.php:

  'excluded_routes' => [
      'health-check',
  ],
  

Integration Tips

• CI/CD Pipelines: Disable the package in environments where Composer runs non-interactively (e.g., CI) by setting:

  PACKAGE_NAME_DISABLE=true
  

• Queue Workers: If using queues, ensure workers are stopped during updates to avoid race conditions.

Gotchas and Tips

Pitfalls

1. Middleware Order: Ensure the package's middleware (Vendor\PackageName\Http\Middleware\CheckForUpdates) is registered before other middleware that might handle 404s or errors.
2. Long-Running Processes: If Composer hangs, the updating page will continue refreshing indefinitely. Monitor Composer processes externally if needed.
3. Caching: Clear Laravel caches (php artisan cache:clear) if the package behaves unexpectedly after updates.

Debugging

• Log Output: Enable debug mode in config/package-name.php to log Composer process detection:

  'debug' => env('PACKAGE_NAME_DEBUG', false),
  

• Check Composer Status: Verify Composer is running by inspecting the composer.json lock file or process list:

  ps aux | grep composer
  

Extension Points

• Custom Logic: Extend the Vendor\PackageName\Services\UpdateDetector class to add pre/post-update hooks.
• Notifications: Integrate with Laravel Notifications to alert admins when updates occur:

  event(new \Vendor\PackageName\Events\UpdateStarted());
  

• Environment Restrictions: Restrict the package to specific environments (e.g., production) in the config:

  'enabled_envs' => ['production', 'staging'],
  

Config Quirks

• Default Values: The package uses sensible defaults (e.g., auto-detects Composer processes via composer.json locks). Override only if necessary.
• Middleware Priority: If the package fails to block requests, manually reorder middleware in app/Http/Kernel.php:

  protected $middlewareGroups = [
      'web' => [
          \Vendor\PackageName\Http\Middleware\CheckForUpdates::class,
          // ... other middleware
      ],
  ];