Google Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require antimattr/google-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       Antimattr\GoogleBundle\AntimattrGoogleBundle::class => ['all' => true],
   ];
   

2. Configuration Define your Google API credentials in config/packages/antimattr_google.yaml:

   antimattr_google:
       client_id: '%env(GOOGLE_CLIENT_ID)%'
       client_secret: '%env(GOOGLE_CLIENT_SECRET)%'
       redirect_uri: '%env(GOOGLE_REDIRECT_URI)%'
       api_key: '%env(GOOGLE_API_KEY)%'
   

3. First Use Case: OAuth Login Add the login route to your routes.yaml:

   antimattr_google_login:
       path: /login/google
       controller: Antimattr\GoogleBundle\Controller\AuthController::login
   

   Use the AuthService in a controller:

   use Antimattr\GoogleBundle\Service\AuthService;
   
   public function login(AuthService $authService)
   {
       return $authService->getLoginUrl();
   }
   

Implementation Patterns

OAuth Workflow

1. Initiate Login Redirect users to Google OAuth:

   $loginUrl = $authService->getLoginUrl(['email', 'profile']);
   return new RedirectResponse($loginUrl);
   

2. Handle Callback Process the OAuth response:

   public function callback(AuthService $authService, Request $request)
   {
       $user = $authService->handleCallback($request);
       // Store user data in session or DB
   }
   

3. User Data Retrieval Fetch user details after login:

   $userData = $authService->getUserData();
   

API Integration

1. Service Initialization Inject the GoogleApiService:

   use Antimattr\GoogleBundle\Service\GoogleApiService;
   
   public function __construct(GoogleApiService $googleApi)
   {
       $this->googleApi = $googleApi;
   }
   

2. Make API Requests Example: Fetch Calendar Events:

   $events = $this->googleApi->call('calendar.events.list', [
       'calendarId' => 'primary',
       'timeMin' => (new \DateTime())->format('c'),
   ]);
   

3. Handle Responses Parse JSON responses:

   $response = $this->googleApi->call('drive.files.list');
   $files = json_decode($response->getBody(), true);
   

Event Listeners

1. Extend Default Behavior Subscribe to events (e.g., google.auth.success):

   // src/EventListener/GoogleAuthListener.php
   public function onAuthSuccess(AuthSuccessEvent $event)
   {
       // Custom logic (e.g., sync user to local DB)
   }
   

2. Register Listener In services.yaml:

   services:
       App\EventListener\GoogleAuthListener:
           tags:
               - { name: kernel.event_listener, event: google.auth.success, method: onAuthSuccess }
   

Gotchas and Tips

Common Pitfalls

1. Redirect URI Mismatch

   • Ensure redirect_uri in config matches Google Cloud Console settings.
   • Debug: Check antimattr_google.error logs for URI validation errors.

2. Scopes Not Requested

   • Explicitly define required scopes (e.g., ['email', 'profile']) in getLoginUrl().
   • Missing scopes cause partial user data or failures.

3. API Key Restrictions

   • Restrict API keys in Google Cloud Console to your app’s domain/IP.
   • Use environment variables for sensitive keys (never hardcode).

4. Token Expiry

   • Refresh tokens automatically using AuthService::refreshToken().
   • Cache tokens in the session or database with expiry handling.

Debugging Tips

1. Enable Verbose Logging Set in config/packages/antimattr_google.yaml:

   debug: true
   

2. Inspect Raw Responses Use GoogleApiService::call() with debug: true:

   $response = $this->googleApi->call('oauth2/v2/userinfo', [], true);
   

3. Test Locally Use Google’s OAuth Playground to validate scopes/endpoints.

Extension Points

1. Custom User Provider Implement Antimattr\GoogleBundle\User\UserProviderInterface to map Google data to your user model:

   public function loadUserFromGoogleData(array $data): UserInterface
   {
       return new User($data['email'], $data['sub']);
   }
   

2. Override Services Extend GoogleApiService or AuthService via dependency injection:

   services:
       App\Service\CustomGoogleApi:
           decorates: 'antimattr_google.api'
           arguments: ['@App\Service\CustomGoogleApi.inner']
   

3. Add New API Clients Extend Antimattr\GoogleBundle\Client\ClientFactory to support non-OAuth APIs (e.g., Maps, Vision):

   public function createCustomClient(string $service)
   {
       return new \Google_Client([
           'key' => $this->config['api_key'],
           'service' => $service,
       ]);
   }