Improve migration docs: import/export WordPress sites with Playground

[flexseth]

Much of what Playground does is meant to be portable. Whether you want to import an existing website to demo a plugin, change a theme and provide a working demo back to the client... importing and exporting is a big part of what the Playground does.

However, there is virtually no documentation on how to import content or websites with Playground.

Action items

• Improve docs on importing content via WXR
• Improve docs on importing via WXZ (what is this?)
• Manually importing and exporting sites via CLI & MySQL + files - see Support .sql files in the importer #1201

Existing documentation

Import a WXZ or a WXR file

You can import a WordPress export file by uploading a WXZ, or WXR file in /wp-admin/.

• Fix broken link / improve - PR Updated link to native WordPress importer #1243

You can also use JSON Blueprints. See getting started with Blueprints to learn more.

• Provide functioning blueprint code sample and import file

This is different from the import feature described above. The import feature exports the entire site, including the database. This import feature imports a WXR or WXZ file into an existing site.

• Clarify. No context. - Waiting on Site Transfer protocol Sync Protocol #797

What is WXZ file? No documentation....

• Create documentation and sample WXZ file if applicable - not applicable - wait for Site Transfer protocol

About WXZ import...
#88 (comment)

[adamziel]

Improve docs on importing content via WXR

Fully agreed. The importFileStep should be just called importWXR while keeping the old name working.

Improve docs on importing via WXZ (what is this?)

I'd just remove WXZ support at this point. I'm not sure if anyone uses it or is aware of that format and at the same time it adds a maintenance overhead. If someone reports a WXZ issue, we won't be able fix it. Besides, the Site Transfer Protocol will solve the same problem, but more completely and without problems with IDs and database relations.

Manually importing and exporting sites via CLI & MySQL + files

The WordPress Playground plugin enables that from wp-admin. We don't yet have other export&import workflows in place. @bgrgicak what do you think about adding a "Download Snapshot" button to that plugin so that it could be easily imported into Playground?

The ultimate solution will be the Site Transfer Protocol, but we're not there yet. The Documentation Workflow explores the first baby steps with rewriting Site URLs in the exported files.

[bgrgicak]

The WordPress Playground plugin enables that from wp-admin. We don't yet have other export&import workflows in place. @bgrgicak what do you think about adding a "Download Snapshot" button to that plugin so that it could be easily imported into Playground?

Sounds good, it shouldn't be a lot of work. Should we also add import support?
Adding a CLI command for both wouldn't be a lot of extra work.

[adamziel]

Should we also add import support?

I wouldn't do it yet. Sure, there's existing code we could transplant, but without the upcoming bits from Site Transfer Protocol it will break.

Adding a CLI command for both wouldn't be a lot of extra work.

Let's hold on with that and keep the scope minimal for now. It's difficult enough to keep up with maintaining the existing Playground implementations.

[bgrgicak]

I added Playground snapshot as an option to Tools > Export.

The exported ZIP doesn't work with Playground because the export format is different for the Playground plugin and Playground web. This will need to be addressed separately.

@adamziel Should we adjust the plugin export format to match Playground, or should we add this as another format to Playground?

[bgrgicak]

@adamziel Should we adjust the plugin export format to match Playground, or should we add this as another format to Playground?

This will need to be implemented in Playground. The Playground export uses wp-content/database/.ht.sqlite and that plugin uses schema/_Schema.sql. These two exports are in different formats.
I suggest that we add some code that detects if schema/_Schema.sql exists in the import zip and execute it as SQL. This would match what the plugin is doing.

[adamziel]

Agreed, both places should be the same format and the .sql file might be impossible to avoid if it needs to be portable. I'm just worried about binary data.

[bgrgicak]

Here is the export PR WordPress/playground-tools#219
It also updates the db path to wp-content/database/database.sql.

[bgrgicak]

Playground import issue #1201

[flexseth]

Should we also add import support?

I wouldn't do it yet. Sure, there's existing code we could transplant, but without the upcoming bits from Site Transfer Protocol it will break.

Adding a CLI command for both wouldn't be a lot of extra work.

Let's hold on with that and keep the scope minimal for now. It's difficult enough to keep up with maintaining the existing Playground implementations.

For now I'm going to look at the ways it's possible to import/export and add that to the docs.
Check back to the issue for updates when the tasks are completed.

[flexseth]

I'll be working on these docs for the Yoast contributor day!

• Online Yoast Contributor Day - April 18, 2024 #1185

[flexseth]

Functioning example on the Blueprints Gallery page