Google Api Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require beyerz/google-api-bundle
   

   Add the bundle to config/bundles.php:

   return [
       Beyerz\GoogleApiBundle\BeyerzGoogleApiBundle::class => ['all' => true],
   ];
   

2. Configuration Place your client_secret.json in config/packages/beyerz_google_api/client_secret.json (or adjust path in config). Configure config/packages/beyerz_google_api.yaml:

   beyerz_google_api:
       application_name: 'MyApp'
       client_secret_path: '%kernel.project_dir%/config/packages/beyerz_google_api/client_secret.json'
       scopes:
           - 'https://www.googleapis.com/auth/userinfo.email'
   

3. First Use Case Inject the GoogleApiService in a controller/service:

   use Beyerz\GoogleApiBundle\Service\GoogleApiService;
   
   class MyController extends AbstractController {
       public function __construct(private GoogleApiService $googleApi) {}
   
       public function index() {
           $userInfo = $this->googleApi->getUserInfo();
           return $this->json($userInfo);
       }
   }
   

Implementation Patterns

Common Workflows

1. OAuth Flow Redirect users to Google OAuth:

   $authUrl = $this->googleApi->getAuthorizationUrl();
   return $this->redirect($authUrl);
   

   Handle callback:

   $token = $this->googleApi->handleAuthCallback($request);
   $this->googleApi->setAccessToken($token);
   

2. API Calls Use the service to interact with Google APIs:

   // Gmail example
   $messages = $this->googleApi->getGmailService()->users_messages->listUsersMessages('me');
   
   // People API example
   $contacts = $this->googleApi->getPeopleService()->people->connections->listConnections('people/me');
   

3. Service Management Access specific Google services:

   $driveService = $this->googleApi->getDriveService();
   $files = $driveService->files->listFiles();
   

4. Token Refresh Automatically handle token refresh:

   try {
       $data = $this->googleApi->getUserInfo();
   } catch (Exception $e) {
       $this->googleApi->refreshAccessToken();
       $data = $this->googleApi->getUserInfo();
   }
   

Integration Tips

• Dependency Injection Prefer constructor injection for GoogleApiService to ensure proper lifecycle management.

• Configuration Overrides Override bundle config per environment (e.g., config/packages/dev/beyerz_google_api.yaml).

• Event Listeners Listen for token refresh events:

  $eventDispatcher->addListener(
      GoogleApiEvents::TOKEN_REFRESHED,
      function (TokenRefreshedEvent $event) {
          // Log or store the new token
      }
  );
  

• Custom Services Extend the bundle’s GoogleApiService for project-specific logic:

  class CustomGoogleApiService extends GoogleApiService {
      public function customMethod() {
          // Custom logic
      }
  }
  

Gotchas and Tips

Pitfalls

1. Token Storage

   • The bundle does not persist tokens by default. Implement a custom CredentialsManager or use Symfony’s security.token_storage for session-based storage.
   • Example for session storage:

     beyerz_google_api:
         credentials_manager: 'Beyerz\GoogleApiBundle\Manager\SessionCredentialsManager'
     

2. Scope Management

   • Scopes are not dynamically validated. Ensure your scopes config includes all required permissions for your use case.
   • Missing scopes will throw Google_Auth_Exception.

3. Service Initialization

   • Google services (e.g., Gmail, Drive) are lazy-loaded. Accessing them before authentication will fail.
   • Always check $this->googleApi->isAuthorized() before making API calls.

4. Deprecated PHP Version

   • The bundle supports PHP 5.6+, but modern Symfony (5.4+) requires PHP 7.4+. Test thoroughly if using older PHP.

Debugging Tips

• Enable Debug Logging Add to config/packages/monolog.yaml:

  handlers:
      google_api:
          type: stream
          path: "%kernel.logs_dir%/%kernel.environment%.google_api.log"
          level: debug
  

• Check Token Validity Use the isAccessTokenExpired() method to debug token issues:

  if ($this->googleApi->isAccessTokenExpired()) {
      $this->googleApi->refreshAccessToken();
  }
  

• Common Exceptions

  • Google_Service_Exception: API-specific errors (check response details).
  • Google_Auth_Exception: Token/auth issues (validate scopes and credentials).

Extension Points

1. Custom Credentials Manager Extend CredentialsManager to integrate with your auth system:

   class MyCredentialsManager extends CredentialsManager {
       public function getAccessToken() {
           // Fetch from your storage (DB, cache, etc.)
       }
   }
   

2. Add New Google Services Register additional services in services.yaml:

   services:
       Beyerz\GoogleApiBundle\Service\GoogleApiService:
           arguments:
               $services: ['Gmail', 'Drive', 'People']  # Add your service names
   

3. Override Service Factories Replace the default service factory for custom behavior:

   $factory = new CustomGoogleServiceFactory($client);
   $this->googleApi->setServiceFactory($factory);
   

4. Event-Driven Extensions Listen for bundle events to extend functionality:

   $eventDispatcher->addListener(
       GoogleApiEvents::SERVICE_INITIALIZED,
       function (ServiceInitializedEvent $event) {
           $event->getService()->setUseBatch(true); // Example: Enable batch mode
       }
   );
   

Configuration Quirks

• Client Secret Path Use absolute paths or Symfony’s %kernel.project_dir% placeholder for portability.

• Scopes Duplication The README includes duplicate scopes (e.g., plus.login appears twice). Clean up your config to avoid unnecessary requests.

• Service Caching Google services are instantiated once per request. Clear caches if modifying the bundle’s service configuration dynamically.