WooCommerce Is Generating GraphQL From PHP—Here’s the Catch

WooCommerce 10.9 introduced an experimental “dual API” that starts with authoritative PHP command and data-transfer classes, then generates a matching GraphQL schema at build time. Extension developers can use the infrastructure for their own APIs. The appeal is obvious: one typed domain contract can serve PHP callers and remote GraphQL clients without maintaining two hand-written implementations. The catch is equally important. The feature is experimental, the core product and coupon surface is a proof of concept, PHP 8.1 or newer is required, and backward compatibility is not guaranteed. This is a powerful staging experiment—not a reason to replace a stable production integration next week.

One source of truth changes API work

The code API uses ordinary PHP classes decorated with attributes. Executable command classes become GraphQL queries or mutations, while DTOs become input and output types. A build script generates the GraphQL layer from those declarations. Conventions handle the obvious mapping, and attributes add names, descriptions, scalar information, and capability requirements.

This can eliminate schema drift where the PHP service supports a field the GraphQL layer forgot or where authorization was added to one path but not the other. The generated API is only as correct as the authoritative classes, however.

Design commands around business capability

A command should express a bounded operation such as retrieving a coupon or updating a product field, not expose an arbitrary model with unrestricted setters. Use explicit input types, validate cross-field rules, and keep side effects inside a transaction where required.

Generated transport does not replace domain design. If the PHP command mixes authorization, storage details, formatting, and unrelated actions, GraphQL generation will publish that confusion more efficiently.

Treat attributes as a public contract

Names, descriptions, nullability, array element types, and scalar mappings shape how external developers use the API. Review those attributes like code and documentation. A vague description becomes confusion in every generated explorer and client.

Do not expose internal class names simply because generation can see them. Choose stable API language, separate internal DTOs from public DTOs when necessary, and version material breaking changes deliberately.

Authorization must survive generation

The infrastructure includes capability-oriented authorization and allows custom principal and authorization mechanisms. Test authentication and object-level access through the generated endpoint, not only by calling PHP classes in unit tests. A user allowed to read one store or product set must not query another by changing an argument.

Also constrain query depth, complexity, pagination, and expensive relationships. A typed GraphQL schema can still permit a small request that creates disproportionate database work.

Generated code belongs in the build pipeline

The GraphQL layer is generated during development rather than improvised on each request. Commit or package generated artifacts according to the project’s documented workflow, make builds reproducible, and fail CI when authoritative classes and generated output drift.

Pin the WooCommerce version used for generation. Experimental infrastructure may change, and generating locally with one version while production runs another can create a contract the server cannot honor.

Run an isolated experiment

Choose a read-only internal integration with a narrow product or coupon query. Enable the feature only in development or staging, generate the schema, add authorization and complexity tests, and compare query count and latency with the existing REST or PHP path. Do not place a public mobile app on an unstable schema.

Document the removal plan as well as the adoption plan. Experiments are safer when the team knows how to turn them off and return to the current integration.

Watch the direction without betting the store

The dual API shows a credible direction: typed PHP capabilities can drive local execution and remote interfaces, reducing duplicated contracts. Extensions that already separate commands, DTOs, authorization, and transport will be better positioned if the approach stabilizes.

WooCommerce’s official dual API introduction is explicit about its experimental status and PHP requirements. Learn from the architecture, prototype where failure is cheap, and wait for a stable contract before making it foundational.

Measure N+1 behavior before celebrating flexibility

GraphQL lets clients request connected objects conveniently, but naive resolvers can turn nested selections into repeated product, variation, coupon, or metadata queries. Capture query counts for representative documents and use batching or data-loader patterns where the infrastructure supports them. Set server-side ceilings before exposing the endpoint beyond trusted testers.

Persisted operations can reduce risk for first-party clients by limiting production traffic to reviewed query shapes. Pair them with schema-change checks so a build cannot remove a field still used by the storefront or mobile application.

Define an experiment exit criterion before implementation: acceptable query cost, complete authorization coverage, reproducible generation, and a documented compatibility strategy. Review the result when WooCommerce publishes the next contract update. If the infrastructure stabilizes, the prototype becomes informed groundwork. If it changes direction, the isolated test can be removed without trapping a customer-facing integration on an unsupported surface.

Photo by Startup Stock Photos on Pexels.