Google Api Laravel Package

Product Decisions This Supports

• Build vs. buy for Google Workspace integrations. The package is a thin Laravel-native wrapper over google/apiclient. If the roadmap calls for Gmail send, Calendar events, Drive file operations, or Books lookups, adopting it converts a multi-sprint OAuth/token plumbing project into a config-and-controller task. The realistic scope of the build decision is "OAuth 2.0 flow + token persistence + fluent service wrappers" — not the underlying Google SDK, which remains a dependency either way.
• Feature sequencing for email/calendar features. Because the bundled adapters are fluent and opinionated (e.g., GoogleApi::forUser($user)->gmail()->to(...)->subject(...)->send()), a PM can commit to "send transactional email from a queued job" or "push events to a user's calendar" as a small, well-bounded story rather than an epic with an unknown OAuth tail.
• Multi-tenant / per-user delegation as a first-class product capability. The forUser() + UserScopedStorageAdapter design supports background jobs and console commands acting on behalf of a specific user without an authenticated session. This unlocks product features like scheduled digests, invoice delivery, and calendar sync workers — the kinds of things that otherwise get punted because "token handling in queues is hard."
• Security posture decisions. DatabaseStorageAdapter encrypts token columns at rest and is the default; SessionStorageAdapter exists for short-lived flows. That gives a PM a defensible default for a security review instead of asking engineering to invent one.
• Integration breadth vs. depth trade-off. Four bundled adapters (Calendar, Gmail, Drive, Books) cover common use cases, and GoogleApi::service(Sheets::class) is an escape hatch to any Google service. This supports a roadmap where one Google integration ships now and adjacent ones are cheap follow-ons.
• Scope control via Composer cleanup. The pre-autoload-dump / google/apiclient-services config lets you ship only the services you use rather than all ~200 Google APIs — a real deployment-size and dependency-surface decision, not just cosmetics.

When to Consider This Package

Adopt when most of these are true:

• The stack is already on PHP ^8.5 and Laravel ^13.0 — this is a hard constraint, not a preference. The package's composer.json requirements will block adoption on any older Laravel/PHP combination, and 0.11.0 explicitly bumped to PHP 8.5 / Laravel 13.
• You need one to four of Calendar, Gmail, Drive, or Books, plus optionally a small number of adjacent services via GoogleApi::service().
• You want first-party Laravel OAuth ergonomics: a redirect-to-createAuthUrl(), callback controller, TokenNotFoundException carrying the auth URL, config-published scopes and prompt enums.
• You need per-user token storage for queued jobs or console commands, and you want encrypted-at-rest DB tokens without building it.
• The team values a small, readable, MIT-licensed wrapper over an abstraction layer, and is comfortable reading vendor source when needed.
• You can accept single-maintainer risk with a fork/replace fallback (the wrapper is thin enough to internalize if the maintainer disappears).

Look elsewhere when any of these are true:

• You are on Laravel 10/11/12 or PHP < 8.5. You will be locked out of the current release line; pinning an old version is a maintenance tax, and the changelog shows several releases are largely tooling/CI/dependency churn rather than capability.
• You need exhaustive Google API coverage with typed, idiomatic wrappers. Only four adapters ship; everything else is raw google/apiclient objects through service().
• You need vendor support, SLAs, or a security-review paper trail from a commercial provider. 60 stars and 0 dependents is not a procurement argument.
• You need Google Cloud / service-account / domain-wide-delegation flows as a first-class concern. The README is centered on user OAuth consent flows.
• Your integration is large enough to justify direct google/apiclient usage with your own token repository — the wrapper's value shrinks as the number of custom services grows, and you inherit the package's release cadence as a constraint.
• You require broad production precedent. Zero dependents means you are effectively a design partner.

How to Pitch It (Stakeholders)

To executives (one paragraph): We can ship Google Calendar and Gmail integration with roughly a few days of engineering instead of a multi-week OAuth project. This package is a small, MIT-licensed Laravel wrapper that handles the consent flow, stores users' Google tokens encrypted in our database, and lets background jobs act on a specific user's behalf — which is the part that usually blocks these features. It's low lock-in: it sits on top of Google's official PHP SDK, so if we ever walk away, the underlying client and our data stay. The trade-off is that it's a 60-star, single-maintainer package that requires the newest Laravel and PHP versions, so it's a fit for a fast, well-scoped integration and not a long-term platform bet.

To engineering (the honest version): It's a convenience layer, not a framework. Strengths: published config with scope enums, pluggable StorageAdapterInterface (DB default with encrypted columns, session alternative), AccessToken value object with isExpired() / hasRefreshToken(), and forUser() for jobs. The escape hatch is real — GoogleApi::service(Sheets::class) returns the authorized Google client, so we're never blocked on missing adapters. Costs and risks: hard requirement on PHP 8.5 / Laravel 13, only four bundled adapters, no dependents in the wild, and a changelog that is largely release automation and dependency bumps. Mitigations: vendor it or fork it if necessary (the surface is small), keep our business logic behind our own service classes rather than calling the facade everywhere, and treat the token storage interface as the seam we'd replace first.

Recommendation to state explicitly: Approve as a scoped, reversible dependency for the Calendar/Gmail feature set on the Laravel 13 stack, with a mandatory thin internal abstraction over the facade and a documented exit path to direct google/apiclient. Do not adopt it as a standard across legacy applications, and do not let it become the only way the product talks to Google.