Hooks/Filters

Modify various pieces of Instant Images functionality using the provided hooks and filters.

In WordPress, hooks are a way for one piece of code to interact with or modify another piece of code at pre-defined locations. Instant Images provides a limited number of hooks that developers can use to modify or extend core plugin functionality.

Upload

instant_images_after_upload

The instant_images_after_upload action is triggered after a successful image upload to the media library. This hook allows for custom functions to be run against the uploaded image.

// functions.php
add_action( 'instant_images_after_upload', function( $args  ) {
  // Add custom field to store the image provider.
  add_post_meta( $args['attachment_id'], '_instant_images_attachment_provider', $args['provider'], true );
  
  // Add custom field to store the original image ID.
  add_post_meta( $args['attachment_id'], '_instant_images_attachment_id', $args['id'], true );
});

The code sample above adds custom meta that stores various provider data by attachment_id.

The args parameter returned in the hook contains an array of relevant image data for the uploaded image.

// $args
[
  'filename'       => // The filename,
  'id'             => // Orginal image ID,
  'title'          => // Image title,
  'alt'            => // Image alt,
  'caption'        => // Image caption,
  'attachment_id'  => // Attachment ID,
  'attachment_url' => // Attachment URL,
  'provider'       => // Image provider,
  'original_url'   => // URL to the orginal image,
]

instant_images_attribution

The instant_images_attribution hook is used to transform the image attribution that is added to a photo prior to upload. This hook uses a template tag system for transforming variables into readable data.

// {image_url}    = Image Permalink.
// {username}     = The authors username.
// {user_url}     = URL to the image author profile.
// {provider}     = The image provider.
// {provider_url} = URL to the image provider (unsplash, pexels etc).

add_filter( 'instant_images_attribution', function() {
	return __( 'This <a href="{image_url}">image</a> is by <a href="{user_url}">{username}</a> and available for free on <a href="{provider_url}">{provider}</a>', 'framework' );
} );

Content Safety

Some of our providers allow for toggling of a safe search parameter which attempts to verify that image content does not violate submission guidelines by containing nudity or violence.

By default, Instant Images has safe searching enabled on all providers however, this setting can be adjusted by using the following filters for each provider.

// Unsplash
add_filter( 'instant_images_unsplash_content_filter', function(){
  return 'high';
}); 

// Openverse
add_filter( 'instant_images_openverse_mature', '__return_true' );

// Pixabay
add_filter( 'instant_images_pixabay_safesearch', '__return_false' );

User Roles

instant_images_user_role

This filter allows for the modification of the user role permitted access to the Instant Images core plugin pages and functionality.

add_filter( 'instant_images_user_role', function(){
  return 'edit_theme_options'; // upload_files
} );

instant_images_settings_user_role

This filter allows for modification of the user role permitted access to the Instant Images settings page.

add_filter( 'instant_images_settings_user_role', function(){
  return 'edit_theme_options'; // manage_options
} );

API Query

instant_images_query_debug

Enabling query_debug will console.log the Instant Images query parameters to your developer tools for each API request lookup.

add_filter( 'instant_images_query_debug', '__return_true' );