PHP Academy · Pelajaran

Membangun Skema dengan graphql-php

Definisikan tipe dan skema dengan webonyx/graphql-php.

Membangun Skema dengan graphql-php adalah pelajaran PHP Academy gratis di CoddyKit. Ini adalah pelajaran 2 dari 4. Kamu bisa membaca pelajaran lengkapnya di bawah secara gratis — lalu praktikkan langsung di browser dengan editor kode bawaan dan tutor AI 24/7. Ini adalah bagian dari jalur belajar PHP Academy, dan progresmu tersinkronisasi di web dan aplikasi CoddyKit. Kursus PHP Academy mencakup 4 pelajaran total.

graphql-php: Implementasi Referensi

webonyx/graphql-php adalah port PHP de facto dari implementasi referensi GraphQL. Pustaka ini menyediakan sistem tipe, pengurai, pemeriksa, dan pelaksana. Anda mendefinisikan skema secara terprogram (objek PHP) atau dari SDL (mengutamakan skema). Dalam pelajaran ini, kita membangun skema secara manual agar Anda memahami fungsi setiap bagiannya.

composer require webonyx/graphql-php

Skalar dan Registri Tipe

Setiap nilai GraphQL pada akhirnya bermuara pada sebuah skalar: Int, Float, String, Boolean, ID. Dalam graphql-php, semua ini berada pada fasad Type. Karena tipe objek saling merujuk (termasuk merujuk pada dirinya sendiri), pola yang umum digunakan adalah TypeRegistry statis yang menyimpan memo setiap tipe sehingga Anda hanya membangunnya sekali.

<?php
use GraphQL\Type\Definition\Type;

// Built-in scalars, returned as singletons:
var_dump(Type::int()->name);     // "Int"
var_dump(Type::string()->name);  // "String"
var_dump(Type::id()->name);      // "ID"
var_dump(Type::nonNull(Type::string())->toString()); // "String!"

Mendefinisikan ObjectType

Sebuah ObjectType memiliki name dan peta fields. Setiap bidang menyatakan type-nya dan dapat memiliki panggilan balik resolve. Jika Anda menghilangkan resolve, graphql-php menggunakan penyelesai bawaan, yang membaca kunci larik atau properti/pengambil yang cocok dari nilai induk.

<?php
use GraphQL\Type\Definition\ObjectType;
use GraphQL\Type\Definition\Type;

$postType = new ObjectType([
    'name' => 'Post',
    'fields' => [
        'id'    => Type::nonNull(Type::id()),
        'title' => Type::nonNull(Type::string()),
        'body'  => Type::string(),
    ],
]);

Nilai Wajib dan Pembungkus Daftar

Tipe pembungkus menyatakan sifat boleh kosong dan kardinalitas:

Type::nonNull(T) → T! (tidak pernah null).
Type::listOf(T) → [T] (sebuah daftar, yang mungkin null dan mungkin memiliki anggota null).
[Post!]! = daftar yang tidak null berisi kiriman yang tidak null → nonNull(listOf(nonNull($postType))).

Pastikan ini benar: ini adalah kontrak null skema Anda dengan klien.

<?php
use GraphQL\Type\Definition\Type;

// [Post!]!  -- a required list whose elements are never null
$wrapped = Type::nonNull(Type::listOf(Type::nonNull(Type::string())));
echo $wrapped->toString(), "\n"; // [String!]!

Bidang Tertunda Memutus Referensi Melingkar

Sebuah User memiliki posts, dan sebuah Post memiliki author (seorang User). Untuk membangun tipe yang saling merujuk, berikan fields sebagai fungsi penutup, bukan larik. Fungsi tersebut dijalankan secara tertunda setelah kedua tipe tersedia, sehingga menghindari masalah ayam dan telur.

<?php
use GraphQL\Type\Definition\ObjectType;
use GraphQL\Type\Definition\Type;

class Types {
    private static array $cache = [];

    public static function user(): ObjectType {
        return self::$cache['User'] ??= new ObjectType([
            'name' => 'User',
            'fields' => fn() => [           // lazy!
                'id'    => Type::nonNull(Type::id()),
                'name'  => Type::nonNull(Type::string()),
                'posts' => Type::listOf(self::post()),
            ],
        ]);
    }

    public static function post(): ObjectType {
        return self::$cache['Post'] ??= new ObjectType([
            'name' => 'Post',
            'fields' => fn() => [
                'id'     => Type::nonNull(Type::id()),
                'title'  => Type::nonNull(Type::string()),
                'author' => self::user(),    // back-reference
            ],
        ]);
    }
}

Argumen Bidang

Bidang dapat menerima argumen. Deklarasikan argumen tersebut di bawah kunci args; argumen itu tiba sebagai parameter kedua ($args) penyelesai. Argumen itu sendiri bertipe, dapat bersifat wajib, dan dapat membawa defaultValue.

<?php
use GraphQL\Type\Definition\Type;

$userField = [
    'type' => Type::string(),
    'args' => [
        'id'     => Type::nonNull(Type::id()),
        'locale' => ['type' => Type::string(), 'defaultValue' => 'en'],
    ],
    'resolve' => fn($root, array $args) => "user {$args['id']} ({$args['locale']})",
];

Tipe Query Akar

Setiap skema memerlukan tipe akar Query—titik masuk yang dapat digunakan klien untuk memulai. Di sini kita menyediakan satu bidang hello agar dapat menjalankan proses secara menyeluruh. Argumen pertama penyelesai akar adalah rootValue skema (sering kali null).

<?php
use GraphQL\Type\Definition\ObjectType;
use GraphQL\Type\Definition\Type;

$queryType = new ObjectType([
    'name' => 'Query',
    'fields' => [
        'hello' => [
            'type' => Type::string(),
            'args' => ['name' => Type::nonNull(Type::string())],
            'resolve' => fn($root, array $args) => 'Hello, ' . $args['name'],
        ],
    ],
]);

Merakit dan Menjalankan Skema

Bungkus tipe kueri dalam sebuah Schema, lalu jalankan string kueri melalui GraphQL::executeQuery(). Objek hasilnya dikonversi menjadi larik kanonis { data, errors } melalui toArray().

<?php
require 'vendor/autoload.php';

use GraphQL\GraphQL;
use GraphQL\Type\Schema;
use GraphQL\Type\Definition\ObjectType;
use GraphQL\Type\Definition\Type;

$queryType = new ObjectType([
    'name' => 'Query',
    'fields' => [
        'hello' => [
            'type' => Type::string(),
            'args' => ['name' => Type::nonNull(Type::string())],
            'resolve' => fn($root, $args) => 'Hello, ' . $args['name'],
        ],
    ],
]);

$schema = new Schema(['query' => $queryType]);
$result = GraphQL::executeQuery($schema, '{ hello(name: "Ada") }');
echo json_encode($result->toArray());
// {"data":{"hello":"Hello, Ada"}}

Alternatif Mengutamakan Skema dengan BuildSchema

Jika Anda lebih menyukai SDL, BuildSchema::build() mengurai string skema menjadi skema yang dapat dijalankan. Setelah itu, Anda memasang penyelesai secara terpisah (misalnya, melalui panggilan balik penyelesai bidang), sehingga definisi tipe tetap deklaratif, sementara logika tetap berada di PHP.

<?php
use GraphQL\Utils\BuildSchema;

$sdl = <<<'GQL'
type Query {
  hello(name: String!): String
}
GQL;

$schema = BuildSchema::build($sdl);
// Provide resolvers via the executeQuery $fieldResolver argument
// or with a type config decorator.

Validasikan Sebelum Dirilis

graphql-php secara otomatis memvalidasi kueri yang masuk terhadap skema sebelum eksekusi. Anda juga dapat memastikan skema itu sendiri konsisten secara internal pada waktu pembangunan/CI dengan $schema->assertValid()—temukan salah ketik dan referensi yang rusak sebelum penerapan, bukan saat permintaan berlangsung.

<?php
use GraphQL\Type\Schema;

/** @var Schema $schema */
$schema->assertValid(); // throws InvariantViolation on a broken schema
echo "schema OK\n";

Enum dan Skalar Kustom

Selain objek, dua jenis tipe melengkapi sebagian besar skema. EnumType membatasi sebuah bidang pada sekumpulan nilai bernama yang tetap. CustomScalarType memungkinkan Anda mendefinisikan skalar domain (DateTime, surel) dengan logika serialize/parseValue/parseLiteral sendiri, sehingga nilai divalidasi dan dinormalisasi di batas masuk.

<?php
use GraphQL\Type\Definition\EnumType;

$statusEnum = new EnumType([
    'name' => 'PostStatus',
    'values' => [
        'DRAFT'     => ['value' => 0],
        'PUBLISHED' => ['value' => 1],
        'ARCHIVED'  => ['value' => 2],
    ],
]);
// A field typed as $statusEnum only accepts DRAFT/PUBLISHED/ARCHIVED.

Pemeriksaan Singkat

Mengapa fields diberikan sebagai fungsi penutup?

Rangkuman

Anda telah membangun skema dari awal:

Skalar dan tipe pembungkus (nonNull, listOf) menyatakan kontrak boleh kosong/kardinalitas.
ObjectType dengan peta bidang (atau fungsi penutup tertunda) mendefinisikan bentuk data Anda.
Registri tipe yang menyimpan memo menangani referensi melingkar.
Bidang menerima args bertipe; tipe akar Query adalah titik masuk.
GraphQL::executeQuery() menjalankannya; assertValid() melindungi skema dalam CI.

Berikutnya: penyelesai, mutasi, dan langganan.

Pertanyaan yang Sering Diajukan

Apakah pelajaran “Membangun Skema dengan graphql-php” gratis?

Ya — teks lengkap “Membangun Skema dengan graphql-php” gratis dibaca di sini di web. Untuk praktiknya secara interaktif (editor kode bawaan dan tutor AI 24/7) dan buka sisa kursus PHP Academy, upgrade ke CoddyKit PRO. Kursus PHP Academy mencakup 4 pelajaran total.

Apa yang akan aku pelajari di “Membangun Skema dengan graphql-php”?

Definisikan tipe dan skema dengan webonyx/graphql-php. Kamu berlatih PHP Academy dengan kode praktik yang langsung kamu jalankan di browser, dan tutor AI 24/7 menjawab pertanyaanmu saat kamu mengerjakan pelajaran ini.

Apakah aku perlu pengalaman untuk memulai PHP Academy?

Tidak diperlukan pengalaman sebelumnya. PHP Academy di CoddyKit dirancang untuk pemula hingga pelajar tingkat lanjut, jadi kamu bisa memulai di sini atau dari awal dan belajar sesuai kecepatan kamu sendiri. Ini adalah pelajaran 2 dari 4.

Berapa lama pelajaran “Membangun Skema dengan graphql-php” memakan waktu?

Sebagian besar pelajaran CoddyKit memakan waktu sekitar 5–10 menit. Setiap pelajaran ringkas dan interaktif, jadi kamu membuat kemajuan stabil dan melanjutkan dari tempat kamu tinggalkan di web dan aplikasi.

Bisakah aku menulis dan menjalankan kode dalam pelajaran PHP Academy ini?

Ya. Setiap pelajaran PHP Academy menyertakan editor kode bawaan, jadi kamu menulis dan menjalankan kode nyata langsung di browser dan mendapatkan umpan balik AI instan — tidak diperlukan penyiapan lokal.

Semua pelajaran dalam kursus ini

← Kembali ke PHP Academy