Cloud Common Protos Laravel Package

Technical Evaluation

Architecture fit

google/cloud-common-protos is a contract layer, not an application layer. It ships generated PHP classes for shared protobuf types (google.rpc.Status, google.type.*, google.longrunning.Operation, audit-log and HTTP-request messages) that Google Cloud APIs reuse. For a Laravel/PHP product the realistic architecture position is:

• Transitive dependency (default): pulled in automatically by google/cloud-logging, google/cloud-pubsub, google/cloud-trace, and most google/cloud-* SDKs. No architectural decision is actually being made here; it arrives with the SDK.
• Direct dependency (narrow): justified only when you need the common messages without a full GCP SDK — e.g., emitting google.rpc.Status-shaped error payloads from your own API, hand-building LogEntry structures, or generating your own protobuf clients for a gRPC service.
• Poor fit: mutable, Eloquent-shaped domain modelling. Protobuf messages are immutable-by-convention DTOs; Laravel's idioms (fluent builders, mass assignment, model events) do not map onto them. Any non-trivial use needs an adapter/DTO mapper between the two worlds.

Net: the package is plumbing. Its architectural value is standardization — one canonical shape for status/error/audit payloads across services — not capability. Do not position it as a feature enabler in a roadmap.

Integration feasibility

Composer-only, no service provider, no config, no facade. composer require google/cloud-common-protos:^1.0. Two real constraints:

1. google/protobuf v5 constraint. v1.0.0 exists specifically because the dependency was bumped to protobuf v5 (see the v1.0.0 breaking-change note). Anything else in the tree pinned to protobuf ^3/^4 will block the upgrade.
2. Runtime, not extension. The google/protobuf PHP runtime works in pure PHP; ext-protobuf is an optional accelerator (materially faster, but not required). This is worth explicitly correcting in any internal write-up — requiring a C extension at the platform level is a much bigger ask than accepting a Composer package, and it is not actually required.

gRPC (grpc/grpc, ext-grpc) is only in scope if you are calling gRPC transports or running a gRPC server. REST/JSON via the standard SDKs does not need it.

Technical risk

Key questions

1. Do we consume this directly or transitively? If transitively, the decision is version governance, not adoption.
2. Which GCP services are in scope, and are any of them gRPC-only? That determines whether ext-grpc enters the platform baseline.
3. Is ext-protobuf acceptable in our build/runtime images, or do we standardize on pure PHP? This is a platform-team decision with a clear performance trade-off.
4. Do we already carry google/common-protos (pre-split)? If so, who owns rationalizing to a single artifact?
5. What is the serialization contract for anything crossing our API boundary — who owns the mapping tests?
6. Who is the accountable owner for proto-schema/version governance on an ongoing basis?

Integration Approach

Stack fit

Fits Laravel 10/11 on PHP 8.1+ with Composer 2 without friction. It is a library of plain classes: register clients in the container as singletons, but never wrap protobuf messages in the container or in config. Keep them at the edges — request/response boundaries, log formatters, queue payload serializers, and outbound GCP calls.

Migration path

1. Inventory first. Run composer show -t and composer why google/cloud-common-protos (and google/common-protos) to confirm whether it is already present. In most Laravel apps it is, via a GCP SDK.
2. Do not add it by hand if an SDK already supplies it; pin the SDK and let resolution follow.
3. Rationalize duplicates. If both common-protos and cloud-common-protos are present, converge on one in a dedicated PR — not bundled with a feature branch.
4. Upgrade to ^1.0 deliberately. This is the protobuf-v5 cutover; schedule it as its own change with a regression pass on every protobuf-touching path.
5. Only then consider direct usage (custom gRPC, error envelope standardization).

Compatibility

• Wire compatibility is guaranteed by protobuf itself; the risk is in JSON mapping and PHP-level API surfaces, not the wire format.
• Deprecated fields generate warnings rather than failures — route deprecations into your normal log-monitoring channel so they surface before removal.
• Pin google/protobuf explicitly (e.g. ^5.0) rather than relying on transitive resolution, and pin the common-protos version in composer.lock as you would any generated-code artifact.

Sequencing

1. Dependency audit and duplicate rationalization.
2. Explicit pins in composer.json (^1.0 + google/protobuf).
3. Serialization contract tests (round-trip: proto → JSON → consumer) committed before any feature depends on it.
4. Platform decision on ext-protobuf / ext-grpc, applied to CI and runtime images.
5. Direct-usage adapter layer (proto ↔ DTO ↔ Eloquent) only if a concrete feature demands it.
6. gRPC transport work, if ever, as a separate initiative with its own owner.

Operational Impact

Maintenance

Near-zero at the application level: no runtime process, no migrations, no config, no cron. Maintenance cost is entirely dependency surface — regenerated code arriving through routine Composer updates. The practical obligation is a controlled update cadence (monthly or SDK-driven), not ongoing engineering.

Support

Upstream support is routed to the googleapis/google-cloud-php monorepo, not this repository; the README says so explicitly. Licensing is Apache-2.0, AS-IS. Google Cloud support plans cover SDK usage, not this artifact individually. Practically: your own team owns breakage, so keep the blast radius small by keeping usage at the edges.

Scaling

Generated classes are static and cheap; the scaling variable is serialization cost. Pure-PHP protobuf is roughly an order of magnitude slower than ext-protobuf — irrelevant for a few thousand messages a minute, relevant for high-volume log enrichment or per-request structured logging at scale. Second-order concern: log/storage amplification if you attach full protobuf-encoded payloads to every entry.

Failure modes

• Protobuf runtime-version mismatch after an unrelated dependency bump — surfaces as fatal errors at first serialization, often only in production paths that lack coverage.
• Extension ABI break after a PHP minor upgrade when ext-protobuf is pinned in the image.
• JSON shape drift in public API responses (int64-as-string, camelCase) breaking downstream consumers.
• Silent schema lag — pinned package misses newly documented GCP fields; writes succeed but fields are dropped.
• Ecosystem confusion — a developer adds google/common-protos alongside cloud-common-protos, producing duplicate classes and autoload ambiguity.
• Misdiagnosed risk — the low star/fork counts read as "abandoned" to reviewers unfamiliar with monorepo-split leaf packages.

Ramp-up

Low for consumption through SDKs — most engineers never touch the types directly. Moderate for anyone writing raw message construction or JSON serialization: budget roughly 1–2 days for a Laravel developer to be productive, and about a sprint of focused work (plus external expertise or training) before a team can confidently own a gRPC contract or an error-envelope standard. The ramp-up cost is really protobuf literacy, not this package. If the team cannot absorb that, stay on REST SDKs and treat this purely as a pinned transitive dependency — which, for the large majority of Laravel products, is the correct TPM recommendation.