Df Graphql Laravel Package

Getting Started

dreamfactory/df-graphql is not a general-purpose Laravel package — it is a DreamFactory platform plugin that bolts a GraphQL service type onto a DreamFactory instance. You cannot composer require it into an arbitrary Laravel app and get a GraphQL server; it assumes df-core, the DreamFactory service container, its auth model, and its admin UI. Treat it as "configuration of a running DreamFactory" rather than "a library you code against."

Minimal path:

1. Stand up DreamFactory 4.x+ (Docker is the least painful route: docker run -d -p 80:80 dreamfactorysoftware/df-docker), complete the setup wizard, and confirm the admin UI loads.
2. Install the plugin into the platform's composer root, not your app:

   composer require dreamfactory/df-graphql
   php artisan df:setup
   php artisan config:clear && php artisan cache:clear
   

3. In Admin → Services, create a new service of type GraphQL, give it a name/API key, and select which existing services (a SQL DB, a REST connector, etc.) it should expose.
4. Hit the endpoint: POST /api/v2/{api_key}/{graphql_service_name} with your API key header.

Where to look first: the package's src/ for the service provider and service type class, config/ for any schema/exposure defaults, and the DreamFactory admin service definition screen — the UI is where 90% of the real behavior lives. The DreamFactory docs for the GraphQL service are more useful than the repo README.

First use case: expose an existing SQL database service as GraphQL so a frontend can fetch a nested record in one round trip instead of three REST calls:

query {
  todo_item(limit: 10) {
    id
    name
    complete
  }
}

Implementation Patterns

Facade over REST, not hand-written resolvers. The dominant pattern is: configure a DreamFactory service (database, Salesforce, S3, custom script), then let the GraphQL service auto-generate types, queries, and CRUD mutations from it. You are not writing resolve() functions for the common case — you are curating exposure.

Scoped endpoints per consumer. Create multiple GraphQL services (e.g. graphql_public, graphql_admin) each exposing a different subset of underlying services. This is the package's main lever for API surface control and pairs naturally with DreamFactory roles/API keys.

CRUD mutations for database-backed services. For SQL services you get generated create_*, update_*, delete_* mutations with the table's fields as inputs. Non-database services are typically read-only or expose only what their REST verbs support.

Client integration. From a Laravel or JS client, point Apollo/urql at the endpoint with the DreamFactory auth headers:

Http::withHeaders([
    'X-DreamFactory-API-Key' => config('services.df.key'),
    'X-DreamFactory-Session-Token' => $sessionToken,
])->post(config('services.df.url').'/api/v2/'.$apiKey.'/graphql_public', [
    'query' => $query,
    'variables' => $vars,
]);

Schema customization. For anything the auto-generator gets wrong (naming, hiding a column, aliasing a relationship), the extension point is the schema/config layer plus a custom DreamFactory service in front of the awkward backend — not subclassing the GraphQL service. Keep custom logic in the underlying service where DreamFactory's scripting (V8/PHP) and role checks already apply.

Caching. Persist the schema and cache introspection results; rebuilding it on every request against a large database is where this package hurts.

Gotchas and Tips

• Version lockstep is the whole game. df-graphql is a thin plugin against a moving df-core. The last tagged release is early 2023 and the repo has essentially no community around it, so pin both dreamfactory/df-core and this package and test upgrades in a staging instance. Do not assume "latest of each" composes.
• Auth failures look like schema failures. A 401 from the underlying service often surfaces as a GraphQL field error rather than a clean auth error. Check the DreamFactory log (storage/logs/) and the underlying service's own endpoint before blaming GraphQL.
• Introspection and the schema cache. After adding a column or a new service, the schema will appear stale until you clear the DreamFactory cache and, if enabled, the schema cache. Disable introspection in production but remember your tooling (GraphiQL, codegen) needs it during development.
• No DataLoader. Nested selections can translate into per-field REST calls against the backing service. Flatten queries, use limit, and watch backend logs for N+1 patterns — this is the most common performance complaint.
• Filter/pagination arguments leak through. DreamFactory's filter, limit, offset, order conventions appear as GraphQL args and don't always match idiomatic GraphQL pagination (cursors, connections). Plan client code accordingly.
• Error shape is DreamFactory's, not the GraphQL spec's. Wrap client error handling; don't assume extensions.code conventions from Apollo-land.
• Debugging levers: APP_DEBUG=true on the DreamFactory instance, GraphiQL at the service endpoint, direct REST calls to the underlying service to isolate whether a bug is GraphQL-layer or backend-layer.
• Maturity risk is real. One star, zero dependents, ~2-year-old release. For greenfield work, evaluate whether DreamFactory's built-in GraphQL support (if your platform version already ships it) or a standalone Laravel GraphQL stack (Lighthouse, webonyx directly) is a better fit before adopting this.