GraphQL vs REST en PHP : que choisir pour votre projet en 2024 ?

GraphQL vs REST en PHP : guerre d'architectures ou outils pour différentes tâches ?

Lorsque vous ouvrez à nouveau votre éditeur de code pour écrire un nouvel endpoint pour votre application PHP, vous ne pouvez pas vous défaire d'un sentiment de déjà-vu. Créer un contrôleur encore une fois ? Écrire à nouveau la validation ? Et si vous essayiez quelque chose de nouveau ? Le débat entre GraphQL et REST dans le monde du développement PHP rappelle le débat éternel entre « Lara » et « Symfony » — chacun défend sa stack jusqu'à en perdre la voix. Mais soyons honnêtes : les deux approches ne sont pas une religion, ce sont des outils. Et aujourd'hui, nous allons les démonter pièce par pièce, regarder du code réel et décider quand l'API REST en PHP est votre choix, et quand il faut envisager GraphQL en PHP.

Petit rappel : qu'est-ce que c'est ?

REST (Representational State Transfer) est un style architectural basé sur les principes des ressources et des méthodes HTTP. Vous frappez à /api/users, vous obtenez une liste d'utilisateurs. Vous en voulez un seul ? Ajoutez /api/users/42. Tout est logique, prévisible et banal.

GraphQL est un langage de requêtes créé par Facebook. Vous n'êtes pas lié à une URL. Vous envoyez une seule requête à un endpoint unique (par exemple, /graphql) et vous dites : « Donne-moi le nom de l'utilisateur 42, ses 5 derniers articles et le nombre de likes pour chacun ». Le serveur renvoie exactement ce que vous avez demandé. Pas un octet de plus.

À première vue, GraphQL semble gagner haut la main. Mais ne vous précipitez pas pour jeter votre bon vieux REST. Chacun a ses pièges, surtout dans le contexte du développement en PHP.

Comparaison des architectures : de la théorie au code

REST : le classique

En PHP, REST est implémenté via le routage. Des frameworks comme Laravel ou Symfony le font avec élégance. Exemple d'un contrôleur REST typique sur Laravel :

<?php\n\nnamespace App\\Http\\Controllers\\Api;\n\nuse App\\Models\\User;\nuse Illuminate\\Http\\Request;\n\nclass UserController extends Controller\n{\n    public function index()\n    {\n        return User::all();\n    }\n\n    public function show($id)\n    {\n        $user = User::with('posts.comments')->findOrFail($id);\n        return response()->json($user);\n    }\n\n    public function store(Request $request)\n    {\n        $validated = $request->validate([\n            'name' => 'required|string',\n            'email' => 'required|email|unique:users',\n        ]);\n\n        $user = User::create($validated);\n        return response()->json($user, 201);\n    }\n}

Les avantages sont évidents : simplicité de la mise en cache (cache HTTP, Varnish), structure d'URL claire, large support d'outils (Postman, Swagger). Les inconvénients — le problème du sur-chargement (over-fetching) et du sous-chargement (under-fetching). Si le frontend n'a besoin que des noms des utilisateurs, mais que vous renvoyez tous les champs du modèle dans la réponse, c'est du sur-chargement. Si vous avez besoin du nom et de la liste d'amis, mais que vous faites deux requêtes, c'est du sous-chargement.

GraphQL : la flexibilité avec un piège

Pour implémenter GraphQL en PHP, il existe d'excellentes bibliothèques : webonyx/graphql-php (PHP pur) et lighthouse-php/lighthouse (pour Laravel). Exemple de schéma et de résolveur avec graphql-php :

<?php\n\nuse GraphQL\\GraphQL;\nuse GraphQL\\Type\\Definition\\ObjectType;\nuse GraphQL\\Type\\Definition\\Type;\nuse GraphQL\\Type\\Schema;\n\n$userType = new ObjectType([\n    'name' => 'User',\n    'fields' => [\n        'id' => Type::int(),\n        'name' => Type::string(),\n        'email' => Type::string(),\n        'posts' => [\n            'type' => Type::listOf($postType),\n            'resolve' => function ($user) {\n                return getPostsByUserId($user['id']);\n            }\n        ],\n    ],\n]);\n\n$queryType = new ObjectType([\n    'name' => 'Query',\n    'fields' => [\n        'user' => [\n            'type' => $userType,\n            'args' => [\n