Virtual Identity Laravel Package

Getting Started

First Steps

1. Installation

   composer require beecms/virtual-identity
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="BeeCMS\VirtualIdentity\VirtualIdentityServiceProvider" --tag="config"
   

2. Configuration

   • Review config/virtual-identity.php for API keys (YouTube, Facebook, Twitter, Instagram).
   • Ensure keys are set in your .env (e.g., YOUTUBE_API_KEY, FACEBOOK_APP_ID).

3. Basic Usage

   • Fetch a user’s social data (e.g., YouTube):

     use BeeCMS\VirtualIdentity\Facades\VirtualIdentity;
     
     $youtubeData = VirtualIdentity::get('youtube', 'channel-id');
     dd($youtubeData);
     

First Use Case

• Aggregate a user’s social profiles into a single Laravel model. Example:

  $user = User::find(1);
  $user->youtube = VirtualIdentity::get('youtube', $user->youtube_id);
  $user->facebook = VirtualIdentity::get('facebook', $user->facebook_id);
  $user->save();
  

Implementation Patterns

Common Workflows

1. Fetching Social Data

   • Use the facade for simplicity:

     $data = VirtualIdentity::get('twitter', 'user-handle');
     

   • Or inject the service:

     public function __construct(private VirtualIdentityService $virtualIdentity) {}
     
     $this->virtualIdentity->get('instagram', 'profile-id');
     

2. Storing Data

   • Normalize responses into a Laravel model (e.g., SocialProfile):

     $profile = new SocialProfile();
     $profile->platform = 'youtube';
     $profile->data = VirtualIdentity::get('youtube', $channelId);
     $profile->save();
     

3. Caching Responses

   • Cache API responses to reduce calls (e.g., using Laravel’s cache):

     $data = Cache::remember("social_{$platform}_{$id}", now()->addHours(1), function () use ($platform, $id) {
         return VirtualIdentity::get($platform, $id);
     });
     

4. Error Handling

   • Wrap calls in try-catch:

     try {
         $data = VirtualIdentity::get('facebook', 'invalid-id');
     } catch (\Exception $e) {
         Log::error("Failed to fetch Facebook data: " . $e->getMessage());
         return response()->json(['error' => 'Social data unavailable'], 500);
     }
     

Integration Tips

• Laravel Scout: Index social data for search (e.g., YouTube video titles).
• Notifications: Trigger updates when social data changes (e.g., new Instagram posts).
• API Rate Limiting: Respect platform limits (e.g., Twitter’s 15 requests/15-minute window).
• Queue Jobs: Offload heavy API calls to queues:

  FetchSocialDataJob::dispatch('twitter', 'user-handle');
  

Gotchas and Tips

Pitfalls

1. API Key Restrictions

   • Some platforms (e.g., YouTube) require OAuth 2.0 for certain endpoints. The package may not support these out of the box.
   • Fix: Use platform-specific SDKs (e.g., google/apiclient) for advanced features.

2. Rate Limits

   • Free-tier APIs (e.g., Twitter) throttle requests. Implement exponential backoff:

     try {
         $data = VirtualIdentity::get('twitter', $id);
     } catch (\BeeCMS\VirtualIdentity\Exceptions\RateLimitExceeded $e) {
         sleep($e->getRetryAfter());
         retry();
     }
     

3. Data Format Inconsistencies

   • Responses vary by platform (e.g., YouTube returns snippet, Facebook returns from). Normalize before storing:

     $normalized = collect($data)->only(['id', 'name', 'url', 'created_at']);
     

4. Deprecated Endpoints

   • Platforms change APIs frequently (e.g., Facebook’s Graph API v2.0+). Test thoroughly and monitor for breaking changes.

Debugging

• Enable Logging Add to config/virtual-identity.php:

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

  Logs will appear in storage/logs/laravel.log.

• Inspect Raw Responses Temporarily modify the service to dump raw data:

  // In VirtualIdentityService.php
  $response = $this->http->get($url);
  \Log::debug('Raw response:', [$response->body()]);
  

Extension Points

1. Add New Platforms

   • Extend the VirtualIdentityService to support unsupported platforms (e.g., TikTok):

     // In a custom service
     public function get($platform, $id)
     {
         if ($platform === 'tiktok') {
             return $this->fetchTikTokData($id);
         }
         return parent::get($platform, $id);
     }
     

2. Custom Data Mappers

   • Override response parsing for specific needs:

     VirtualIdentity::extend('youtube', function ($data) {
         return collect($data)->merge(['views' => $data['statistics']['viewCount']]);
     });
     

3. Webhooks for Real-Time Updates

   • Use platform webhooks (e.g., Instagram’s Subscription API) to push updates instead of polling.

Config Quirks

• Environment Variables Ensure keys are prefixed correctly in .env:

  YOUTUBE_API_KEY=your_key
  FACEBOOK_APP_ID=your_app_id
  TWITTER_BEARER_TOKEN=your_token
  

• Default Platforms The package may not support all fields for every platform. Check the source for limitations.

Pro Tips

• Use Laravel Mixins to attach social data to Eloquent models:

  use BeeCMS\VirtualIdentity\Facades\VirtualIdentity;
  
  User::macro('fetchSocialData', function () {
      $this->youtube = VirtualIdentity::get('youtube', $this->youtube_id);
      $this->facebook = VirtualIdentity::get('facebook', $this->facebook_id);
      return $this;
  });
  

• Leverage Laravel Nova for a UI to manage social profiles.
• Test with Mock APIs (e.g., Mockoon) before relying on live endpoints.