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.

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

prepare_items_query( $prepared_args = array() X-Ref

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

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

create_item_permissions_check( $request ) X-Ref

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

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

create_item( $request ) X-Ref

Creates a single attachment.

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

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().

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

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.

return: array|WP_Error
param: WP_REST_Request $request

handle_featured_media( $featured_media, $post_id ) X-Ref

Determines the featured media based on a request param.

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

update_item( $request ) X-Ref

Updates a single attachment.

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

post_process_item( $request ) X-Ref

Performs post-processing on an attachment.

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

post_process_item_permissions_check( $request ) X-Ref

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

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

edit_media_item_permissions_check( $request ) X-Ref

Checks if a given request has access to editing media.

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

edit_media_item( $request ) X-Ref

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

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

prepare_item_for_database( $request ) X-Ref

Prepares a single attachment for create or update.

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

prepare_item_for_response( $item, $request ) X-Ref

Prepares a single attachment output for response.

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

prepare_links( $post ) X-Ref

Prepares attachment links for the request.

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

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.

return: array{ file: non-empty-string, url: non-empty-string, type: non-empty-string }|WP_Error Data from wp_handle_sideload().
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.

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

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

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).

return: array{ file: non-empty-string, url: non-empty-string, type: non-empty-string }|WP_Error Data from wp_handle_upload().
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.

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().

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

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.

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

get_attachment_filesize( int $attachment_id ) X-Ref

Gets the attachment's file size in bytes.

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

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.

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

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.

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

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.

return: true|WP_Error True if valid, WP_Error if invalid.
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.

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.

return: bool True if the value exceeds the maximum plus tolerance.
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.

sideload_item( WP_REST_Request $request ) X-Ref

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

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

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.

return: string Filtered file name.
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.

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).

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

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.

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

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.

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

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.

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

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

PHP Cross Reference of WordPress Trunk (Updated Daily)

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

Defines 1 class