=== PageFerry - Move Pages from Staging to Live ===
Contributors: vadimc
Tags: staging, migration, export, import, gutenberg
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 8.1
Stable tag: 1.3.8
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Move a WordPress page from staging to live, with its images. Export and import Gutenberg pages between sites.

== Description ==

Move a WordPress page from staging to live with PageFerry, a free export and import plugin for the WordPress block editor (Gutenberg). Bring the page and its images together in one ZIP, review it on the destination site, then create a draft or update an existing page.

Use PageFerry to publish a landing page built on staging, transfer a blog post with its images, or copy a Gutenberg page to another WordPress site. You can also export from a local development site: the destination imports the files from your ZIP without connecting to the source site.

Create a new draft or update a page you choose. Before importing, you can edit the title, URL slug and excerpt, choose a featured image and page template, and select media, categories and tags. The page content and supported custom field values are imported together.

PageFerry updates image references and links to the source site so they work on the destination. Media files already in the destination Media Library are reused when their contents match exactly. Files with the same name but different contents are imported separately.

Supported custom post types, custom categories and tags, and Advanced Custom Fields (ACF) values can move too. Install the plugins or theme that provide those content types, blocks and fields on the destination site first. ACF field definitions are not included in the ZIP.

The result screen and Import log help you check what was saved. Before updating existing content, PageFerry saves a recovery snapshot of the previous version. You can read the snapshot and restore the values manually in WordPress.

PageFerry moves one page at a time. It does not transfer an entire website, themes, plugins, site settings, SEO metadata or a whole Media Library. Pages made with unsupported page builders are refused. Bulk imports, direct site-to-site transfers and multisite migrations are outside its scope.

Small ZIPs upload in one request. If a ZIP exceeds the site's upload limit, PageFerry prepares it in your browser and uploads its media files one at a time. Both methods use the same import checks. Individual file and total-size limits still apply; see the FAQ.

PageFerry is free and open source. No account, license key or external import service is required.

== Installation ==

1. Install and activate PageFerry on both WordPress sites. You can upload the plugin ZIP through Plugins → Add New → Upload Plugin.
2. On the source site, open the page in the editor. Under PageFerry Export, click Export page to download its ZIP.
3. On the destination site, go to Tools → PageFerry Import. Choose the ZIP, then choose Create a new draft or Update existing content. For an update, select the page you want to replace.
4. Check the Content type setting and click Review import. Check the destination, page details, media and any items that need attention. Edit the details and select the items you want to import.
5. Confirm the import. Open the result in the WordPress editor and check the page. Publish the draft when it is ready.

The Content type setting starts with the type recorded in the ZIP. You can choose another supported type. A matching title never selects a page for update automatically.

Requirements: WordPress 6.5 or later and PHP 8.1 or later. The PHP ZIP extension is required for export and for opening ZIPs on the server. Sites without it can import through the browser with JavaScript enabled.

== Screenshots ==

1. Choose a ZIP and create a draft or select an existing page to update.
2. Review page details and planned changes before importing.
3. Open the imported page and check what was saved.
4. Read a recovery snapshot saved before updating a page.

== Frequently Asked Questions ==

= Can I move a page from staging to live? =

Yes. Install PageFerry on both sites, export the page on staging, then import its ZIP on the live site. Create a new draft to check before publishing, or select an existing page to update. Updating a published page changes the live page as soon as the import is saved; it keeps its published status.

PageFerry updates only the content you select and the media, categories, tags and supported fields included in the import. It does not replace the live site's database, themes, plugins or settings. Before updating a page, it saves a recovery snapshot. Restoration is manual.

= Can I copy a page to another WordPress site or export from localhost? =

Yes. The sites can use different hosts or domains, and the source can be a local WordPress installation. The ZIP contains the exported media files, so the destination does not need to connect to the source. Install the theme, custom block plugins and matching field definitions needed to display the page on the destination first.

= Does it work with Elementor or other page builders? =

PageFerry supports the WordPress block editor (Gutenberg). If an export identifies Elementor, Divi, Beaver Builder, Bricks or WPBakery content, PageFerry refuses the import and names the builder. Rebuild the page in the block editor, then export it again.

Install the theme and any custom block plugins needed to display the page on the destination site. PageFerry does not transfer them.

= What happens to images already in my Media Library? =

PageFerry compares file contents using SHA-256 checksums. Before reusing a file, it checks the existing file again. A deleted or changed file is not reused just because an old record says it matches.

Identical files are reused. Files with the same name but different contents are imported separately. Reused attachments keep their existing details. The review shows how many files will be added or reused, and which files are missing.

= Will importing change my files or page text? =

PageFerry keeps each new media file's original contents as its main file. WordPress can create thumbnails and add a filename suffix when another file already uses that name. PageFerry does not automatically scale, rotate or convert the main file. If the filename does not match the file type, or a site plugin changes the file during upload, the import stops with an explanation before saving the page.

Automatic changes in page content, excerpts and supported custom fields are limited to media references and the source site's address. Other URL paths, query strings, page text, formatting and block settings stay as they were in the ZIP. Details you edit or select in the review follow your choices.

= Should I create a draft or update an existing page? =

Choose Create a new draft to add content without replacing an existing page. Choose Update existing content to replace the content of a page you select, along with the details you include in the review.

An update keeps the page's publication status. The current URL slug is kept unless you edit it. If you update a published page, the saved changes appear on the live site. A recovery snapshot is saved first.

The selected page must have the Content type you chose. You can import into another supported type, but check that the categories, tags and page template are available for it.

= Can I choose which parts to import? =

Yes. The review lists every media file and category or tag from the ZIP. You can edit the title, excerpt and URL slug, choose a featured image and template, and deselect items you do not want. Reset returns an edited detail to its value from the ZIP.

For categories and tags, leave Clear current unchecked to keep the page's existing choices and add the selected ones. Check Clear current to replace them. If Clear current is checked and nothing is selected, the existing choices are removed. The All checkbox and individual checkboxes do not change that setting.

Parent categories are included when needed to recreate the category structure. Existing categories keep their current parents. Names, URL slugs and parent categories are used to match existing choices; older ZIPs with names only are matched by name.

Some files in the ZIP may not be used on the page. Files marked “Check this file” start unchecked. Select any you need before importing. Images and links that use deselected files may still point to the source site or stop working. Check them in the editor after importing.

A featured image must also be selected in the Media section. Previews come from the uploaded files; some image formats or sizes cannot be previewed. All files are prepared before you make these choices. The page content and supported custom field values are always imported together.

= What if some details could not be saved, or the connection was lost? =

A partial result means the page content was saved, but some details need attention. The result and import log identify those details and link to a recovery snapshot when one is available. Check the saved page before continuing.

If the connection is lost after the import starts, the server may still save the page. Check the destination and Import log before trying again so you do not create a duplicate. PageFerry does not automatically repeat the import. A missing log entry alone does not prove that nothing was saved.

= Where is the previous version of an updated page? =

Go to Tools → PageFerry Import → Recovery snapshots. Before an update, PageFerry saves the previous title, content, excerpt, URL slug, categories and tags, featured image and other page data. Successful updates retain the most recent 20 snapshots; partial results keep their recovery data.

Open the snapshot and use its values to restore the page manually in the WordPress editor. Ask a developer for help with other saved page data if needed. Opening a snapshot makes no changes. There is no one-click restore button.

= How large can my ZIP and media files be? =

Each media file must fit the site's upload limit and PageFerry's 256 MiB file limit. If a file is too large, reduce it and export the page again, or ask your host to raise a lower upload limit. The error identifies the file.

PageFerry also limits the whole import:

* Up to 500 media files to upload and 5,000 media items in the ZIP's media list.
* Up to 4 MiB of page information and a 1 GiB compressed ZIP containing at most 2,048 entries.
* Browser preparation allows up to 512 MiB of media in total.
* Server preparation allows media totalling twice a positive site upload limit, capped at 1 GiB. If no positive upload limit is available, it uses 512 MiB.

Site administrators can lower these limits. The browser reads files one at a time and waits for each upload before reading the next. A ZIP can be refused before the review if it exceeds a limit.

Exports follow the source site's import limits too. The source server needs temporary space for copies of the media files and the finished ZIP. A destination site with lower limits may still refuse the export.

= Does PageFerry move ACF custom fields? =

Yes. PageFerry moves supported ACF values stored in blocks and in custom fields on the exported page. It updates image, file and gallery references to use the imported media, and updates supported links to the source site.

Install ACF and matching field definitions on the destination first. Field definitions and site-wide ACF options are not included. Fields unavailable on the destination are skipped and listed in the review and import log. Fields with no saved value on the source are omitted; on updates, the corresponding destination values are kept. Saved empty values and zero values do transfer. Export with PageFerry 1.2.2 or later to use this handling of saved values.

Fields that refer to other posts, categories, tags or users are copied unchanged. Those references may point to different content on the destination, so check them after importing. Nested groups, repeaters and flexible content need matching field definitions. If their structure does not match, the whole field is skipped and its existing destination value is kept.

Fields using ACF's Save Terms or bidirectional update settings are skipped, including groups containing such fields. The review and log explain the skipped fields. These imports leave related objects and reused attachments unchanged; only media created by the current import can be attached to the destination page through these ACF writes.

For developers: ACF block values stored in block comments are carried with the content. Blocks using usePostMeta (ACF PRO 6.3 or later) also carry their saved field values. Page-level fields are checked against the fields available for the chosen post type or selected page and restored through the ACF API.

= What happens to synced patterns? =

Synced patterns are not included in the ZIP. The imported page keeps their references, so that part of the page may be empty or show different content on the destination site. Detach the pattern on the source page and export again, or recreate and check it on the destination before importing.

= Where are temporary files stored? =

PageFerry uses a private temporary folder outside WordPress and its uploads folder. It checks the location and permissions before using it. Export and import stop if private storage is unavailable.

The uploaded ZIP is deleted after server preparation. Files from cancelled or abandoned imports may remain temporarily; later visits to the PageFerry admin screen trigger cleanup after an idle period. Files still in use are protected. Imports prepared in an older uploads location need a new review. Older folders are removed only when PageFerry can verify that they belong to an inactive import; unrelated uploaded files are kept.

For hosts: set PAGEFERRY_PRIVATE_DIR in wp-config.php to an existing private parent folder if PHP's temporary folder is unsuitable. Keep it outside all public document roots and web-server aliases. Secure PHP's upload temporary folder too. All PHP processes handling the same import must share this storage and support consistent file locks and rename operations; containers need a shared private storage mount.

= Does PageFerry contact an external service? =

No. PageFerry makes no outbound requests and uses no remotely loaded scripts, account or license key. Its JavaScript is bundled with the plugin, including the fflate ZIP library (version 0.8.3, MIT license; https://github.com/101arrowz/fflate).

Import and export actions check WordPress permissions and security tokens. Media access and editing permissions are checked for the content involved.

== Changelog ==

= 1.3.8 =
* Improve detection of images and files in saved block settings and supported ACF fields. Files that may be unused start unchecked unless the saved page confirms their use.
* Preserve font settings, dimensions, counts and references to other content when their numbers match an imported media file.
* Continue saving the page when destination plugins process uploaded media. Keep verification of PageFerry's own file copies and protection against automatic WordPress resizing, rotation and conversion.

= 1.3.7 =
* Show a loading placeholder for image previews and retry temporary failures. Load previews one at a time and share matching previews across Media and Featured image.
* Add a descriptive plugin name and clarify staging-to-live page transfers, copying pages between sites and exports from local WordPress installations in the plugin description and FAQ.

= 1.3.6 =
* Reuse identical Media Library files even when they are stored outside dated upload folders, renamed or missing from earlier matching records.
* Recognize images and files in saved ACF block fields, including repeaters, groups, flexible content and clones.
* Preserve exported media during import and prevent WordPress from automatically scaling, rotating or converting main files. Destination plugins can apply their own media processing.
* Preserve page formatting and unrelated values. Automatic content changes are limited to media IDs, media URLs and the source site's protocol and domain.
* Use clearer labels, help, warnings and import results throughout PageFerry.
* Show safe SVG previews and block names in the review. Keep unchanged reused files included and show destination choices after selecting a ZIP.
* Replace the upload function disallowed by WordPress.org and add Plugin Check to the standard release checks.

= 1.3.5 =
* Show each import template once, with its display name. Keep the ZIP, default and current-template choices available.
* Avoid incorrect missing-template notices when templates share a display name.
* Show the export date and update the draft title in the review as it is edited.
* Reduce repeated media checks and loading while keeping the final import checks.
* Use private temporary storage, check export size limits and verify ZIP downloads.
* Add repeatable Docker checks for supported WordPress and PHP versions.

= 1.3.4 =
* Update the review immediately after edits, bulk selections and resets, without sending server requests.
* Save the choices shown when the import is confirmed, with permission and file checks before saving.
* Keep valid choices ready to import without waiting for a review refresh.

= 1.3.3 =
* Update review summaries immediately when page details, media, categories, tags, featured images or templates change.
* Reduce repeated media and review checks while editing, with final checks before saving.
* Keep typed values and controls in place during checks, including slow responses and retries.

= 1.3.2 =
* Switch between Import, Import log and Recovery snapshots without losing the current import.
* Check edits automatically before confirmation and preserve newer choices during slow checks.
* Hide empty category and tag rows and unnecessary Clear controls.

= 1.3.1 =
* Improve the import layout with ZIP and destination cards, featured-image choices, media labels and inline review details.

= 1.3.0 =
* Add the Set up, Review and Result import flow, with details visible on the page.
* Read the post type and page title from the ZIP. Allow edits to the title, URL slug, excerpt, featured image and template before confirmation.
* Allow categories and tags to be added to existing choices or replace them using Clear current.
* Distinguish saved pages, partial results and results that could not be confirmed, with recovery information when available.

= 1.2.5 =
* Preserve import log entries and media matching records when imports run at the same time, including after cleanup.
* Save each import's new media matching records together.

= 1.2.4 =
* Skip incompatible nested ACF values before changing a field, preserving existing values and explaining the skip in the review and result.

= 1.2.3 =
* Preserve backslashes in imported ACF values, including paths, regular expressions, JSON and nested fields. Avoid reporting a failure when those values were saved correctly.

= 1.2.2 =
* Export only saved ACF values, including nested values. Keep saved empty and zero values, and preserve destination values for omitted fields during updates.

= 1.2.1 =
* Skip ACF fields that use Save Terms or bidirectional updates, including groups containing those fields, and explain the skipped values.
* Keep reused attachments connected to their existing pages. ACF imports can attach only newly imported media to the destination page.

= 1.2.0 =
* Move the exported page's own ACF field values, with updated media references and links.
* Restore fields available on the destination and explain skipped or incompletely saved values in the review and log. Field definitions and site-wide options are not included.

= 1.1.0 =
* Support custom post types using the block editor, along with their categories and tags. The content type must already be available on the destination.
* Move saved ACF usePostMeta block values, update media references and links, and report skipped values. References to other content are copied unchanged and need checking.

= 1.0.0 =
* First release: move a block editor page or post and its media in a ZIP, update image references and site links, reuse identical files, and create a draft or update selected content.
* Save the previous version before updates and record import results. Refuse imports identified as unsupported page-builder content.
