Building GraphQL APIs with PHP

# CHAPTER 18

Building GraphQL APIs with PHP #

1. Introduction #

2. Learning Objectives #

• Architect a clean folder structure for a PHP GraphQL API.

• Separate Schema definitions, Types, and Resolvers into distinct files.

• Manage database connections and pass them via the Context object.

• Understand how modern PHP frameworks (like Laravel) handle GraphQL.

3. Beginner-Friendly Explanation #

In PHP, putting all your GraphQL logic in one file is the giant pile. Architecture is separating it out. We will create a folder just for "Types", a folder for "Database Models", and a central "Router" that simply accepts the HTTP request and delegates the work. This makes your code clean, readable, and highly maintainable.

4. Real-World Examples #

• Custom PHP Backend: A lightweight API built without frameworks. It uses Composer for autoloading, PDO for MySQL connections, and strict directory structures for defining GraphQL Types.

• Laravel GraphQL (Lighthouse): In enterprise environments, developers use the Laravel framework alongside packages like Nuwave Lighthouse. Lighthouse allows you to write pure Schema SDL, and it automatically connects it to your Laravel Eloquent Database Models.

5. Recommended Folder Structure #

/my-graphql-api
|-- /src
|   |-- /Types          (Defines UserType.php, PostType.php)
|   |-- /Resolvers      (Functions that fetch data)
|   |-- /Models         (Database connection classes)
|   |-- Schema.php      (Combines all Types into Root Query/Mutation)
|-- /vendor             (Composer dependencies)
|-- composer.json
|-- index.php           (The single entry point / GraphQL endpoint)

6. The Entry Point (index.php) #

<?php
require &#039;vendor/autoload.php';

use GraphQL\GraphQL;
use App\Schema;
use App\Models\Database;

// 1. Initialize DB
$db = new Database(&#039;localhost', 'root', '', 'graphql_db');

// 2. Set Context
$context = [
    &#039;db' => $db,
    &#039;user' => authenticateUser() // Your auth logic
];

// 3. Get Payload
$rawInput = file_get_contents(&#039;php://input');
$input = json_decode($rawInput, true);
$query = $input[&#039;query'];
$variables = $input[&#039;variables'] ?? null;

// 4. Execute
$result = GraphQL::executeQuery(Schema::get(), $query, null, $context, $variables);
echo json_encode($result->toArray());
?>

7. Defining Types in Separate Files #

src/Types/UserType.php:

namespace App\Types;
use GraphQL\Type\Definition\ObjectType;
use GraphQL\Type\Definition\Type;

class UserType extends ObjectType {
    public function __construct() {
        $config = [
            'name' => 'User',
            'fields' => [
                'id' => Type::id(),
                'name' => Type::string(),
                'email' => Type::string()
            ]
        ];
        parent::__construct($config);
    }
}

8. Database Integration #

In the Resolver:

'resolve' => function($root, $args, $context) {
    // Uses the Database connection passed via Context
    return $context['db']->findUserById($args['id']);
}

9. Best Practices #

• Use PSR-4 Autoloading: Configure your composer.json to automatically load your classes from the /src directory. You should never use require_once manually for your classes.

• Keep index.php Clean: Your entry point should be less than 50 lines of code. All complex logic should be abstracted into classes.

• Consider a Framework: While building from scratch is great for learning, if you are building a commercial application in PHP, use a framework like Laravel or Symfony with a dedicated GraphQL package to save hundreds of hours of setup.

10. Common Mistakes #

• Circular Dependencies: When UserType requires PostType, and PostType requires UserType, PHP can get stuck in an infinite loop. The webonyx library solves this by allowing fields to be defined as a closure (an anonymous function function() { return [...] }) so they are evaluated lazily.

• Database Logic inside Types: Never put PDO/MySQL connection credentials inside your Type files. Always pass them down via the $context.

11. Mini Exercises #

1. 1. In the proposed folder structure, which folder contains the classes that directly interact with MySQL?

1. 2. Why is the database connection instantiated in index.php and passed into $context?

12. Coding Challenges #

13. MCQs with Answers #

14. Interview Questions #

• Q: Describe how you would organize the folder structure of a large-scale GraphQL application built in core PHP.

• Q: How do you solve circular dependency issues when defining GraphQL types that reference each other?

• Q: What is the benefit of using an established framework (like Lighthouse for Laravel) over building a GraphQL server from scratch?

15. FAQs #

16. Summary #

17. Next Chapter Recommendation #