Adding a Manual Migration Task

<?php

namespace App\ManualMigrations\Migrations\MigrateNotesFiles;

use App\AsyncTask\Service\LegacyBridge\AsyncTaskLegacyHandler;
use App\AsyncTask\Service\TaskHandler\AbstractAsyncTaskHandler;
use App\AsyncTask\Service\TaskHandler\AsyncTaskBatchItem;
use App\Data\Entity\Record;
use App\Data\LegacyHandler\PreparedStatementHandler;
use App\Engine\Model\Feedback;
use App\MediaObjects\Repository\MediaObjectManagerInterface;
use App\MediaObjects\Services\LocalFileMediaObjectMigratorInterface;
use Psr\Log\LoggerInterface;

class MigrateNotesFilesTaskHandler extends AbstractAsyncTaskHandler
{
    public function __construct(
        protected AsyncTaskLegacyHandler $legacyHandler,
        protected PreparedStatementHandler $preparedStatementHandler,
        protected MediaObjectManagerInterface $mediaObjectManager,
        protected LocalFileMediaObjectMigratorInterface $migrator,
        protected LoggerInterface $logger
    ) {
    }

    public function getHandlerKey(): string
    {
        return 'migrate-notes-files';
    }

    public function getType(): string
    {
        return 'manual-migration-tasks';
    }

    public function getNextBatchToQueue(
        Record $task,
        array $progress,
        int $batchSize
    ): array {
        $offset = $progress['enqueue_offset'] ?? 0;

        try {
            $qb = $this->preparedStatementHandler->createQueryBuilder();
            $qb->select('id', 'filename', 'file_mime_type')
                ->from('notes')
                ->where('filename IS NOT NULL')
                ->andWhere("filename != ''")
                ->andWhere('deleted = 0')
                ->setFirstResult($offset)
                ->setMaxResults($batchSize);

            $results = $qb->executeQuery()->fetchAllAssociative();
        } catch (\Throwable $e) {
            $this->logger->error(
                'MigrateNotesFilesTaskHandler::getNextBatchToQueue failed: '
                . $e->getMessage(),
                ['component' => 'migrate-notes-files']
            );

            return [];
        }

        $items = [];
        foreach ($results as $row) {
            $items[] = new AsyncTaskBatchItem(
                $row['id'],
                [
                    'record_id' => $row['id'],
                    'filename' => $row['filename'],
                    'file_mime_type' => $row['file_mime_type']
                        ?? 'application/octet-stream',
                ]
            );
        }

        return $items;
    }

    public function processItem(Record $task, array $item): Feedback
    {
        $feedback = new Feedback();
        $data = $item['data'] ?? [];
        $recordId = $data['record_id'] ?? '';
        $filename = $data['filename'] ?? '';
        $mimeType = $data['file_mime_type'] ?? 'application/octet-stream';

        if (empty($recordId) || empty($filename)) {
            return $feedback->setSuccess(false)
                ->setMessages(['Missing record_id or filename']);
        }

        $this->legacyHandler->startLegacy();

        try {
            $legacyDir = $this->legacyHandler->getLegacyDir();
            $legacyPath = $legacyDir . '/upload/' . $recordId;

            // Check if already migrated
            $existing = $this->mediaObjectManager->getLinkedMediaObjects(
                'private-documents',
                'Notes',
                $recordId,
                'file'
            );

            if (!empty($existing)) {
                // Clean up legacy file if it still exists
                if (file_exists($legacyPath)) {
                    unlink($legacyPath);
                }

                return $feedback->setSuccess(true)
                    ->setMessages(['Already migrated']);
            }

            if (!file_exists($legacyPath)) {
                return $feedback->setSuccess(false)
                    ->setMessages(['Legacy file not found: upload/' . $recordId]);
            }

            // Perform the migration
            $record = $this->migrator->migrate(
                $legacyPath,
                'private-documents',
                $mimeType,
                $filename,
                $filename,
                'Notes',
                $recordId,
                'file'
            );

            $feedback->setSuccess(true);
            $feedback->setData(['media_object_id' => $record?->getId()]);
        } catch (\Throwable $e) {
            $this->logger->error(
                'MigrateNotesFilesTaskHandler::processItem failed: '
                . $e->getMessage(),
                [
                    'component' => 'migrate-notes-files',
                    'record_id' => $recordId,
                ]
            );
            $feedback->setSuccess(false)->setMessages([$e->getMessage()]);
        } finally {
            $this->legacyHandler->stopLegacy();
        }

        return $feedback;
    }
}

<?php

namespace App\ManualMigrations\Migrations\MigrateNotesFiles;

use ApiPlatform\Metadata\Exception\InvalidArgumentException;
use App\Process\Entity\Process;
use App\Process\Service\ProcessHandlerInterface;

class MigrateNotesFilesAction implements ProcessHandlerInterface
{
    protected const MSG_OPTIONS_NOT_FOUND = 'Process options are not defined';
    protected const PROCESS_TYPE = 'migration-task-migrate-notes-files';

    public function getProcessType(): string
    {
        return self::PROCESS_TYPE;
    }

    public function requiredAuthRole(): string
    {
        return 'ROLE_USER';
    }

    public function getRequiredACLs(Process $process): array
    {
        $options = $process->getOptions();
        $module = $options['module'] ?? '';

        return [
            $module => [
                ['action' => 'view', 'record' => $options['id'] ?? ''],
            ],
        ];
    }

    public function validate(Process $process): void
    {
        if (empty($process->getOptions())) {
            throw new InvalidArgumentException(self::MSG_OPTIONS_NOT_FOUND);
        }

        $options = $process->getOptions();
        if (empty($options['module']) || empty($options['id'])) {
            throw new InvalidArgumentException(self::MSG_OPTIONS_NOT_FOUND);
        }
    }

    public function configure(Process $process): void
    {
        $options = $process->getOptions();
        $process->setId($options['id'] ?? '');
        $process->setAsync(true);
        $process->setAsyncHandlerKey('migrate-notes-files');
        $process->setAsyncRunnerType('manual-migration-tasks');
        $process->setModule($options['module'] ?? '');
    }

    public function run(Process $process): void
    {
        // Empty — async processes are handled by the runner
    }
}

{asyncProcessKeyPrefix}-{service_key_value}
→ migration-task-migrate-notes-files

<?php

declare(strict_types=1);

namespace App\Migrations;

use Doctrine\DBAL\Schema\Schema;
use Symfony\Component\DependencyInjection\ContainerAwareInterface;

final class Version20260217120000 extends BaseMigration
    implements ContainerAwareInterface
{
    public function getDescription(): string
    {
        return 'Add Migrate Notes Attachments manual migration task';
    }

    public function up(Schema $schema): void
    {
        $this->log(
            'Migration Version20260217120000: '
            . 'Adding Migrate Notes Attachments task'
        );

        $serviceKey = 'migrate-notes-files';

        // Guard: skip if already exists
        $existing = $this->connection->fetchOne(
            'SELECT COUNT(*) FROM manual_migration_tasks '
            . 'WHERE service_key = ? AND deleted = 0',
            [$serviceKey]
        );

        if ((int)$existing > 0) {
            $this->log(
                'Migration Version20260217120000: '
                . 'Task already exists, skipping'
            );
            return;
        }

        $now = date('Y-m-d H:i:s');

        $this->connection->insert('manual_migration_tasks', [
            'id' => create_guid(),
            'name' => 'Migrate Notes Attachments',
            'type' => 'background',
            'status' => 'initial',
            'service_key' => $serviceKey,
            'description' => 'Migrates Notes file attachments from '
                . 'legacy storage (upload/{note_id}) to the new '
                . 'media object storage system.',
            'date_entered' => $now,
            'date_modified' => $now,
            'created_by' => '1',
            'modified_user_id' => '1',
            'assigned_user_id' => '1',
            'deleted' => 0,
            'allow_failure_retry_action' => 1,
            'allow_failure_rerun_action' => 0,
        ]);

        $this->log(
            'Migration Version20260217120000: Task added successfully'
        );
    }

    public function down(Schema $schema): void
    {
        $this->connection->executeStatement(
            'DELETE FROM manual_migration_tasks WHERE service_key = ?',
            ['migrate-notes-files']
        );
    }
}

php bin/console cache:clear