Cloud Common Protos Laravel Package

Product Decisions This Supports

• Build vs. buy on cloud-integration plumbing. This package is the "buy" answer for a narrow but recurring problem: representing Google's shared protobuf types (AuditLog, Status, HttpRequest, OperationMetadata) in PHP. Any roadmap item that touches GCP audit logging, standardized error envelopes, or long-running operation metadata should assume these types come from google/cloud-common-protos rather than being hand-rolled — that removes a schema-maintenance workstream from the backlog.
• Observability and compliance roadmap. Structured audit trails mapped to Google Cloud Audit Logs are a common enterprise/security requirement. This package gives you the exact field shapes Google expects, which means "ship audit-grade logging" becomes a scoped feature using official types instead of a bespoke schema plus a future migration.
• Transport strategy: gRPC vs. REST. Where a feature needs gRPC (high-throughput internal services, Pub/Sub streaming, custom endpoints), this dependency is effectively non-negotiable. Where REST suffices, it adds nothing. This is a genuine architectural fork that belongs in roadmap planning, not a sprint-level detail.
• Dependency-policy decisions. With 3 GitHub stars and 0 listed dependents, this is not a package to adopt deliberately — it's a transitive dependency of the Google Cloud PHP SDKs (google/cloud-logging, google/cloud-pubsub, and friends). The PM decision is whether to permit direct ^1.0 pinning in composer.json or require all usage to arrive indirectly through SDKs. Default recommendation: indirect only, direct only when a feature genuinely needs the shared types outside an SDK call path.
• Platform/runtime readiness gating. Adoption implies the google/protobuf PHP extension and, for gRPC, grpc/grpc. That's an infrastructure commitment affecting Docker images, CI runners, and possibly shared hosting. This should be a stated platform prerequisite in the technical roadmap, not discovered mid-sprint.
• Interoperability and API contract design. If the product exposes or consumes Google-shaped payloads (error objects aligned to Google\Rpc\Status, audit entries), using the canonical types reduces integration friction for enterprise customers and partners — a differentiator worth calling out in positioning.
• Data-layer design decisions. Protobuf messages are immutable; Laravel's Eloquent/Collections are mutable. Choosing this package forces a DTO-mapping layer (e.g., spatie/laravel-data). That's an architectural cost to schedule, not a hidden one.

When to Consider This Package

Adopt (directly or indirectly) when:

• You are already using Google Cloud PHP SDKs — in which case it is likely present in composer.lock today and the only real decision is governance, not adoption.
• The product must produce audit logs, error payloads, or operation metadata that match Google Cloud's canonical schema.
• You are building gRPC clients or servers in PHP, or defining custom .proto schemas requiring generated PHP classes.
• You need strict, versioned, backward-compatible contracts between services, and binary-efficient serialization matters at your throughput.
• Compliance or customer contracts require schema parity with a hyperscaler's published definitions.

Look elsewhere (or skip) when:

• The integration is REST-only — e.g., Cloud Storage over HTTP. The package adds a dependency and an extension requirement for zero benefit.
• The team has no protobuf/gRPC experience and no near-term need to build it. Start with REST SDKs; revisit when a concrete feature demands it.
• Your deployment target cannot install the google/protobuf extension (managed/shared hosting, restricted container policies) and no pure-PHP fallback is acceptable.
• You need a self-contained, vendor-neutral serialization layer — this is Google-shaped by definition and creates directional lock-in.
• The requirement is small and stable enough that an array/JSON DTO would do; protobuf is overkill for simple CRUD payloads.

How to Pitch It (Stakeholders)

For executives — one paragraph: This is a small, free (Apache-2.0), Google-maintained library of shared data definitions that our Google Cloud integrations already depend on. It isn't a product feature in itself; it's plumbing that lets us produce audit logs and error responses in exactly the format Google Cloud expects, which shortens compliance work and reduces integration risk with enterprise customers. The strategic decision is not "should we use it" — we almost certainly already do, transitively — but "should we allow it to be used directly," and my recommendation is yes, narrowly, only where a feature needs Google's shared types outside of a standard SDK call. The main cost is a runtime prerequisite (the protobuf PHP extension), which we should confirm in our deployment pipeline before committing to any gRPC-dependent roadmap item.

For engineering — the short version: Adopt as a transitive dependency by default via the Google Cloud PHP SDKs; pin ^1.0 explicitly only where shared types are needed directly. Budget for: the google/protobuf extension in all environments (CI and production), a mapper between immutable protobuf messages and Eloquent/Collections, and custom JSON serialization (serializeToJsonString()) wherever protobuf objects hit an API response. Treat Google's schema deprecations as a monitored, low-severity risk with feature flags as the mitigation. Do not build custom protobuf tooling until a gRPC use case is funded and staffed.