Google Api Laravel Package

Technical Evaluation

Verdict: Conditional go for a time-boxed pilot; not a platform bet. This is a thin, opinionated Laravel wrapper around google/apiclient. The technical risk lives almost entirely in the wrapper's version pinning and maintenance, not in the Google SDK underneath.

Architecture fit

• Laravel-native shape: service provider, facade, publishable config, migration, and interfaces for storage. It slots into a conventional Laravel service without bespoke bootstrapping.
• Sensible seams: auth/transport (GoogleClient), token persistence (StorageAdapterInterface), and service ergonomics (adapters + facade) are separated cleanly, which gives us identifiable extension points.
• forUser() plus UserScopedStorageAdapter is the highest-value capability for our use case — it makes queued jobs and console commands able to act on a user's Google account without an authenticated request context. That is usually the messiest part of a Google integration.
• GoogleApi::service(Sheets::class) is a genuine escape hatch: any of the ~200 Google APIs is reachable without waiting for the package to ship an adapter. This materially reduces lock-in.
• Caveat: only four adapters (Calendar, Gmail, Drive, Books) are actually opinionated. Anything else is raw SDK calls with our own mapping code, so the wrapper's savings shrink the further we go from the bundled four.

Integration feasibility

• Installation is standard composer require + vendor:publish + migrate. Low ceremony.
• The google/apiclient-services cleanup script and allowlist must be added to the consuming app's composer.json. Easy to miss, and it has real artifact-size and CI-cache consequences.
• Credentials are a JSON file path in config, which pushes a secrets-management decision onto us (env-substituted path, mounted secret, or custom loader). The package does not solve that.
• The long pole is Google Cloud Console work — OAuth consent screen, scope selection, redirect URIs, and verification for sensitive/write scopes — not the code.

Technical risk

• Version pinning is the dominant risk. php ^8.5 and laravel ^13.0 are bleeding-edge constraints. If the fleet is on 8.3/8.4 and Laravel 11/12, this package is not installable at all without an upgrade program. It signals good forward hygiene but drastically narrows the addressable install base.
• Bus factor 1, 60 stars, 0 dependents. No ecosystem evidence of production use, no third-party bug pressure, no public security advisory history. Adopting early means underwriting the wrapper ourselves.
• Supply chain depth: we inherit google/apiclient and google/apiclient-services (large but generally well-maintained) plus this wrapper. The wrapper is the thin, unpinned link.
• Encryption at rest for DB tokens is a real plus, but key management and rotation are ours. The README does not describe re-encryption or rotation behavior.
• Deliberately narrow fluent surface: Gmail send/attachments, Calendar CRUD, Drive list/get/upload. Deeper needs — batch requests, push notifications/webhooks, domain-wide delegation, incremental sync — fall back to raw SDK.
• No described retry/backoff, rate-limit awareness, or quota handling. That becomes our code.

Key questions

1. Which Laravel/PHP versions are actually deployed, and is a jump to Laravel 13 / PHP 8.5 funded or aspirational?
2. Do we need write operations (Gmail send, Drive upload) or read-only sync? Write scopes trigger Google verification and raise the blast radius substantially.
3. Is the consent screen already verified for our scopes, and who owns that recurring process?
4. Does the google_tokens schema meet our tenant-isolation and retention requirements, or do we implement a custom adapter from day one?
5. What is our contingency if the maintainer stops shipping — MIT permits a fork, but is that budgeted?
6. Are we comfortable being the first production reference for a 60-star package? If not, what's the true cost of an internal wrapper?

Integration Approach

Stack fit

• Strong for a Laravel monolith or Laravel service already using facades, config publishing, and Eloquent migrations — the conventions mirror first-party packages closely enough that ramp-up is documentation-reading rather than architecture work.
• Weak for non-Laravel PHP services, polyglot estates, or environments with rigid dependency freezes.
• Best fit is the "one Google integration, several scopes, same user" shape (calendar + email + drive). Poor fit for a single narrow integration where the wrapper adds indirection without saving code.

Migration path

• Greenfield: install, publish config, migrate, wire the auth controller, call one adapter behind a flag. Days, not weeks.
• From raw google/apiclient: the wrapper does not hide the SDK, so migration is incremental — adopt GoogleClient plus token storage first, keep existing SDK call sites, then move call sites adapter by adapter. GoogleApi::service() means no call site is blocked on package support.
• From a bespoke internal token store: implement StorageAdapterInterface (and UserScopedStorageAdapter for forUser()). This is the cleanest adoption path — the package becomes our auth/transport layer only, which is the lowest-risk way to consume it.

Compatibility

• The ^8.5 / ^13.0 constraints are hard gates. Run composer why-not before planning anything further.
• The google/apiclient-services cleanup script interacts with CI caching and deploy artifact size; validate in a staging build, not locally.
• Enum-vs-string config is backward compatible ("plain strings still work"), a good signal for minor-version churn tolerance.
• Storage adapter interface changes would be the most disruptive break. Pin to a minor range and read the changelog on every bump.

Sequencing

1. Spike (1–2 days): prove the version gate, install on a throwaway branch, complete an OAuth round trip against a sandbox Google project.
2. Scope and consent decision: finalize scopes; submit for verification if sensitive or write scopes are required. This runs in parallel and is the true critical path.
3. Auth and storage: wire GoogleClient, choose DB adapter vs. custom adapter, settle key management, and centralize TokenNotFoundException → redirect handling in one middleware or exception handler.
4. One read-only integration to production behind a flag (Drive list or Calendar read) to validate refresh, expiry, and failure behavior under real traffic.
5. Write paths (Gmail send, Drive upload) only after the read path is stable and scope approval lands.
6. Background jobs using forUser() — this is where most of the value is; explicitly validate token refresh inside queue workers.
7. Anti-lock-in hardening: wrap the package behind our own service interface so replacing it with direct SDK calls is a bounded change.

Operational Impact

Maintenance

• Low code footprint, but we own credentials/secret rotation, encryption key management for google_tokens, consent-screen upkeep (Google's verification and scope-change review is slow and recurring), and any Google API deprecation response.
• Upstream hygiene is good — CI, PHPStan, Pint, release-please, and a readable per-version changelog — but all of it rests on one maintainer. Reassuring cadence, concentrated risk.
• Pin versions tightly and treat every bump as a review event; the changelog quality makes that cheap.

Support

• No commercial support, SLA, or visible security policy. Name an internal owner for the Google integration before adoption — this is non-negotiable at 0 dependents.
• Debuggability is reasonable: typed exceptions (TokenNotFoundException carrying the auth URL), a readonly AccessToken value object with isExpired() / hasRefreshToken(), and the underlying SDK error surface still reachable.
• Onboarding is cheap for anyone fluent in Laravel and the Google SDK; the per-service docs are sufficient to be productive.

Scaling

• Token storage is per-user rows, read and decrypted per API call. Fine at thousands of users; at high queue throughput, a per-call DB fetch plus decrypt becomes a hot path — implement a Redis-backed adapter via the custom interface if volume justifies it.
• Google-side quotas are the real ceiling: per-user and per-project rate limits, Gmail sending limits, Drive throughput. The package exposes no batching, backoff, or quota-aware retry — we build that layer.
• forUser() in queue workers scales horizontally without auth context, which is the right architectural shape.

Failure modes

• Expired or revoked refresh token (user revokes access, password change, 7-day refresh expiry for apps in testing mode) surfaces as an auth failure mid-job. Requires a defined path: mark disconnected, notify, stop retrying.
• TokenNotFoundException in a queue context where no redirect is possible — must be caught and converted into a failed job with a reason, never an unhandled exception.
• Key rotation without re-encryption in the token table produces silent decryption failures.
• Composer allowlist drift — an API absent from extra.google/apiclient-services fails at runtime with class-not-found, which is a non-obvious diagnosis.
• Wrapper abandonment — no security patches. MIT makes forking viable; budget for it as the explicit contingency.
• Config drift between access_type: Offline and include_grant_scopes is the classic cause of "we never got a refresh token" incidents.

Ramp-up

• A mid-level Laravel engineer is productive in about a day; there are only two concepts to absorb (the OAuth flow and the storage abstraction).
• Platform effort concentrates in the Google Cloud Console. Budget days-to-weeks of calendar time for verification, not engineer time.
• Deliver a half-day internal walkthrough plus a runbook covering the auth flow, revocation handling, key rotation, quota behavior, and the fork contingency.