Yahoo Api Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require agupta/yahoo-api-bundle:dev-master
   

   Register the bundle in app/AppKernel.php:

   new Yahoo\ApiBundle\YahooApiBundle(),
   

2. Configuration: Add to config.yml:

   yahoo_api:
       application_id: 'YOUR_APP_ID'
       consumer_key: 'YOUR_CONSUMER_KEY'
       consumer_secret: 'YOUR_CONSUMER_SECRET'
       callback_url: 'https://yourdomain.com/callback'
   

3. Routing: Import routes in routing.yml:

   yahoo_api:
       resource: "@YahooApiBundle/Resources/config/routing.yml"
       prefix: /
   

4. First Use Case: Redirect users to /yahoo_authorization to initiate OAuth2 flow. After Yahoo redirects back to your callback_url with a code, fetch contacts in your controller:

   $contacts = $this->get('AG.Yahoo.OAuth2.Service')->getContacts($request->get('code'));
   

Implementation Patterns

Workflow Integration

1. OAuth2 Flow:

   • Use /yahoo_authorization as a login/connect endpoint (e.g., for user onboarding).
   • Store the returned code securely (e.g., in session or database) for later use.

2. Service Layer: Inject AG.Yahoo.OAuth2.Service into controllers/services:

   $service = $this->get('AG.Yahoo.OAuth2.Service');
   $contacts = $service->getContacts($code);
   

   Process contacts (e.g., map to your user model):

   foreach ($contacts as $contact) {
       $this->userRepository->upsertFromYahoo($contact);
   }
   

3. Error Handling: Wrap API calls in try-catch blocks:

   try {
       $contacts = $service->getContacts($code);
   } catch (\Exception $e) {
       $this->addFlash('error', 'Failed to fetch Yahoo contacts: ' . $e->getMessage());
       return $this->redirect($this->generateUrl('home'));
   }
   

4. Refresh Tokens: If the bundle supports token refresh (unclear from docs), implement a refreshToken() method in your service layer.

Gotchas and Tips

Pitfalls

1. Deprecated API: Yahoo’s OAuth2 API is outdated (last updated in 2014). Expect rate limits, unstable endpoints, or broken functionality. Test thoroughly.

2. No Token Storage: The bundle doesn’t persist OAuth tokens. Implement a TokenRepository to store access_token and refresh_token (if available) in your database or cache.

3. Callback URL Mismatch: Ensure callback_url in config.yml matches Yahoo’s registered redirect URI. Mismatches will fail silently or return errors.

4. No Pagination: getContacts() may return limited results. Check Yahoo’s API docs for pagination parameters (e.g., start_index, count) and extend the service if needed.

Debugging

1. Enable Debugging: Add debug: true to your yahoo_api config to log OAuth2 requests/responses:

   yahoo_api:
       debug: true
   

2. Inspect Raw Responses: Override the service to log raw API responses:

   $service = $this->get('AG.Yahoo.OAuth2.Service');
   $response = $service->getContacts($code);
   file_put_contents('debug.log', print_r($response, true), FILE_APPEND);
   

3. Common Errors:

   • invalid_request: Missing or malformed code or callback_url.
   • unauthorized_client: Incorrect consumer_key/consumer_secret.
   • server_error: Yahoo API downtime or rate limiting.

Extension Points

1. Custom API Endpoints: Extend the service to call other Yahoo APIs (e.g., calendar, mail) by adding methods to YahooApiBundle\Service\OAuth2Service:

   public function getCalendarEvents($code) {
       $token = $this->getAccessToken($code);
       return $this->httpClient->get('https://social.yahooapis.com/v1/user/calendar/events', [
           'headers' => ['Authorization' => 'Bearer ' . $token]
       ]);
   }
   

2. User Model Mapping: Create a mapper to transform Yahoo contacts into your user model:

   $yahooContact = $contacts[0];
   $user = (new User())
       ->setName($yahooContact['givenName'] . ' ' . $yahooContact['familyName'])
       ->setEmail($yahooContact['emails'][0]['handle']);
   

3. Webhook for Token Refresh: If tokens expire, implement a webhook to refresh them silently (e.g., via Laravel’s scheduler):

   $service->refreshToken($storedRefreshToken);