wp_prepare_attachment_for_js( int|WP_Post $attachment ): array|void

Prepares an attachment post object for JS, where it is expected to be JSON-encoded and fit into an Attachment model.

Contents

Parameters

$attachment int|WP_Post Required
Attachment ID or object.

Top ↑

Return

array|void Array of attachment details, or void if the parameter does not correspond to an attachment.

  • alt string
    Alt text of the attachment.
  • author string
    ID of the attachment author, as a string.
  • authorName string
    Name of the attachment author.
  • caption string
    Caption for the attachment.
  • compat array
    Containing item and meta.
  • context string
    Context, whether it's used as the site icon for example.
  • date int
    Uploaded date, timestamp in milliseconds.
  • dateFormatted string
    Formatted date (e.g. June 29, 2018).
  • description string
    Description of the attachment.
  • editLink string
    URL to the edit page for the attachment.
  • filename string
    File name of the attachment.
  • filesizeHumanReadable string
    Filesize of the attachment in human readable format (e.g. 1 MB).
  • filesizeInBytes int
    Filesize of the attachment in bytes.
  • height int
    If the attachment is an image, represents the height of the image in pixels.
  • icon string
    Icon URL of the attachment (e.g. /wp-includes/images/media/archive.png).
  • id int
    ID of the attachment.
  • link string
    URL to the attachment.
  • menuOrder int
    Menu order of the attachment post.
  • meta array
    Meta data for the attachment.
  • mime string
    Mime type of the attachment (e.g. image/jpeg or application/zip).
  • modified int
    Last modified, timestamp in milliseconds.
  • name string
    Name, same as title of the attachment.
  • nonces array
    Nonces for update, delete and edit.
  • orientation string
    If the attachment is an image, represents the image orientation (landscape or portrait).
  • sizes array
    If the attachment is an image, contains an array of arrays for the images sizes: thumbnail, medium, large, and full.
  • status string
    Post status of the attachment (usually 'inherit').
  • subtype string
    Mime subtype of the attachment (usually the last part, e.g. jpeg or zip).
  • title string
    Title of the attachment (usually slugified file name without the extension).
  • type string
    Type of the attachment (usually first part of the mime type, e.g. image).
  • uploadedTo int
    Parent post to which the attachment was uploaded.
  • uploadedToLink string
    URL to the edit page of the parent post of the attachment.
  • uploadedToTitle string
    Post title of the parent of the attachment.
  • url string
    Direct URL to the attachment file (from wp-content).
  • width int
    If the attachment is an image, represents the width of the image in pixels.

Top ↑

Source

File: wp-includes/media.php. View all references 

function wp_prepare_attachment_for_js( $attachment ) {
	$attachment = get_post( $attachment );

	if ( ! $attachment ) {
		return;
	}

	if ( 'attachment' !== $attachment->post_type ) {
		return;
	}

	$meta = wp_get_attachment_metadata( $attachment->ID );
	if ( str_contains( $attachment->post_mime_type, '/' ) ) {
		list( $type, $subtype ) = explode( '/', $attachment->post_mime_type );
	} else {
		list( $type, $subtype ) = array( $attachment->post_mime_type, '' );
	}

	$attachment_url = wp_get_attachment_url( $attachment->ID );
	$base_url       = str_replace( wp_basename( $attachment_url ), '', $attachment_url );

	$response = array(
		'id'            => $attachment->ID,
		'title'         => $attachment->post_title,
		'filename'      => wp_basename( get_attached_file( $attachment->ID ) ),
		'url'           => $attachment_url,
		'link'          => get_attachment_link( $attachment->ID ),
		'alt'           => get_post_meta( $attachment->ID, '_wp_attachment_image_alt', true ),
		'author'        => $attachment->post_author,
		'description'   => $attachment->post_content,
		'caption'       => $attachment->post_excerpt,
		'name'          => $attachment->post_name,
		'status'        => $attachment->post_status,
		'uploadedTo'    => $attachment->post_parent,
		'date'          => strtotime( $attachment->post_date_gmt ) * 1000,
		'modified'      => strtotime( $attachment->post_modified_gmt ) * 1000,
		'menuOrder'     => $attachment->menu_order,
		'mime'          => $attachment->post_mime_type,
		'type'          => $type,
		'subtype'       => $subtype,
		'icon'          => wp_mime_type_icon( $attachment->ID ),
		'dateFormatted' => mysql2date( __( 'F j, Y' ), $attachment->post_date ),
		'nonces'        => array(
			'update' => false,
			'delete' => false,
			'edit'   => false,
		),
		'editLink'      => false,
		'meta'          => false,
	);

	$author = new WP_User( $attachment->post_author );

	if ( $author->exists() ) {
		$author_name            = $author->display_name ? $author->display_name : $author->nickname;
		$response['authorName'] = html_entity_decode( $author_name, ENT_QUOTES, get_bloginfo( 'charset' ) );
		$response['authorLink'] = get_edit_user_link( $author->ID );
	} else {
		$response['authorName'] = __( '(no author)' );
	}

	if ( $attachment->post_parent ) {
		$post_parent = get_post( $attachment->post_parent );
		if ( $post_parent ) {
			$response['uploadedToTitle'] = $post_parent->post_title ? $post_parent->post_title : __( '(no title)' );
			$response['uploadedToLink']  = get_edit_post_link( $attachment->post_parent, 'raw' );
		}
	}

	$attached_file = get_attached_file( $attachment->ID );

	if ( isset( $meta['filesize'] ) ) {
		$bytes = $meta['filesize'];
	} elseif ( file_exists( $attached_file ) ) {
		$bytes = wp_filesize( $attached_file );
	} else {
		$bytes = '';
	}

	if ( $bytes ) {
		$response['filesizeInBytes']       = $bytes;
		$response['filesizeHumanReadable'] = size_format( $bytes );
	}

	$context             = get_post_meta( $attachment->ID, '_wp_attachment_context', true );
	$response['context'] = ( $context ) ? $context : '';

	if ( current_user_can( 'edit_post', $attachment->ID ) ) {
		$response['nonces']['update'] = wp_create_nonce( 'update-post_' . $attachment->ID );
		$response['nonces']['edit']   = wp_create_nonce( 'image_editor-' . $attachment->ID );
		$response['editLink']         = get_edit_post_link( $attachment->ID, 'raw' );
	}

	if ( current_user_can( 'delete_post', $attachment->ID ) ) {
		$response['nonces']['delete'] = wp_create_nonce( 'delete-post_' . $attachment->ID );
	}

	if ( $meta && ( 'image' === $type || ! empty( $meta['sizes'] ) ) ) {
		$sizes = array();

		/** This filter is documented in wp-admin/includes/media.php */
		$possible_sizes = apply_filters(
			'image_size_names_choose',
			array(
				'thumbnail' => __( 'Thumbnail' ),
				'medium'    => __( 'Medium' ),
				'large'     => __( 'Large' ),
				'full'      => __( 'Full Size' ),
			)
		);
		unset( $possible_sizes['full'] );

		/*
		 * Loop through all potential sizes that may be chosen. Try to do this with some efficiency.
		 * First: run the image_downsize filter. If it returns something, we can use its data.
		 * If the filter does not return something, then image_downsize() is just an expensive way
		 * to check the image metadata, which we do second.
		 */
		foreach ( $possible_sizes as $size => $label ) {

			/** This filter is documented in wp-includes/media.php */
			$downsize = apply_filters( 'image_downsize', false, $attachment->ID, $size );

			if ( $downsize ) {
				if ( empty( $downsize[3] ) ) {
					continue;
				}

				$sizes[ $size ] = array(
					'height'      => $downsize[2],
					'width'       => $downsize[1],
					'url'         => $downsize[0],
					'orientation' => $downsize[2] > $downsize[1] ? 'portrait' : 'landscape',
				);
			} elseif ( isset( $meta['sizes'][ $size ] ) ) {
				// Nothing from the filter, so consult image metadata if we have it.
				$size_meta = $meta['sizes'][ $size ];

				/*
				 * We have the actual image size, but might need to further constrain it if content_width is narrower.
				 * Thumbnail, medium, and full sizes are also checked against the site's height/width options.
				 */
				list( $width, $height ) = image_constrain_size_for_editor( $size_meta['width'], $size_meta['height'], $size, 'edit' );

				$sizes[ $size ] = array(
					'height'      => $height,
					'width'       => $width,
					'url'         => $base_url . $size_meta['file'],
					'orientation' => $height > $width ? 'portrait' : 'landscape',
				);
			}
		}

		if ( 'image' === $type ) {
			if ( ! empty( $meta['original_image'] ) ) {
				$response['originalImageURL']  = wp_get_original_image_url( $attachment->ID );
				$response['originalImageName'] = wp_basename( wp_get_original_image_path( $attachment->ID ) );
			}

			$sizes['full'] = array( 'url' => $attachment_url );

			if ( isset( $meta['height'], $meta['width'] ) ) {
				$sizes['full']['height']      = $meta['height'];
				$sizes['full']['width']       = $meta['width'];
				$sizes['full']['orientation'] = $meta['height'] > $meta['width'] ? 'portrait' : 'landscape';
			}

			$response = array_merge( $response, $sizes['full'] );
		} elseif ( $meta['sizes']['full']['file'] ) {
			$sizes['full'] = array(
				'url'         => $base_url . $meta['sizes']['full']['file'],
				'height'      => $meta['sizes']['full']['height'],
				'width'       => $meta['sizes']['full']['width'],
				'orientation' => $meta['sizes']['full']['height'] > $meta['sizes']['full']['width'] ? 'portrait' : 'landscape',
			);
		}

		$response = array_merge( $response, array( 'sizes' => $sizes ) );
	}

	if ( $meta && 'video' === $type ) {
		if ( isset( $meta['width'] ) ) {
			$response['width'] = (int) $meta['width'];
		}
		if ( isset( $meta['height'] ) ) {
			$response['height'] = (int) $meta['height'];
		}
	}

	if ( $meta && ( 'audio' === $type || 'video' === $type ) ) {
		if ( isset( $meta['length_formatted'] ) ) {
			$response['fileLength']              = $meta['length_formatted'];
			$response['fileLengthHumanReadable'] = human_readable_duration( $meta['length_formatted'] );
		}

		$response['meta'] = array();
		foreach ( wp_get_attachment_id3_keys( $attachment, 'js' ) as $key => $label ) {
			$response['meta'][ $key ] = false;

			if ( ! empty( $meta[ $key ] ) ) {
				$response['meta'][ $key ] = $meta[ $key ];
			}
		}

		$id = get_post_thumbnail_id( $attachment->ID );
		if ( ! empty( $id ) ) {
			list( $src, $width, $height ) = wp_get_attachment_image_src( $id, 'full' );
			$response['image']            = compact( 'src', 'width', 'height' );
			list( $src, $width, $height ) = wp_get_attachment_image_src( $id, 'thumbnail' );
			$response['thumb']            = compact( 'src', 'width', 'height' );
		} else {
			$src               = wp_mime_type_icon( $attachment->ID );
			$width             = 48;
			$height            = 64;
			$response['image'] = compact( 'src', 'width', 'height' );
			$response['thumb'] = compact( 'src', 'width', 'height' );
		}
	}

	if ( function_exists( 'get_compat_media_markup' ) ) {
		$response['compat'] = get_compat_media_markup( $attachment->ID, array( 'in_modal' => true ) );
	}

	if ( function_exists( 'get_media_states' ) ) {
		$media_states = get_media_states( $attachment );
		if ( ! empty( $media_states ) ) {
			$response['mediaStates'] = implode( ', ', $media_states );
		}
	}

	/**
	 * Filters the attachment data prepared for JavaScript.
	 *
	 * @since 3.5.0
	 *
	 * @param array       $response   Array of prepared attachment data. See {@see wp_prepare_attachment_for_js()}.
	 * @param WP_Post     $attachment Attachment object.
	 * @param array|false $meta       Array of attachment meta data, or false if there is none.
	 */
	return apply_filters( 'wp_prepare_attachment_for_js', $response, $attachment, $meta );
}

View on Trac View on GitHub

Top ↑

Hooks

Top ↑

Top ↑

Uses

Uses
Uses Description
wp_filesize() wp-includes/functions.php

Wrapper for PHP filesize with filters and casting the result as an integer.
mysql2date() wp-includes/functions.php

Converts given MySQL date string into a different format.
wp_get_attachment_url() wp-includes/post.php

Retrieves the URL for an attachment.
wp_get_attachment_metadata() wp-includes/post.php

Retrieves attachment metadata for attachment ID.
wp_mime_type_icon() wp-includes/post.php

Retrieves the icon for a MIME type or attachment.
image_constrain_size_for_editor() wp-includes/media.php

Scales down the default size of an image.
wp_get_attachment_image_src() wp-includes/media.php

Retrieves an image to represent an attachment.
wp_get_attachment_id3_keys() wp-includes/media.php

Returns useful keys to use to lookup data from an attachment’s stored metadata.
get_post_thumbnail_id() wp-includes/post-thumbnail-template.php

Retrieves the post thumbnail ID.
get_attachment_link() wp-includes/link-template.php

Retrieves the permalink for an attachment.
get_edit_post_link() wp-includes/link-template.php

Retrieves the edit post link for post.
get_media_states() wp-admin/includes/template.php

Retrieves an array of media states from an attachment.
get_edit_user_link() wp-includes/link-template.php

Retrieves the edit user link.
size_format() wp-includes/functions.php

Converts a number of bytes to the largest unit the bytes will fit into.
WP_User::__construct() wp-includes/class-wp-user.php

Constructor.
get_compat_media_markup() wp-admin/includes/media.php
human_readable_duration() wp-includes/functions.php

Converts a duration to human readable format.
wp_get_original_image_path() wp-includes/post.php

Retrieves the path to an uploaded image file.
wp_get_original_image_url() wp-includes/post.php

Retrieves the URL to an original attachment image.
get_attached_file() wp-includes/post.php

Retrieves attached file path based on attachment ID.
get_bloginfo() wp-includes/general-template.php

Retrieves information about the current site.
wp_create_nonce() wp-includes/pluggable.php

Creates a cryptographic token tied to a specific action, user, user session, and window of time.
wp_basename() wp-includes/formatting.php

i18n-friendly version of basename().
apply_filters() wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.
__() wp-includes/l10n.php

Retrieves the translation of $text.
current_user_can() wp-includes/capabilities.php

Returns whether the current user has the specified capability.
get_post_meta() wp-includes/post.php

Retrieves a post meta field for the given post ID.
get_post() wp-includes/post.php

Retrieves post data given a post ID or post object.
Show 23 more uses Hide more uses

Top ↑

Used By

Used By
Used By Description
wp_ajax_media_create_image_subsizes() wp-admin/includes/ajax-actions.php

Handles creating missing image sub-sizes for just uploaded images via AJAX.
wp_ajax_crop_image() wp-admin/includes/ajax-actions.php

Handles cropping an image via AJAX.
WP_Customize_Media_Control::to_json() wp-includes/customize/class-wp-customize-media-control.php

Refresh the parameters passed to the JavaScript via JSON.
wp_ajax_upload_attachment() wp-admin/includes/ajax-actions.php

Handles uploading attachments via AJAX.
wp_ajax_get_attachment() wp-admin/includes/ajax-actions.php

Handles getting an attachment via AJAX.
wp_ajax_save_attachment_compat() wp-admin/includes/ajax-actions.php

Handles saving backward compatible attachment attributes via AJAX.
WP_Customize_Upload_Control::to_json() wp-includes/customize/class-wp-customize-upload-control.php

Refresh the parameters passed to the JavaScript via JSON.
Show 2 more used by Hide more used by

Top ↑

Changelog

Changelog
Version Description
3.5.0 Introduced.

Top ↑

User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 4You must log in to vote on the helpfulness of this note
    Contributed by slushman —

    Here are the fields returned by this function:

    • id
    • title
    • filename
    • url
    • link
    • alt
    • author
    • description
    • caption
    • name
    • status
    • uploadedTo
    • date
    • modified
    • menuOrder
    • mime
    • type
    • subtype
    • icon
    • dateFormatted
    • nonces – this is an array containing each nonce
    • editLink
    • sizes: this sub-array contains the following for each size:
      • height
      • width
      • url
      • orientation
    • width
    • height
    • fileLength
    • combat
    • Skip to note 2 content
      You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
      Contributed by Codex —

      Example

      Pass image data to a js gallery.

      <?php
function wpdocs_my_js_gallery_add_gallery_images() {
	$post = get_post();

	$gallery_images = array();

	$attachments = get_posts( array(
		'post_type'      => 'attachment',
		'post_status'    => 'inherit',
		'post_parent'    => $post->ID,
		'post_mime_type' => 'image',
	) );

	foreach( $attachments as $attachment )
		$gallery_images[] = wp_prepare_attachment_for_js( $attachment->ID );

	wp_localize_script( 'my-js-gallery', 'my_js_gallery', array(
		'images' => $gallery_images,
	) );
}
add_action( 'wp_head', 'wpdocs_my_js_gallery_add_gallery_images', 1 );

    You must log in before being able to contribute a note or feedback.