Social Api Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require acts/social-api-bundle
   

   Register the bundle in config/app.php under providers:

   Camdram\SocialApiBundle\CamdramSocialApiBundle::class,
   

2. Configuration Publish the default config:

   php artisan vendor:publish --provider="Camdram\SocialApiBundle\CamdramSocialApiBundle" --tag=config
   

   Update config/social_api.php with your API credentials (e.g., facebook, twitter keys/tokens).

3. First Use Case: Fetching Twitter Data Inject the service into a controller or command:

   use Camdram\SocialApiBundle\Service\TwitterService;
   
   public function __construct(TwitterService $twitterService) {
       $this->twitterService = $twitterService;
   }
   

   Call a method (e.g., fetch user timeline):

   $tweets = $this->twitterService->getUserTimeline('username');
   

Implementation Patterns

Core Workflows

1. Service Integration

   • Use dependency injection for FacebookService/TwitterService in controllers, commands, or jobs.
   • Example: Fetch Facebook posts in a Laravel job:

     use Camdram\SocialApiBundle\Service\FacebookService;
     
     public function handle() {
         $posts = $this->facebookService->getPosts('page_id');
         // Process posts...
     }
     

2. OAuth Handling

   • Configure OAuth credentials in config/social_api.php:

     'facebook' => [
         'client_id' => env('FACEBOOK_CLIENT_ID'),
         'client_secret' => env('FACEBOOK_CLIENT_SECRET'),
         'redirect_uri' => env('FACEBOOK_REDIRECT_URI'),
     ],
     

   • Use built-in methods for OAuth flows (e.g., getAuthorizationUrl()).

3. Extending APIs

   • Create custom services by extending Camdram\SocialApiBundle\Service\AbstractService.
   • Example: Add a LinkedInService:

     class LinkedInService extends AbstractService {
         protected $baseUri = 'https://api.linkedin.com/v2/';
         // Custom methods...
     }
     

4. Rate Limiting & Caching

   • Cache responses with Laravel’s cache system:

     $cachedTweets = Cache::remember("twitter_{$username}_timeline", now()->addHours(1), function() use ($username) {
         return $this->twitterService->getUserTimeline($username);
     });
     

5. Error Handling

   • Wrap API calls in try-catch blocks:

     try {
         $data = $this->facebookService->getPost('post_id');
     } catch (\Camdram\SocialApiBundle\Exception\ApiException $e) {
         Log::error($e->getMessage());
         return response()->json(['error' => 'Failed to fetch data'], 500);
     }
     

Gotchas and Tips

Pitfalls

1. Deprecated/Archived Status

   • The package is archived (no active maintenance). Validate API endpoints/methods against the latest social API docs (e.g., Twitter API v2 vs. v1.1).
   • Example: Twitter’s getUserTimeline() may not support v2’s pagination. Use getUserTweets() instead if available.

2. OAuth Token Management

   • Tokens aren’t persisted by default. Store them in the database or cache:

     // Save token after OAuth flow
     $token = $this->facebookService->getAccessToken($code);
     User::find(auth()->id())->update(['facebook_token' => $token]);
     

3. Endpoint Changes

   • Social APIs frequently change endpoints. Override methods in custom services:

     public function getUserTimeline($screenName) {
         return $this->callApi('https://api.twitter.com/2/users/by/username/'.$screenName.'/tweets');
     }
     

4. Rate Limits

   • Social APIs enforce rate limits (e.g., Twitter: 900 requests/15 mins). Implement exponential backoff:

     try {
         $response = $this->callApi($endpoint);
     } catch (\Camdram\SocialApiBundle\Exception\RateLimitException $e) {
         sleep($e->getRetryAfter());
         return $this->callApi($endpoint);
     }
     

Tips

1. Logging

   • Log API responses for debugging:

     \Log::debug('Twitter API Response', ['data' => $tweets]);
     

2. Testing

   • Mock services in tests:

     $this->mock(TwitterService::class)->shouldReceive('getUserTimeline')
         ->once()->andReturn(['tweet' => 'test']);
     

3. Environment-Specific Config

   • Use .env for credentials:

     FACEBOOK_CLIENT_ID=your_id
     TWITTER_CONSUMER_KEY=your_key
     

4. Webhooks

   • For real-time updates (e.g., Twitter), use webhooks with Laravel’s HandleIncomingWebhook middleware.

5. Documentation Gaps

   • Refer to the original README and social API docs (e.g., Twitter API, Facebook Graph API).