Shariff Laravel Package

Technical Evaluation

Architecture Fit

• Privacy-First Social Sharing: Remains aligned with GDPR/CCPA compliance by avoiding third-party trackers. No architectural changes impact this.
• Decoupled Backend: Stateless design unchanged; still suitable for microservices or standalone API deployment.
• Service-Oriented: Modularity preserved, though StumbleUpon and Flattr services are now removed (see Key Questions for impact).
• Facebook API Update: Now uses Graph API v25.0, which may introduce breaking changes (e.g., deprecated fields, rate limits). Requires validation against your use case.

Integration Feasibility

• Laravel Compatibility:
  • PHP 8.2/8.3/8.4 Support: Aligns with Laravel 10/11. Drops PHP 7.4/8.0, which may require infrastructure updates if still in use.
  • Guzzle/HTTP Client: Unchanged; Laravel’s Http facade remains compatible.
  • Cache Integration: No changes to Laminas Cache or Laravel Cache facade compatibility.
• Service Removal:
  • StumbleUpon/Flattr: If your app relied on these, frontend/backend logic must be updated (see Operational Impact).
  • Facebook v25.0: May require adjustments to requested fields (e.g., /shares endpoint changes). Test thoroughly.

Technical Risk

• Facebook API v25.0:
  • Breaking Changes: New version may deprecate fields or alter rate limits. Validate your fields parameter in API calls (e.g., shares may require link.shares).
  • Migration Risk: If using custom fields, ensure compatibility with v25.0’s schema.
• Service Deprecation:
  • StumbleUpon/Flattr: Remove references in:
    • Laravel config (config/shariff.php).
    • Frontend templates (e.g., share buttons).
    • Database/analytics if storing historical data.
• PHP Version Drop:
  • Infrastructure Risk: If running PHP 7.4/8.0, upgrade to 8.2+ to avoid compatibility issues.
• Error Handling:
  • New Services: No additions, but validate existing services (e.g., Pinterest) for v25.0 compatibility.
  • Fallbacks: Ensure graceful degradation for Facebook API failures (e.g., cached data or user notifications).

Key Questions

1. Facebook API v25.0 Compatibility:
   • Are you using custom fields in /me/links or /shares endpoints? Verify against v25.0 docs.
   • Will rate limits change? Monitor usage post-upgrade.
2. Deprecated Services:
   • Did your app use StumbleUpon/Flattr? If so, replace with alternatives (e.g., Twitter/X or LinkedIn) or remove frontend/analytics references.
3. PHP Version:
   • Are you running PHP 7.4/8.0? Upgrade to 8.2+ to avoid integration failures.
4. Cache Invalidation:
   • With Facebook API changes, will cached responses become stale? Adjust TTLs or implement event-driven invalidation.
5. Frontend Impact:
   • Do share buttons or analytics depend on removed services? Update templates/configs (e.g., config/shariff.php):

     'services' => [
         'facebook' => true,
         'twitter'  => true,
         // 'stumbleupon' => false, // Explicitly disable
         // 'flattr'      => false,
     ],
     

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Service Provider/Facade: Unchanged. Wrap backend in ShariffService as before.
  • Cache: Continue using Laravel’s Cache facade (Redis/file). No changes required.
  • Queue: Offload heavy requests to shariff:fetch jobs (unchanged).
• Frontend:
  • Static JS: Shariff’s frontend library remains compatible. Update button configs to reflect removed services.
  • API Consumption: If using /api/shariff, validate responses for missing fields (e.g., stumbleupon).
  • Example config update:

    // Before (if using StumbleUpon)
    shariff.init({
      services: ['facebook', 'stumbleupon'],
    });
    // After
    shariff.init({
      services: ['facebook', 'twitter'], // Updated
    });
    

Migration Path

1. Phase 0: Pre-Upgrade Validation (New)

   • Step 1: Test Facebook API v25.0 compatibility.
     • Call /me/links?fields=shares and verify response structure.
     • Check rate limits with your expected traffic.
   • Step 2: Audit for StumbleUpon/Flattr usage.
     • Search codebase for stumbleupon/flattr (e.g., configs, templates, analytics).
     • Log historical data if storing share counts for these services.

2. Phase 1: Standalone API Update

   • Deploy v11.0.0 in isolation (e.g., /shariff directory).
   • Test endpoint: /shariff?url={encoded_url}.
   • Validate:
     • Facebook counts include correct fields (e.g., link.shares).
     • No errors for removed services (should return null or omit).

3. Phase 2: Laravel Integration

   • Update composer.json to heise/shariff:^11.0.
   • Run composer update.
   • Update config/shariff.php to disable removed services:

     'services' => [
         'facebook' => true,
         'twitter'  => true,
         // 'stumbleupon' => false,
         // 'flattr'      => false,
     ],
     

   • Reuse existing ShariffService wrapper (no changes needed).

4. Phase 3: Caching Layer

   • If using cached responses, invalidate old entries for:
     • Removed services (e.g., shariff_{url}_stumbleupon).
     • Facebook API changes (shorten TTL temporarily during testing).
   • Example invalidation:

     Cache::forget("shariff_{$url}_stumbleupon");
     Cache::forget("shariff_{$url}_flattr");
     

5. Phase 4: Frontend Sync

   • Update share buttons to match services config in shariff.init().
   • If using dynamic API calls, handle missing fields gracefully:

     fetch('/api/shariff?url=' + encodeURIComponent(url))
       .then(response => response.json())
       .then(data => {
         // Handle missing services
         if (!data.facebook) data.facebook = { shares: 0 };
         renderShareCounts(data);
       });
     

Compatibility

• PHP 8.2/8.3/8.4: Fully supported. Laravel 10/11 compatibility confirmed.
• Laravel Facades: Guzzle and Cache facades remain unchanged.
• Service Providers: No conflicts with Laravel’s container.
• Database: No persistence changes; cache-agnostic.
• Facebook API: Breaking: Validate fields parameter for v25.0. Example:

  // Old (may break in v25.0)
  $response = $facebook->get("/me/links?href={$url}&fields=shares");
  // New (if required)
  $response = $facebook->get("/me/links?href={$url}&fields=link.shares");
  

Sequencing

Operational Impact

Maintenance

• Configuration:
  • Update config/shariff.php to disable removed services.
  • Add notes for Facebook API version (v25.0) in config comments.
• Updates:
  • Facebook API: Monitor for v26.0+ changes (quarterly reviews).
  • PHP: Schedule infrastructure upgrade if using PHP <8.2.
• Logging:
  • Enhance error logging to capture Facebook API deprecation warnings:

    try {
        $counts = $shariff->get($url);
    } catch (\Exception $e) {
        Log::warning("Shariff API warning for {$url}: " . $e->getMessage());
        return $fallbackCounts;
    }
    

Support

• Error Handling:
  • Facebook API: Implement