Class: WP_REST_Attachments_Controller

Extends WP_REST_Posts_Controller

Core controller used to access attachments via the REST API.


Properties

Name Type(s) Default Value Summary
post_type string Inherited ⋅ Post type.
meta WP_REST_Post_Meta_Fields Inherited ⋅ Instance of a post meta fields object.
namespace string Inherited ⋅ The namespace of this controller's route.
rest_base string Inherited ⋅ The base of this controller's route.

Methods

WP_REST_Attachments_Controller:: __construct( string $post_type )

Constructor. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$post_type string

Post type.


WP_REST_Attachments_Controller:: add_additional_fields_schema( array $schema )

Adds the schema from additional fields to a schema array. Since 4.7.0.

The type of object is inferred from the passed schema.

Arguments

Name Type(s) Default Value Description
$schema array

Schema array.

Returns

array

Modified Schema array.


WP_REST_Attachments_Controller:: add_additional_fields_to_object( array $object, WP_REST_Request $request )

Adds the values from additional fields to a data object. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$object array

Data object.

$request WP_REST_Request

Full details about the request.

Returns

array

Modified data object with additional fields.


WP_REST_Attachments_Controller:: can_access_password_content( WP_Post $post, WP_REST_Request $request )

Checks if the user can access password-protected content. Since 4.7.0.

This method determines whether we need to override the regular password check in core with a filter.

Arguments

Name Type(s) Default Value Description
$post WP_Post

Post to check against.

$request WP_REST_Request

Request data to check.

Returns

boolean

True if the user can access password-protected content, otherwise false.


WP_REST_Attachments_Controller:: check_assign_terms_permission( WP_REST_Request $request )

Checks whether current user can assign all terms sent with the current request. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$request WP_REST_Request

The request object with post and terms data.

Returns

boolean

Whether the current user can assign the provided terms.


WP_REST_Attachments_Controller:: check_create_permission( object $post )

Checks if a post can be created. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$post object

Post object.

Returns

boolean

Whether the post can be created.


WP_REST_Attachments_Controller:: check_delete_permission( object $post )

Checks if a post can be deleted. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$post object

Post object.

Returns

boolean

Whether the post can be deleted.


WP_REST_Attachments_Controller:: check_is_post_type_allowed( object | string $post_type )

Checks if a given post type can be viewed or managed. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$post_type object | string

Post type name or object.

Returns

boolean

Whether the post type is allowed in REST.


WP_REST_Attachments_Controller:: check_read_permission( object $post )

Checks if a post can be read. Since 4.7.0.

Correctly handles posts with the inherit status.

Arguments

Name Type(s) Default Value Description
$post object

Post object.

Returns

boolean

Whether the post can be read.


WP_REST_Attachments_Controller:: check_template( string $template, WP_REST_Request $request )

Check whether the template is valid for the given post. Since 4.9.0.

Arguments

Name Type(s) Default Value Description
$template string

Page template filename.

$request WP_REST_Request

Request.

Returns

boolean | WP_Error

True if template is still valid or if the same as existing value, or false if template not supported.


WP_REST_Attachments_Controller:: check_update_permission( object $post )

Checks if a post can be edited. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$post object

Post object.

Returns

boolean

Whether the post can be edited.


WP_REST_Attachments_Controller:: check_upload_size( array $file )

Determine if uploaded file exceeds space quota on multisite. Since 4.9.8.

Replicates check_upload_size().

Arguments

Name Type(s) Default Value Description
$file array

$_FILES array for a given file.

Returns

true | WP_Error

True if can upload, error for errors.


WP_REST_Attachments_Controller:: create_item( WP_REST_Request $request )

Creates one item from the collection. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$request WP_REST_Request

Full data about the request.

Returns

WP_Error | WP_REST_Response

Response object on success, or WP_Error object on failure.


WP_REST_Attachments_Controller:: create_item_permissions_check( WP_REST_Request $request )

Checks if a given request has access to create items. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$request WP_REST_Request

Full data about the request.

Returns

WP_Error | boolean

True if the request has access to create items, WP_Error object otherwise.


WP_REST_Attachments_Controller:: delete_item( WP_REST_Request $request )

Deletes one item from the collection. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$request WP_REST_Request

Full data about the request.

Returns

WP_Error | WP_REST_Response

Response object on success, or WP_Error object on failure.


WP_REST_Attachments_Controller:: delete_item_permissions_check( WP_REST_Request $request )

Checks if a given request has access to delete a specific item. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$request WP_REST_Request

Full data about the request.

Returns

WP_Error | boolean

True if the request has access to delete the item, WP_Error object otherwise.


WP_REST_Attachments_Controller:: filter_response_by_context( array $data, string $context )

Filters a response based on the context defined in the schema. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$data array

Response data to fiter.

$context string

Context defined in the schema.

Returns

array

Filtered response.


WP_REST_Attachments_Controller:: get_additional_fields( string $object_type = null )

Retrieves all of the registered additional fields for a given object-type. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$object_type string

Optional. The object type.

Returns

array

Registered additional fields (if any), empty array if none or if the object type could not be inferred.


WP_REST_Attachments_Controller:: get_available_actions( WP_Post $post, $request )

Get the link relations available for the post and current user. Since 4.9.8.

Arguments

Name Type(s) Default Value Description
$post WP_Post

Post object.

$request

Returns

array

List of link relations.


WP_REST_Attachments_Controller:: get_collection_params( )

Retrieves the query params for the collections. Since 4.7.0.

Returns

array

Query parameters for the collection.


WP_REST_Attachments_Controller:: get_context_param( array $args = array() )

Retrieves the magical context param. Since 4.7.0.

Ensures consistent descriptions between endpoints, and populates enum from schema.

Arguments

Name Type(s) Default Value Description
$args array

Optional. Additional arguments for context parameter. Default empty array.

Returns

array

Context parameter details.


WP_REST_Attachments_Controller:: get_endpoint_args_for_item_schema( string $method = \WP_REST_Server::CREATABLE )

Retrieves an array of endpoint arguments from the item schema for the controller. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$method string

Optional. HTTP method of the request. The arguments for CREATABLE requests are checked for required values and may fall-back to a given default, this is not done on EDITABLE requests. Default WP_REST_Server::CREATABLE.

Returns

array

Endpoint arguments.


WP_REST_Attachments_Controller:: get_fields_for_response( WP_REST_Request $request )

Gets an array of fields to be included on the response. Since 4.9.6.

Included fields are based on item schema and _fields= request argument.

Arguments

Name Type(s) Default Value Description
$request WP_REST_Request

Full details about the request.

Returns

array

Fields to be included in the response.


WP_REST_Attachments_Controller:: get_filename_from_disposition( array<mixed,string> $disposition_header )

Parses filename from a Content-Disposition header value. Since 4.7.0.

As per RFC6266:

content-disposition = "Content-Disposition" ":"
                       disposition-type *( ";" disposition-parm )

disposition-type    = "inline" | "attachment" | disp-ext-type
                    ; case-insensitive
disp-ext-type       = token

disposition-parm    = filename-parm | disp-ext-parm

filename-parm       = "filename" "=" value
                    | "filename*" "=" ext-value

disp-ext-parm       = token "=" value
                    | ext-token "=" ext-value
ext-token           = <the characters in token, followed by "*">

Arguments

Name Type(s) Default Value Description
$disposition_header array<mixed,string>

List of Content-Disposition header values.

Returns

string | null

Filename if available, or null if not found.


WP_REST_Attachments_Controller:: get_item( WP_REST_Request $request )

Retrieves one item from the collection. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$request WP_REST_Request

Full data about the request.

Returns

WP_Error | WP_REST_Response

Response object on success, or WP_Error object on failure.


WP_REST_Attachments_Controller:: get_item_permissions_check( WP_REST_Request $request )

Checks if a given request has access to get a specific item. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$request WP_REST_Request

Full data about the request.

Returns

WP_Error | boolean

True if the request has read access for the item, WP_Error object otherwise.


WP_REST_Attachments_Controller:: get_item_schema( )

Retrieves the item's schema, conforming to JSON Schema. Since 4.7.0.

Returns

array

Item schema data.


WP_REST_Attachments_Controller:: get_items( WP_REST_Request $request )

Retrieves a collection of items. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$request WP_REST_Request

Full data about the request.

Returns

WP_Error | WP_REST_Response

Response object on success, or WP_Error object on failure.


WP_REST_Attachments_Controller:: get_items_permissions_check( WP_REST_Request $request )

Checks if a given request has access to get items. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$request WP_REST_Request

Full data about the request.

Returns

WP_Error | boolean

True if the request has read access, WP_Error object otherwise.


WP_REST_Attachments_Controller:: get_media_types( )

Retrieves the supported media types. Since 4.7.0.

Media types are considered the MIME type category.

Returns

array

Array of supported media types.


WP_REST_Attachments_Controller:: get_object_type( )

Retrieves the object type this controller is responsible for managing. Since 4.7.0.

Returns

string

Object type for the controller.


WP_REST_Attachments_Controller:: get_post( integer $id )

Get the post, if the ID is valid. Since 4.7.2.

Arguments

Name Type(s) Default Value Description
$id integer

Supplied ID.

Returns

WP_Post | WP_Error

Post object if ID is valid, WP_Error otherwise.


WP_REST_Attachments_Controller:: get_public_item_schema( )

Retrieves the item's schema for display / public consumption purposes. Since 4.7.0.

Returns

array

Public item schema data.


Retrieve Link Description Objects that should be added to the Schema for the posts collection. Since 4.9.8.

Returns

array


Determines the featured media based on a request param. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$featured_media integer

Featured Media ID.

$post_id integer

Post ID.

Returns

boolean | WP_Error

Whether the post thumbnail was successfully deleted, otherwise WP_Error.


WP_REST_Attachments_Controller:: handle_status_param( string $post_status, object $post_type )

Determines validity and normalizes the given status parameter. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$post_status string

Post status.

$post_type object

Post type.

Returns

string | WP_Error

Post status or WP_Error if lacking the proper permission.


WP_REST_Attachments_Controller:: handle_template( string $template, integer $post_id, boolean $validate = false )

Sets the template for a post. Since 4.7.0. Since 4.9.0.

Arguments

Name Type(s) Default Value Description
$template string

Page template filename.

$post_id integer

Post ID.

$validate boolean

Whether to validate that the template selected is valid.


WP_REST_Attachments_Controller:: handle_terms( integer $post_id, WP_REST_Request $request )

Updates the post's terms from a REST request. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$post_id integer

The post ID to update the terms form.

$request WP_REST_Request

The request object with post and terms data.

Returns

null | WP_Error

WP_Error on an error assigning any of the terms, otherwise null.


WP_REST_Attachments_Controller:: prepare_date_response( string $date_gmt, string | null $date = null )

Checks the post_date_gmt or modified_gmt and prepare any post or modified date for single post output. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$date_gmt string

GMT publication time.

$date string | null

Optional. Local publication time. Default null.

Returns

string | null

ISO8601/RFC3339 formatted datetime.


WP_REST_Attachments_Controller:: prepare_item_for_database( WP_REST_Request $request )

Prepares one item for create or update operation. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$request WP_REST_Request

Request object.

Returns

WP_Error | object

The prepared item, or WP_Error object on failure.


WP_REST_Attachments_Controller:: prepare_item_for_response( mixed $item, WP_REST_Request $request )

Prepares the item for the REST response. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$item mixed

WordPress representation of the item.

$request WP_REST_Request

Request object.

Returns

WP_Error | WP_REST_Response

Response object on success, or WP_Error object on failure.


WP_REST_Attachments_Controller:: prepare_items_query( array $prepared_args = array(), WP_REST_Request $request = null )

Determines the allowed query_vars for a get_items() response and prepares them for WP_Query. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$prepared_args array

Optional. Prepared WP_Query arguments. Default empty array.

$request WP_REST_Request

Optional. Full details about the request.

Returns

array

Items query arguments.


Prepares links for the request. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$post WP_Post

Post object.

Returns

array

Links for the given post.


WP_REST_Attachments_Controller:: prepare_response_for_collection( WP_REST_Response $response )

Prepares a response for insertion into a collection. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$response WP_REST_Response

Response object.

Returns

array | mixed

Response data, ready for insertion into collection data.


WP_REST_Attachments_Controller:: protected_title_format( )

Overwrites the default protected title format. Since 4.7.0.

By default, WordPress will show password protected posts with a title of "Protected: %s", as the REST API communicates the protected status of a post in a machine readable format, we remove the "Protected: " prefix.

Returns

string

Protected title format.


WP_REST_Attachments_Controller:: register_routes( )

Registers the routes for the objects of the controller. Since 4.7.0.


WP_REST_Attachments_Controller:: sanitize_post_statuses( string | array $statuses, WP_REST_Request $request, string $parameter )

Sanitizes and validates the list of post statuses, including whether the user can query private statuses. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$statuses string | array

One or more post statuses.

$request WP_REST_Request

Full details about the request.

$parameter string

Additional parameter to pass to validation.

Returns

array | WP_Error

A list of valid statuses, otherwise WP_Error object.


WP_REST_Attachments_Controller:: update_additional_fields_for_object( array $object, WP_REST_Request $request )

Updates the values of additional fields added to a data object. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$object array

Data Object.

$request WP_REST_Request

Full details about the request.

Returns

boolean | WP_Error

True on success, WP_Error object if a field cannot be updated.


WP_REST_Attachments_Controller:: update_item( WP_REST_Request $request )

Updates one item from the collection. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$request WP_REST_Request

Full data about the request.

Returns

WP_Error | WP_REST_Response

Response object on success, or WP_Error object on failure.


WP_REST_Attachments_Controller:: update_item_permissions_check( WP_REST_Request $request )

Checks if a given request has access to update a specific item. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$request WP_REST_Request

Full data about the request.

Returns

WP_Error | boolean

True if the request has access to update the item, WP_Error object otherwise.


WP_REST_Attachments_Controller:: upload_from_data( array $data, array $headers )

Handles an upload via raw POST data. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$data array

Supplied file data.

$headers array

HTTP headers from the request.

Returns

array | WP_Error

Data from wp_handle_sideload().


WP_REST_Attachments_Controller:: upload_from_file( array $files, array $headers )

Handles an upload via multipart/form-data ($_FILES). Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$files array

Data from the $_FILES superglobal.

$headers array

HTTP headers from the request.

Returns

array | WP_Error

Data from wp_handle_upload().


WP_REST_Attachments_Controller:: validate_user_can_query_private_statuses( mixed $value, WP_REST_Request $request, string $parameter )

Validates whether the user can query private statuses. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$value mixed

Status value.

$request WP_REST_Request

Request object.

$parameter string

Additional parameter to pass for validation.

Returns

WP_Error | boolean

True if the user may query, WP_Error if not.


WordPress Developer Newsletter

Stay on top of the latest WordPress API changes, developer tool updates, security alerts and more.