Performance Characteristics 

TypoGraph implements a DataLoader pattern to prevent N+1 query problems:

• Batch Loading: All related records are fetched in a single optimised query per relation type
• Request-Scoped Caching: Each record is loaded only once per GraphQL request
• Field Selection: Only fields requested in the GraphQL query are fetched from the database
• Order Preservation: Related records are returned in the same order as stored (respects MM table sorting)

For example, querying 100 research disciplines with related entries for experts in these disciplines from a research information database results in only two database queries: one query for all taxonomies and one query for all unique disciplines referenced by those taxonomies.

Origins 

This extension has been developed by the Digital Academy of the Academy of Sciences and Literature | Mainz while refactoring on the research information system Portal Kleine Fächer, which provides detailed information on minor subjects at German universities and other institutions of higher education. The examples in this documentation still reflect this initial context.

AI Note 

The initial basic extension design has been completely done by humans. However, developers of this extension use Claude Code (Sonnet 4.5, 4.6; Opus 4.6) to streamline routine tasks, upgrades, improve code quality etc. All changes depending on AI (as far as we are aware) are confirmed by a qualified human software developer before merged into the main branch.

Why Relations Need Configuration 

Unlike scalar fields (strings, integers), object-type fields require the TypoGraph extension to:

1. Identify which database column stores the relation reference
2. Know which table to query for the related records
3. Understand the storage format (single UID, comma-separated UIDs, or MM table)

Without explicit configuration, TypoGraph will log a warning and return null for unconfigured relations.

Relation Configuration Structure 

Relations are configured under the typograph.relations key in the site configuration, nested as <TypeName>: <fieldName>: <config>:

typograph:
  relations:
    TypeName:
      fieldName:
        sourceField: database_column_name
        targetType: RelatedTypeName
        storageType: uid  # uid | commaSeparated | mmTable | foreignKey

        # Additional fields for mmTable storage type:
        mmTable: tx_some_mm_table
        mmSourceField: uid_local
        mmTargetField: uid_foreign
        mmSortingField: sorting

        # Additional fields for foreignKey storage type:
        foreignKeyField: column_in_target_table

Configuration Fields 

Storage Types 

The following variants are available for the storageType field.

tx_taxonomy table:
  uid: 1
  name: "Computer Science"
  main_discipline: 42  ← Single UID

type Taxonomy {
  name: String
  mainDiscipline: Discipline
}

typograph:
  relations:
    Taxonomy:
      mainDiscipline:
        sourceField: main_discipline
        targetType: Discipline
        storageType: uid

tx_taxonomy table:
  uid: 1
  name: "Computer Science"
  disciplines: "12,45,78"  ← Comma-separated UIDs

type Taxonomy {
  name: String
  disciplines: [Discipline]
}

typograph:
  relations:
    Taxonomy:
      disciplines:
        sourceField: disciplines
        targetType: Discipline
        storageType: commaSeparated

tx_expert table:
  uid: 5
  name: "Dr. Smith"

tx_expert_discipline_mm table:
  uid_local: 5      ← References expert
  uid_foreign: 12   ← References discipline
  sorting: 1

tx_discipline table:
  uid: 12
  name: "Physics"

type Expert {
  name: String
  disciplines: [Discipline]
}

typograph:
  relations:
    Expert:
      disciplines:
        targetType: Discipline
        storageType: mmTable
        mmTable: tx_expert_discipline_mm
        mmSourceField: uid_local
        mmTargetField: uid_foreign
        mmSortingField: sorting

tx_taxonomy table:
  uid: 5
  name: "Applied Sciences"

tx_discipline table:
  uid: 1
  name: "Physics"
  discipline_taxonomy: 5  ← Foreign key pointing to taxonomy

tx_discipline table:
  uid: 2
  name: "Physics"          ← Same name, different record
  discipline_taxonomy: 5  ← Same taxonomy reference

tx_discipline table:
  uid: 3
  name: "Chemistry"
  discipline_taxonomy: 5  ← Another discipline for same taxonomy

type Taxonomy {
  name: String
  disciplines: [Discipline]
}

type Discipline {
  name: String
}

typograph:
  relations:
    Taxonomy:
      disciplines:
        targetType: Discipline
        storageType: foreignKey
        foreignKeyField: discipline_taxonomy

Complete Configuration Example 

This is a complete example with multiple relation types:

typograph:

  # Schema files
  schemaFiles:
    - 'EXT:pkf_website/Resources/Private/Schemas/Query.graphql'
    - 'EXT:pkf_website/Resources/Private/Schemas/Taxonomy.graphql'
    - 'EXT:pkf_website/Resources/Private/Schemas/Discipline.graphql'
    - 'EXT:pkf_website/Resources/Private/Schemas/Expert.graphql'

  # Root elements to tables mapping
  tableMapping:
    disciplines: tx_dmdb_domain_model_discipline
    experts: tx_academy_domain_model_persons
    taxonomies: tx_dmdb_domain_model_discipline_taxonomy

  # Relation configuration
  relations:

    Taxonomy:
      # Single UID relation
      mainDiscipline:
        sourceField: main_discipline
        targetType: Discipline
        storageType: uid

      # Comma-separated UIDs relation
      disciplines:
        sourceField: disciplines
        targetType: Discipline
        storageType: commaSeparated

      # Foreign key relation (inverse/legacy MM)
      relatedDisciplines:
        targetType: Discipline
        storageType: foreignKey
        foreignKeyField: discipline_taxonomy

    Expert:
      # MM table relation
      disciplines:
        targetType: Discipline
        storageType: mmTable
        mmTable: tx_academy_persons_discipline_mm
        mmSourceField: uid_local
        mmTargetField: uid_foreign
        mmSortingField: sorting

GraphQL Query Example 

With the configuration above, you can now query nested relations:

{
  experts {
    familyName
    givenName
    disciplines {
      name
    }
  }
}

Configuration Structure 

Transforms are configured under the typograph.fieldTransforms key in the site configuration, nested as <TypeName>: <fieldName>: <transformName>:

typograph:
  fieldTransforms:
    TypeName:
      fieldName: transformName

Keys follow GraphQL naming: TypeName matches a type in your schema (e.g. Content) and fieldName matches a field on that type (e.g. bodytext). Internally the resolver converts the field name to the corresponding database column name via camelCaseToLowerCaseUnderscored, the same conversion used everywhere else in TypoGraph.

Built-In Transforms 

typograph:
  fieldTransforms:
    Content:
      bodytext: typolinks

<p>See <a href="t3://page?uid=76#64">this page</a> for details.</p>

<p>See <a href="/path/to/page/#c64">this page</a> for details.</p>

TSFE-Related Caveats 

Because TypoGraph's middleware runs before typo3/cms-frontend/page-resolver, there is no running TypoScriptFrontendController. LinkFactory copes with this by lazily building a minimal TSFE from the request attributes attached by the earlier typo3/cms-frontend/site middleware (site, language, routing). This is sufficient for all built-in link types.

TypoScript-driven link behaviour such as config.linkVars, config.forceAbsoluteUrls, or custom typolinkBuilder entries is not applied, because the full TypoScript setup is never loaded. If your site relies on any of those, configure the equivalent at a different level (e.g. absolute URLs via Site configuration).

Full lib.parseFunc_RTE processing (paragraph wrapping, <br> handling, HTML-sanitizer integration, …) is not available from this middleware position because it depends on the TypoScript setup array being populated by the regular frontend pipeline. The typolinks transform deliberately scopes itself to link rewriting for this reason.

Registering Custom Transforms 

To add your own transform, implement Digicademy\\TypoGraph\\Transformer\\TransformerInterface and register it under a short name in Configuration/Services.yaml:

<?php

declare(strict_types=1);

namespace Vendor\Sitepackage\Transformer;

use Digicademy\TypoGraph\Transformer\TransformerInterface;
use Psr\Http\Message\ServerRequestInterface;

final class MyCustomTransformer implements TransformerInterface
{
    public function transform(mixed $value, ServerRequestInterface $request): mixed
    {
        // return $value unchanged when it is not of a type you handle
        if (!is_string($value)) {
            return $value;
        }
        // …your post-processing…
        return $value;
    }
}

services:
  _defaults:
    autowire: true
    autoconfigure: true
    public: false

  Vendor\Sitepackage\:
    resource: '../Classes/*'

  # Extend the TransformerRegistry provided by TypoGraph with the
  # new transform under a short name. Keep the `typolinks` entry so
  # the built-in transform remains available alongside yours.
  Digicademy\TypoGraph\Transformer\TransformerRegistry:
    arguments:
      $transformers:
        typolinks: '@Digicademy\TypoGraph\Transformer\TypolinksTransformer'
        myCustom: '@Vendor\Sitepackage\Transformer\MyCustomTransformer'

Transforms must:

• Return the input unchanged for value types they do not handle.
• Avoid throwing for unexpected inputs. The resolver logs and swallows exceptions so that one misbehaving transform does not abort the entire GraphQL response, but logging contributes noise; prefer a defensive early return.

Error Behaviour 

• If a configured transform name has no entry in the registry, the resolver logs a warning and leaves the raw value in place. This is usually a typo in site configuration or a missing DI wiring.
• If a transform throws, the resolver logs an error and leaves the raw value in place for the affected record.
• If the current request is not attached (only possible when calling ResolverService::process() directly without a request), transforms are skipped entirely.

How It Works 

When a root query field returns a Connection type (a type whose name ends with Connection), TypoGraph automatically applies cursor-based pagination. If the return type is a plain list (e.g. [Discipline]), the resolver behaves as before and no pagination is applied.

Cursors are opaque, base64-encoded strings. Clients should treat them as opaque tokens and never parse or construct them manually.

Schema Setup 

To enable pagination for a type, you need to define three types in your GraphQL schema and include the shared Pagination.graphql schema file provided by the TypoGraph extension.

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

typograph:
  schemaFiles:
    - 'EXT:typograph/Resources/Private/Schemas/Pagination.graphql'
    - 'EXT:sitepackage/Resources/Private/Schemas/Query.graphql'
    # ...

type Expert {
  familyName: String
  givenName: String
}

type ExpertConnection {
  edges: [ExpertEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type ExpertEdge {
  cursor: String!
  node: Expert!
}

type Query {
  experts(familyName: String): [Expert]
  expertsConnection(familyName: String, first: Int, after: String): ExpertConnection
}

Pagination Configuration 

Configure default and maximum page sizes in the site configuration:

typograph:
  pagination:
    defaultLimit: 20
    maxLimit: 100

Querying With Pagination 

Using the pagination arguments first and after, or last and before allows for fine-grained pagination that can be combined the the usual filter arguments.

{
  expertsConnection(first: 10) {
    edges {
      cursor
      node {
        familyName
        givenName
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

{
  expertsConnection(first: 10, after: "Y3Vyc29yOjQy") {
    edges {
      cursor
      node {
        familyName
        givenName
      }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      endCursor
    }
  }
}

{
  expertsConnection(familyName: "Smith", first: 5) {
    edges {
      node {
        familyName
        givenName
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

Response Structure 

{
  "data": {
    "expertsConnection": {
      "edges": [
        {
          "cursor": "Y3Vyc29yOjE=",
          "node": {
            "familyName": "Smith",
            "givenName": "Jane"
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "hasPreviousPage": false,
        "startCursor": "Y3Vyc29yOjE=",
        "endCursor": "Y3Vyc29yOjE="
      },
      "totalCount": 42
    }
  }
}

How It Works 

Sorting is based on two components:

1. A ComparatorInterface implementation injected via dependency injection. This defines how strings are compared (e.g. locale-aware collation).
2. A sortBy argument on the GraphQL query that specifies which field to sort by.

When both are present, TypoGraph applies the comparator to sort result sets. When either is absent, results are returned in their default order (UID for connection queries, database default for plain lists).

Sorting Behaviour 

Sorting behaviour differs depending on the query type:

Plain list queries (e.g. [Expert])

The full result set is sorted by the comparator before being returned.

Connection queries (e.g. ExpertConnection)

Cursor-based pagination relies on UID ordering for stable pagination across pages. The comparator sorts records within the current page only after the database query and pagination slicing. This means the overall page boundaries are determined by UID order, but the records within each page are reordered by the comparator.

Using the sortBy Argument 

Clients specify which field to sort by using the sortBy argument on a query field. To enable this, add sortBy: String to the relevant query fields in your GraphQL schema:

type Query {
  experts(sortBy: String): [Expert]
  expertsConnection(sortBy: String, first: Int, after: String): ExpertConnection
}

The sortBy value should be the camelCase GraphQL field name (e.g. familyName). TypoGraph converts it to the snake_case database column name automatically.

{
  experts(sortBy: "familyName") {
    familyName
    givenName
  }
}

When sortBy is omitted, no comparator-based sorting is applied and results are returned in their default database order.

Nonexistent fields: If the sortBy value refers to a field that does not exist in the result records, sorting is silently skipped and the original order is preserved.

Implementing a Custom Comparator 

TypoGraph ships a ComparatorInterface with a single method:

namespace Digicademy\TypoGraph\Comparator;

interface ComparatorInterface
{
    public function compare(string $a, string $b): int;
}

The method follows PHP's standard comparison contract: return a negative integer if $a < $b, zero if equal, or a positive integer if $a > $b.

To provide a custom comparator, create a class implementing this interface in your sitepackage or extension:

namespace Vendor\MySitepackage\Comparator;

use Digicademy\TypoGraph\Comparator\ComparatorInterface;

class LocalizedComparator implements ComparatorInterface
{
    private static array $collators = [];

    public function compare(string $a, string $b): int
    {
        if (!isset(self::$collators['de_DE'])) {
            self::$collators['de_DE'] = \Collator::create('de_DE');
        }

        return self::$collators['de_DE']->compare($a, $b);
    }
}

Then register your implementation as the ComparatorInterface service in your extension's Services.yaml:

services:
  Digicademy\TypoGraph\Comparator\ComparatorInterface:
    class: Vendor\MySitepackage\Comparator\LocalizedComparator

TypoGraph's ResolverService accepts the comparator as an optional constructor dependency. When no implementation is registered, the parameter defaults to null and no custom sorting is applied.

Complete Example 

Given this schema and configuration:

type Query {
  experts(sortBy: String): [Expert]
  expertsConnection(sortBy: String, first: Int, after: String): ExpertConnection
}

type Expert {
  familyName: String
  givenName: String
}

A plain list query sorted by family name:

{
  experts(sortBy: "familyName") {
    familyName
    givenName
  }
}

The same type sorted by a different field:

{
  experts(sortBy: "givenName") {
    familyName
    givenName
  }
}

A connection query sorts records within each page:

{
  expertsConnection(sortBy: "familyName", first: 10) {
    edges {
      node {
        familyName
        givenName
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

How It Works 

Custom resolving depends on two components:

1. A CustomResolverInterface implementation that handles one specific root field name. It receives the GraphQL arguments, ResolveInfo, and (optionally) the current PSR-7 request, and returns the resolved value in whatever shape the schema expects.
2. A CustomResolverRegistry that collects every implementation registered in the DI container via a tagged iterator. Its get(string $fieldName) returns the handler for a given field, or null if none is registered.

TypoGraph's ResolverService consults the registry at the start of every Query-level resolve call. When a custom resolver matches the current field name, its return value is used directly and the default tableMapping dispatch is skipped for that field. When no custom resolver matches, resolution falls through to the regular tableMapping path and there is no behaviour change for existing fields.

The customResolverRegistry constructor argument of ResolverService is nullable; when absent (e.g., in projects that do not register any custom resolver), the feature has zero runtime cost.

When to Use a Custom Resolver 

Use a custom resolver when a root field:

• Aggregates across multiple tables in a way tableMapping cannot express (joins, sums, pivots).
• Delegates to an existing service whose result shape already matches the GraphQL type (no reason to duplicate the logic in the schema).
• Needs arguments or behaviour that do not fit the standard equality filters TypoGraph derives from each root field's arguments (e.g., enum-valued partitioning parameters).

Prefer plain tableMapping when the field really is "list rows from one table, optionally filter and paginate". That path is declarative and gets cursor pagination, sortBy, and field transforms for free.

Implementing the Interface 

CustomResolverInterface has two methods:

namespace Digicademy\TypoGraph\CustomResolver;

use GraphQL\Type\Definition\ResolveInfo;
use Psr\Http\Message\ServerRequestInterface;

interface CustomResolverInterface
{
    public function getFieldName(): string;

    public function resolve(
        array $args,
        ResolveInfo $info,
        ?ServerRequestInterface $request
    ): mixed;
}

getFieldName() must return the exact name of the Query root field this resolver handles. It is used as the lookup key in the registry, so a field name collision between two resolvers is a configuration error (see the section on collisions below).

resolve() receives the GraphQL arguments (associative array keyed by the argument name from the schema), the ResolveInfo object (exposing the selection set and return type), and the current PSR-7 request if one is attached to the resolve call.

The return value must match the schema's declared return type. Once it is returned, TypoGraph's nested resolution logic walks the structure as usual, so associative arrays and plain objects with matching properties both work.

Registering a Resolver 

Every CustomResolverInterface implementation is auto-tagged with typograph.custom_resolver by the _instanceof rule in EXT:typograph/Configuration/Services.yaml. The CustomResolverRegistry receives a !tagged_iterator argument populated from that tag.

Important Symfony DI detail: _instanceof is file-local. A rule declared in one extension's Services.yaml does not apply to services declared in a different extension's Services.yaml. Consuming extensions must repeat the rule in their own Services.yaml so their resolver services pick up the tag:

services:
  _defaults:
    autowire: true
    autoconfigure: true
    public: false

  # Repeat TypoGraph's tagging rule so our CustomResolverInterface
  # implementations become part of the CustomResolverRegistry's
  # tagged iterator.
  _instanceof:
    Digicademy\TypoGraph\CustomResolver\CustomResolverInterface:
      tags: ['typograph.custom_resolver']

  Vendor\Sitepackage\:
    resource: '../Classes/*'

No explicit service entry for the resolver class is required — the resource: glob picks it up, and the _instanceof rule tags it.

Registering the Field in the Schema 

A custom resolver only dispatches for fields declared in the GraphQL schema. Add the field to Query.graphql (or wherever your root type lives) like any other:

type Query {
  # …regular tableMapping-backed fields…

  disciplineStats: [DisciplineStat!]!
}

Types referenced by a custom-resolved field must be declared in a schema file loaded before the one that references them. TypoGraph concatenates the files listed in typograph.schemaFiles in order, so put the types' schema file earlier in the list than Query.graphql (the Stats schema in this example):

typograph:
  schemaFiles:
    - 'EXT:typograph/Resources/Private/Schemas/Pagination.graphql'
    - 'EXT:sitepackage/Resources/Private/Schemas/Stats.graphql'
    - 'EXT:sitepackage/Resources/Private/Schemas/Query.graphql'
    # …other type files…

The root field does not need a tableMapping entry. Fields handled by a custom resolver never reach the tableMapping dispatch path.

Complete Example 

A sitepackage wants to expose a disciplineStats root field that returns one row per discipline along with the number of experts attached to it. The count crosses two tables (discipline and expert) joined by a foreign key, so the default tableMapping dispatch cannot express it: each DisciplineStat row is a projection of an aggregate, not of a single database row. A custom resolver is the right fit.

type DisciplineStat {
  discipline: String!
  expertCount: Int!
}

type Query {
  # …regular tableMapping-backed fields (experts, disciplines, …)…

  disciplineStats: [DisciplineStat!]!
}

namespace Vendor\Sitepackage\GraphQL\Resolver;

use Digicademy\TypoGraph\CustomResolver\CustomResolverInterface;
use GraphQL\Type\Definition\ResolveInfo;
use Psr\Http\Message\ServerRequestInterface;
use TYPO3\CMS\Core\Database\ConnectionPool;

final class DisciplineStatsResolver implements CustomResolverInterface
{
    public function __construct(
        private readonly ConnectionPool $connectionPool,
    ) {}

    public function getFieldName(): string
    {
        return 'disciplineStats';
    }

    public function resolve(array $args, ResolveInfo $info, ?ServerRequestInterface $request): array
    {
        // One query joining discipline and expert, grouped per
        // discipline — the kind of shape tableMapping cannot express.
        $queryBuilder = $this->connectionPool
            ->getQueryBuilderForTable('tx_myextension_domain_model_discipline');
        $rows = $queryBuilder
            ->select('d.name AS discipline')
            ->addSelectLiteral('COUNT(e.uid) AS expertCount')
            ->from('tx_myextension_domain_model_discipline', 'd')
            ->leftJoin('d', 'tx_myextension_domain_model_expert', 'e', 'e.discipline = d.uid')
            ->groupBy('d.uid', 'd.name')
            ->orderBy('d.name', 'ASC')
            ->executeQuery()
            ->fetchAllAssociative();

        return array_map(
            static fn(array $row): array => [
                'discipline'  => (string)$row['discipline'],
                'expertCount' => (int)$row['expertCount'],
            ],
            $rows,
        );
    }
}

With the _instanceof rule in the sitepackage's Services.yaml (shown in the previous section), nothing further is needed. The resolver is discovered at container build time and dispatched on every request to disciplineStats.

Dispatch Order and Precedence 

At the root level of a Query, ResolverService::resolve() runs in this order:

1. Check the CustomResolverRegistry for a handler matching the current ResolveInfo::$fieldName. If one exists, call it and return its value.
2. Otherwise fall through to tableMapping dispatch.

Inside the resolved value (nested fields on returned objects), standard resolution continues to apply: relation fields declared in typograph.relations still resolve through the default path, and field transforms declared in typograph.fieldTransforms still run against the records returned by your resolver. Your resolver does not have to re-implement those features; it only has to produce a value whose shape matches the schema.

Field Name Uniqueness and Collisions 

The registry stores at most one resolver per field name. If two services both implement CustomResolverInterface and return the same getFieldName() value, the last one registered wins. Symfony DI's iteration order is deterministic within a single container build but is not guaranteed across refactors, so colliding field names should be treated as a configuration error.

If you need to ship multiple alternative resolvers for the same field (e.g. behind a feature toggle), pick which one to register in your Services.yaml rather than relying on iteration order.

Error Behaviour 

• If the current field has no matching custom resolver, dispatch falls through silently to tableMapping. Fields that are neither mapped to a table nor handled by a custom resolver return null — exactly the default behaviour from before the hook was introduced.
• Exceptions thrown inside resolve() are not swallowed by the registry. They propagate to ResolverService::process() where GraphQL-level errors are logged and surfaced as a structured error response. Prefer returning empty arrays or null for domain-level "no data" conditions so they do not pollute the log.
• Consuming projects that never register a custom resolver are not affected by anything in this document; the registry is injected as an optional dependency and the hook is a no-op when it is absent.