wp_playlist_shortcode( array $attr ): string

Description

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$attrarray

Array of default playlist attributes.

• $typestringdefault: 'audio'

  Type of playlist to display. Accepts 'audio' or 'video'.

• $orderstringdefault: 'ASC'

  Designates ascending or descending order of items in the playlist. Accepts 'ASC', 'DESC'.

• $orderbystring

  Any column, or columns, to sort the playlist. If $ids are passed, this defaults to the order of the $ids array ('post__in'). Otherwise default is 'menu_order ID'.

• $idintdefault: is the current post ID

  If an explicit $ids array is not present, this parameter will determine which attachments are used for the playlist.

• $idsarraydefault: empty

  Create a playlist out of these explicit attachment IDs. If empty, a playlist will be created from all $type attachments of $id.

• $excludearraydefault: empty

  List of specific attachment IDs to exclude from the playlist.

• $stylestringdefault: 'light'

  Playlist style to use. Accepts 'light' or 'dark'.

• $tracklistbooldefault: true

  Whether to show or hide the playlist.

• $tracknumbersbooldefault: true

  Whether to show or hide the numbers next to entries in the playlist.

• $imagesbooldefault: true

  Show or hide the video or audio thumbnail (Featured Image/post thumbnail).

• $artistsbooldefault: true

  Whether to show or hide artist name in the playlist.

Return value

string

Playlist output. Empty string if the passed type is unsupported.

Performance profile

How much work a call to wp_playlist_shortcode() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Heavy

Reaches the database via get_post().

Scaling

Scales with input

The body loops, so the work grows with what you pass in.

Instructions

68–201

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 407.

Plugin surface

2 hooks

Third-party callbacks on 'post_playlist', 'wp_playlist_scripts' run inside this call, and their cost is not bounded by anything here.

Called by

0

Nothing in core calls this; the cost is only what you spend yourself.

What it touches

• querycontent queryget_post()called directly
• hookthird-party callbacksapply_filters()called directly
• cacheobject cachewp_cache_get()one call below wp_playlist_shortcode()

Further down the call graph this can also reach option, serialize and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 13 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost wp_playlist_shortcode() can have, taken from its control-flow graph on PHP 8.5.

This body has more branch combinations than are worth enumerating, so the table covers the outcomes found first rather than every one that exists.

Hooks and filters fired · 2

2 hooks fire while wp_playlist_shortcode() runs, in this order:

1. 1
   apply_filters( post_playlist )filterline 3222 (+30 into the body)

   Filters the playlist output.

2. 2
   do_action( wp_playlist_scripts )actionline 3404 (+212 into the body)

   Prints and enqueues playlist scripts, styles, and JavaScript templates.

Uses · 21

• get_post()Retrieves post data given a post ID or post object.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• shortcode_atts()Combines user attributes with known attributes and fill in defaults when needed.
• get_posts()Retrieves an array of the latest posts, or posts matching the given criteria.
• get_children()Retrieves all children of the post parent ID.
• current_user_can()Returns whether the current user has the specified capability.
• post_password_required()Determines whether the post requires password and whether a correct password has been provided.
• is_feed()Determines whether the query is for a feed.
• wp_get_attachment_link()Retrieves an attachment page link using an image or icon, if possible.
• wp_validate_boolean()Filters/validates a variable as a boolean.
• wp_get_attachment_url()Retrieves the URL for an attachment.
• wp_check_filetype()Retrieves the file type from the file name.

Source code

View on Trac ↗View on GitHub ↗

3192function wp_playlist_shortcode( $attr ) {3193	global $content_width;3194	$post = get_post();3195 3196	static $instance = 0;3197	++$instance;3198 3199	static $is_loaded = false;3200 3201	if ( ! empty( $attr['ids'] ) ) {3202		// 'ids' is explicitly ordered, unless you specify otherwise.3203		if ( empty( $attr['orderby'] ) ) {3204			$attr['orderby'] = 'post__in';3205		}3206		$attr['include'] = $attr['ids'];3207	}3208 3209	/**3210	 * Filters the playlist output.3211	 *3212	 * Returning a non-empty value from the filter will short-circuit generation3213	 * of the default playlist output, returning the passed value instead.3214	 *3215	 * @since 3.9.03216	 * @since 4.2.0 The `$instance` parameter was added.3217	 *3218	 * @param string $output   Playlist output. Default empty.3219	 * @param array  $attr     An array of shortcode attributes.3220	 * @param int    $instance Unique numeric ID of this playlist shortcode instance.3221	 */3222	$output = apply_filters( 'post_playlist', '', $attr, $instance );3223 3224	if ( ! empty( $output ) ) {3225		return $output;3226	}3227 3228	$atts = shortcode_atts(3229		array(3230			'type'         => 'audio',3231			'order'        => 'ASC',3232			'orderby'      => 'menu_order ID',3233			'id'           => $post ? $post->ID : 0,3234			'include'      => '',3235			'exclude'      => '',3236			'style'        => 'light',3237			'tracklist'    => true,3238			'tracknumbers' => true,3239			'images'       => true,3240			'artists'      => true,3241		),3242		$attr,3243		'playlist'3244	);3245 3246	$id = (int) $atts['id'];3247 3248	if ( 'audio' !== $atts['type'] ) {3249		$atts['type'] = 'video';3250	}3251 3252	$args = array(3253		'post_status'    => 'inherit',3254		'post_type'      => 'attachment',3255		'post_mime_type' => $atts['type'],3256		'order'          => $atts['order'],3257		'orderby'        => $atts['orderby'],3258	);3259 3260	if ( ! empty( $atts['include'] ) ) {3261		$args['include'] = $atts['include'];3262		$_attachments    = get_posts( $args );3263 3264		$attachments = array();3265		foreach ( $_attachments as $key => $val ) {3266			$attachments[ $val->ID ] = $_attachments[ $key ];3267		}3268	} elseif ( ! empty( $atts['exclude'] ) ) {3269		$args['post_parent'] = $id;3270		$args['exclude']     = $atts['exclude'];3271		$attachments         = get_children( $args );

Changelog

Introduced in 3.9.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 7.1.0 tag, from src/wp-includes/media.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.