Shopping Common Protos Laravel Package

Technical Evaluation

What this package actually is. google/shopping-common-protos is a Composer package of PHP classes generated by protoc from Google's Shopping API .proto definitions. It contains shared message types (e.g. google.shopping.type.* — destinations, channels, price/availability enums) and no service clients, no transport, no auth. On its own it cannot call any Google API. Its purpose is to be a transitive dependency of the real client libraries (google/shopping-merchant-*, google/shopping-css-*, google/shopping-merchant-reports, etc.).

Architecture fit. Poor fit as a direct dependency; good fit as plumbing. In a Laravel application the natural integration is:

Laravel domain layer
  └── google/shopping-merchant-<resource>   (GAPIC client, REST or gRPC)
        └── google/shopping-common-protos   (value objects only)
              └── google/protobuf

If a TPM is evaluating this package in isolation, the correct conclusion is: do not add it directly. Add the service package you actually need and let Composer resolve this one. The exception is when you write adapter code that type-hints against google.shopping.type.* messages independent of any client — legitimate, but rare.

Integration feasibility. Low friction mechanically: one composer require, PSR-4 autoloading, framework-agnostic, no service provider, no config, no migrations, no runtime side effects. Constraints to verify before committing:

• PHP 8.1+ and google/protobuf (with ext-protobuf strongly preferred; the pure-PHP fallback is materially slower).
• Transport decision: REST via google/gax + PSR-18/PSR-7 HTTP client, or gRPC via ext-grpc. Laravel's HTTP client is not used by GAPIC clients — they need a PSR-18 implementation, so plan for symfony/http-client or guzzlehttp/guzzle explicitly.
• Auth: service-account JSON or workload identity via google/auth; credentials handling belongs in Laravel config/secret management, not in the package.

Technical risk. The risk is not in this package's code (it is generated, deterministic, and effectively static) — it is in coupling and version skew:

Key questions to resolve before green-lighting.

1. Which API are we targeting — the new Merchant API (merchantapi.googleapis.com) or the legacy Content API for Shopping v2.1? The former is the supported path and the reason these protos exist.
2. Do we need this package directly, or only as a resolved dependency? If directly, what code type-hints against its messages?
3. Is there an existing Google SDK in the app that already constrains google/protobuf?
4. REST or gRPC? Does the target environment have ext-grpc and ext-protobuf?
5. What is the quota/throughput requirement per Merchant Center account? (Multi-account or multi-sub-account usage changes the architecture.)
6. Are we prepared to treat generated message classes as an anti-corruption boundary rather than leaking them into controllers, jobs, and Eloquent models?

Integration Approach

Stack fit. Composer-native, framework-agnostic — compatible with Laravel 10/11/12 and any PHP 8.1+ runtime. It slots in below the application layer. Recommended placement:

• Install the service package(s) you need (google/shopping-merchant-products, -inventories, -reports, google/shopping-css, etc.).
• Treat common-protos as an implicit, Composer-managed transitive dependency.
• Build a thin App\Services\GoogleShopping adapter that returns your own DTOs / value objects.
• Register a singleton binding in a service provider for the GAPIC client; keep credentials in config/services.php + env, never in the package's own config.
• Queue all write operations (product inserts, inventory updates) — these are rate-limited network calls and belong in jobs with backoff, not in request cycles.

Migration path. If the organisation is on google/apiclient with Content API v2.1, this is a model migration, not a library swap. The Merchant API is proto/JSON-shaped and resource-oriented; field names, enums, and batch semantics differ from the old REST API. Sequence:

1. Inventory every current Content API call site and map each to a Merchant API resource/method.
2. Stand up the new adapter in parallel and dual-write to a sandbox Merchant Center account.
3. Cut over read paths first, then write paths, behind a feature flag.
4. Decommission the old client only after a full reconciliation cycle on product/inventory state.

If this is a greenfield integration, skip migration entirely and go straight to the Merchant API.

Compatibility notes.

• Enum values in generated PHP are class constants — code that stores them as integers in the database will need a mapping layer to survive regeneration.
• Protobuf oneof fields surface as a single nullable property plus a getX() accessor; do not model them as nullable columns without a discriminator.
• Well-known types (Timestamp, Duration, Money) do not map cleanly to Laravel's Carbon/integer cents conventions — normalise at the adapter boundary.
• Pin with composer.lock and upgrade all Google packages in one PR; partial upgrades are the dominant failure mode.

Sequencing (suggested 4 sprints).

1. Sprint 1 — Spike. Confirm API target, auth, and transport. Prove one read call end-to-end in a sandbox account with the service package (not common-protos directly).
2. Sprint 2 — Adapter + domain model. DTOs, enum mapping, Money/Timestamp normalisation, feature flag scaffolding.
3. Sprint 3 — Write paths. Queued jobs, idempotency keys, retry/backoff policy, dead-letter handling, reconciliation job.
4. Sprint 4 — Hardening. Quota dashboards, serialization regression tests, dependency automation, runbooks.

Operational Impact

Maintenance. Low-touch but not zero-touch. The package is regenerated whenever Google's proto definitions change; releases can arrive frequently and contain additive or breaking generated-code changes. Policy: treat it as a third-party black box — never patch vendor code, never fork, pin via lockfile, and use Dependabot/Renovate with all google/* packages grouped into a single PR gated by the adapter's contract tests. Budget roughly one dependency-upgrade cycle per quarter plus reactive upgrades when a required field or resource appears.

Support. No commercial SLA on the package itself; GitHub Issues only. Escalation for API behaviour, quotas, or account issues goes through Google Cloud / Merchant Center support, which is a separate channel and a separate contract. Practically: the package will not "break" in the way a hand-written library does — it will simply be stale relative to the API. The real support burden lands on the service client packages and on Google's API-side changes, not here.

Scaling. This package is not on the hot path in any meaningful way — it is message construction and serialization. Scaling considerations live elsewhere:

• Quota-bound, not CPU-bound. Merchant API per-account and per-project quotas will be your ceiling. Design for batched/bulk endpoints from day one; naive per-item loops will hit 429s under modest catalogue sizes.
• Enable ext-protobuf (and ext-grpc if using gRPC) on every web and worker node; the pure-PHP protobuf runtime is a measurable tax at volume.
• Horizontal worker scaling works cleanly because the package is stateless — no shared mutable state, safe under Octane and queue workers.
• Memory is negligible per message; large catalogues should be streamed/paginated rather than accumulated.

Failure modes and detection.

Ramp-up. Installation and first successful call: hours. Productive, correct use: 2–4 weeks for a mid-level Laravel engineer. The learning curve is not Laravel — it is protobuf semantics (enums as constants, oneof handling, well-known types, absence-vs-default), GAPIC client conventions (pagination iterators, long-running operations, retry config), and Google's Merchant Center data model (accounts, sub-accounts, data sources, destinations, supplemental feeds). Recommend: one engineer owns the integration and the adapter boundary, all other engineers consume only the internal DTOs, and the proto classes never appear outside App\Services\GoogleShopping.

TPM bottom line. Green-light the capability (Merchant API integration) with a scoped spike; do not green-light google/shopping-common-protos as a named, directly-managed dependency. Its low adoption metrics are characteristic of generated proto plumbing and should not factor into the decision. Track it as a transitive dependency with automated upgrade hygiene, and place all architectural scrutiny on the service client selection, the quota/batching design, and the adapter boundary.