Media

upload_mimes controls what get_allowed_mime_types() and the uploader accept — adding a type here does not make it safe by itself; WordPress still runs its own file-content checks.

Signature

Example

add_filter( 'upload_mimes', function( $mimes ) {
    $mimes['svg'] = 'image/svg+xml';
    return $mimes;
} );

Common Use Cases

• Allow SVG or other blocked file types
• Restrict uploads to a smaller set of types by role
• Add support for a niche file format

wp_get_attachment_image_attributes touches every image WordPress renders through its own media functions — including inside blocks and thumbnails — so scope changes carefully.

Signature

Example

add_filter( 'wp_get_attachment_image_attributes', function( $attr ) {
    $attr['loading'] = 'lazy';
    $attr['decoding'] = 'async';
    return $attr;
} );

Common Use Cases

• Add loading="lazy" or fetchpriority attributes
• Override alt text site-wide
• Add custom data-* attributes for a lightbox script

add_attachment fires the moment WordPress writes a new attachment post to the database — before any image sizes or EXIF metadata have been generated. Use it to react to a new upload existing, not to read its generated data.

Signature

Example

add_action( 'add_attachment', function( $post_ID ) {
    error_log( 'New attachment: ' . $post_ID );
} );

Common Use Cases

• Log or audit new uploads
• Auto-tag or auto-categorize uploaded media
• Trigger an external sync (CDN, DAM) when a file is added
• Set default attachment meta values on creation

wp_generate_attachment_metadata is where WordPress hands you the finished sizes/EXIF metadata array for a fresh upload — the standard place to add your own custom fields to that structure.

Signature

Example

add_filter( 'wp_generate_attachment_metadata', function( $metadata, $attachment_id ) {
    $metadata['custom_processed'] = true;
    return $metadata;
}, 10, 2 );

Common Use Cases

• Add custom fields to attachment metadata
• Precompute derived values (aspect ratio, dominant color) at upload time
• Sync image metadata to an external DAM or CDN
• Filter which generated sizes actually get kept

big_image_size_threshold controls whether an oversized upload gets scaled down to a 'large' version before WordPress builds the rest of its size set — directly affects storage use and upload processing time.

Signature

Example

add_filter( 'big_image_size_threshold', function( $threshold ) {
    return 1920;
} );

Common Use Cases

• Reduce storage use from oversized uploads
• Speed up media processing on large images
• Tune the threshold per site's actual display needs
• Disable auto-scaling for sites that need full-resolution originals

delete_attachment is your last chance to read an attachment's post meta or file path before wp_delete_attachment() removes the database row and the files on disk.

Signature

Example

add_action( 'delete_attachment', function( $post_id ) {
    error_log( 'Deleting attachment: ' . $post_id );
} );

Common Use Cases

• Purge CDN or cache entries tied to the file
• Clean up related custom meta or database rows
• Log deletions for an audit trail
• Block deletion of protected files (via a related filter, not this action)

edit_attachment fires specifically when the classic Media > Edit Media screen saves its fields (title, caption, alt text, description) — it's the admin-side counterpart to save_post for attachments.

Signature

Example

add_action( 'edit_attachment', function( $post_ID ) {
    error_log( 'Attachment updated: ' . $post_ID );
} );

Common Use Cases

• Validate or enforce alt text on save
• Sync updated media metadata to an external system
• Log editorial changes to media fields
• Re-trigger custom taxonomy assignment after a manual edit

wp_handle_upload fires right after a file physically lands in the uploads directory, before any attachment post exists for it — earlier in the pipeline than add_attachment.

Signature

Example

add_filter( 'wp_handle_upload', function( $upload ) {
    error_log( 'File uploaded to: ' . $upload['file'] );
    return $upload;
} );

Common Use Cases

• Push newly uploaded files to a CDN or external storage
• Log or audit raw uploads before a post record exists
• Rewrite the returned file path/URL for a custom storage backend
• Run virus/malware scanning on the raw uploaded file