Filter Hook since 2.1.0

wp_generate_attachment_metadata

Filters the generated attachment metadata array

Description

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.

When it runs

Runs inside wp_generate_attachment_metadata(), after WordPress has generated intermediate image sizes and read EXIF data, before the array is saved as post meta.

Signature

apply_filters( 'wp_generate_attachment_metadata', array $metadata, int $attachment_id, string $context );

Parameters

metadata array — The generated attachment metadata (sizes, width, height, EXIF).
attachment_id int — The attachment post ID the metadata belongs to.
context string — Either 'create' (new upload) or 'update' (metadata regeneration).

Examples

Basic

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

Add a custom flag to the metadata array.

Real case

add_filter( 'wp_generate_attachment_metadata', function( $metadata, $attachment_id ) {
    if ( isset( $metadata['width'], $metadata['height'] ) ) {
        $metadata['aspect_ratio'] = round( $metadata['width'] / $metadata['height'], 2 );
    }
    return $metadata;
}, 10, 2 );

Precompute and store an aspect ratio for later use in templates.

Edge case

add_filter( 'wp_generate_attachment_metadata', function( $metadata, $attachment_id, $context ) {
    if ( 'update' === $context ) {
        return $metadata; // skip on manual 'Regenerate Thumbnails' runs
    }
    return $metadata;
}, 10, 3 );

Distinguish a first-time upload from a later thumbnail-regeneration pass using $context.

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

Common mistakes

Forgetting to return $metadata — an unreturned or null value wipes out the entire generated sizes array
Not checking $context, which can cause expensive logic to re-run on every manual thumbnail regeneration, not just new uploads

Related hooks

Fires after add_attachment
Fires before big_image_size_threshold

FAQ

What happens if I forget to return the metadata array?

The attachment loses its generated sizes and dimension data — always return $metadata, even unmodified.

Does this run on every page load for existing images?

No — only when metadata is generated or explicitly regenerated (new upload, or a 'Regenerate Thumbnails' action), not on normal display.

Source: wp-admin/includes/image.php

Group wizard

One session: this hook, then each related_hooks entry. Walk it and tell us what to change.

wp_generate_attachment_metadata → add_attachment → big_image_size_threshold

functions.php — wp_generate_attachment_metadata

functions.php

<?php
/**
 * Practice: hook into wp_generate_attachment_metadata
 */
add_filter( 'wp_generate_attachment_metadata', function( $metadata, $attachment_id, $context ) {
	// Write your callback here. Always return the value.

	return $metadata;
} );

Group tour

wp_generate_attachment_metadata · Hook 1 of 3 · Step 1 of 6

Meet wp_generate_attachment_metadata

Filters the generated attachment metadata array

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.

type filterphase mediasince 2.1.0source wp-admin/includes/image.php

apply_filters( 'wp_generate_attachment_metadata', array $metadata, int $attachment_id, string $context );

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

PHP wp_generate_attachment_metadata · Hook 1 of 3 · Step 1 of 6

Practice the wp_generate_attachment_metadata WordPress filter hook in our interactive sandbox — a VS Code-style editor with a step-by-step wp_generate_attachment_metadata tutorial, add_filter exercises, and instant feedback. No local WordPress install required.