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()
  • Deletes old thumbnails, updates MIME type, refreshes _wp_attached_file meta, and regenerates attachment metadata
  • --skip-delete — skip deletion of old thumbnail files
  • --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, and error cases (invalid ID, missing file)

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 images.

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

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 81.13208% with 10 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/Media_Command.php	81.13%	10 Missing ⚠️

📢 Thoughts on this report? Let us know!