GraphQL in Symfony mit API Platform: Wann es reicht und wann nicht

1. Was API Platform GraphQL automatisch generiert

API Platform ist ein Symfony-Framework für die Erstellung von API-first-Applikationen. Mit der optionalen GraphQL-Unterstützung (aktiviert durch das Paket api-platform/graphql) wird aus den annotierten PHP-Klassen automatisch ein vollständiges GraphQL-Schema generiert. Für jede API-Resource entstehen automatisch: eine Query für ein einzelnes Objekt, eine Query für Sammlungen mit Pagination, Mutations für Create, Update und Delete, sowie alle notwendigen Input- und Connection-Typen. Das ist ein erheblicher Geschwindigkeitsvorteil für einfache CRUD-APIs.

Die Schema-Generierung basiert auf Doctrine-Entities oder anderen PHP-Klassen, die mit dem #[ApiResource]-Attribut und optional #[ApiProperty]-Attributen annotiert sind. Felder können einzeln ein- oder ausgeschlossen werden, Serialization-Groups steuern, welche Daten in verschiedenen Kontexten sichtbar sind. Das Ergebnis ist ein GraphQL-Schema, das mit dem Datenmodell synchron ist – ohne manuelle SDL-Dateien pflegen zu müssen. Für schnelle Prototypen, interne Tools und einfache CRUD-Szenarien ist das ein echter Vorteil.

2. Grundkonfiguration: GraphQL in API Platform aktivieren

Die Aktivierung von GraphQL in API Platform erfordert wenige Konfigurationsschritte. Das GraphQL-Paket wird via Composer installiert, in der API Platform Konfiguration wird GraphQL aktiviert und optional GraphiQL für interaktives Schema-Exploring. Ab diesem Punkt wird jede #[ApiResource]-Klasse automatisch in das GraphQL-Schema aufgenommen. Die Standardoperationen – Query und Mutation für jede Resource – werden ohne weitere Konfiguration bereitgestellt. Zusätzliche GraphQL-Operationen können über Attribute direkt an der Klasse konfiguriert werden.

Ein wichtiger Unterschied zu manuell geschriebenen GraphQL-Schemata: In API Platform ist das Schema immer ein Spiegel des Datenmodells. Schema-Design-Entscheidungen, die vom Datenmodell abweichen, erfordern explizite Konfiguration oder Custom Resolver. Das ist gleichzeitig die größte Stärke (automatische Konsistenz) und die größte Schwäche (begrenzte Kontrolle über das exponierte Schema). Wer strikt domänenorientiertes Schema-Design bevorzugt, wo das Schema unabhängig vom Datenbankmodell definiert wird, stößt schnell an die Grenzen des automatischen Ansatzes.

# Auto-generated schema from API Platform — based on PHP Entity annotations
# This is what API Platform generates from #[ApiResource] classes

type Query {
  product(id: ID!): Product
  products(
    page: Int
    itemsPerPage: Int
    order: ProductFilter_order
    name: String
    name_list: [String]
    price: Float
    price_between: [Float]
  ): ProductCollection
}

type Mutation {
  createProduct(input: createProductInput!): createProductPayload
  updateProduct(input: updateProductInput!): updateProductPayload
  deleteProduct(input: deleteProductInput!): deleteProductPayload
}

type Product {
  id: ID!
  name: String!
  description: String
  price: Float!
  category: Category
  createdAt: String!
}

# API Platform generates Connection types for pagination
type ProductCollection {
  collection: [Product]
  paginationInfo: ProductPaginationInfo!
}

3. Stärken: wo der automatische Ansatz wirklich hilft

API Platform GraphQL ist besonders stark bei internen Verwaltungsapplikationen, bei denen das Datenmodell und das GraphQL-Schema eng zusammenliegen. Ein Admin-Backend für Content-Management, ein internes Dashboard für Auftragsverwaltung oder eine API für mobile Apps, die nur CRUD-Operationen benötigen – in diesen Szenarien ist der automatische Ansatz produktiv. Das Team pflegt nur PHP-Klassen, das Schema aktualisiert sich automatisch. Neue Felder an der Entity erscheinen sofort im Schema, ohne manuelle SDL-Aktualisierung.

Auch für schnelle API-Prototypen in frühen Projektphasen ist API Platform GraphQL wertvoll. Wenn das Datenmodell noch in Bewegung ist und das Team iterativ entwickelt, vermeidet der automatische Ansatz die doppelte Pflege von PHP-Code und GraphQL-Schema. Sobald das Projekt reifer wird und das Schema stabil werden muss, kann man von der automatischen Generierung zu mehr manueller Kontrolle übergehen, ohne die gesamte Architektur zu ändern. API Platform erlaubt diesen graduellen Übergang durch Custom Resolver und explizite Schema-Konfiguration.

4. Grenzen: wo die Automatik versagt

Die erste Grenze zeigt sich bei komplexen domänenspezifischen Mutations. Eine Mutation wie "Bestellung aufgeben" ist kein simples Create einer Order-Entity. Sie umfasst Lagerprüfungen, Preisberechnung, Zahlungsinitialisierung, E-Mail-Versand und Inventory-Reservierung. API Platform kann eine createOrder-Mutation generieren, aber die Geschäftslogik dahinter muss in einem Custom-State-Processor implementiert werden. Je komplexer die Geschäftslogik, desto mehr Konfiguration und Custom-Code ist nötig – bis der Vorteil der Automatik schwindet.

Die zweite Grenze ist fehlende Kontrolle über das generierte Schema. API Platform generiert Schema-Namen, Typen und Strukturen basierend auf PHP-Klassenamen und Annotationen. Das Ergebnis entspricht oft nicht dem domänenorientierten Schema-Design, das Frontend-Teams erwarten. Feldnamen, die von PHP-Konventionen (camelCase) abweichen, Connection-Types, die für einfache Fälle zu komplex sind, und automatisch generierte Filter, die für Frontend-Entwickler nicht selbsterklärend sind – all das erfordert zusätzliche Konfiguration, die die initiale Zeitersparnis wieder aufzehrt.

# Custom mutation in API Platform — when auto-generated CRUD is not enough
# Implemented via a custom MutationResolver class

type Mutation {
  # Auto-generated — simple CRUD
  createProduct(input: createProductInput!): createProductPayload

  # Custom mutation — complex domain operation
  placeOrder(input: PlaceOrderInput!): PlaceOrderPayload!
  applyDiscountCode(input: ApplyDiscountInput!): ApplyDiscountPayload!
  processReturn(input: ProcessReturnInput!): ProcessReturnPayload!
}

input PlaceOrderInput {
  clientMutationId: String
  cartId: ID!
  shippingMethodCode: String!
  paymentMethodCode: String!
  billingAddressId: ID!
  shippingAddressId: ID
}

type PlaceOrderPayload {
  clientMutationId: String
  order: Order
  userErrors: [PlaceOrderError!]!
}

type PlaceOrderError {
  code: PlaceOrderErrorCode!
  message: String!
  field: String
}

enum PlaceOrderErrorCode {
  OUT_OF_STOCK
  PAYMENT_FAILED
  INVALID_ADDRESS
  COUPON_EXPIRED
}

5. Custom Resolver und Mutations in API Platform

API Platform bietet zwei Erweiterungspunkte für benutzerdefinierte Logik: State Provider für Queries und State Processor für Mutations. Ein State Provider implementiert die Datenzugriffslogik für eine bestimmte Operation und ersetzt oder ergänzt die automatische Doctrine-Abfrage. Ein State Processor implementiert die Ausführungslogik für Create-, Update- und Delete-Operationen. Beide sind als PHP-Klassen implementiert, die über Dependency Injection konfiguriert werden.

Für komplett benutzerdefinierte Mutations, die keine Entsprechung in einer Doctrine-Entity haben, kann man das graphQlOperations-Attribut mit einer Mutation-Operation und einem Custom Resolver konfigurieren. Der Custom Resolver ist eine PHP-Klasse, die das MutationResolverInterface implementiert. Diese Flexibilität erlaubt es, API Platform als Rahmen zu nutzen und die automatische Generierung nur dort zu verwenden, wo sie passt, während komplexe Operationen vollständig manuell implementiert werden. Das Resultat ist oft ein hybrider Ansatz: einfache CRUD-Operationen automatisch, komplexe Domänenoperationen manuell.

6. Das N+1-Problem mit Doctrine und API Platform

Doctrine, das Standard-ORM in Symfony, lädt verknüpfte Entitäten standardmäßig lazy. In einem GraphQL-Kontext bedeutet das: Wenn eine Collection-Query eine Liste von Produkten zurückgibt und jedes Produkt seine zugehörige Kategorie exponiert, macht Doctrine für jedes Produkt eine separate SQL-Abfrage für die Kategorie. Bei 20 Produkten entstehen 21 Abfragen statt einer. Dieses N+1-Problem tritt automatisch auf, wenn API Platform Doctrine-Entitäten ohne spezifische Query-Optimierung exponiert.

API Platform und Doctrine bieten mehrere Lösungsansätze. Mit Eager Loading über fetch="EAGER" oder explizite JOIN FETCH-Abfragen in einem Custom State Provider werden verknüpfte Entitäten in einer einzigen Abfrage geladen. Der Doctrine DataLoader sammelt alle angeforderten IDs in einem Tick und löst sie in einer Batch-Abfrage auf. Für komplexere Szenarien kann ein Query Builder in einem Custom State Provider die exakt optimale Abfrage formulieren. Das Ergebnis ist aber immer mehr manueller Code – der Vorteil der automatischen Generierung nimmt mit der Komplexität der Beziehungen ab.

7. API Platform vs. handgefertigtes GraphQL: der Vergleich

Die Alternative zu API Platform in Symfony ist eine vollständig manuelle GraphQL-Implementierung mit der Bibliothek webonyx/graphql-php. Dabei werden SDL-Schema-Dateien manuell definiert, Resolver-Klassen manuell implementiert und der gesamte Request-Lifecycle manuell konfiguriert. Das erfordert mehr Initialaufwand, bietet aber vollständige Kontrolle über jedes Detail des Schemas und der Ausführungslogik. Ein handgefertigtes GraphQL-Schema ist oft sauberer domänenorientiert, leichter verständlich für Frontend-Teams und hat bessere Performance, weil Resolver-Ketten gezielt optimiert werden können.

Die Entscheidung ist keine binäre. Ein Hybrid-Ansatz ist für viele Projekte sinnvoll: API Platform für einfache CRUD-Operationen, die tatsächlich nur das Datenmodell exponieren, und handgefertigte Custom Resolver für komplexe Domänenoperationen. Das kombiniert die Geschwindigkeit der Automatik mit der Kontrolle des manuellen Ansatzes.

8. Vergleich mit Magento GraphQL

Magentos GraphQL-Implementierung ist vollständig handgefertigt: SDL-Dateien definieren das Schema, Resolver-Klassen implementieren die Ausführungslogik, und der Dependency-Injection-Container verbindet beides. Das bedeutet vollständige Kontrolle über jedes Detail des Schemas, erkauft durch mehr manuelle Arbeit. Wer ein eigenes Magento-Modul mit GraphQL-Unterstützung entwickelt, schreibt SDL-Dateien, Resolver-Klassen und konfiguriert die Resolver-Verknüpfungen in di.xml. Das ist präziser und performanter als API Platform, aber aufwändiger in der Erstentwicklung.

In Projekten, die sowohl Symfony als auch Magento einsetzen, stellt sich manchmal die Frage, welcher Ansatz für welchen Teil der Applikation geeignet ist. Magento handhabt Commerce-spezifische Logik (Katalog, Checkout, Kundenverwaltung) mit seinem handgefertigten GraphQL optimal. Symfony mit API Platform kann sinnvoll sein für angrenzende Services – zum Beispiel ein CMS-Service oder ein B2B-Portal –, bei denen einfachere CRUD-Operationen dominieren und die Entwicklungsgeschwindigkeit wichtiger ist als vollständige Schema-Kontrolle.

# Comparison: Magento handcrafted vs. API Platform auto-generated

# Magento: explicit SDL with domain-specific naming and types
# File: etc/schema.graphqls in custom module
type Query {
  customOrders(
    filter: CustomerOrdersFilterInput
    sort: CustomerOrderSortInput
    pageSize: Int = 20
    currentPage: Int = 1
    scope: ScopeTypeEnum
  ): CustomerOrders
}

type CustomerOrders {
  items: [CustomerOrder]!
  page_info: SearchResultPageInfo!
  total_count: Int!
}

# API Platform: auto-generated, Doctrine-coupled naming
# From: #[ApiResource] class Order {}
type Query {
  order(id: ID!): Order
  orders(
    page: Int
    itemsPerPage: Int
    order: OrderFilter_order
    status: String
    customer_id: Int
  ): OrderCollection
}
# Note: naming follows PHP class structure, not domain language

9. Entscheidungsbaum: wann welcher Ansatz?

Die Entscheidung zwischen API Platform GraphQL und handgefertigtem GraphQL hängt von mehreren Faktoren ab. API Platform ist die richtige Wahl, wenn das Projekt hauptsächlich CRUD-Operationen auf Doctrine-Entitäten exponiert, die Domain-Logik einfach ist und die Schema-Struktur eng am Datenmodell bleiben kann. Typische Szenarien: interne Admin-Tools, einfache REST-zu-GraphQL-Migrationen und Prototypen. In diesen Fällen spart die automatische Generierung erheblich Zeit und reduziert Boilerplate.

Handgefertigtes GraphQL ist die bessere Wahl, wenn das Projekt komplexe Domänenoperationen hat, die über simples CRUD hinausgehen, wenn das Schema gezielt für Frontend-Entwickler optimiert sein soll, wenn Performance-Optimierungen in Resolver-Ketten erforderlich sind oder wenn das Schema unabhängig vom Datenbankmodell weiterentwickelt werden muss. In Commerce-Projekten, wo Mutations wie "Bestellung aufgeben" oder "Rückgabe beantragen" viele Services koordinieren, ist der handgefertigte Ansatz fast immer die richtige Wahl – unabhängig davon, ob Magento oder ein Custom-Symfony-Projekt verwendet wird.

10. Zusammenfassung

API Platform GraphQL löst ein spezifisches Problem sehr gut: es macht CRUD-APIs mit GraphQL in kurzer Zeit produktiv. Wo das Schema direkt das Datenmodell widerspiegeln kann, wo die Geschäftslogik einfach ist und wo Entwicklungsgeschwindigkeit wichtiger als Schema-Kontrolle ist, spart API Platform signifikant Zeit. Die Grenzen zeigen sich bei komplexen Domänenoperationen, beim N+1-Problem mit Doctrine, bei der fehlenden Kontrolle über Schema-Naming und -Struktur, und wenn das Schema unabhängig vom Datenbankmodell wachsen soll.

Die praktische Empfehlung: API Platform als Startpunkt für neue Symfony-Projekte nutzen und gezielt mit Custom Resolvern und State Processors erweitern, wo die Automatik nicht ausreicht. Für Commerce-Projekte oder Systeme mit komplexer Domänenlogik ist von Anfang an in handgefertigtes GraphQL zu investieren. Der Magento-Ansatz – vollständig handgefertigt, vollständige Schema-Kontrolle, Resolver delegieren an Service-Klassen – ist die reifere aber aufwändigere Alternative, die sich bei wachsender Komplexität auszahlt.

11. FAQ: GraphQL in Symfony mit API Platform