Pusher Laravel Package

Technical Evaluation

Architecture Fit

• Use Case Alignment: The package is tailored for asynchronous push notifications (WebPush API) via Chrome/Mozilla, fitting well in architectures requiring background job processing (e.g., Laravel queues). However, its niche focus (WebPush only) limits broader applicability (e.g., SMS, email).
• Design Philosophy: The Push/Message/Handler abstraction aligns with strategy pattern and promise-based async workflows, which can integrate cleanly into Laravel’s job queues (e.g., Illuminate\Bus\Queueable). The Pusher service’s state management (pending → done) mirrors Laravel’s job lifecycle.
• Key Strengths:
  • Parallel requests via Guzzle 6 (unlike minishlink/web-push, which is synchronous by default).
  • Multi-provider support (GCM/Mozilla) with multi-key redundancy (useful for failover).
  • Recipient-level feedback (e.g., unsubscribing failed deliveries), which pairs well with Laravel’s event-driven systems (e.g., push.failed events).
• Key Weaknesses:
  • Archived/Unmaintained: No active development or security patches (risk of compatibility breaks with PHP/Laravel updates).
  • Limited Features: No built-in rate limiting, retries, or batch optimization (must be implemented manually).
  • Guzzle 6 Dependency: Laravel 9+ defaults to Guzzle 7+, requiring version pinning or wrapper logic.

Integration Feasibility

• Laravel Ecosystem Fit:
  • Jobs/Queues: Can wrap Push objects in Laravel jobs (e.g., SendPushJob) for async execution via queue:work.
  • Service Container: Handlers/API keys can be bound as Laravel services (e.g., app.bind(GCMHandler::class, fn() => new GCMHandler(config('services.gcm.key')))).
  • Events: Emit custom events (e.g., PushSent, PushFailed) to trigger downstream actions (e.g., analytics, retries).
• Database Considerations:
  • Push State Persistence: Requires a table to track Push states (e.g., id, status, recipients, created_at). Laravel’s migrations can scaffold this.
  • Recipient Management: Needs a subscriptions table (e.g., endpoint, provider, auth_key) to map to Recipient objects.
• Testing:
  • Mockable Design: Handlers can be mocked for unit tests (e.g., GCMHandler stubs).
  • Integration Tests: Require a staging WebPush provider (e.g., Firebase Test Lab) to validate delivery.

Technical Risk

• Deprecation Risk: Guzzle 6 is EOL (no security updates). Upgrading to Guzzle 7+ may break async features.
• Provider API Changes: GCM/Mozilla WebPush APIs evolve (e.g., Google’s deprecation of GCM). Handlers may need updates.
• Performance Overhead:
  • Parallel Requests: Guzzle 6’s async may not scale linearly due to connection limits (requires tuning concurrency).
  • Memory Usage: Large recipient lists could bloat PHP memory (test with memory_get_usage()).
• Error Handling:
  • Silent Failures: No built-in dead-letter queue for failed pushes (must implement manually).
  • Retry Logic: Missing exponential backoff for transient failures (e.g., network issues).

Key Questions

1. Why Not Alternatives?
   • Why not minishlink/web-push (actively maintained) or spatie/laravel-webpush (Laravel-specific)?
   • Does this package’s async/parallel design justify the maintenance risk?
2. Provider Strategy:
   • Are multiple API keys (e.g., GCM) a hard requirement, or is a single key sufficient?
   • Is Mozilla support critical, or is Chrome-only acceptable?
3. Scaling Needs:
   • What’s the expected throughput (e.g., 100 vs. 10,000 pushes/hour)? Parallelism may need tuning.
   • Will pushes be triggered by user actions (e.g., "send now") or batch-processed (e.g., nightly)?
4. Observability:
   • How will push success/failure rates be monitored? (e.g., Prometheus metrics, Laravel Horizon).
   • Are audit logs needed for compliance (e.g., GDPR unsubscribes)?
5. Forking Plan:
   • If adopting, will the team fork/maintain this repo, or use it as a reference for a custom implementation?

Integration Approach

Stack Fit

• Laravel Core:
  • Jobs: Wrap Push logic in Illuminate\Bus\Queueable jobs (e.g., SendWebPushJob).
  • Service Container: Register handlers as Laravel bindings (e.g., app.bind(HandlerInterface::class, GCMHandler::class)).
  • Events: Dispatch custom events (e.g., PushSent, PushFailed) using Laravel’s event system.
• Dependencies:
  • Guzzle 6: Pin to ^6.5 in composer.json (conflict with Laravel’s Guzzle 7+).
  • PHP 7.4+: Required for Guzzle 6 async features (Laravel 8+ compatible).
• Database:
  • Push Table:

    Schema::create('pushes', function (Blueprint $table) {
        $table->id();
        $table->string('status')->default('pending'); // pending, done, failed
        $table->json('recipients'); // Array of {endpoint, provider, handler}
        $table->json('metadata'); // Custom payload
        $table->timestamps();
    });
    

  • Subscriptions Table:

    Schema::create('push_subscriptions', function (Blueprint $table) {
        $table->id();
        $table->string('endpoint'); // User’s push endpoint
        $table->string('provider'); // 'gcm', 'mozilla'
        $table->string('auth_key');
        $table->foreignId('user_id')->constrained();
        $table->timestamps();
    });
    

Migration Path

1. Phase 1: Proof of Concept
   • Fork the repo and test basic push delivery (single recipient, single handler).
   • Validate async behavior with Laravel’s queue:work --daemon.
2. Phase 2: Core Integration
   • Implement Laravel job wrapper for Push objects.
   • Add database persistence for push states/recipients.
   • Integrate with Laravel events for observability.
3. Phase 3: Scaling & Resilience
   • Add rate limiting (e.g., GuzzleHttp\HandlerStack middleware).
   • Implement retry logic for failed pushes (e.g., Laravel\Queue\Failed\FailedJob).
   • Optimize parallelism (e.g., limit Guzzle concurrency to avoid throttling).

Compatibility

• Laravel Versions:
  • Compatible: Laravel 8+ (PHP 7.4+).
  • Workarounds: For Laravel 9+, use a Guzzle 7 wrapper or polyfill async logic.
• Provider APIs:
  • GCM: Deprecated; replace with Firebase Cloud Messaging (requires handler rewrite).
  • Mozilla: Monitor MDN WebPush updates.
• Async Stack:
  • Queue Drivers: Test with database, redis, and beanstalkd (avoid sync for production).
  • Horizon: Use Laravel Horizon for job monitoring and retry queues.

Sequencing

1. Setup Dependencies:
   • Composer: composer require guzzlehttp/guzzle:^6.5 bpolaszek/bentools-pusher.
   • PHP: Ensure ext-curl and ext-json are enabled.
2. Database Schema:
   • Migrate pushes and push_subscriptions tables.
3. Handler Configuration:
   • Configure API keys in .env (e.g., GCM_API_KEY=...).
   • Bind handlers in AppServiceProvider:

     public function register() {
         $this->app->bind(GCMHandler::class, fn() => new GCMHandler(config('services.gcm.key')));
     }
     

4. Job Implementation:
   • Create SendWebPushJob: