Google Bundle Laravel Package

Getting Started

• Install the v3 release with Composer and confirm the new doctrine/cache dependency is present. This is a major-version release, so treat any 2.x integration as needing an upgrade pass.
• Publish the package config and inspect it first for: AdWords API version, OAuth credentials, developer token, client customer ID, and Doctrine cache settings. The cache configuration is now the most important v3-specific area.
• Put credentials in .env rather than the config file: developer token, OAuth client ID/secret, refresh token, and default client customer ID. For MCC access, also confirm the login customer ID.
• Look at the package service provider and client/facade entry point before writing application code. Determine whether the package exposes a singleton client, a manager, or a factory; that affects multi-account usage.
• First use case: perform a read-only campaign or keyword report against a test/sandbox account. Verify authentication, API version, and cache configuration before attempting any mutate operations.
• Run php artisan config:clear after changing credentials or cache settings. If the package uses Doctrine’s filesystem cache, confirm the configured cache directory exists and is writable.

Implementation Patterns

• Wrap the package client behind an application service or repository. Controllers and Livewire components should not call the AdWords client directly; this keeps API version changes and v3 cache changes isolated.
• Centralize selector/field definitions in one place. AdWords API 6.0.0 has version-specific fields and service behavior; scattering field names across the codebase makes future upgrades expensive.
• Use queued jobs for reporting and synchronization. AdWords calls are slow and quota-limited; jobs give you retries, backoff, and visibility without blocking requests.
• Separate read paths from write paths. For reporting, use read-only selectors, paginate results, and persist raw responses for audit/debugging. For mutations, validate inputs, log the intended operation, and only then call the API.
• Treat Doctrine cache as an infrastructure concern, not as Laravel’s cache. Configure it explicitly for the package and do not assume Cache::remember() or Laravel cache tags apply to AdWords client metadata.
• For multi-account applications, resolve a client per customer ID rather than reusing one global singleton with mutated credentials. Keep account context explicit in job payloads and service method signatures.
• Map API responses into application DTOs or arrays at the boundary. This protects your domain code from AdWords object shapes and makes testing against recorded responses practical.
• In tests, fake your wrapper/service rather than the SOAP/HTTP layer. Keep a small number of contract tests that run against a sandbox account when credentials are available.

Gotchas and Tips

• v3.0.0 is a breaking release. The switch to Doctrine Cache may invalidate assumptions about Laravel cache drivers, cache clearing, and cache key prefixes. Audit any custom caching around the package.
• Doctrine cache is not Laravel cache. Filesystem cache paths, permissions, and lifetimes must be configured separately; stale cache can make credential or config changes appear ignored.
• AdWords API 6.0.0 is legacy. Do not assume newer Google Ads API features or fields exist. “Field not found,” “service not found,” or selector errors often indicate version mismatch rather than bad data.
• Authentication has several independent pieces: developer token approval, OAuth refresh token, client customer ID, and optionally login customer ID for MCC. A valid OAuth token alone is not enough.
• Watch quota and rate limits. Implement exponential backoff for transient SOAP/HTTP failures, but do not blindly retry mutate operations unless they are idempotent.
• Log request IDs and high-level request/response metadata, but never log developer tokens, OAuth secrets, or full credential payloads.
• If behavior seems inconsistent after deployment, check bootstrap/cache/config.php and run php artisan config:clear. Also clear the Doctrine cache directory when rotating credentials or changing API settings.
• Likely extension points are the client factory, cache provider configuration, and response mapping layer. Prefer binding your own implementation through the container over editing vendor code.