Migration Assistant

Migration Assistant

Migration Assistant export, import, and rollback report workflows for Capell.

At A Glance

• Package: capell-app/migration-assistant
• Namespace: Capell\MigrationAssistant\
• Surfaces: Filament admin, queue, database
• Service providers: packages/migration-assistant/src/Providers/MigrationAssistantServiceProvider.php
• Capell dependencies: capell-app/admin, capell-app/core
• Third-party dependencies: lorisleiva/laravel-actions, spatie/laravel-package-tools

Why It Helps Your Capell Workflow

• Provides import workflows, source readers, mapping, preview, validation, execution state, and rollback reports for content moves.
• Helps owners de-risk migrations by showing what will change before import and what changed afterwards.
• Gives developers extension points for sources, targets, relations, row contributors, collision detection, and rollback behavior.

Best Used With

• WordPress Importer
• Media Library
• Diagnostics

What It Adds

• Migration Assistant export, import, and rollback report workflows for Capell.
• Admin resources: ImportSessionResource.
• Recovery Center page import workflow: upload, review, resolve relations, validate, queue execution, and inspect rollback evidence.

Why It Matters

For developers: Separates migration work into services, actions, DTOs, jobs, events, source readers, target registries, and resolver contracts so package and flat-file data can be moved with explicit ownership rules.

For teams: Supports controlled migration workflows where content, media, relationships, source files, and rollback evidence can be reviewed before and after import.

Built With

This package makes its Composer dependencies visible because they are part of the value proposition, not just plumbing. When an upstream package has a public repository, its linked preview card points readers back to the maintainers so their work gets proper credit.

Capell packages used here

• Capell Admin
• Capell Core

Open-source packages used here

• Laravel Actions - single-purpose action classes that keep package workflows out of controllers and Filament resources.
• Spatie Laravel Package Tools - Laravel package bootstrapping for config, migrations, commands, translations, and service provider setup.

Linked package previews

Screens And Workflow

Screenshots are generated from docs/screenshots.json during package deployment.

• Import session index or host admin surface.
• Page import upload and validation workflow.
• Import validation summary.
• Relation resolution review.
• Rollback report view.
• Package export intent screen.

Technical Shape

• MigrationAssistantServiceProvider registers the package.
• Config file: migration-assistant.php.
• Migrations create import_rollback_reports and import_sessions, including generic import target columns.
• Jobs execute import plans.
• Events report import completed or failed.
• Services cover package reading, writing, CSV/XML reading, mapping, validation, relation resolution, media ingest, preview, and rollback reporting.
• WordPress WXR support is intentionally provided by the separate capell-app/wordpress-importer package, which registers a source reader with Migration Assistant.

Code Map

Admin Surface

• Resources: ImportSessionResource.
• Pages: ImportPagesPage, ListImportSessions, ViewImportSession. ImportSitesPage remains a hidden placeholder until the site-import wizard ships.

Runtime Surface

• Jobs: ExecuteImportPlanJob.
• Commands: migration-assistant:export, migration-assistant:import, migration-assistant:status, migration-assistant:rollback-report, migration-assistant:rollback-execute.

Data And Persistence

• import_rollback_reports stores the import session, created model ids, source filename/checksum, summary counts, executing user/time, and manual rollback instructions.

• import_sessions stores import kind, generic target type/id, status, manifest, decisions, validation state, and result summary.

• Retention and deletion rules should be verified against the host application policy.

• Models: ImportRollbackReport, ImportSession.

• Migrations: 2026_05_10_190859_01_create_import_sessions_table.php, 2026_05_10_190859_02_create_import_rollback_reports_table.php, 2026_06_04_000001_rename_import_rollback_reports_table.php.

• Config: packages/migration-assistant/config/migration-assistant.php.

• Data objects live in src/Data/; use them for payloads, form state, and view models.

Extension Points

• Contracts: ImportSessionSubNavigationExtender, ImportSourceReader, MigrationAssistantContextResolver, MigrationAssistantRowContributor, PageCollisionDetector, PageImportTargetResolver.
• Events: ImportCompleted, ImportFailed.
• Listeners: SendImportSessionNotifications.
• Register Capell extension points, routes, migrations, settings, render hooks, and resources from service providers.

Install Impact

• Adds import_rollback_reports and import_sessions tables.
• Adds migration-assistant queue configuration.
• Uses disk and path config for imports, exports, and working files.
• May require queue workers for long-running imports.
• No public routes are registered by this package.

Install And Setup

• Install with composer require capell-app/migration-assistant in the host Capell application.
• Run migrations through the host application package install flow.
• In this repository, verify package changes with vendor/bin/pest; do not use php artisan.

Admin And Access

• Import session access is guarded by ImportSessionPolicy.
• Policy support: OwnershipMap (packages/migration-assistant/src/Policy/OwnershipMap.php)

Common Pitfalls

• Configure MIGRATOR_QUEUE and MIGRATOR_DISK before large imports.
• Check upload and package size limits before importing client archives.
• Run queue workers before testing async import jobs.
• Review relation resolution before applying imported data.
• Use migration-assistant:export --page={id} --json or migration-assistant:export --site={id} --json for scripted package creation.
• Use migration-assistant:import {archive} --json to create and validate an import session; add --execute to queue it or --sync for controlled one-off execution.
• Use migration-assistant:status --json, migration-assistant:rollback-report {session} --json, and migration-assistant:rollback-execute {session} --dry-run --json for headless CI or migration audit checks.

Docs

• docs index
• credits-and-acknowledgements.md
• extension-points.md
• import-export-workflow.md
• migration-assistant.md
• overview.md

Testing

Run package tests from the repository root:

vendor/bin/pest packages/migration-assistant/tests --configuration=phpunit.xml

Maintenance Notes

• Put behaviour changes in src/Actions/; UI classes, commands, and controllers should call actions instead of owning domain logic.
• Use package Data classes at boundaries instead of passing anonymous arrays between layers.
• Use backed enums for persisted values and enum labels for Filament options.

Migration Assistant

Status: Available, schema-owning · Kind: package · Tier: premium · Bundle: operations · Contexts: admin, console · Product group: Capell Operations

This page is the consolidated implementation overview for the Migration Assistant package. It is extracted from the package README, service providers, migrations, config files, routes, resources, models, actions, and the shared Capell ERD notes where available.

What This Package Adds

Migration Assistant provides the Capell Migration Assistant: package export/import, CSV/XML source reads, source contracts for add-on importers, field mapping, preview, validation, dependency graph review, relation resolution, media ingest, queued execution, and rollback reports.

• Page imports are owned here: the Recovery Center page upload, review, relation resolution, validation, dispatch, and status polling flow lives in Migration Assistant.
• Import source contracts expose rows, columns, metadata, and a suggested target.
• Native CSV and XML readers cover common flat-file migrations without extra Composer dependencies.
• Field mapping targets Capell pages and types. Collection-like imports resolve through the same target registry until another package registers a concrete collection target.
• Preview output separates creates, skips, warnings, and blocking errors before execution.
• Rollback reports capture created model class/id pairs, imported URL/media counts, source filename/checksum, executing user/time, and manual rollback instructions.
• Import session tracking, retry/cancel flow, notifications, and queued execution.
• Package reader/writer services.
• Import validation, relation resolution, dependency graph, and media ingest services.

Developer Notes

Separates migration work into services, actions, DTOs, jobs, events, source readers, target registries, and resolver contracts so package and flat-file data can be moved with explicit ownership rules.

• MigrationAssistantServiceProvider registers the package.
• Config file: migration-assistant.php.
• Migrations create import_rollback_reports and import_sessions, including generic target fields.
• Jobs execute import plans.
• Events report import completed or failed.
• Services cover package reading, writing, CSV/XML reading, mapping, preview, validation, relation resolution, media ingest, and rollback reports.
• WordPress WXR support lives in capell-app/wordpress-importer, which depends on this package and registers its reader through the source registry.

Operational Notes

Supports controlled migration workflows where content, media, source files, and relationships need review before import and operators need evidence after execution.

• Adds import_rollback_reports and import_sessions tables.
• Adds migration-assistant queue configuration.
• Uses disk and path config for imports, exports, and working files.
• May require queue workers for long-running imports.
• No public routes are registered by this package.

Data And Retention

• import_rollback_reports stores import session, created model ids, source filename/checksum, summary counts, executing user/time, and manual rollback instructions.
• import_sessions stores import kind, generic target type/id, status, manifest, decisions, validation state, and result summary.
• Retention and deletion rules should be verified against the host application policy.

Screenshot Plan

• Import session index or host admin surface.
• Page import upload and validation workflow.
• Import validation summary.
• Relation resolution review.
• Rollback report view.
• Package export intent screen.

Screenshots

Validation, relation resolution, rollback, and export screenshots need seeded import sessions before they can show distinct workflow states.

Pitfalls

• Configure MIGRATOR_QUEUE and MIGRATOR_DISK before large imports.
• Check upload and package size limits before importing client archives.
• Run queue workers before testing async import jobs.
• Review relation resolution before applying imported data.

Verification

• Run vendor/bin/pest packages/migration-assistant/tests when package tests exist.
• Run the relevant host-app migration or package install flow in a disposable database.
• Open the listed admin or frontend surface and compare it with the screenshot plan.

Package Manifest

• Composer name: capell-app/migration-assistant
• Product group: Capell Operations
• Kind: package
• Tier: premium
• Bundle: operations
• Contexts: admin, console
• Requires: capell-app/admin, capell-app/core
• Optional dependencies: None listed.

Admin Surfaces

• ImportPagesPage (packages/migration-assistant/src/Filament/Pages/ImportPagesPage.php, slug recovery-center/import-pages)
• ImportSitesPage (packages/migration-assistant/src/Filament/Pages/ImportSitesPage.php, slug recovery-center/import-sites) is a hidden placeholder until the site-import wizard ships.
• ImportSessionResource (packages/migration-assistant/src/Filament/Resources/ImportSessions/ImportSessionResource.php)

Commands

• migration-assistant:status {session?} --json reports recent import sessions or a specific session by id/UUID.
• migration-assistant:export --page={id} --json and migration-assistant:export --site={id} --json create page/site migration packages for CI and scripted moves.
• migration-assistant:import {archive} --json creates and validates an import session; --execute queues the validated session and --sync runs it inline.
• migration-assistant:rollback-report {session} --json reports created records and manual rollback instructions for a completed import session.

Routes And Config

• Config: packages/migration-assistant/config/migration-assistant.php

Permissions And Gates

• Policy: OwnershipMap (packages/migration-assistant/src/Policy/OwnershipMap.php)

Migrations

• Migration: create_import_rollback_reports_table.php
• Migration: create_import_sessions_table.php

ERD Excerpt

erDiagram
    USERS ||--o{ IMPORT_SESSIONS : starts
    USERS ||--o{ IMPORT_ROLLBACK_REPORTS : executes
    IMPORT_SESSIONS ||--o{ IMPORT_ROLLBACK_REPORTS : reports

    IMPORT_ROLLBACK_REPORTS {
        bigint id PK
        uuid uuid
        bigint import_session_id FK
        bigint user_id FK
        string source_filename
        string source_package_checksum
        json created_models
        json summary
        text manual_instructions
        timestamp executed_at
    }

    IMPORT_SESSIONS {
        bigint id PK
        uuid uuid
        bigint user_id FK
        string kind
        string status
        json manifest
        json result_summary
    }

Screenshot Automation

Deployment should read screenshots.json, install the package with demo data, resolve each admin surface or frontend URL, and write images to packages/migration-assistant/docs/screenshots.

• Import session index or host admin surface.
• Import validation summary.
• Relation resolution review.
• Rollback report view.
• Package export intent screen.