Google Business Client Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require comsa/google-business-client-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       Comsa\GoogleBusinessClientBundle\ComsaGoogleBusinessClientBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console config:dump-reference Comsa\GoogleBusinessClientBundle\Configuration
   

   Update .env with your Google API credentials:

   GOOGLE_BUSINESS_API_KEY=your_api_key
   GOOGLE_BUSINESS_CLIENT_ID=your_client_id
   GOOGLE_BUSINESS_CLIENT_SECRET=your_client_secret
   GOOGLE_BUSINESS_REDIRECT_URI=your_redirect_uri
   

3. First Use Case: Fetching Business Profile Inject the client into a service/controller:

   use Comsa\GoogleBusinessClientBundle\Service\GoogleBusinessClient;
   
   class BusinessController extends Controller
   {
       public function __construct(private GoogleBusinessClient $client) {}
   
       public function showProfile()
       {
           $businessAccountId = 'your_business_account_id';
           $profile = $this->client->getBusinessProfile($businessAccountId);
           return response()->json($profile);
       }
   }
   

Implementation Patterns

Common Workflows

1. Authentication Flow

   • Use the OAuth2 service for user authentication:

     $authUrl = $this->client->getAuthUrl();
     // Redirect user to $authUrl
     

   • Handle callback:

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

2. CRUD Operations

   • Create/Update Locations:

     $location = [
         'name' => 'Main Store',
         'address' => '123 Main St',
         'phoneNumber' => '+1234567890',
     ];
     $this->client->createLocation($businessAccountId, $location);
     

   • Fetch/Update Profiles:

     $profile = $this->client->getBusinessProfile($businessAccountId);
     $this->client->updateBusinessProfile($businessAccountId, ['hours' => [...]]);
     

3. Event-Driven Updates

   • Subscribe to webhooks for real-time updates:

     $this->client->subscribeToWebhook($businessAccountId, $webhookUrl, ['LOCATION_UPDATED']);
     

Integration Tips

• Laravel Events: Dispatch custom events for business profile changes:

  event(new BusinessProfileUpdated($businessAccountId, $profile));
  

• Queue Jobs: Offload heavy operations (e.g., bulk location updates) to queues:

  UpdateLocationsJob::dispatch($businessAccountId, $locations)->onQueue('google-business');
  

• API Rate Limiting: Implement middleware to handle Google API rate limits:

  $response = $this->client->withRetry()->getBusinessProfile($businessAccountId);
  

Gotchas and Tips

Pitfalls

1. Token Expiry

   • Google OAuth tokens expire. Use the refreshToken() method or implement a token refresh listener:

     $this->client->setRefreshToken($refreshToken);
     $this->client->refreshToken();
     

   • Tip: Store refresh tokens securely (e.g., Laravel Sanctum or database).

2. Business Account ID Mismatch

   • Ensure $businessAccountId matches the Google Business Profile ID. Verify via:

     $this->client->listBusinessAccounts();
     

3. API Quotas

   • Monitor usage via Google Cloud Console.
   • Tip: Implement exponential backoff for retries:

     $this->client->withRetry(3, 1000)->createLocation($businessAccountId, $location);
     

Debugging

• Enable Debug Mode:

  $this->client->setDebug(true); // Logs requests/responses to storage/logs/google_business.log
  

• Validate Payloads: Use Google’s API reference to validate request/response structures.

Extension Points

1. Custom Services Extend the base client for domain-specific logic:

   class CustomBusinessClient extends GoogleBusinessClient
   {
       public function syncInventory($businessAccountId, array $items)
       {
           // Custom logic
       }
   }
   

2. Event Listeners Listen for Google Business events (e.g., BusinessProfileUpdated):

   public function handle(BusinessProfileUpdated $event)
   {
       // Sync with CRM, update UI, etc.
   }
   

3. Configuration Overrides Override default config in config/packages/comsa_google_business_client.php:

   return [
       'api_version' => 'v1',
       'default_business_account' => '123456789',
   ];
   

Pro Tips

• Batch Operations: Use batchCreateLocations() for bulk updates.
• Webhook Validation: Verify webhook payloads with Google’s signature:

  $this->client->validateWebhook($request, $secret);
  

• Local Testing: Use the Google Business API emulator for local development.