From Drupal to TYPO3: A No-Nonsense Migration Playbook

{
  "data": [{
    "type": "node--article",
    "id": "b5c1-uuid",
    "attributes": {
      "title": "My Article",
      "body": { "value": "<p>HTML…</p>", "format": "basic_html" },
      "created": "2025-05-01T10:20:30+00:00",
      "langcode": "en",
      "path": { "alias": "/blog/my-article" }
    },
    "relationships": {
      "field_image": { "data": [{ "type": "file--file", "id": "f-uuid" }] },
      "field_tags":  { "data": [{ "type": "taxonomy_term--tags", "id": "t-uuid" }] }
    }
  }],
  "included": [{
    "type": "file--file",
    "id": "f-uuid",
    "attributes": {
      "filename": "hero.jpg",
      "uri": { "url": "https://example.com/sites/default/files/hero.jpg" }
    }
  }]
}

function fetchDocuments(string $url): array {
  $out = [];
  while ($url) {
    $json = json_decode(file_get_contents($url), true);
    if (!is_array($json)) break;
    $out[] = $json;
    $url = $json['links']['next']['href'] ?? null; // JSON:API pagination
  }
  return $out;
}
// Example: articles with includes
$docs = fetchDocuments('https://drupal.example/jsonapi/node/article?filter[langcode]=en&include=field_image,uid,field_tags&page[limit]=50');
file_put_contents('stage/articles_en.json', json_encode($docs, JSON_PRETTY_PRINT|JSON_UNESCAPED_SLASHES));

$docs = json_decode(file_get_contents('stage/articles_en.json'), true);

function indexIncluded(array $doc): array {
  $files = $terms = [];
  foreach (($doc['included'] ?? []) as $res) {
    if ($res['type'] === 'file--file') {
      $files[$res['id']] = [
        'uuid' => $res['id'],
        'filename' => $res['attributes']['filename'] ?? '',
        'url' => $res['attributes']['uri']['url'] ?? null,
      ];
    } elseif (str_starts_with($res['type'], 'taxonomy_term--')) {
      $terms[$res['id']] = [
        'uuid' => $res['id'],
        'name' => $res['attributes']['name'] ?? '',
        'slug' => $res['attributes']['path']['alias'] ?? null
      ];
    }
  }
  return [$files, $terms];
}

foreach ($docs as $doc) {
  [$fileIndex, $termIndex] = indexIncluded($doc);

  foreach ($termIndex as $t) {
    upsertCategory($t['uuid'], ['title' => $t['name'], 'slug' => $t['slug'] ?: slugify($t['name'])]);
  }

  foreach ($doc['data'] as $node) {
    if ($node['type'] !== 'node--article') continue;

    $uuid  = $node['id'];
    $attr  = $node['attributes'];
    $rels  = $node['relationships'] ?? [];

    $title = $attr['title'] ?? '';
    $body  = $attr['body']['value'] ?? '';
    $lang  = $attr['langcode'] ?? 'en';
    $alias = $attr['path']['alias'] ?? null;
    $slug  = $alias ?: '/'.slugify($title);

    $pageUid = upsertPage($uuid, [
      'pid' => 0,
      'title' => $title,
      'slug' => $slug,
      'sys_language_uid' => langUid($lang),
    ]);

    insertTextElement($pageUid, normalizeHtml($body), $title);

    foreach ((array)($rels['field_image']['data'] ?? []) as $imgRef) {
      $fileMeta = $fileIndex[$imgRef['id']] ?? null;
      if (!$fileMeta || empty($fileMeta['url'])) continue;
      $fileUid = ensureFalFromUrl($fileMeta['url'], $fileMeta['filename']);
      attachImageToPage($pageUid, $fileUid);
    }

    foreach ((array)($rels['field_tags']['data'] ?? []) as $ref) {
      relatePageToCategory($pageUid, externalIdToCategoryUid($ref['id']));
    }

    if ($alias) rememberRedirect($alias, $slug, 301);
  }
}

flushRememberedRedirects();

/* Helper signatures you’ll implement with TYPO3 APIs (DataHandler + FAL):
upsertCategory($externalId, $data): int
upsertPage($externalId, $data): int
insertTextElement($pid, $html, $header): int
ensureFalFromUrl($url, $filename): int
attachImageToPage($pageUid, $fileUid): void
relatePageToCategory($pageUid, $categoryUid): void
externalIdToCategoryUid($externalId): ?int
langUid($langcode): int
slugify($text): string
normalizeHtml($html): string
rememberRedirect($source, $target, $status): void
flushRememberedRedirects(): void
*/