# Voyager Importer

## Package docs status

This page is generated from package source documentation in `the Capell packages repository` and the checked-in manifest. Source documentation is not distribution status. Before running a Composer command, verify that the exact package and compatible 1.x release are available through public Packagist or the authenticated marketplace account.

| Field | Value |
| --- | --- |
| Composer package | `capell-app/voyager-importer` |
| Package slug | `voyager-importer` |
| Product group | Capell Operations |
| Tier | free |
| Bundle | `operations` |
| Runtime contexts | `admin`, `console` |
| Capell version | `^1.0` |
| Catalogue role | extension |
| Release channel | Labs |
| Source repository | `capell-app/packages` |
| Source path | `packages/voyager-importer` |
| Docs source | `packages/voyager-importer/docs` |
| Manifest | [`capell.json`](https://github.com/capell-app/packages/edit/main/packages/voyager-importer/capell.json) |

<!-- prettier-ignore-start -->

## What This Plugin Adds

Voyager Importer is an **Available**, **No schema impact** Capell package in the **Capell Operations** product group. It ships as `capell-app/voyager-importer` and extends these surfaces: admin, console.

Voyager Importer inspects a Voyager database and previews migration counts without loading Voyager classes.

Operators can review an inventory and a preview before a migration is available to execute.

Status details:

- Status: Available
- Tier: free
- Bundle: operations
- Composer package: `capell-app/voyager-importer`
- Namespace: `Capell\VoyagerImporter`
- Theme key: not applicable

## Why It Matters

**For developers:** A typed contributor contract provides a place to describe host-specific mappings.

**For teams:** A preview helps migration teams inspect source counts before any import is attempted.

## Screens And Workflow

Marketplace media is declared in `capell.json`:

![Voyager Importer extension preview image](assets/marketplace/extension-card.jpg)

- Voyager Importer extension preview for Marketplace cards.

## Technical Shape

### Service providers

- `Capell\VoyagerImporter\VoyagerImporterServiceProvider`

### Config files

- `packages/voyager-importer/config/voyager-importer.php`

### Extension contracts

- `VoyagerImportContributor`
- `VoyagerTableImportContributor`

### Actions

- `ApplyVoyagerResourceMetadataAction`
- `AssignVoyagerUserRolesAction`
- `ConvertVoyagerSettingValueAction`
- `DeactivateImportedVoyagerUrlAction`
- `DetectVoyagerNavigationConflictsAction`
- `DetectVoyagerSchemaAction`
- `DetectVoyagerUrlConflictsAction`
- `DiscoverVoyagerMediaAction`
- `EnsureVoyagerUserEmailSafeAction`
- `ImportVoyagerContributorTablesAction`
- `ImportVoyagerMediaAction`
- `ImportVoyagerMenusAction`
- `ImportVoyagerPageUrlAction`
- `ImportVoyagerPagesAction`
- `ImportVoyagerPostsAction`
- `ImportVoyagerRedirectsAction`
- `ImportVoyagerTranslationsAction`
- `InvalidateImportedVoyagerCachesAction`
- `InventoryVoyagerAction`
- `MapVoyagerColumnsAction`
- `PreviewVoyagerAction`
- `ReconcileLegacyVoyagerSourceKeysAction`
- `RefuseLegacyVoyagerSourceKeysAction`
- `ResolveImportedVoyagerUsersAction`
- `ResolveVoyagerAuthorAction`
- `ResolveVoyagerLayoutTargetsAction`
- `ResolveVoyagerSettingKeyAction`
- `ResolveVoyagerTemplateAction`
- `RewriteImportedVoyagerHtmlAction`
- `RewriteImportedVoyagerJsonAction`
- `RewriteVoyagerMediaUrlsAction`
- `SaveImportedVoyagerTranslationAction`

### Data objects

- `VoyagerImportCounts`
- `VoyagerImportOptions`
- `VoyagerMediaWrite`
- `VoyagerMenuItem`
- `VoyagerPageImportResult`
- `VoyagerSchema`
- `VoyagerTableImportDefinition`
- `VoyagerTranslationGroup`

### Command signatures

- `voyager-importer:import`
- `voyager-importer:inventory`
- `voyager-importer:make-resource`
- `voyager-importer:reconcile-legacy`

### Console command classes

- `ImportVoyagerCommand`
- `InventoryVoyagerCommand`
- `MakeVoyagerResourceCommand`
- `ReconcileLegacyVoyagerCommand`

### Manifest contributions

- `console-command: Capell\VoyagerImporter\Manifest\VoyagerImporterConsoleCommandContribution`

## Data Model

This package has no schema impact. It extends Capell through `console-command` contributions instead of declaring package-owned tables.

## Install Impact

- Required packages: `capell-app/admin`, `capell-app/core`, `capell-app/migration-assistant`.
- Admin navigation: no admin page or resource contribution is declared.
- Admin/editor extensions: none declared.
- Permissions: no package permission declarations or Shield gates detected; host access rules still apply.
- Public routes: none declared.
- Database changes: no package migrations declared.
- Config: `config/voyager-importer.php`.
- Settings: no package settings declared.
- Queues or schedules: none declared.
- Cache tags: none declared.
- Commands: `voyager-importer:import`, `voyager-importer:inventory`, `voyager-importer:make-resource`, `voyager-importer:reconcile-legacy`.

## Common Pitfalls

- Keep required Capell packages on compatible v4 releases: `capell-app/admin`, `capell-app/core`, `capell-app/migration-assistant`.
- Review package configuration before production-like verification: `config/voyager-importer.php`.

## Troubleshooting

| Symptom | Likely cause | Check | Fix |
| --- | --- | --- | --- |
| Package surface is missing after install | Provider or manifest is not loaded | Confirm `capell.json`, package `composer.json`, and provider registration | Reinstall the package, refresh Composer autoload, and clear host caches |
| Execution refuses the source label or reports a changed server | The label is unknown, or it is bound to a different database server | Compare the label and connection with those used for the earlier session | Reuse the original label; if the source has genuinely moved rerun with `--repoint-source`, or use `--new-source` to bind a server registered to another label |
| Duplicate permission keys appear as skipped | Voyager permissions rows repeat a key | Read the skipped count in the session result | No action is needed; each key is imported once and repeats are counted as skipped duplicates |
| A column such as avatar is reported as unmapped | The destination table has no such column | Check the destination users table | Add the column, or rerun with `--skip-unmapped` to record the skipped field names |
| Execution fails | A source row or destination write was rejected | Read the `Cause:` line, which names the exception class and, for a database error, its SQLSTATE and driver code without row values | Fix the cause, then resume with `--session=<uuid>` and the same `--connection` and `--source-label` |

## Quick Start

1. Install the package: `composer require capell-app/voyager-importer`.
2. See it working: run `php artisan voyager-importer:inventory`.
3. Run `php artisan list voyager-importer` and confirm these commands are listed: `voyager-importer:import`, `voyager-importer:inventory`, `voyager-importer:make-resource`, `voyager-importer:reconcile-legacy`. Run any of them with `--help` to see its options.

## Upgrading

No manual steps between minor versions.

Read [CHANGELOG.md](CHANGELOG.md) before upgrading.

## Next Steps

- [Package docs](README.md)
- [Overview](overview.md)
- [Worked extension examples](extension-contracts.md)
- [Admin guide](admin-guide.md)
- Configuration files: [`config/voyager-importer.php`](config/voyager-importer.php).
- [Troubleshooting](#troubleshooting)
- [Screenshot contract](screenshots.json)
- [Marketplace assets](assets/marketplace/)
- [Capell content language plan](../../docs/CONTENT_LANGUAGE_PLAN.md)
- [Capell documentation design system](../../docs/DESIGN_SYSTEM.md)
- [Capell and package ERD notes](../../docs/erd/capell-and-package-erds.md)
- Related packages: [Migration Assistant](../migration-assistant/README.md), [Blog](../blog/README.md), [Navigation](../navigation/README.md).

<!-- prettier-ignore-end -->