Download the PHP package luremo/craft-link-migrator without Composer
On this page you can find all versions of the php package luremo/craft-link-migrator. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download luremo/craft-link-migrator
More information about luremo/craft-link-migrator
Files in luremo/craft-link-migrator
Package craft-link-migrator
Short Description Staged migration plugin for moving Verbb Hyper fields and content to Craft's native Link field with audit, prepare, content, and finalize workflows.
License MIT
Homepage https://github.com/LuremoDigital/Link-migration
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package craft-link-migrator
Link Migrator
Migrate Verbb Hyper or Typed Link Field fields and content to Craft CMS native Link fields — safely, in stages, from the CLI.
Link Migrator gives Craft teams a staged CLI workflow from Verbb Hyper or Typed Link Field to Craft's native Link field. Audit, prepare parallel native fields, migrate content with backups, review template impact, and finalize the layout cutover when everything is ready.
The original Hyper fields and values remain intact throughout the migration. CLI write commands require --force=1, and each migration stage produces reports you can inspect before continuing.
Link Migrator is an independent product and is not affiliated with Verbb. Hyper is a plugin by Verbb.
Features
- CLI only: run the staged workflow locally, in CI, or from deployment scripts.
- Audit before writing: inspect Hyper and Typed Link fields, supported mappings, lossy cases, and template API mismatches.
- Keep source data intact: prepare parallel native Link fields instead of replacing Hyper fields in place.
- Migrate safely: process content in batches, resume interrupted runs, and optionally back up each source value.
- Verify before cutover: re-read migrated content and refuse finalization while non-empty source values remain unverified.
- Review template impact: find common Hyper- and Typed-Link-only properties and methods that need updating.
- Track every run: write human-readable logs and JSON reports to Craft's runtime storage.
- Automate safely: use dry runs, explicit write confirmation, and reports in deployment scripts.
Requirements
- PHP 8.2+
- Craft CMS 5.3+
- Each source plugin installed and enabled until preparation, content migration, and finalization are complete
- Craft CMS 5.6+ recommended for the full native Link advanced-field set
Installation
Install Link Migrator from the Craft Plugin Store or use Composer:
Link Migrator is free to use, with every feature included and no edition split.
Migration Walkthrough
Use this sequence for a single environment. Back up the database and project config first, keep Hyper installed, and inspect each generated report before proceeding.
audit, status, and mismatches do not change fields, content, or migration mappings. mismatches intentionally exits non-zero when it finds potential source Link API usage. Every non-dry-run write command requires --force=1; finalize additionally requires --acknowledge-mismatches=1 when the scanner finds mismatches. A successful content run can still return non-zero for warnings, so resolve its report before finalizing.
Migrate one field
Pass the source Hyper field handle to every stage:
Multi-Environment Deployment
prepare-fields and finalize change field definitions and layouts, so run them only in the environment that authors project config. Commit and deploy the resulting project-config changes. Content and the plugin's mapping state are database data, so run adopt-prepared and content in every deployed environment.
adopt-prepared records the mapping for a deployed native field without changing fields or layouts, so it can run where allowAdminChanges is disabled. It expects <sourceHandle>Native; use --field and --target for a different handle. Do not deploy the final layout change until content is verified everywhere: project-config application cannot perform that per-environment verification for you.
How the Migration Works
| Stage | What it does | Writes data? |
|---|---|---|
audit |
Discovers Hyper and Typed Link Field sources, mapping support, code references, and likely API mismatches. | No |
prepare-fields |
Creates native Link fields, places them beside their source fields in layouts, and records the mappings. | Yes |
adopt-prepared |
Records mappings for native Link fields that arrived through deployed project config, without creating fields. | Plugin state only |
content |
Copies supported values into prepared native fields and verifies saved values. | Yes |
status |
Shows each field's phase, target handle, and migration counters. | No |
finalize |
Reconciles live content, then removes source fields from layouts when every value is ready. | Yes |
prepare-fields, adopt-prepared, content, and finalize refuse CLI writes unless --force=1 is present. If template mismatches are found, finalization also requires --acknowledge-mismatches=1 after you have reviewed and accepted the template impact. Dry runs do not write field mappings, migration state, project config, or content.
Finalization does not delete source fields. It removes them from field layouts and leaves the prepared native Link fields in place.
Supported Mappings
Typed Link Field support applies when its plugin is installed and enabled: url, email, tel, entry, asset, and category migrate to their matching native Link types. Typed custom values migrate as native URLs only when the custom type is enabled and the prepared native URL configuration accepts the normalized value. Root-relative URLs, anchors, and custom schemes are enabled only when Typed Link has custom validation disabled and the installed Craft version supports the matching setting; stale disabled custom settings never broaden native input. Missing query prefixes normalize to ?, while an unrepresentable suffix is stripped without discarding the link. Custom/default text, target, automatic noopener noreferrer, title, ARIA label, query suffixes, and valid element-source restrictions are retained where the prepared target supports them. Typed Link's custom-text required/max-length constraints have no native equivalent and are reported as lossy. Stripped attributes produce per-element warnings and optional backups, and block readiness. Unknown enabled types, explicit-empty element sources, and entirely stale element-source restrictions refuse prepare rather than broadening access. site, user, Commerce/event, and other registered Typed Link types are skipped with their complete hydrated source payload retained in an optional backup.
| Hyper type | Native Link type | Support |
|---|---|---|
| URL | URL | Full |
| Entry | Entry | Full |
| Asset | Asset | Full |
| Category | Category | Full |
| Full | ||
| Phone | Phone (tel) |
Full |
| Custom or plugin type | URL when a scalar URL is available | Partial; review required |
The migration also carries over label/text, target/new-tab behavior, URL suffix, title, class, ID, and rel where the installed Craft version supports them. Prepared target handles default to <sourceHandle>Native.
Unsupported or lossy cases
- Hyper fields that allow multiple links
- Embed-only data
- SMS links, because Craft's native Link field has no SMS type
- User, site, or plugin-specific link types without a native equivalent
- Custom fields attached to Hyper link types
Unsupported values are skipped and reported. Custom link data is included in optional backups but is not converted into native Link data.
Template Impact
Source and native Link values do not expose the same Twig and PHP APIs. Run the scanner before finalizing:
The command exits non-zero when it finds likely mismatches, making it useful in CI and deployment checklists. Source-only API names are scoped to audited field handles and simple Twig/PHP aliases, so unrelated application methods do not block finalization. Native no-argument getLink(), getElement(), and getUrl() calls are left alone.
Common changes include:
| Source API | Native Link |
|---|---|
.text or .linkText |
Usually .label; review source fallback behaviour |
linkValue |
.value or .url |
Typed Link customText |
.label |
Typed Link getCustomText(), getDefaultText(), getText(), getIntrinsicText() |
Review custom/intrinsic/default/fallback precedence explicitly; .label is not always equivalent |
Typed Link customQuery |
.urlSuffix |
Typed Link linkedId, linkedTitle, linkedUrl |
.element, .value, .label, or .url as appropriate |
Typed Link linkedSiteId, getSiteId(), cross-site helpers |
Native Link cannot preserve a target site that differs from the owner site |
getElement() |
.element; remove Typed Link’s ignoreStatus argument |
hasElement() |
Check .element directly |
Typed Link getRawLinkAttributes() / getLinkAttributes() |
.attributes on Craft 5.9+, or map attributes manually; merge passed overrides explicitly |
Typed Link getUrl(options) |
.url, with URL modifications handled explicitly |
| Typed Link setting and empty-state helpers, including Twig getter properties | Read the native value/owner element directly |
| Hyper link classes | Short type handles such as entry, asset, or url |
getLink() with source-specific arguments, getHtml(), getData() |
Render or map explicitly |
The scanner is a guide, not proof that every integration is compatible. GraphQL output also changes, so review template integrations before migrating production content.
Reports, Backups, and State
Audit, mismatch, prepare, content, and finalize runs each write a JSON report and log file to:
With --create-backup=1, content migration writes per-element source payloads to:
Resumable per-element state is stored in {{%linkmigrator_migrations}}. Prepared source-to-target mappings are stored in {{%linkmigrator_fieldmappings}} only after prepare-fields or adopt-prepared writes them. Audit and status remain read-only.
Use the informational summary at any time:
This reports migrated, skipped, warning, error, and backup counts. It does not restore content automatically.
Safety Checklist
- Back up the database and project config before every non-dry run.
- Review audit warnings, unsupported fields, and mismatch results before continuing.
- Keep Hyper or Typed Link Field installed and enabled until reports are clean, templates are updated, and finalization has succeeded.
- Run content migration in each environment because Craft content is environment-specific.
- Verify the site and templates before removing Hyper from the project.
Support
- Bug reports: GitHub Issues. Include Craft, PHP, source-plugin versions, and the relevant JSON report.
- Changelog: CHANGELOG.md
- Template migration guide: docs/TEMPLATE-IMPACT.md
- Plugin Store description: docs/plugin-store-description.md
License
Link Migrator is released under the MIT License.
Built by Luremo for the Craft CMS community.
