Changeset 63381

Timestamp:

08/28/2026 12:45:55 AM (7 weeks ago)

Author:

westonruter

Message:

Code Quality: Resolve the encapsedStringPart.nonString error.

The get_attachment_fields_to_edit() function documented every value of its returned array as a field definition array, but the attachment_fields_to_edit filter may also add a _final entry holding raw HTML, which get_media_item() interpolates into a string. Declare that structure in a @phpstan-return tag so the _final entry is typed as a string while the remaining keys stay typed as field definition arrays, and widen the plain @return to a union so the array shape remains a proper subtype of it.

The menu_order key is listed explicitly in the shape because get_media_item() unsets it. Unsetting a key that an unsealed array shape does not declare collapses the shape into a plain union of its value types, which would reintroduce the imprecision for every other field.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/13078.
Follow-up to r61594, r63020.

Props dpantazis.
See #65817.

Location:

trunk

Files:

• phpstan.neon.dist (modified) (1 diff)
• src/wp-admin/includes/media.php (modified) (1 diff)
• tests/phpstan/baselines/encapsedStringPart.nonString.neon (deleted)

trunk/phpstan.neon.dist

@@ -43 +43 @@
         - tests/phpstan/baselines/empty.property.neon
         - tests/phpstan/baselines/empty.variable.neon
-        - tests/phpstan/baselines/encapsedStringPart.nonString.neon
         - tests/phpstan/baselines/foreach.nonIterable.neon
         - tests/phpstan/baselines/function.alreadyNarrowedType.neon

trunk/src/wp-admin/includes/media.php

@@ -1399 +1399 @@
  * @param WP_Post $post
  * @param array   $errors
- * @return array<string, array<string, mixed>> The attachment fields.
+ * @return array<string, array<string, mixed>|string> The attachment fields, keyed by field name. Each value is a
+ *                                                    field definition array, except for the `_final` key, which the
+ *                                                    `attachment_fields_to_edit` filter may set to raw HTML that is
+ *                                                    rendered after all other fields.
+ *
+ * @phpstan-return array{
+ *     _final?: string,
+ *     menu_order?: array<string, mixed>, // Listed explicitly so that unsetting it in get_media_item() does not collapse this shape.
+ *     ...<string, array<string, mixed>>
+ * }
  */
 function get_attachment_fields_to_edit( $post, $errors = null ) {