Further WIP on document migration

Author: gsteel

.gitignore

@@ -2,4 +2,6 @@
 /var/cache/*
 !/var/cache/.gitkeep
 rector.php
-.env
+.env.netglue-to-asset-target.env
+*.env
+config/**/*local.*

README.md

@@ -1,3 +1,39 @@
 # Tooling to Clone Prismic Repositories
 
-WIP…
+This is a project that you should clone and run in an environment where you have PHP 8.4 installed.
+
+It's not fancy, but it seems to work OK.
+
+It's also still WIP…
+
+## Things that definitely don't work
+
+Cloning multiple locales hasn't been implemented. I currently have no need for it, so it's unlikely to be implemented unless someone else does it.
+
+## Usage
+
+### Clone
+
+You know how to do this already right?
+
+### Setup Environment
+
+[Create a new repository at prismic.io](https://prismic.io/dashboard/new-repository) and go through the initial on-boarding until you can set the master locale. Use a master locale that matches the source locale, however, you can override the locale to match the target _(blindly)_ if you are confident that'd be OK. For example, copying from `en-us` to `en-gb` or vice versa would be fine. Look at [`./config/autoload/repository.global.php`](./config/autoload/repository.global.php) for more details.
+
+Copy the [`./example.env.dist`](./example.env.dist) file to `./.env` and fill out the relevant details. You only need to supply _read_ tokens if your repository requires them. _Write_ tokens are mandatory for both source and target, but no writes happen on the source.
+
+On your **source** repo, make sure that any documents you want to be cloned have been published. Un-published docs, or docs published to releases will not be copied.
+
+### Run
+
+```bash
+php bin/run.php
+```
+
+## What happens
+
+- _All_ assets are copied from source to target, not just the ones that are used in your documents. If an error occurs during asset copying, You can re-try safely. You won't end up with duplicated assets.
+- _All_ document type definitions are cloned from source to target along with any shared slices. Again, these are tracked, so can be retried if any errors occur during transfer.
+- _All_ source documents are downloaded at the **master ref**.
+- Works through source documents one at a time, adjusting image identifiers and sends the data to the target migration release.
+- TODO - Once all documents are processed, adjust all internal document links to point at the new equivalent document.

bin/run.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+use Prismic\Cloner\Asset\AssetMapper;
+use Prismic\Cloner\DocumentType\CloneDocumentTypes;
+use Prismic\Cloner\Migration\DocumentMigrator;
+use Psr\Container\ContainerInterface;
+
+$container = require_once __DIR__ . '/../config/container.php';
+
+assert($container instanceof ContainerInterface);
+
+$assetMapper = $container->get(AssetMapper::class);
+$assetMapper(true);
+
+$typeCloner = $container->get(CloneDocumentTypes::class);
+$typeCloner();
+
+$documentMigrator = $container->get(DocumentMigrator::class);
+$documentMigrator->migrate();

composer.lock

@@ -28,5 +28,8 @@
 
         // Where a map of migrated document id's is persisted
         'doc-migration-tracker-filename' => 'migrated-documents.json',
+
+        // Where cached document json is persisted per repository
+        'document-cache-directory-name' => 'documents',
     ],
 ];

config/autoload/application.global.php

@@ -17,29 +17,52 @@
 use Prismic\Cloner\Factory\PathConfigFactory;
 use Prismic\Cloner\Migration\DefaultTitleResolver;
 use Prismic\Cloner\Migration\DocumentMigrationTracker;
+use Prismic\Cloner\Migration\DocumentMigrator;
 use Prismic\Cloner\Migration\Factory\DocumentMigrationTrackerFactory;
+use Prismic\Cloner\Migration\Factory\DocumentMigratorFactory;
+use Prismic\Cloner\Migration\Factory\TitleResolverFactory;
+use Prismic\Cloner\Migration\ResolveSinglesToTypeLabel;
 use Prismic\Cloner\Migration\TitleResolver;
 use Prismic\Cloner\PathConfig;
+use Prismic\Cloner\Transformer\AdjustInternalLinks;
+use Prismic\Cloner\Transformer\FixAssetIdentifiers;
+use Prismic\Cloner\Transformer\PostTransform;
+use Prismic\Cloner\Transformer\PostTransformFactory;
+use Prismic\Cloner\Transformer\PreTransform;
+use Prismic\Cloner\Transformer\PreTransformFactory;
 
 // phpcs:disable SlevomatCodingStandard.Namespaces.ReferenceUsedNamesOnly
 
 return [
     'dependencies' => [
         'factories' => [
+            // Utils, generic deps
             CurlClient::class => InvokableFactory::class,
             FinfoMimeTypeDetector::class => InvokableFactory::class,
-            CopyAsset::class => ReflectionBasedAbstractFactory::class,
+
+            // Main tooling services
             PathConfig::class => PathConfigFactory::class,
+            CopyAsset::class => ReflectionBasedAbstractFactory::class,
             AssetMapper::class => AssetMapperFactory::class,
             CloneDocumentTypes::class => CloneDocumentTypesFactory::class,
             DocumentTypes::class => DocumentTypesFactory::class,
             DocumentMigrationTracker::class => DocumentMigrationTrackerFactory::class,
+            DocumentMigrator::class => DocumentMigratorFactory::class,
+
+            // Tools for figuring out the document title
             DefaultTitleResolver::class => ReflectionBasedAbstractFactory::class,
+            ResolveSinglesToTypeLabel::class => ReflectionBasedAbstractFactory::class,
+            TitleResolver::class => TitleResolverFactory::class,
+
+            // Tools for pre- and post-processing the documents
+            FixAssetIdentifiers::class => ReflectionBasedAbstractFactory::class,
+            AdjustInternalLinks::class => ReflectionBasedAbstractFactory::class,
+            PreTransform::class => PreTransformFactory::class,
+            PostTransform::class => PostTransformFactory::class,
         ],
         'aliases' => [
             Psr\Http\Client\ClientInterface::class => CurlClient::class,
             MimeTypeDetector::class => FinfoMimeTypeDetector::class,
-            TitleResolver::class => DefaultTitleResolver::class,
         ],
     ],
 ];

config/autoload/dependencies.global.php

@@ -30,6 +30,12 @@
             'name' => $_ENV['TARGET_REPO'],
             'writeToken' => $_ENV['TARGET_WRITE_TOKEN'],
             'readToken' => $_ENV['TARGET_READ_TOKEN'],
+            /**
+             * If you are copying from a repo in say 'en-us' and need the target to be 'en-gb', you can supply a
+             * 'forceLanguage' option to override the language of the source document.
+             * Bear in mind this is not going to be very helpful for multi-language repos
+             */
+            //'forceLanguage' => 'en-gb',
         ],
     ],
 

config/autoload/repository.global.php

@@ -0,0 +1,13 @@
+# Copy this file to `.env` and change values to match your requirements
+
+# Bare repository names, not URIs
+SOURCE_REPO=source-name
+TARGET_REPO=target-name
+
+# You must supply write token for both source and target
+SOURCE_WRITE_TOKEN=
+TARGET_WRITE_TOKEN=
+
+# Read tokens are optional, but required if your repos are setup to require one
+SOURCE_READ_TOKEN=
+TARGET_READ_TOKEN=