Change Detector Laravel Package

Technical Evaluation

Architecture Fit

• Use Case Alignment:
  • Cache Invalidation: Ideal for Laravel’s config_cache, route_cache, and opcache by detecting changes in config/, routes/, or app/ directories.
  • CI/CD Optimization: Reduces unnecessary rebuilds by triggering only when relevant files (e.g., composer.json, package.json) change.
  • Dynamic Configuration: Enables runtime checks for constants, environment variables, or feature flags without manual version tracking.
  • Dependency Validation: Detects PHP version/extension mismatches or Composer dependency changes pre-deploy.
• Laravel Synergy:
  • Integrates with Laravel’s event system (e.g., filesystem.updated, composer.installed) and service container.
  • Complements Laravel Forge/Envoyer for deployment hooks (e.g., validating PHP versions post-deploy).
  • Works with Laravel Mix/Vite for asset regeneration triggers.
• Limitations:
  • No built-in database schema change detection (requires custom logic or integration with Laravel Migrations).
  • No real-time filesystem watching (relies on explicit checks or cron jobs; use ReactPHP or Symfony EventDispatcher for real-time needs).
  • No Laravel-specific cache directory awareness (e.g., bootstrap/cache)—requires custom configuration.

Integration Feasibility

• Low-Coupling Design:
  • Service Provider Integration: Register detectors as singletons in Laravel’s container.
  • Facade Pattern: Create a ChangeDetector facade for clean syntax (e.g., ChangeDetector::hasChanged()).
  • Event Listeners: Bind detectors to Laravel events (e.g., Composer\ScriptHandler events or Illuminate\Filesystem\Events).
• PHP 8.1+ Compatibility:
  • Aligns with Laravel 10+/11+ requirements; minimal risk for PHP 8.0 with polyfills.
• Testing Readiness:
  • Psalm/Infection Coverage: Indicates strong type safety and edge-case handling.
  • Mutation Testing: Stryker results suggest resilience to regressions.
  • Lack of Laravel-Specific Tests: May require custom test suites for integration scenarios.

Technical Risk

Key Questions

1. Detection Scope:
   • Should changes be detected at the file level (e.g., config/app.php) or directory level (e.g., config/)? How does this affect cache invalidation granularity?
2. Trigger Mechanism:
   • Will changes be polled (cron) or event-driven (e.g., Laravel’s filesystem events or Composer\ScriptHandler)?
3. False Positive Handling:
   • How will we filter out noise (e.g., vendor/, node_modules/, or log files)? Use ignore() or regex-based exclusions?
4. Deployment Hooks:
   • Should this integrate with Envoyer/Forge for automated rollback triggers (e.g., PHP version mismatches)?
5. Custom Detectors:
   • Are Laravel-specific detectors needed (e.g., DatabaseSchemaDetector, EnvDetector, or CacheDirectoryDetector)?
6. Caching Strategy:
   • How will detector results be cached (e.g., Redis TTL, file-based caching) to avoid redundant checks?
7. Error Handling:
   • How will failures (e.g., unreadable files, permission issues) be logged and alerted (e.g., Sentry, Laravel Notifications)?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Cache Invalidation: Replace manual cache:clear with automated triggers (e.g., FileChangeDetector for bootstrap/cache).
  • Asset Pipelines: Hook into mix-manifest.json or vite-manifest.json changes to restart queues or rebuild assets.
  • Dependency Management: Use ComposerPackageChangeDetector to validate PHP/extension versions pre-deploy.
  • Dynamic Config: Detect changes in config/ or .env to reload services (e.g., config('app.debug')).
• Third-Party Tools:
  • Envoyer: Add a change-detector script to post-deploy hooks for validation.
  • Laravel Telescope: Log change events for debugging and auditing.
  • Laravel Horizon: Trigger queue flushes on config changes (e.g., config('queue.connections')).
  • GitHub Actions/GitLab CI: Use detectors to skip steps if no relevant changes are detected.

Migration Path

1. Phase 1: Proof of Concept (1–2 Days)
   • Install the package and test basic detectors:

     composer require typhoon/change-detector
     

   • Validate FileChangeDetector for critical files (e.g., routes/web.php, config/app.php).
   • Compare results with manual filemtime() checks.
2. Phase 2: Event-Driven Integration (3–5 Days)
   • Bind detectors to Laravel events:

     // app/Providers/ChangeDetectorServiceProvider.php
     public function boot(): void
     {
         event(new FilesystemUpdated('config/app.php'));
         // Or use Composer events:
         Composer::scriptEvent('post-update-cmd', function () {
             ChangeDetector::detect('composer-lock');
         });
     }
     

   • Create a ChangeDetector facade for clean syntax:

     // app/Facades/ChangeDetector.php
     public static function hasChanged(string $path): bool { ... }
     

3. Phase 3: CI/CD Integration (2–3 Days)
   • Add detectors to GitHub Actions/GitLab CI for pre-deploy validation:

     # .github/workflows/deploy.yml
     - name: Validate PHP Version
       run: php artisan change:detect --check=php-version
     

   • Integrate with Envoyer/Forge for post-deploy hooks:

     # post-deploy.sh
     php artisan change:detect --check=config,routes --cache=redis
     

4. Phase 4: Monitoring and Optimization (Ongoing)
   • Log detected changes to Telescope/Sentry.
   • Cache results in Redis to reduce I/O:

     Cache::remember('file_mtime:config/app.php', now()->addHours(1), fn() => filemtime('config/app.php'));
     

   • Benchmark performance with large file counts (e.g., 10K+ files).

Compatibility