Download the PHP package pomelchenko/yii2-graphql without Composer

yii-graphql

Using Facebook GraphQL PHP server implementation. Extends graphql-php to apply to YII2.

Languages: 中文

Originally created by tsingsun; continued development in this fork.

Features

• Configuration includes simplifying the definition of standard graphql protocols.
• Based on the full name defined by the type, implementing on-demand loading and lazy loading, and no need to define all type definitions into the system at load.
• Mutation input validation support.
• Provide controller integration and authorization support.

Install

Using composer

Requires PHP ≥ 7.4 and is tested against webonyx/graphql-php 14.x and ecodev/graphql-upload 6.1.x.

Before upgrading, review the version-by-version instructions in UPGRADE.md.

Development

Run PHP_CodeSniffer and PHPStan locally before opening PRs:

Type

The type system is the core of GraphQL, which is embodied in GraphQLType. By deconstructing the GraphQL protocol and using the graph-php library to achieve fine-grained control of all elements, it is convenient to extend the class according to its own needs

The main elements of GraphQLType

The following elements can be declared in the $attributes property of the class, or as a method, unless stated otherwise. This also applies to all elements after this.

Query

GraphQLQuery and GraphQLMutation inherit GraphQLField. The element structure is consistent, and if you would like a reusable Field, you can inherit it. Each query of Graphql needs to correspond to a GraphQLQuery object

The main elements of GraphQLField

Mutation

Definition is similar to GraphQLQuery, please refer to the above.

Inline query definitions

If you prefer not to create a dedicated GraphQLQuery class, schema entries may also be declared as plain arrays using the same structure that webonyx/graphql-php expects. Provide the type, args, and resolver (closure, callable array, etc.) directly in the configuration. GraphQL::type() can be referenced even before Yii::$app is instantiated, so simply pass the resulting Type:

This is useful for simple fields or when you already have reusable resolver classes. For more complex logic you can still rely on dedicated GraphQLQuery/GraphQLMutation classes so that type(), args(), resolve() and rules() remain encapsulated.

Simplified Field Definition

Simplifies the declarations of Field, removing the need to defined as an array with the type key.

Standard Definition

Simplified Definition

Yii Implementation

General configuration

JsonParser configuration required

Module support

Can easily be implemented by extending yii\graphql\GraphQLModule (or implementing GraphQLModuleInterface and using the trait). The trait is responsible for initialization.

In your application configuration file:

Use the controller to receive requests by using yii\graphql\GraphQLAction

Component Support

also you can include the trait with your own components,then initialization yourself.

Input validation

Validation rules are supported. In addition to graphql based validation, you can also use Yii Model validation, which is currently used for the validation of input parameters. The rules method is added directly to the mutation definition.

Mutation validation helper

GraphQLMutation ships with the yii\graphql\traits\ShouldValidate trait. Whenever your mutation defines rules() (same format as a regular Yii model), the trait wraps the resolver and calls DynamicModel::validateData() before resolve() executes. If validation fails, an InvalidParamException is thrown automatically and the resolver is not executed.

Custom validators, inline callbacks, and any other Yii rule syntax are fully supported, so you can reuse existing validation logic without duplicating it inside resolvers.

Authorization verification

Since graphql queries can be combined, such as when a query merges two query, and the two query have different authorization constraints, custom authentication is required. I refer to this query as "graphql actions"; when all graphql actions conditions are configured, it passes the authorization check.

Authenticate

In the behavior method of controller, the authorization method is set as follows

If you want to support IntrospectionQuery authorization, the corresponding graphql action is __schema

Authorization

If the user has passed authentication, you may want to check the access for the resource. You can use GraphqlAction's checkAccess method in the controller. It will check all graphql actions.

When checkAccess is configured, GraphQLAction invokes it for every requested GraphQL action even when CompositeAuth is not attached. Mutation transport and access-check requirements are available as opt-in hardening so existing applications keep their current behavior:

With these options enabled, the selected mutation must use POST as both the original HTTP transport method and Yii's effective method, and must have a configured checkAccess callback. Yii's _method parameter and X-Http-Method-Override header cannot upgrade a non-POST transport or downgrade a POST transport while satisfying requirePostForMutations. Applications that intentionally trust method overrides must set this flag to false and validate the proxy and override before GraphQLAction runs.

requirePostForMutations defaults to null: a non-POST mutation keeps the legacy behavior but emits an E_USER_DEPRECATED warning. Set it explicitly to false to retain that behavior without a warning; its default will become true in the next major release. requireAccessCheckForMutations defaults to false and remains opt-in. Mutation detection follows the operation selected by operationName, so other operations in the same document do not activate these requirements.

Multipart upload support

GraphQLAction detects operations/map payloads and delegates parsing to ecodev/graphql-upload. Ensure multipart/form-data requests include those keys so uploaded files are injected into GraphQL variables.

Testing

Run the test suite locally or via Docker:

This exercises the GraphQL facade, controller action, upload middleware, and custom types to guard against regressions when dependencies are upgraded.

GitLab release pipeline

When this repository is mirrored into GitLab (Settings → Repository → Mirroring repositories) and the Trigger pipelines when updates are mirrored option is enabled, GitLab creates a pipeline after a tag is mirrored. The bundled .gitlab-ci.yml includes the publish_package job only for tags in the strict MAJOR.MINOR.PATCH format without a v prefix (for example, 0.17.1). The job uses the GitLab Packages API plus the job token to update your private Composer registry entry based on CI_COMMIT_TAG, but it must be started manually by a maintainer.

Steps to publish a release:

1. Configure mirroring (or push from GitHub Actions) so GitLab sees every new tag.
2. Enable the “trigger pipelines” flag on the mirror or push directly so GitLab CI starts for mirrored updates.
3. Create and push a tag in the MAJOR.MINOR.PATCH format without a v prefix, such as 0.17.1.
4. After GitLab receives the tag, open the resulting pipeline and manually start publish_package. The Composer package is not published until this job is approved and started.

Demo

Creating queries based on graphql protocols

Each query corresponds to a GraphQLQuery file.

Define type files based on query protocols

Query instance

Exception Handling

You can config the error formater for graph. The default handle uses yii\graphql\ErrorFormatter, which optimizes the processing of Model validation results.

Future

• ActiveRecord tool for generating query and mutation class.
• Some of the special syntax for graphql, such as @Directives, has not been tested