Download the PHP package wedrix/watchtower without Composer

Watchtower

Watchtower helps you serve GraphQL APIs from Doctrine ORM entities without writing the same resolver boilerplate over and over. You provide a GraphQL SDL schema, point Watchtower at your Doctrine EntityManager, and add small plugin files only where your API needs custom behavior.

It is built on graphql-php and works well in Symfony, Slim, or any PHP application that already uses Doctrine ORM.

What You Get

• GraphQL queries backed by Doctrine entities and associations.
• Schema generation from Doctrine mappings to get started quickly.
• Offset and cursor pagination for collection fields.
• Plugin hooks for filters, ordering, computed fields, search, mutations, subscriptions, constraints, projections, and authorization.
• Custom scalar support through small PHP definition files.
• Production cache generation for schemas, plugins, and scalar definitions.

Requirements

• PHP ^8.0
• Doctrine ORM ^2.20 || ^3.3
• graphql-php ^15.30.2

Doctrine ORM 3 requires PHP 8.1 or newer.

Nested collection pagination with limit requires a database with SQL window function support, such as PostgreSQL, MySQL 8+, MariaDB 10.2+, SQLite 3.25+, SQL Server 2005+, Oracle, or DB2.

Installation

For Symfony applications, the companion bundle has framework-specific installation notes: github.com/Wedrix/watchtower-symfony-bundle

A Symfony demo application is available here: github.com/Wedrix/watchtower-symfony-demo-application

Project Layout

Watchtower only needs a few writable paths in your application:

The exact paths are up to your application. Use the same paths when creating the Console and Executor.

Basic Setup

Watchtower exposes two entry points:

• Wedrix\Watchtower\Console() for development tasks such as generating schemas, plugin stubs, scalar definitions, and production cache files.
• Wedrix\Watchtower\Executor() for running GraphQL operations in your HTTP endpoint, worker, or test harness.

Create a Console Helper

Wrap the Console object in whatever CLI system your project already uses.

Generate the starter SDL from Doctrine mappings:

Use the generated SDL as a starting point. generateSchema() creates entity query types and built-in scalar definitions for DateTime, Limit, Page, and Cursor when they do not already exist. Add mutations, subscriptions, enum/interface/union definitions, and custom computed fields to the SDL yourself.

After editing an existing SDL file, run schema:update if your application uses the schema cache. It clears stale schema cache files; it does not merge Doctrine mapping changes into your SDL.

Add a GraphQL Endpoint

In an HTTP endpoint, create an Executor and call executeQuery().

Pass framework services, request objects, users, tenants, or other application state through contextValue; plugins can read it from $node->context().

Schema Usage

Watchtower uses GraphQL SDL as the public contract for your API.

Top-level query fields can find entities by unique identifiers. Relation fields resolve automatically when the GraphQL field maps to a Doctrine association.

For compound keys, pass all fields that make a unique key. For example, if your SDL exposes a field like this:

query it with both key parts:

Through Associations

Direct Doctrine associations do not need extra SDL directives. If a field represents a relation through an explicit association entity, add @watchtowerAssociation.

The through value is the association field on the returned type.

Abstract Types

Enums, interfaces, and unions are normal SDL. Resolver, mutation, or search plugins that return interface or union results must include __typename.

Pagination

Collection fields are paginated through queryParams.

Use offset pagination with limit and optional page:

Use cursor pagination with after or before, usually with limit and a deterministic ordering:

Use the last returned row's _cursor as after for the next page, or the first returned row's _cursor as before for the previous page. If you maintain SDL manually, declare _cursor: Cursor on entity types where clients can request cursors:

Treat _cursor as an opaque string in clients. Pass the returned value back as after or before; clients do not need to decode or edit it.

Ordering plugins used with cursor pagination must call $queryBuilder->registerCursorOrdering() for every ordered value that belongs in the cursor. If a query uses multiple orderings, register cursor fields in the same order as the effective ORDER BY clauses. Include a stable unique tie-breaker, usually id, at the end.

If you need to create cursor values directly in tests or custom tooling, encode a JSON object with every registered cursor key:

Cursor pagination rules:

• Use either after or before, not both.
• Do not combine cursor pagination with page.
• Select at least one ordering that registers cursor fields.
• Include all registered cursor keys if you construct a cursor manually.

Plugins

Plugins are plain PHP files loaded from the configured pluginsDirectory. Use console helpers to generate the files, then fill in the application logic.

The console writes each plugin into the correct directory with the expected function name. Fill in the generated function body.

For addResultAuthorizorPlugin(), pass false for a single-object result authorizor and true for a collection result authorizor.

The generated namespace must stay as-is. For example, node authorizors use Wedrix\Watchtower\NodeAuthorizorPlugin, result authorizors use Wedrix\Watchtower\ResultAuthorizorPlugin, and mutations use Wedrix\Watchtower\MutationPlugin.

Filters

Expose filters in SDL:

Then implement the filter plugin:

Clients use it like this:

Sharing Joins Between Plugins

When a constraint, filter, ordering, or selector needs an association, use joinOnce() or leftJoinOnce() when the query should have exactly one join for that path. These methods follow Doctrine's join style and return the builder. If the same join already exists with a different alias, Watchtower throws so the duplicate shape is caught early.

When a plugin needs to reference the alias, ask for the join alias first:

For deeper paths, compose the chain explicitly and use the alias returned from each step:

Choose the join method that matches the data you want:

• Use joinOnce() when the association is required.
• Use leftJoinOnce() when rows without the association should remain.
• Use a separate join when you need a different join condition; duplicate-join checks treat the condition as part of the join identity.

Use selectAlias() for AS or AS HIDDEN aliases, and parameterName() for named parameters such as :tenantId.

For expensive association paths, add a query-shape test. Call $queryBuilder->assertNoDuplicateJoins() after your plugins have modified the query, or set WATCHTOWER_STRICT_QUERY_SHAPE=1 in test runs. If you want to make your own assertion, duplicateJoinPaths() returns repeated equivalent joins by path and alias.

Orderings

Expose orderings in SDL. Each ordering takes a required rank; lower ranks are applied first.

Implement the ordering plugin:

Use the optional fourth argument to pass the Doctrine/DBAL parameter type used when comparing cursor values.

Computed Fields

Use a selector when the value can be selected by the Doctrine query:

Use a resolver when the value comes from PHP code, another service, or an external API:

Resolvers and mutations can return null, int, bool, float, string, arrays, or values handled by custom scalars. Object results should be associative arrays; collection results should be lists.

Search

Add a search field to the collection query params and create a search resolver:

When queryParams.search is present and a search resolver exists for the type, return the full collection result from the search resolver. The resolver receives only the current Node; the context keys above are application-defined.

HydrationQuery(Node $node, EntityManager $entityManager, Plugins $plugins, bool $applyFilters = true) is optional. It returns a fresh Doctrine query with base selections, projections, constraints, and client filters applied. Pass false as the fourth argument to omit filters. Construct it only for the current node or another already-authorized node from the same search batch. It deliberately applies neither ordering nor pagination, which remain owned by the search provider. A resolver that skips hydration must provide any private values its result authorizors require.

Mutations

Declare mutations in SDL and implement the matching mutation plugin.

Constraints, Projections, Node Authorizors, and Result Authorizors

Use constraints to apply query restrictions before Doctrine fetches data, such as tenant scoping or soft-delete rules.

Use a node authorizor for rules that can be decided from the operation, arguments, selected fields, and context. It runs before Doctrine queries, search calls, resolvers, mutations, and subscriptions.

Use a projection to add private selects, shared joins, or parameters needed by downstream query plugins and result authorizors on every Doctrine hydration path.

Use result authorizors to validate resolved results across queries, search, mutations, and subscriptions.

For collections, Watchtower runs the root result authorizor once, the collection result authorizor once, and then the singular result authorizor for every non-null row. The singular result authorizor receives the original collection Node, so it can distinguish the collection path with isACollection(). Individual results keep the root-then-singular order.

Use constraints for mandatory database predicates, node authorizors for request-shape rules that must fail before work begins, and result authorizors for row-dependent checks.

Custom Scalars

Create a scalar definition stub:

This creates money_type_definition.php in scalar_type_definitions/. Implement serialize(), parseValue(), and parseLiteral() in the generated namespace:

Production Cache

While developing, use optimize: false so file edits are picked up without regenerating the cache.

For production:

1. Give each application release its own cache directory. Configure Console() and Executor() with the same directory for that release.
2. Generate the complete cache during deployment, before starting that release's request-serving workers. If generation fails, do not activate the release.
3. Create the executor with optimize: true.
4. When the schema, plugins, or scalar definitions change, generate a new release's cache instead of replacing the cache used by running workers.

Each cache file is published atomically, so readers cannot observe a partially written file. The schema, scalar definitions, and plugins are replaced separately, however; publication is not atomic across the complete set. Different releases must not share a cache directory, because their workers could read mismatched files. Workers using the same unchanged release may generate its cache concurrently.

The example below assumes __DIR__ belongs to an immutable release directory and var/cache is not shared with other releases. For an external cache location, include the release identifier in the path, such as /var/cache/my-app/release-123, and use that path for both the console and executor. Retain the old release's cache until its workers have stopped.

Security

Watchtower delegates execution to graphql-php. Use graphql-php validation rules, depth limits, complexity limits, authentication, and transport protections appropriate for your application: webonyx.github.io/graphql-php/security

Pass custom validation rules through $executor->executeQuery(..., validationRules: $rules).

Common Gotchas

• GraphQL names are case-sensitive, but PHP function and namespace names are not. Avoid type or field names that differ only by case.
• Doctrine entity class base names must be unique across the application. Do not use both App\Catalog\Product and App\Shop\Product in the same Watchtower schema.
• Composite association keys are supported only to one level of nesting.
• Avoid custom aliases or parameter names that start with __root, __parent, or __primary.
• For nested filters and orderings, avoid constraining the query to one concrete $node->parentId() unless the predicate is correct for every parent being resolved.

Development

Run the test suite:

Run grouped workflows:

Run Doctrine compatibility lanes:

Run static and formatting checks:

Versioning

This project follows Semantic Versioning 2.0.0.

Published releases are available at github.com/Wedrix/watchtower/releases.

Contributing

For significant features or breaking changes, please start a discussion in the repository first.

For smaller fixes:

1. Fork the project.
2. Make your changes.
3. Open a pull request.

Reporting Vulnerabilities

Send security reports to [email protected]. Security vulnerabilities will be addressed promptly.

License

Watchtower is open-source software distributed under the MIT license.