refactor: Move filter into wp_get_media_library_attachment_months()

Consolidate the media_library_months_with_files filter inside
the function so both call sites just use the getter. No
transient caching. Add test for filter override behavior.

Author: apermo

src/wp-admin/includes/media.php

@@ -2852,11 +2852,7 @@ function media_upload_library_form( $errors ) {
 
 	<div class="alignleft actions">
 		<?php
-		/** This filter is documented in wp-includes/media.php */
-		$months = apply_filters( 'media_library_months_with_files', null );
-		if ( ! is_array( $months ) ) {
-			$months = wp_get_media_library_attachment_months();
-		}
+		$months = wp_get_media_library_attachment_months();
 
 		$month_count    = count( $months );
 		$selected_month = isset( $_GET['m'] ) ? (int) $_GET['m'] : 0;

src/wp-includes/media.php

@@ -4866,25 +4866,7 @@ function wp_enqueue_media( $args = array() ) {
 		);
 	}
 
-	/**
-	 * Allows overriding the list of months displayed in the media library.
-	 *
-	 * By default (if this filter does not return an array), a query will be
-	 * run to determine the months that have media items.  This query can be
-	 * expensive for large media libraries, so it may be desirable for sites to
-	 * override this behavior.
-	 *
-	 * @since 4.7.4
-	 *
-	 * @link https://core.trac.wordpress.org/ticket/31071
-	 *
-	 * @param stdClass[]|null $months An array of objects with `month` and `year`
-	 *                                properties, or `null` for default behavior.
-	 */
-	$months = apply_filters( 'media_library_months_with_files', null );
-	if ( ! is_array( $months ) ) {
-		$months = wp_get_media_library_attachment_months();
-	}
+	$months = wp_get_media_library_attachment_months();
 
 	foreach ( $months as $month_year ) {
 		$month_year->text = sprintf(
@@ -5148,9 +5130,6 @@ function wp_enqueue_media( $args = array() ) {
 /**
  * Retrieves the months that have media library attachments.
  *
- * Results are cached in a transient and automatically invalidated when
- * attachments are created, updated, or deleted.
- *
  * Example:
  *
  *     $months = wp_get_media_library_attachment_months();
@@ -5168,6 +5147,26 @@ function wp_enqueue_media( $args = array() ) {
 function wp_get_media_library_attachment_months(): array {
 	global $wpdb;
 
+	/**
+	 * Allows overriding the list of months displayed in the media library.
+	 *
+	 * By default (if this filter does not return an array), a query will be
+	 * run to determine the months that have media items.  This query can be
+	 * expensive for large media libraries, so it may be desirable for sites to
+	 * override this behavior.
+	 *
+	 * @since 4.7.4
+	 *
+	 * @link https://core.trac.wordpress.org/ticket/31071
+	 *
+	 * @param array<int, object{year: string, month: string}>|null $months An array of objects with `month` and `year`
+	 *                                properties, or `null` for default behavior.
+	 */
+	$months = apply_filters( 'media_library_months_with_files', null );
+	if ( is_array( $months ) ) {
+		return $months;
+	}
+
 	return $wpdb->get_results(
 		$wpdb->prepare(
 			"SELECT DISTINCT YEAR( post_date ) AS year, MONTH( post_date ) AS month

tests/phpunit/tests/media/wpGetMediaLibraryAttachmentMonths.php

@@ -35,4 +35,36 @@ public function test_returns_months() {
 		$this->assertSame( '2024', $months[1]->year );
 		$this->assertSame( '11', $months[1]->month );
 	}
+
+	/**
+	 * Tests that the filter overrides the query result.
+	 *
+	 * @ticket 63279
+	 */
+	public function test_filter_overrides_result() {
+		self::factory()->post->create(
+			array(
+				'post_type' => 'attachment',
+				'post_date' => '2025-06-01 00:00:00',
+			)
+		);
+
+		$override = array(
+			(object) array(
+				'year'  => '2020',
+				'month' => '1',
+			),
+		);
+
+		add_filter(
+			'media_library_months_with_files',
+			static function () use ( $override ) {
+				return $override;
+			}
+		);
+
+		$months = wp_get_media_library_attachment_months();
+
+		$this->assertSame( $override, $months );
+	}
 }