Add wp media replace subcommand

[Copilot]

Adds a wp media replace <attachment-id> <file> subcommand to swap the underlying file of an existing attachment while preserving its identity (ID, title, alt text, caption, etc.).

Changes

• src/Media_Command.php — New replace() method:

  • Accepts a local path or URL as the replacement file (same handling as import)
  • Sideloads the new file into the uploads directory via wp_handle_sideload()
  • Cleans up temp file on sideload failure to prevent leaks in the system temp dir
  • Deletes old thumbnails, the previous full-size file, and (on WP 5.3+) the original pre-scaled image to avoid orphaned files in uploads
  • Updates MIME type via wp_update_post() with $wp_error=true for proper error detection
  • Validates wp_generate_attachment_metadata() return value before updating; preserves existing metadata on failure
  • Refreshes _wp_attached_file meta and regenerates attachment metadata
  • --skip-delete — skip deletion of old thumbnail files and full-size file
  • --porcelain — output only the attachment ID (useful for scripting)

• composer.json — Registers media replace in extra.commands

• features/media-replace.feature — Behat tests covering: local file, URL, porcelain mode, metadata preservation, error cases (invalid ID, missing file), and --skip-delete flag (asserts old file is preserved on disk)

Usage

# Replace with a local file
$ wp media replace 123 ~/new-image.jpg
Replaced file for attachment ID 123 with '/home/user/new-image.jpg'.
Success: Replaced 1 of 1 attachments.

# Replace with a remote URL, return ID only
$ wp media replace 123 'http://example.com/image.jpg' --porcelain
123

# Replace without deleting the old file
$ wp media replace 123 ~/new-image.jpg --skip-delete
Replaced file for attachment ID 123 with '/home/user/new-image.jpg'.
Success: Replaced 1 of 1 attachments.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Feature request: media replace subcommand</issue_title>
<issue_description>Hi,

I would like to suggest a new feature (subcommand) that would allow to seamlessly replace media file of existing attachment: media replace <file> <attachment_id>.

For the time being, I use Enable Media Replace whenever I need to replace media file, but it would be great to have a command line equivalent.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Feature request: media replace subcommand #90

---

📍 Connect Copilot coding agent with Jira, Azure Boards or Linear to delegate work to Copilot in one click without leaving your project management tool.

[codecov]

Codecov Report

❌ Patch coverage is 75.34247% with 18 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/Media_Command.php	75.34%	18 Missing ⚠️

📢 Thoughts on this report? Let us know!