Attachments REST API: Add support for filtering attachments by multiple media types #10054

ramonjd · 2025-09-26T07:02:05Z

This patch carries on from #9211

This patch enhances the REST API media endpoint to allow filtering by multiple values for the media_type and mime_type parameters. This enables more flexible queries, such as requesting images and videos in a single API call.

The implementation supports both comma-separated strings and arrays for input, while maintaining full backward compatibility. Unit tests are included to cover the new functionality and edge cases.

Additionally, this patch add further tests to check that requests containing both media_type and mime_type values return as expected.

Trac ticket: https://core.trac.wordpress.org/ticket/63668

Props to @himanshupathak95

Testing

npm run test:php -- --filter WP_Test_REST_Attachments_Controller

In the block editor, some example core data calls to the REST API:

await wp.data.resolveSelect( 'core' ).getEntityRecords( 'postType', 'attachment', { media_type: ['audio'], mime_type: 'video/mp4' } );
await wp.data.resolveSelect( 'core' ).getEntityRecords( 'postType', 'attachment', { media_type: ['video', 'audio'] } );
await wp.data.resolveSelect( 'core' ).getEntityRecords( 'postType', 'attachment', { mime_type: 'video/mp4,audio/mpeg'  } );

github-actions · 2025-09-26T07:19:52Z

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

The Plugin and Theme Directories cannot be accessed within Playground.
All changes will be lost when closing a tab with a Playground instance.
All changes will be lost when refreshing the page.
A fresh instance is created each time the link below is clicked.
Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

github-actions · 2025-09-29T00:53:19Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props ramonopoly, andrewserong, mukesh27, adamsilverstein, timothyblynjacobs, swissspidy.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

andrewserong

This is testing well for me and generally looks like a good idea, especially for a DataViews-powered media library that would need this in order to be able to show multiple media types at the same time.

I left a comment, but I'm wondering if we could consolidate the behaviour to the existing media_type arg, but set it to allow either a string or an array, rather than adding the extra arg?

src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php

swissspidy · 2025-09-29T07:25:16Z

I left a comment, but I'm wondering if we could consolidate the behaviour to the existing media_type arg, but set it to allow either a string or an array, rather than adding the extra arg?

Strongly suggest the same. No need for a new param.

tests/phpunit/tests/rest-api/rest-attachments-controller.php

andrewserong

This is testing great for me, I also tested manually within a JS context by running the following from the console and the responses all looked correct:

wp.data.select( 'core' ).getEntityRecords( 'postType', 'attachment', { media_type: 'image' } );
wp.data.select( 'core' ).getEntityRecords( 'postType', 'attachment', { media_type: ['image', 'audio'] } );

LGTM, but I also understand if you'd like to get an approving review from folks more experienced with the REST API!

ramonjd · 2025-09-30T06:16:15Z

I completely missed https://core.trac.wordpress.org/ticket/63668 and #9211

Looks like #9211 handles mime_type as well.

I'll ping over there to see if work can carry on in that PR. If, for any reason, it cannot, I'll bring the changes over here and assign props to @himanshupathak95

adamsilverstein · 2025-10-02T16:12:49Z

src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php

-			'type'        => 'string',
-			'enum'        => array_keys( $media_types ),
+			'description' => __( 'Limit result set to attachments of a particular media type or media types.' ),
+			'oneOf'       => array(


Array may already accept strings so oneOf and string type may not be needed? Not sure about this, please check or maybe @TimothyBJacobs can confirm.

Thanks @adamsilverstein 🙇🏻

I think #9211 might be the one to follow since it was up first and takes care of mime_types too.

I'll update #9211 as required if the author can't.

I forgot to close this one, sorry!

Actually, I can't push to that branch so I'll move it over here.

Array may already accept strings so oneOf and string type may not be needed?

The type has changed to 'type' => array( 'string', 'array' ), for simplification. Is that okay?

Array may already accept strings so oneOf and string type may not be needed?

The type has changed to 'type' => array( 'string', 'array' ), for simplification. Is that okay?

right, and it may be possible to simplify further as type => 'array' because I believe array will also accept a string and convert it to a single element array. Not certain about this (its from memory), the unit tests should be able to confirm if I am right.

Ah yeah, that works great. It looks like rest_sanitize_array calls wp_parse_list, which always processes comma-separated strings into arrays during sanitization.

So this will coerce the value to an array. I'll update.

Thanks for nudging me in that direction.

Yep exactly, just type of array is sufficient.

Thanks for confirming @TimothyBJacobs - I know you pointed this out to me recently on another ticket, but appreciate the confirmation and taking the time to review here.

I appreciate the help on this one, folks! 🙇🏻

ramonjd · 2025-10-03T03:38:31Z

I've based this PR on @himanshupathak95's work over in #9211

I think it's ready for another look - the base functionality hasn't changed, except for the additional feature of being able to filter by multiple mime types AND multiple media types or a combination of both.

src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php

andrewserong · 2025-10-03T06:34:46Z

This is still testing well for me 👍
Just left a question about whether or not we should be including all the mime types in an enum or go with a simple string type in the collection params, but other than that it's looking good to me!

andrewserong · 2025-10-07T04:44:33Z

This is still looking good to me after the latest changes 👍

ramonjd · 2025-10-07T05:31:30Z

Thanks @andrewserong! I'll let it settle a day or two then merge in it.

…types. This update introduces a new `media_types` parameter to the WP REST Attachments Controller, allowing users to filter attachment queries by an array of media types. Additionally, the existing `media_type` parameter remains functional, ensuring backward compatibility. `post_mime_type` already supports multiple mime types.

…ket reference 64046.

…types in the WP REST Attachments Controller. Updated related tests to verify functionality and ensure backward compatibility.

@himanshupathak95

…ents Controller to support array values for filtering. Updated tests to validate functionality and ensure compatibility with existing features. Pulling over work from WordPress#9211 Props to @himanshupathak95

…troller to enforce array input. Updated tests to validate new behavior and ensure proper error responses for invalid parameters.

…on from schema definition. Updated related tests and fixtures to reflect this change.

ramonjd · 2025-10-09T05:23:02Z

Committed in r60917

ramonjd requested review from aaronjorbin, adamsilverstein, andrewserong, talldan and tellthemachines September 29, 2025 00:49

ramonjd self-assigned this Sep 29, 2025

ramonjd added the enhancement label Sep 29, 2025

ramonjd marked this pull request as ready for review September 29, 2025 00:53

andrewserong reviewed Sep 29, 2025

View reviewed changes

src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php Outdated Show resolved Hide resolved

mukeshpanchal27 reviewed Sep 29, 2025

View reviewed changes

tests/phpunit/tests/rest-api/rest-attachments-controller.php Show resolved Hide resolved

andrewserong approved these changes Sep 30, 2025

View reviewed changes

adamsilverstein requested a review from TimothyBJacobs October 2, 2025 16:00

adamsilverstein reviewed Oct 2, 2025

View reviewed changes

ramonjd mentioned this pull request Oct 3, 2025

REST API: Support multiple media types and MIME types when listing media #9211

Closed

ramonjd force-pushed the update/attachments-allow-filtering-by-multiple-media-types branch from 18e0b5b to ea0c42c Compare October 3, 2025 03:31

swissspidy requested review from rmccue and spacedmonkey October 3, 2025 06:28

andrewserong reviewed Oct 3, 2025

View reviewed changes

src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php Outdated Show resolved Hide resolved

ramonjd added 4 commits October 9, 2025 12:28

Added since 6.9.0 annotation to prepare_items_query

1d812e0

Update API generated fixture

154ba92

Use right version 6.9.0

1c0c5e3

ramonjd added 8 commits October 9, 2025 12:34

Tests: Update docblocks for media type filtering tests to include tic…

8ac8bf3

…ket reference 64046.

Extend media_type parameter to support filtering by multiple media …

9cda1c8

…types in the WP REST Attachments Controller. Updated related tests to verify functionality and ensure backward compatibility.

Regenerate fixtures

39d7680

Extend media_type and mime_type parameters in the WP REST Attachm…

545f841

…ents Controller to support array values for filtering. Updated tests to validate functionality and ensure compatibility with existing features. Pulling over work from WordPress#9211 Props to @himanshupathak95

regenerate fixture

686891f

Refactor media type and mime type handling in WP REST Attachments Con…

7ad084c

…troller to enforce array input. Updated tests to validate new behavior and ensure proper error responses for invalid parameters.

regen fixtures

3f81a01

Refactor WP REST Attachments Controller to remove MIME type enumerati…

c43d2dc

…on from schema definition. Updated related tests and fixtures to reflect this change.

ramonjd force-pushed the update/attachments-allow-filtering-by-multiple-media-types branch from 5ee634b to c43d2dc Compare October 9, 2025 01:38

ramonjd closed this Oct 9, 2025

ramonjd mentioned this pull request Nov 6, 2025

Fix adding blocks through media tab with experimental modal. WordPress/gutenberg#73029

Merged

github-actions bot mentioned this pull request Nov 9, 2025

PHP backports for WP 6.9 WordPress/gutenberg#72379

Closed

ramonjd mentioned this pull request Nov 27, 2025

Attachments Controller: Allow strings as media_type WordPress/gutenberg#73626

Closed

Attachments REST API: Add support for filtering attachments by multiple media types #10054

Attachments REST API: Add support for filtering attachments by multiple media types #10054

Uh oh!

Conversation

ramonjd commented Sep 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Testing

Uh oh!

github-actions bot commented Sep 26, 2025

Test using WordPress Playground

Some things to be aware of

Uh oh!

github-actions bot commented Sep 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

andrewserong left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

swissspidy commented Sep 29, 2025

Uh oh!

Uh oh!

andrewserong left a comment

Choose a reason for hiding this comment

Uh oh!

ramonjd commented Sep 30, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ramonjd commented Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

andrewserong commented Oct 3, 2025

Uh oh!

andrewserong commented Oct 7, 2025

Uh oh!

ramonjd commented Oct 7, 2025

Uh oh!

ramonjd commented Oct 9, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

ramonjd commented Sep 26, 2025 •

edited

Loading

github-actions bot commented Sep 29, 2025 •

edited

Loading

ramonjd commented Oct 3, 2025 •

edited

Loading