PHPXRef 0.7.1 : WordPress Trunk (Updated Daily) : Detail view of class-wp-rest-attachments-controller.php

Class: WP_REST_Attachments_Controller - X-Ref

Core controller used to access attachments via the REST API.

Registers the routes for attachments.

get_endpoint_args_for_item_schema( $method = WP_REST_Server::CREATABLE ) X-Ref

Retrieves the query params for the attachments collection.

param: string $method Optional. HTTP method of the request.
return: array<string, array<string, mixed>> Endpoint arguments.

prepare_items_query( $prepared_args = array() X-Ref

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

param: array $prepared_args Optional. Array of prepared arguments. Default empty array.
param: WP_REST_Request $request Optional. Request to prepare items for.
return: array Array of query arguments.

create_item_permissions_check( $request ) X-Ref

Checks if a given request has access to create an attachment.

param: WP_REST_Request $request Full details about the request.
return: true|WP_Error Boolean true if the attachment may be created, or a WP_Error if not.

create_item( $request ) X-Ref

Creates a single attachment.

param: WP_REST_Request $request Full details about the request.
return: WP_REST_Response|WP_Error Response object on success, WP_Error object on failure.

create_item_from_url( WP_REST_Request $request ) X-Ref

Sideloads an external image from a URL into the media library.

Downloads the remote file on the server, avoiding a cross-origin browser
fetch that fails under cross-origin isolation. Whether sub-sizes are
generated is governed by the filters applied in create_item().

param: WP_REST_Request $request Full details about the request.
return: WP_REST_Response|WP_Error Response object on success, WP_Error object on failure.

remove_client_side_media_processing_filters() X-Ref

Removes filters added for client-side media processing.

insert_attachment( $request ) X-Ref

Inserts the attachment post in the database. Does not update the attachment meta.

param: WP_REST_Request $request
return: array|WP_Error

handle_featured_media( $featured_media, $post_id ) X-Ref

Determines the featured media based on a request param.

param: int $featured_media Featured Media ID.
param: int $post_id Post ID.
return: bool|WP_Error Whether the post thumbnail was successfully deleted, otherwise WP_Error.

update_item( $request ) X-Ref

Updates a single attachment.

param: WP_REST_Request $request Full details about the request.
return: WP_REST_Response|WP_Error Response object on success, WP_Error object on failure.

post_process_item( $request ) X-Ref

Performs post-processing on an attachment.

param: WP_REST_Request $request Full details about the request.
return: WP_REST_Response|WP_Error Response object on success, WP_Error object on failure.

post_process_item_permissions_check( $request ) X-Ref

Checks if a given request can perform post-processing on an attachment.

param: WP_REST_Request $request Full details about the request.
return: true|WP_Error True if the request has access to update the item, WP_Error object otherwise.

edit_media_item_permissions_check( $request ) X-Ref

Checks if a given request has access to editing media.

param: WP_REST_Request $request Full details about the request.
return: true|WP_Error True if the request has read access, WP_Error object otherwise.

edit_media_item( $request ) X-Ref

Applies edits to a media item and creates a new attachment record.

param: WP_REST_Request $request Full details about the request.
return: WP_REST_Response|WP_Error Response object on success, WP_Error object on failure.

prepare_item_for_database( $request ) X-Ref

Prepares a single attachment for create or update.

param: WP_REST_Request $request Request object.
return: stdClass|WP_Error Post object.

prepare_item_for_response( $item, $request ) X-Ref

Prepares a single attachment output for response.

param: WP_Post $item Attachment object.
param: WP_REST_Request $request Request object.
return: WP_REST_Response Response object.

prepare_links( $post ) X-Ref

Prepares attachment links for the request.

param: WP_Post $post Post object.
return: array Links for the given attachment.

get_item_schema() X-Ref

Retrieves the attachment's schema, conforming to JSON Schema.

return: array Item schema as an array.

upload_from_data( $data, $headers, $time = null ) X-Ref

Handles an upload via raw POST data.

param: string      $data    Supplied file data.
param: array       $headers HTTP headers from the request.
param: string|null $time    Optional. Time formatted in 'yyyy/mm'. Default null.
return: array{ file: non-empty-string, url: non-empty-string, type: non-empty-string }|WP_Error Data from wp_handle_sideload().

get_filename_from_disposition( $disposition_header ) X-Ref

Parses filename from a Content-Disposition header value.

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 "*">

param: string[] $disposition_header List of Content-Disposition header values.
return: string|null Filename if available, or null if not found.

get_collection_params() X-Ref

Retrieves the query params for collections of attachments.

return: array Query parameters for the attachment collection as an array.

upload_from_file( $files, $headers, $time = null ) X-Ref

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

param: array       $files   Data from the `$_FILES` superglobal.
param: array       $headers HTTP headers from the request.
param: string|null $time    Optional. Time formatted in 'yyyy/mm'. Default null.
return: array{ file: non-empty-string, url: non-empty-string, type: non-empty-string }|WP_Error Data from wp_handle_upload().

get_media_types() X-Ref

Retrieves the supported media types.

Media types are considered the MIME type category.

return: array Array of supported media types.

check_upload_size( $file ) X-Ref

Determine if uploaded file exceeds space quota on multisite.

Replicates check_upload_size().

param: array $file $_FILES array for a given file.
return: true|WP_Error True if can upload, error for errors.

get_edit_media_item_args() X-Ref

Gets the request args for the edit item route.

return: array

get_attachment_filename( int $attachment_id ) X-Ref

Gets the attachment's original file name.

param: int $attachment_id Attachment ID.
return: string|null Attachment file name, or null if not found.

get_attachment_filesize( int $attachment_id ) X-Ref

Gets the attachment's file size in bytes.

param: int $attachment_id Attachment ID.
return: int|null Attachment file size in bytes, or null if not available.

sideload_item_permissions_check( $request ) X-Ref

Checks if a given request has access to sideload a file.

Sideloading a file for an existing attachment
requires both update and create permissions.

param: WP_REST_Request $request Full details about the request.
return: true|WP_Error True if the request has access to update the item, WP_Error object otherwise.

validate_image_size_names( $value, string $param ) X-Ref

Validates an image size name, or an array of names sharing a single file.

Shared by the sideload endpoint, which names the size a file is produced
for, and the finalize endpoint, which names the size each submitted entry
is stored under. Both need the same set, and finalize accepts a payload of
its own rather than one this class produced, so leaving it unconstrained
there would let a submission write an arbitrary key into the metadata
'sizes' array or route a file into a branch it was never produced for.

param: mixed $value The image size name, or an array of names.
param: string $param Parameter name, used in the error messages.
return: true|WP_Error True when every name is valid, WP_Error otherwise.

get_special_image_sizes() X-Ref

Returns the image size names which name a single file rather than a sub-size.

Each of these is handled on its own in {@see self::sideload_item()} and stored
under its own key by {@see self::finalize_item()}, so unlike a regular
sub-size none of them may appear in an array of names sharing one file.

return: string[] Special image size names.

validate_image_dimensions( int $width, int $height, string $image_size, int $attachment_id ) X-Ref

Validates that uploaded image dimensions are appropriate for the specified image size.

param: int    $width         Uploaded image width.
param: int    $height        Uploaded image height.
param: string $image_size    The target image size name.
param: int    $attachment_id The attachment ID.
return: true|WP_Error True if valid, WP_Error if invalid.

dimension_exceeds_max( int $value, int $max, int $tolerance ) X-Ref

Checks whether a dimension exceeds the maximum allowed value.

A maximum of zero means the dimension is unconstrained.

param: int $value The actual dimension in pixels.
param: int $max The maximum allowed dimension in pixels. Zero means no constraint.
param: int $tolerance Pixel tolerance allowed for rounding differences.
return: bool True if the value exceeds the maximum plus tolerance.

sideload_item( WP_REST_Request $request ) X-Ref

Side-loads a media file without creating a new attachment.

param: WP_REST_Request $request Full details about the request.
return: WP_REST_Response|WP_Error Response object on success, WP_Error object on failure.

filter_wp_unique_filename( $filename, $dir, $number, $attachment_filename ) X-Ref

Filters wp_unique_filename during sideloads.

wp_unique_filename() will always add numeric suffix if the name looks like a sub-size to avoid conflicts.
Adding this closure to the filter helps work around this safeguard.

Example: when uploading myphoto.jpeg, WordPress normally creates myphoto-150x150.jpeg,
and when uploading myphoto-150x150.jpeg, it will be renamed to myphoto-150x150-1.jpeg
However, here it is desired not to add the suffix in order to maintain the same
naming convention as if the file was uploaded regularly.

The suffix is only dropped when no file of that name already exists in $dir,
so this never returns a name that would overwrite one. The unsuffixed name
must also derive from the attachment's own file name, and
{@see self::sideload_item()} pins the upload to the attachment's own
directory, so any name returned here belongs to the attachment being
extended.

param: string      $filename            Unique file name.
param: string      $dir                 Directory path.
param: int|string  $number              The highest number that was used to make the file name unique
param: string|null $attachment_filename Original attachment file name.
return: string Filtered file name.

validate_sub_size_provenance( int $attachment_id, array $sub_sizes ) X-Ref

Validates the `sub_sizes` file names against what this attachment produced.

The {@see self::finalize_item()} method stores the client-supplied `file`
and `original_image` values in the attachment metadata, where they are
later resolved within the attachment's upload directory and read or deleted
(for example by {@see wp_get_original_image_path()}, {@see wp_getimagesize()},
and {@see wp_delete_attachment_files()}).

Every file the sideload endpoint creates is recorded under
{@see self::META_KEY_SIDELOAD_FILE_NAME} as it is produced, using
server-generated names. finalize accepts a `file` or `original_image`
value only when it matches one of those recorded names (or the
attachment's own attached file, which it definitionally owns).

param: int $attachment_id The attachment being finalized.
param: array $sub_sizes Sub-size metadata collected from sideloads.
return: true|WP_Error True if every file name was produced here, WP_Error otherwise.

get_sideloaded_file_names( int $attachment_id, bool $include_provenance = true ) X-Ref

Returns the file names which a finalize request may store for an attachment.

The set is the file names the sideload endpoint recorded as it produced
them (ref. {@see self::META_KEY_SIDELOAD_FILE_NAME}), plus the attachment's own
attached file - accepted in both its uploads-relative and basename form so
a scaled main-file pointer validates regardless of which the client
echoes - plus the names already stored in the attachment's own metadata.

param: int $attachment_id The attachment being finalized.
param: bool $include_provenance Whether to include the sideload provenance rows.
return: string[] File names that may appear in the finalize submission.

get_attachment_upload_subdir( string $attached_file ) X-Ref

Returns the uploads subdirectory an attachment is stored in.

Used to place a sideloaded file alongside the attachment it extends. The
result is concatenated into a filesystem path by the caller, so it is
returned only when the attachment resolves inside the uploads directory
and the stored path is well formed.

param: string $attached_file Absolute path to the attached file.
return: string|null Subdirectory beginning with a slash, an empty string when the

finalize_item( WP_REST_Request $request ) X-Ref

Finalizes an attachment after client-side media processing.

Applies the sub-size metadata collected from sideload responses in a
single metadata update, then triggers the 'wp_generate_attachment_metadata'
filter so that server-side plugins can process the attachment after all
client-side operations (upload, thumbnail generation, sideloads) are
complete.

param: WP_REST_Request $request Full details about the request.
return: WP_REST_Response|WP_Error Response object on success, WP_Error object on failure.

File Size:	3458 lines (118 kb)
Included or required:	0 times
Referenced:	0 times
Includes or requires:	4 files wp-admin/includes/file.php wp-admin/includes/ms.php wp-admin/includes/image.php wp-admin/includes/media.php

PHP Cross Reference of WordPress Trunk (Updated Daily)

/wp-includes/rest-api/endpoints/ -> class-wp-rest-attachments-controller.php (summary)

Defines 1 class