RML Gallery Block Converter

Converts Real Media Library Gallery blocks into native WordPress Gallery blocks.

This plugin is intended for one-time content migration when a site wants to stop using Real Media Library galleries and manage images directly in the WordPress block editor.

What It Converts

The converter scans post content for:

<!-- wp:real-media-library/gallery {"fid":123} /-->

It replaces each RML Gallery block with a native core Gallery block containing nested core Image blocks.

The generated Gallery block:

• Uses standard WordPress core/gallery and core/image blocks.
• Links images to their media files.
• Preserves the RML gallery image order where available.
• Uses the original attachment ID when an RML row is a shortcut.
• Preserves image alt text and captions from the WordPress attachment.

Requirements

• WordPress 6.0 or newer.
• PHP 7.4 or newer.
• Real Media Library must still be active, or at least its database table must still exist, while conversion runs.

Admin Tool

After activation, go to:

Tools -> RML Gallery Converter

The tool provides:

• Post type selection.
• Optional single post ID targeting.
• Dry run mode.
• Conversion mode.
• Optional mode to keep the original RML Gallery block after inserting the converted Gallery block.
• Pre-conversion WordPress revision capture when the post type supports revisions.
• Rollback for posts that were converted by this plugin.
• Cleanup action for deleting converter backup/report metadata after migration is accepted.
• Per-post conversion report.

Recommended Workflow

1. Back up the database.
2. Keep Real Media Library active.
3. Run a dry run.
4. Review the listed posts and warnings.
5. Optionally enter a single post ID and convert one post first.
6. Run conversion for the full selected scope.
7. Review converted posts in the editor and on the front end.
8. Deactivate Real Media Library only after verification.
9. Keep this plugin available until rollback is no longer needed.

Single Post Testing

Enter a post ID in the Single post ID field to scan or convert only that post.

When a single post ID is provided, post type selections are ignored for that run.

Keeping the Original RML Block

By default, conversion replaces each RML Gallery block with a native WordPress Gallery block.

For comparison testing, enable Keep the original RML Gallery block after inserting the new core Gallery block. This inserts the converted Gallery block before the original RML block.

This option is off by default because most migrations should end with only native Gallery blocks in the content.

Rollback

Before updating a post, the converter stores the original post_content in post meta.

When the post type supports WordPress revisions, the converter also saves a pre-conversion revision immediately before updating the post. This helps preserve the RML Gallery version in normal WordPress revision history.

Rollback restores that original content for selected post types. It does not delete the stored backup meta, so rollback can be repeated if needed.

Cleanup

After converted content has been reviewed and rollback is no longer needed, use Delete Conversion Backups to remove this plugin's backup and report metadata for the selected scope.

Cleanup deletes only these post meta keys:

_rmlgbc_original_post_content
_rmlgbc_original_post_content_date
_rmlgbc_converted_at
_rmlgbc_conversion_report

Cleanup does not delete Real Media Library data and does not change post content.

Notes

• The plugin does not delete Real Media Library folders, galleries, shortcuts, or database tables.
• The plugin only changes post content when conversion is explicitly run.
• The plugin is most useful as a temporary migration utility, but it can remain installed while converted content is being reviewed.

Release Process

1. Update the version in rml-gallery-block-converter.php.
2. Commit changes.
3. Create and push a version tag, for example:

git tag v1.0.0
git push origin main
git push origin v1.0.0

The GitHub Actions release workflow builds a plugin zip from the tag.