Skip to content

Hooks/Docs: wp_audio_shortcode and wp_video_shortcode — @param string $audio/$video but WP_Post|null is passed #24

Open

Description

@apermo

Problem

Both wp_audio_shortcode and wp_video_shortcode filters document their third parameter ($audio / $video) as @param string ("Audio/Video file"), but the actual variable passed can be a WP_Post object or null.

Root cause

In both shortcode functions, the variable is initialized as null and optionally set to the result of reset() on an attached-media query (which returns a WP_Post object when media exists):

$audio = null;
// ...
if ( ! $primary ) {
    $audios = get_attached_media( 'audio', $post_id );
    $audio  = reset( $audios ); // returns WP_Post|false
    // ...
}
// Later:
return apply_filters( 'wp_audio_shortcode', $html, $atts, $audio, ... );

So $audio / $video can be WP_Post|false|null at the point of the filter call, not string.

The description "Audio file." / "Video file." appears to document the intended semantic (the source URL), but the variable itself holds the post object (used earlier for $audio->ID), not a URL string.

wp_audio_shortcode

https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-includes/media.php#L3557-L3568

/**
 * @param string $audio   Audio file.
 * ...
 */
return apply_filters( 'wp_audio_shortcode', $html, $atts, $audio, $post_id, $library );

wp_video_shortcode

https://github.com/apermo/wordpress-develop/blob/trunk/src/wp-includes/media.php#L3852-L3863

/**
 * @param string $video   Video file.
 * ...
 */
return apply_filters( 'wp_video_shortcode', $output, $atts, $video, $post_id, $library );

Fix

Update both @param tags to reflect the actual type:

- * @param string $audio   Audio file.
+ * @param WP_Post|false|null $audio The audio attachment post object, or false/null if not set.
- * @param string $video   Video file.
+ * @param WP_Post|false|null $video The video attachment post object, or false/null if not set.

Note: this is a breaking change for plugin authors relying on the documented type. It may warrant a @since X.X.0 note about the type correction.

Activity

  1. apermo commented on Mar 8, 2026

    @apermo
    OwnerAuthor

    Verification

    Traced both functions line by line to confirm the possible values of $audio / $video:

    wp_audio_shortcode() (media.php:3384–3569)

    • Line 3418: $audio = null;
    • Line 3436: $primary = false;
    • Lines 3437–3455: $primary set to true if src attr or any typed attr has a valid extension. $audio is not touched.
    • Line 3458–3473: If $primary is still false:
      • Line 3459: $audios = get_attached_media( 'audio', $post_id );
      • Line 3461–3462: If empty → return; (function exits, filter never fires)
      • Line 3465: $audio = reset( $audios ); → WP_Post
      • Line 3468–3469: If wp_get_attachment_url() is empty → return; (function exits)
    • Line 3568: apply_filters( 'wp_audio_shortcode', $html, $atts, $audio, ... )

    At the filter call, $audio is always either null (primary path) or WP_Post (fallback path). Never false — the empty() check at line 3461 exits before reset() could return false on an empty array.

    wp_video_shortcode() (media.php:3619–3864)

    Identical flow:

    • Line 3647: $video = null;
    • Line 3717–3730: Same fallback pattern with get_attached_media( 'video', ... )
    • Line 3723: $video = reset( $videos ); → WP_Post
    • Line 3863: apply_filters( 'wp_video_shortcode', $output, $atts, $video, ... )

    Same conclusion: $video is null or WP_Post, never false.

    Corrected fix

    The type should be WP_Post|null (not WP_Post|false|null as originally proposed):

    - * @param string $audio   Audio file.
    + * @param WP_Post|null $audio   Audio attachment post object, or null if a source was provided directly.
    - * @param string $video   Video file.
    + * @param WP_Post|null $video   Video attachment post object, or null if a source was provided directly.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    verifiedIssue is manually verified.

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions