Add Attachments processor class for handling ActivityPub media

[obenland]

Fixes #2277

Proposed changes:

This PR introduces a new Attachments processor class that provides unified handling of ActivityPub attachments (images, videos, audio, documents) for both remote URLs and local files.

• Unified attachment processing: New Attachments class centralizes all attachment handling logic previously scattered across multiple classes
• Remote URL support: Downloads and imports media from ActivityPub network using media_handle_sideload()
• Local file support: Processes files from Mastodon archive imports without moving originals
• Smart media markup generation: Automatically generates appropriate WordPress blocks (gallery for multiple images, video/audio blocks for media files)
• Classic Editor compatibility: New integration adds filter-based extensibility for custom markup generation
• Metadata preservation: Stores source URLs and alt text for images via post meta

Other information:

• Have you written new tests for your changes, if applicable?

Testing instructions:

Test remote attachments (ActivityPub network):

1. Set up a test ActivityPub post with images from another server (e.g., Mastodon instance)
2. Send a Create activity with attachments to your WordPress site
3. Verify the post is created with images properly attached and displayed
4. Check that alt text from the ActivityPub name field is preserved as image alt text
5. Verify images are saved to WordPress media library with correct metadata

Test local attachments (Mastodon import):

1. Export a Mastodon archive that includes posts with media attachments
2. Go to Tools > Import > Mastodon
3. Upload the archive ZIP file and run the import
4. Verify posts are imported with their original media preserved
5. Check that images appear correctly in the post content (as gallery blocks or individual images)
6. Confirm attachment metadata (source URL) is preserved

Test Classic Editor integration:

1. Activate Classic Editor plugin
2. Create a post that receives ActivityPub attachments
3. Verify that attachments are properly appended to post content
4. Test the activitypub_attachments_media_markup filter for custom markup

Run automated tests:

npm run env-test

All tests should pass, including the 14 new tests in class-test-attachments.php.

Changelog entry

• Automatically create a changelog entry from the details below.

Changelog Entry Details

Significance

• Patch
• Minor
• Major

Type

• Added - for new features
• Changed - for changes in existing functionality
• Deprecated - for soon-to-be removed features
• Removed - for now removed features
• Fixed - for any bug fixes
• Security - in case of vulnerabilities

Message

Add unified attachment processor for handling ActivityPub media imports from both remote URLs and local files, with automatic media block generation and Classic Editor support.

[Copilot]

Pull Request Overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 7 comments.

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Jiwoon-Kim]

For example, if the hosting policy offers unlimited databases but only 1 GB of storage space, would that still be sufficient for normal use?

[pfefferle]

The image is still added twice, if it is inline and an attachment. I think we should de-duplicate them and not add the attachment if the image is already inline.

Pardon me! This works like a charm and I simply messed up my test!

[Copilot]

Pull Request Overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Menrath]

I haven't reviewed that, but just by reading the title and desc, does this also target #1914 ?

[Jiwoon-Kim]

@Menrath Personally, I think it’s better to handle post-type objects like Article and Note separately from media-type objects like Image, Video, and Audio.
Since the uploadMedia endpoint is already defined and object retrieval is supported,
I believe we could implement a local user uploadMedia endpoint on the frontend through extensions of the Media Library and Attachment Page features.

• https://www.w3.org/TR/activitypub/#uploading-media
• https://www.w3.org/wiki/SocialCG/ActivityPub/MediaUpload#uploadMedia
• https://www.w3.org/TR/activitypub/#retrieving-objects

However, I’m not entirely sure whether it’s truly necessary to parse the attachment property from a remote actor’s Note or Article and store it in the local media library.
For example, even if a WordPress hosting plan provides an unlimited database, it might only offer 1 GB of storage.
If the system automatically caches all external media from remote actors, the local site’s storage could quickly fill up with spam, effectively preventing any further media uploads.

That’s why I suggested that direct file links should be treated as hotlinks,
and that we should only record them in the database (as something like remote_attachment_page)
when the actor has an uploadMedia endpoint and the object is a genuine media object.

In any case, implementing remote media local caching now could still be useful later,
since it would provide reusable infrastructure when implementing selective local caching in the future.
So while I don’t oppose the current PR, I can’t say I fully agree with its direction.

---

I wanted to suggest that WordPress could independently implement a sharedMedia endpoint to enable the reuse of remote media objects.

[obenland]

does this also target #1914 ?

@Menrath Probably not this one specifically, but mayve a combination of #2311 and #2363

[obenland]

@pfefferle This should be ready for another look when you get a chance

[Jiwoon-Kim]

I discovered something quite shocking: you should never use an Image object directly inside the attachment property of a WordPress post.

[pfefferle]

Why do you use the word "shocking" in this regards! I can't see why this is shocking!

[pfefferle]

@Jiwoon-Kim can you please stop using clickbaity titles/wordings like that!

[Jiwoon-Kim]

I’m sorry about that. I had just finished reviewing all the related object types, properties, and endpoints, and the conclusion I reached was honestly quite shocking to me personally. I wrote the post before I had fully calmed down from that excitement.

[pfefferle]

If you think there is something wrong with the implementation, please file a bug! Explain the issue, be precise and link to the relevant code/documentation!

[pfefferle]

@obenland What about hooking the Attachment importer into do_action( "save_post_{$post->post_type}", $post_id, $post, $update ); instead of a direct calling in the create and update functions?

Not every user has enough storage or maybe uses a different form of caching, so it might be nice to be able to unhook the caching mechanism!?

[Jiwoon-Kim]

I will make my final statement regarding this PR.
An image file must always be wrapped within an Image object.
However, if the Image object does not contain an id, there is no way for WordPress to assign an attachment ID to it.
Therefore, if the Image object itself cannot be cached, the image file must not be cached either.

I believe the media upload mechanism should be perfectly symmetrical with the remote media object/file caching process.
To remain consistent with WordPress’s native media upload workflow, this approach should be enforced.

In particular, servers MUST append an id property to the object, and SHOULD include the uploaded and/or processed file paths in the object's url property.
https://www.w3.org/wiki/SocialCG/ActivityPub/MediaUpload#uploadMedia

[pfefferle]

@Jiwoon-Kim as I already tried to explain to you multiple times: this is not about "uploading" data! we are working on S2S communication, not on C2S!

this is a simple local caching of remote images that are part of a post (Note or Article), the exact same way, any other platform (including Mastodon) is doing it!