webonyx/graphql-php: a spec-first GraphQL server for PHP

What webonyx/graphql-php is for, and who should pick it up

PHP has no shortage of ways to expose data over HTTP, and most of them end with a controller that hand-rolls a response shape per endpoint. webonyx/graphql-php takes the other route: you declare types once, and the library resolves a query against them. The README describes it as a PHP implementation of the GraphQL specification based on the reference implementation in JavaScript, and states it is fully compliant with the October 2021 GraphQL specification, with September 2025 compliance in progress and tracked in issue 1931.

The audience is narrow and specific. You already run PHP, you already have domain code you trust, and you want a single endpoint that lets clients ask for the fields they need instead of accepting whatever a fixed controller returns. The library sits below your framework. It does not ship routing, middleware, authentication or a database layer, and nothing in the README suggests it intends to. If you want GraphQL because a mobile team keeps asking for slightly different payloads from the same REST resource, this is the layer that removes that negotiation. If you want GraphQL because it sounds modern, the same type system will still demand that you model your domain honestly, and that work does not disappear.

How execution works: schema, resolvers, and the reference implementation lineage

The architecture follows graphql-js closely enough that anyone who has read that codebase will recognise the shape. You build a schema from type definitions; the library parses an incoming query document, validates it against that schema, and then executes it, walking the selection set and calling a resolver for each field it needs. Resolvers are where your application code lives: the library hands over the parent value, the arguments, and the context object you supplied, and expects a value or a promise back.

That promise handling is why the examples directory matters. Alongside a hello-world and a blog example, the repository includes 03-standard-server, 04-async-php, and 05-type-config-decorator. The async example exists because PHP's typical request lifecycle is synchronous, and a GraphQL executor that resolves fields independently can benefit from concurrent I/O. The library supports that, but it does not arrange it for you.

Versioning is worth reading before you write code against it. The README states the project follows Semantic Versioning 2.0.0, and that only elements marked with the @api PHPDoc tag, plus constants in the class-reference docs, are guaranteed stable within major versions. Everything else, including internal classes you might be tempted to reach for, can change between minor or patch releases. Treat that as a real constraint on how deep your integration goes.

Installing webonyx/graphql-php and running a first query

Installation is a single Composer command, exactly as the README gives it:

composer require webonyx/graphql-php

After that, the fastest way to see the library work is the hello-world example, which the README points to in the examples directory. The README states there are several ready examples in that directory, with a specific README file per example; it does not reproduce their code, so the schema construction and execution wiring live in those files rather than in the README itself. The repository layout shows the example folders: 00-hello-world, 01-blog, 02-schema-definition-language, 03-standard-server, 04-async-php, 05-type-config-decorator and 06-per-schema-scalar-override.

What the README does give you is where the rest of the documentation lives. Full documentation is available at webonyx.github.io/graphql-php or in the docs directory of the repository. If you are following a GraphQL PHP tutorial that assumes a framework integration, check which package it actually installs, because this one stops at the library boundary: the install command above is the entire setup step the README documents.

The framework integration gap, and what that costs you

The most common disappointment with this package comes from expecting it to be the whole stack. It is not. There is no Laravel service provider, no Symfony bundle, and no built-in HTTP endpoint in the README. The standard-server example shows the shape of an endpoint, but you still own request parsing, content negotiation, error formatting, authentication, and query depth or complexity limits.

That last point deserves emphasis. A GraphQL endpoint accepts arbitrary query shapes from clients, and the specification's flexibility is also an attack surface. The README does not document built-in query cost analysis or automatic depth limiting, so if you expose this publicly, those protections are your responsibility to add. The same applies to persisted queries and caching, which the README does not cover.

There is also a forward-looking caveat in the first lines of the README: the repository is planned to move to a new home, with an announcement discussion linked for details. That does not affect the code you install today, but it does affect where you file issues and where you watch for changes. If your team's process depends on a stable repository URL for dependency tracking, read that discussion before you standardise on it.

graphql-php versus a PHP GraphQL client, and versus graphql-js

Two comparisons are worth making, because the search terms around this project often blur them.

First, server versus client. webonyx/graphql-php is a server-side implementation: it parses and executes queries against a schema you define. If your PHP application needs to consume someone else's GraphQL API, this is the wrong package, and the README makes no claim otherwise. A client library is a different dependency with a different job.

Second, versus graphql-js. The README is explicit that this project is based on the JavaScript reference implementation, and the practical difference is the runtime, not the semantics. With graphql-js you get the reference implementation in its native environment and the largest surrounding ecosystem. With graphql-php you keep your PHP application, your existing autoloading, and your deployment process, at the cost of tracking a port rather than the original. The compliance statement is the thing to weigh: October 2021 is done, September 2025 is in progress. If a feature you need landed only in the newer specification, check issue 1931 before assuming it is available.

Maintenance, upgrades and the MIT licence

The repository is not archived, and the last push was on 2026-09-22, so the project is being worked on. Recent releases show a steady cadence: v15.37.0 on 2026-07-28, v15.37.1 on 2026-07-29, and v15.37.2 on 2026-08-14. The README states that the most recent version is actively developed on master, and that older versions are generally no longer supported, with possible exceptions for sponsors. That is a clear upgrade expectation: staying on a stale major version is not a supported position.

Upgrade cost is bounded by the public API definition. Because only @api-tagged elements and class-reference constants are guaranteed stable within a major version, a major bump is where you should expect breakage, and the repository ships UPGRADE.md for exactly that. Read it before bumping, not after.

The licence is MIT, which permits commercial use and modification. Nothing in the README attaches conditions to that. If you make money using the project, the README asks you to consider sponsoring the maintainer on GitHub Sponsors or the project on OpenCollective. That is a request, not a licence term, and the distinction is worth keeping straight when you explain the dependency to whoever approves your budget.

Editorial conclusion

Adopt webonyx/graphql-php when you want a GraphQL server inside an existing PHP application and are willing to write your own schema wiring, error formatting and endpoint plumbing. Do not adopt it expecting a Laravel or Symfony integration, a client, or a hosted playground: the repository ships a library plus examples, and the README points at the docs directory and the project site for everything else. Before committing, read the announcement about the planned move to a new home, check UPGRADE.md for the migration path from your current major version, and confirm whether the September 2025 specification work tracked in issue 1931 covers the features your schema needs.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. webonyx/graphql-php on GitHub