graphql-php: October 2021 is done, September 2025 is not, and @api is the contract
PHP implementation of the GraphQL specification based on the reference implementation in JavaScript
At a glance
- What is it?
- graphql-php is the PHP implementation of the GraphQL specification, built on the design of the JavaScript reference implementation. It is explicit about two things an adopter needs: which specification edition it satisfies, and which of its elements carry a backwards compatibility promise, which is a much shorter list than the class reference suggests.
- Who is it for?
- graphql-php suits a PHP team that wants the GraphQL specification rather than a framework opinion, and that reads the @api tag before it extends anything. It does not suit a team blocked on September 2025 specification features, since that compliance work is still in progress, and it does not suit anyone planning to depend on internals, because everything without the tag may move in a patch release.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly PHP, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- webonyx/graphql-php4,704 ★ · -11
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| webonyx/graphql-php | 4.7k | 4.7k |
-11 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
October 2021 is complete, September 2025 is in progress
The first substantive line of the README is a compliance statement, and it has two halves with different weights. The project is fully compliant with the October 2021 GraphQL specification. Compliance with the September 2025 specification is in progress, and the work is tracked in issue 1931, which the README links rather than describes.
That split is the first thing to check when you are choosing a library, because a specification edition is a feature list. If your schema needs something introduced after October 2021, this implementation is not yet the place to get it, and the issue number is where you would watch for it rather than a roadmap page that may or may not move.
The second thing the README says about design is that the implementation is based on the reference implementation in JavaScript, graphql-js. So the class and method names you may already know from the JavaScript library are the model here, which shortens the learning curve for anyone who has written a resolver in that ecosystem and tells you where to look when behaviour differs from another PHP GraphQL library.
@api is the line between stable and not
The versioning section is short and unusually precise. The project follows Semantic Versioning 2.0.0. Elements that belong to the public API are marked with the `@api` PHPDoc tag, and constants that appear in the class reference documentation are also part of the public API. Those elements are guaranteed to be stable within major versions. Everything else is outside the backwards compatibility guarantee and may change between minor or patch versions.
So the guarantee is narrow by design, and a narrow guarantee is honest. It means the surface you can safely build on is the set of tagged elements plus the documented constants, which is smaller than the class reference suggests and smaller than an IDE autocomplete list. The practical consequence is a rule for adopters: check for the tag before you extend a class or depend on a helper, and expect an untagged method to move without a major version bump.
There is a second half about versions rather than elements. The most recent version is actively developed on master, and older versions are generally no longer supported, with the explicit exception that support may be made for sponsors. That is a maintenance policy stated in one sentence: you track master, or you track a version that may stop receiving fixes.
composer require is the whole installation
There is one installation line and no configuration step attached to it:
composer require webonyx/graphql-phpThat is the entire instruction. The README does not describe an autoloader to register, a service to register, or a cache directory to prepare, which tells you the package is a library you call directly rather than something that boots itself into a framework.
Documentation lives in two places, the hosted site at webonyx.github.io/graphql-php and the `docs` directory in the repository. The examples directory holds several ready examples, each with its own README file, which is worth knowing because the example list in the tree is numbered and tells you what the library considers the interesting axes: `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`.
That list is the fastest orientation available. A standard server, an asynchronous PHP setup, a decorator for type configuration and a per schema scalar override cover the four things people usually discover they need after the hello world, and each one is a directory you can read rather than a snippet to paste.
Code style is fixed inside three Docker images, one file allowed PHP 8.1
The Makefile shows how the project keeps its own formatting honest across a wide PHP range, and the mechanism is a container per interpreter version. It builds a tagged image from `.php-cs-fixer.dockerfile` and runs it against the working tree:
docker build --quiet --tag="graphql-php-cs-fixer-$(1)" --build-arg="IMAGE=$(1)" --file=.php-cs-fixer.dockerfile .
docker run --rm --volume="$(PWD):/app" "graphql-php-cs-fixer-$(1)" $(2)Three interpreters are covered: `php:7.4-cli-bullseye` for everything, `php:8.0-cli-bullseye` restricted with `--path-mode=intersection` to `src/Type/Definition/Deprecated.php` and `src/Type/Definition/Description.php`, and `php:8.1-cli-trixie` restricted to `src/Type/Definition/PhpEnumType.php` and its test.
The restriction is the interesting part. Files that need newer language features are named explicitly and formatted against a newer interpreter, while the rest of the codebase is held to 7.4 syntax. So a file called PhpEnumType can use the enum syntax introduced in PHP 8.1, and everything else cannot, which is a much more concrete statement about supported runtimes than a version range in a README would be.
make it runs fix, stan, test and docs, in that order
One target is the whole contributor loop. The `it` target depends on `fix stan test docs` and is described as running the commonly used targets, so a change is formatted, statically analysed, tested and has its documentation regenerated before anyone looks at it.
Each of those four is a thin wrapper. `fix` runs Rector through `composer rector`, php-cs-fixer in the Docker images described earlier, and prettier over the Markdown files with `npx --yes prettier --write --tab-width=2 '*.md' '**/*.md'`. `stan` runs `composer stan`, with a separate `baseline` target to regenerate the PHPStan baseline and a `phpstan.neon` target that writes a file including `phpstan.neon.dist`. `test` is `composer test`, and `bench` is `composer bench` against the `phpbench.json` configuration.
The supporting files match those targets. `rector.php` configures the automated refactoring, `.php-cs-fixer.php` configures the style rules, `phpstan.neon.dist` and `phpstan-baseline.neon` hold the static analysis configuration and its accepted findings, `phpunit.xml.dist` configures the test runner, and `renovate.json` keeps dependencies updated. A repository with this much tooling in the root is telling you it expects contributions, not just issues.
The class reference is generated, and it defines the public API
Documentation here is a build artefact rather than a folder of hand written pages. The `docs` target runs a PHP script and then formats the result:
php generate-class-reference.php
npx --yes prettier --write docs/class-reference.md`generate-class-reference.php` sits at the repository root and produces the class reference, which prettier then formats in place. `mkdocs.yml` is the configuration for the documentation site, and `docs/` holds the prose.
Now connect that to the versioning rule. The README says constants included in the class reference docs are part of the public API, which means this generated file is not just documentation, it is the definition of what is guaranteed stable. If a constant appears there, a change to it is a breaking change; if it does not, the tag on the element is what decides.
That is an unusual design for a compatibility promise, and it has a practical consequence for tooling. Anything that reads the class reference to decide what is safe to call is reading a generated file. `CHANGELOG.md` and `UPGRADE.md` also sit at the root.
The repository says it is moving, and the announcement is the only detail
The first two lines of the README are a move notice. This repository is planned to move to a new home, and the README links an announcement discussion for details and to share feedback. No destination, no date and no migration plan appear in the file itself.
For an adopter the practical questions are narrow. The composer package name in the installation line is `webonyx/graphql-php`, and that is what your `composer.json` depends on regardless of where the source lives. What the move changes for you is where you file issues, where you read the default branch, and whether your fork or your CI mirror needs repointing.
The rest of the root tells you what a mature library repository carries. There is a `SECURITY.md` for disclosure, a `CONTRIBUTING.md`, a `CHANGELOG.md`, an `UPGRADE.md` for people crossing major versions, `.codecov.yml` for coverage reporting, and a `benchmarks/` directory beside `tests/`. There are also `.ai/` and `.claude/` directories and an `ai-sync` target in the Makefile described as generating local agent configuration, which means the project ships machine readable instructions for coding agents alongside its human documentation.
Recent releases are v15.39.0, v15.38.5 and v15.38.4, all on 2026-10-25, and the last push was on 2026-11-02, so the fifteen line branch is where the work is.
Editorial conclusion
graphql-php suits a PHP team that wants the GraphQL specification rather than a framework opinion, and that reads the @api tag before it extends anything. It does not suit a team blocked on September 2025 specification features, since that compliance work is still in progress, and it does not suit anyone planning to depend on internals, because everything without the tag may move in a patch release. Before you adopt, confirm your required spec features against the October 2021 baseline, and read the move announcement before you fork, because the repository says it is planned to move to a new home.
Frequently asked questions
How do I install graphql-php?
One composer command: `composer require webonyx/graphql-php`. There is no service registration or extra configuration step described. Documentation is at webonyx.github.io/graphql-php and in the `docs` directory, and ready examples sit in `examples` with a README per example.
Is graphql-php compliant with the latest GraphQL specification?
It is fully compliant with the October 2021 GraphQL specification. Compliance with the September 2025 specification is in progress and tracked in issue 1931, so features from the newer edition are not available yet.
Which parts of graphql-php are safe to depend on?
The project follows Semantic Versioning 2.0.0 and guarantees stability within major versions only for elements marked with the `@api` PHPDoc tag and for constants included in the class reference documentation. Everything else may change between minor or patch versions.
Which graphql-php versions are still supported?
The most recent version is actively developed on the master branch. Older versions are generally no longer supported, although the README states that exceptions may be made for sponsors. Recent releases are v15.39.0, v15.38.5 and v15.38.4.
Which PHP versions does the graphql-php codebase target?
The Makefile runs php-cs-fixer inside php:7.4-cli-bullseye, php:8.0-cli-bullseye and php:8.1-cli-trixie images, restricting the newer interpreters to named files such as `src/Type/Definition/PhpEnumType.php`. The README itself does not state a minimum PHP version.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/webonyx-graphql-php)Star history chart for your README
[](https://hysenlabs.com/projects/webonyx-graphql-php)Was this useful?