GravityKit\GravityMigrate\Migration\ExternalMigration

Everything a surface does around a form-plugin provider, so that no surface does it twice.

Three of them ask the same questions: the wizard through the AJAX controllers, wp gk migrate plugins|to|from through \GravityKit\GravityMigrate\CLI\Migrate, and the Abilities API once it is built. Which plugin a slug names, which of its forms an operator asked for, what a form loses on the way across, what the run itself reported that nothing before it could have said -- one implementation each, here, called by all three.

The provider objects are the ones the wizard's AJAX controllers call, \ExporterInterface and \ImporterInterface. This is a second caller of the same methods rather than a second implementation of them, because the controllers cannot be the seam: validate_request() requires a nonce and CoreHelpers::process_return() sends JSON and dies, and neither survives WP-CLI or an ability call.

Holds nothing of any caller -- no WP_CLI, no AJAX, and no sentence naming a command-line flag (\GravityKit\GravityMigrate\CLI\MigrationRefusal adds those for the terminal) -- so the unit suite can reach all of it and a third surface can adopt it without inheriting a second's vocabulary.

Since: %ver%

Source: src/Migration/ExternalMigration.php:41

Details

• Kind: class
• Namespace: GravityKit\GravityMigrate\Migration

Properties

Property	Type	Description
$exporters	TargetRegistry	Exporter registry.
$importers	SourceRegistry	Importer registry.
$listed_forms	array<string,	array>

Methods

Method	Description
__construct()	Constructor.
for_this_site()	The migration over this site's own registries.
providers()	What this site can move to and from, and why one of them cannot be used.
provider()	The provider a slug names, for one direction.
registered_slugs()	Every slug registered for a direction, whether or not this site can use it.
resolve_form_ids()	The forms a --forms value names, checked against the ones the provider actually has.
forms_named()	The forms a --forms value names, looked up and refused in the right plugin's name.
listing_name()	What to call the side a --forms list names, which is not the side the operator named.
analyze()	What one form loses on the way across, before anything is written.
run()	Writes one form, and returns what the provider reported about writing it.
messages()	The sentences under one key of a provider payload.
run_warnings()	What the run itself found out, which nothing before it could have said.
forms()	The forms a provider has, listed once per run.
form_ids()	Every form id a provider has, in its own types.
titles()	A provider's form titles, keyed by form id.
created_form_id()	The id of the form a run created, whichever end of the migration created it.
check_form()	Checks one form without writing anything.
migrate_form()	Migrates one form, and reports what the migration said about it.
migrate()	One entry per form: what a migration of these forms did, or would do.
analyze_batch()	What several forms lose on the way across, answered per form.

Method Reference

__construct()

public function __construct( TargetRegistry $exporters, SourceRegistry $importers )

Constructor.

Parameters

Name	Type	Default	Description
$exporters	TargetRegistry		Exporter registry.
$importers	SourceRegistry		Importer registry.

Since: %ver%

Source: src/Migration/ExternalMigration.php:199

for_this_site()

public static function for_this_site(): self

The migration over this site's own registries.

Returns

• self

Since: %ver%

Source: src/Migration/ExternalMigration.php:211

providers()

public function providers( array $directions=[ self::DIRECTION_TO, self::DIRECTION_FROM ] ): array

What this site can move to and from, and why one of them cannot be used.

One row per plugin rather than one per direction, because a plugin is what an operator names on the command line and the two directions are separate answers about it: Fluent Forms needs one class to be read from and two to be written to, so a site can be able to import from a plugin it cannot export to.

A direction is listed only when it is asked for, because the two are gated differently (\Permission::readable_directions()) and a caller that may show one half must not be handed the other: the import half carries a from verdict and, in reason, the names of the classes that half is missing. A direction left out has no column and no say in the reason, rather than a column reading "no" -- which would state something about a direction nobody looked at.

Parameters

Name	Type	Default	Description
$directions	string[]	[ self::DIRECTION_TO, self::DIRECTION_FROM ]	Which of \self::DIRECTION_TO() and DIRECTION_FROM to list.

Returns

• array<int, — array{plugin:string,name:string,to?:string,from?:string,reason:string}>

Since: %ver%

Source: src/Migration/ExternalMigration.php:238

provider()

public function provider( string $direction, string $slug )

The provider a slug names, for one direction.

Parameters

Name	Type	Default	Description
$direction	string		\self::DIRECTION_TO() or \self::DIRECTION_FROM().
$slug	string		Provider slug as the operator typed it.

Returns

• ExporterInterface | ImporterInterface | WP_Error

Since: %ver%

Source: src/Migration/ExternalMigration.php:404

registered_slugs()

public function registered_slugs( string $direction ): array

Every slug registered for a direction, whether or not this site can use it.

Parameters

Name	Type	Default	Description
$direction	string		\self::DIRECTION_TO() or \self::DIRECTION_FROM().

Returns

• string[]

Since: %ver%

Source: src/Migration/ExternalMigration.php:453

resolve_form_ids()

public static function resolve_form_ids( string $requested, array $available, string $source='' )

The forms a --forms value names, checked against the ones the provider actually has.

Membership rather than shape: unlike a Gravity Forms id, another plugin's id is whatever that plugin uses, and the list to check against is already in hand. A refusal names the id that was not found and the ones that were, because "form not found" with nothing beside it leaves the operator guessing at ids.

The side those ids belong to is named by the caller, because this function cannot tell: on an export the ids are GRAVITY FORMS ids, and "that plugin has no form 4" pointed the operator at the destination plugin for a form that is missing from the source.

Parameters

Name	Type	Default	Description
$requested	string		The --forms value.
$available	array		Every id the provider listed, in its own types.
$source	string	''	What to call the side these ids belong to (\self::listing_name()).

Returns

• array | WP_Error — The provider's own ids, in the order asked for.

Since: %ver%

Source: src/Migration/ExternalMigration.php:484

forms_named()

public function forms_named( string $direction, $provider, string $requested )

The forms a --forms value names, looked up and refused in the right plugin's name.

One call rather than three, because the three have to agree: the ids are checked against the listing of ONE side of the migration, and a refusal about them has to name that same side. Left to the caller to assemble, the naming is a step that can be forgotten -- and forgetting it is not visible until an operator is sent to the wrong plugin.

Parameters

Name	Type	Default	Description
$direction	string		\self::DIRECTION_TO() or \self::DIRECTION_FROM().
$provider	ExporterInterface | ImporterInterface		The provider.
$requested	string		The --forms value.

Returns

• array | WP_Error — The provider's own ids, in the order asked for.

Since: %ver%

Source: src/Migration/ExternalMigration.php:571

listing_name()

public static function listing_name( string $direction, $provider ): string

What to call the side a --forms list names, which is not the side the operator named.

wp gk migrate to wpforms --forms=3 names WPForms and then lists GRAVITY FORMS ids: migrate_external() hands the exporter over, and AbstractExporter::list_forms() returns this site's Gravity Forms forms. So a refusal about one of those ids has to say Gravity Forms, or it points the operator at the plugin they are migrating TO for a form that is missing from the one they are migrating FROM.

Parameters

Name	Type	Default	Description
$direction	string		\self::DIRECTION_TO() or \self::DIRECTION_FROM().
$provider	ExporterInterface | ImporterInterface		The provider.

Returns

• string

Since: %ver%

Source: src/Migration/ExternalMigration.php:595

analyze()

public static function analyze( string $direction, $provider, $form_id )

What one form loses on the way across, before anything is written.

An export analysis is given the field-type context the wizard's route attaches, because without it the field table names every field and says nothing about any of them. An import analysis already carries every key from its own adapter, and attaching the export context would describe the wrong end of the migration.

Parameters

Name	Type	Default	Description
$direction	string		\self::DIRECTION_TO() or \self::DIRECTION_FROM().
$provider	ExporterInterface | ImporterInterface		The provider.
$form_id	mixed		Form id in the provider's own terms.

Returns

• array | WP_Error

Since: %ver%

Source: src/Migration/ExternalMigration.php:615

run()

public static function run( string $direction, $provider, $form_id )

Writes one form, and returns what the provider reported about writing it.

Parameters

Name	Type	Default	Description
$direction	string		\self::DIRECTION_TO() or \self::DIRECTION_FROM().
$provider	ExporterInterface | ImporterInterface		The provider.
$form_id	mixed		Form id in the provider's own terms.

Returns

• array | WP_Error

Since: %ver%

Source: src/Migration/ExternalMigration.php:650

messages()

public static function messages( $payload, string $key ): array

The sentences under one key of a provider payload.

warnings, notices and requires_addons are separate channels and stay separate: "this form has been imported before" changes nothing about the form, so it must not print under a heading that says something was lost; and "the Signature Add-On is needed" is not a loss either but something the operator has to do before the form works. The wizard draws the three under three headings, and until the third was read here a dry run printed "Sign here (Signature) -> Signature -- Stays the same" for a field that renders as an empty box on a site without the add-on. A message sent as an object is read for its text, and an empty one is dropped rather than printed as a blank line.

Parameters

Name	Type	Default	Description
$payload	mixed		An analysis or a run result.
$key	string		warnings, notices or requires_addons.

Returns

• string[]

Since: %ver%

Source: src/Migration/ExternalMigration.php:702

run_warnings()

public static function run_warnings( $result, $analysis ): array

What the run itself found out, which nothing before it could have said.

An analysis carries only what is knowable before a form is written. Some warnings are not: WSFormExporter::export_form() asks the installed WS Form for db_conditional_repair() only after the form exists and reports the answer in the payload it returns. That warning reached no surface at all before the wizard's Done screen was given it, and this is the second surface -- GMIG-113 item 2.

The run's warnings minus the ones already read, because the same sentence printed twice reads as two separate losses. Without an analysis -- no dry run, or one that failed -- nothing has been read and every sentence is new.

Parameters

Name	Type	Default	Description
$result	mixed		The payload the run returned for one form.
$analysis	mixed		The analysis printed for it beforehand, if there was one.

Returns

• string[]

Since: %ver%

Source: src/Migration/ExternalMigration.php:738

forms()

public function forms( $provider ): array

The forms a provider has, listed once per run.

Parameters

Name	Type	Default	Description
$provider	ExporterInterface | ImporterInterface		The provider.

Returns

• array

Since: %ver%

Source: src/Migration/ExternalMigration.php:806

form_ids()

public function form_ids( $provider ): array

Every form id a provider has, in its own types.

Parameters

Name	Type	Default	Description
$provider	ExporterInterface | ImporterInterface		The provider.

Returns

• array

Since: %ver%

Source: src/Migration/ExternalMigration.php:828

titles()

public function titles( $provider ): array

A provider's form titles, keyed by form id.

Parameters

Name	Type	Default	Description
$provider	ExporterInterface | ImporterInterface		The provider.

Returns

• array

Since: %ver%

Source: src/Migration/ExternalMigration.php:841

created_form_id()

public static function created_form_id( string $direction, $result )

The id of the form a run created, whichever end of the migration created it.

The two directions report it under different keys, because each names the form it made: an export writes into the destination plugin and calls it target_form_id, an import writes a Gravity Forms form and calls it gravity_form_id.

Parameters

Name	Type	Default	Description
$direction	string		\self::DIRECTION_TO() or \self::DIRECTION_FROM().
$result	mixed		The payload the run returned for one form.

Returns

• mixed — Null when the run named no form.

Since: %ver%

Source: src/Migration/ExternalMigration.php:859

check_form()

public static function check_form( string $direction, $provider, $form_id, array $titles=[] ): array

Checks one form without writing anything.

Parameters

Name	Type	Default	Description
$direction	string		\self::DIRECTION_TO() or \self::DIRECTION_FROM().
$provider	ExporterInterface | ImporterInterface		The provider.
$form_id	mixed		Form id in the provider's own terms.
$titles	array	[]	Form id => title, where the caller has them.

Returns

• array — One form's entry in the report.

Since: %ver%

Source: src/Migration/ExternalMigration.php:878

migrate_form()

public static function migrate_form( string $direction, $provider, $form_id, array $titles=[] ): array

Migrates one form, and reports what the migration said about it.

The form is analysed first, exactly as the wizard does before it writes anything, for two reasons: the warnings that were knowable beforehand are worth reporting, and knowing them is what lets the ones the RUN produced be named as such. A warning WS Form's exporter raises while writing a form -- the installed edition having no db_conditional_repair() -- cannot have been on the analysis, and reaches no surface unless a run reports it.

An analysis that fails is not a reason to refuse the migration: it means nothing was read beforehand, so every sentence the run produces is new.

Parameters

Name	Type	Default	Description
$direction	string		\self::DIRECTION_TO() or \self::DIRECTION_FROM().
$provider	ExporterInterface | ImporterInterface		The provider.
$form_id	mixed		Form id in the provider's own terms.
$titles	array	[]	Form id => title, where the caller has them.

Returns

• array — One form's entry in the report.

Since: %ver%

Source: src/Migration/ExternalMigration.php:926

migrate()

public function migrate( string $direction, $provider, array $form_ids, bool $dry_run ): array

One entry per form: what a migration of these forms did, or would do.

The whole run, so that a surface is left with rendering and nothing else. A dry run reads every form and writes none; a real run does both, and each form is reported whether it went across or not, because a batch that stopped at the first failure would leave the operator unable to say which of the rest are on the site.

Parameters

Name	Type	Default	Description
$direction	string		\self::DIRECTION_TO() or \self::DIRECTION_FROM().
$provider	ExporterInterface | ImporterInterface		The provider.
$form_ids	array		Form ids in the provider's own terms.
$dry_run	bool		Whether to write anything.

Returns

• array<int, — array> One entry per form, in the order asked for.

Since: %ver%

Source: src/Migration/ExternalMigration.php:978

analyze_batch()

public static function analyze_batch( string $direction, $provider, array $form_ids ): array

What several forms lose on the way across, answered per form.

A form that cannot be read is reported against its own id rather than thrown, because a batch that failed whole would blank a screenful of answers over one bad form. Only failures that apply to every id equally -- a bad nonce, a missing capability, an unavailable provider -- belong to the caller, which refuses the request before reaching here.

Both maps are keyed by the id as a string, because a caller looks answers up by what it sent.

Parameters

Name	Type	Default	Description
$direction	string		\self::DIRECTION_TO() or \self::DIRECTION_FROM().
$provider	ExporterInterface | ImporterInterface		The provider.
$form_ids	array		Form ids in the provider's own terms.

Returns

• array{results: — array<string, array>, errors: array<string, string>}

Since: %ver%

Source: src/Migration/ExternalMigration.php:1009