GoalPrevail Image Hub – User Guide

1. What this plugin does

GoalPrevail Image Hub puts eight stock image libraries inside the WordPress admin. You search, filter, adjust the metadata, and import, without leaving your dashboard.

Every provider request runs on your own server. Nothing is routed through a GoalPrevail proxy, no usage is tracked, and your API keys are encrypted before they are stored.

• Eight providers – Openverse, Wikimedia Commons, NASA, Pixabay, Pexels, Flickr, Magnific and GIPHY.
• Three work with no key – Openverse, Wikimedia Commons and NASA are usable the moment you activate.
• Media modal tab – an “Image Hub” tab inside the WordPress media modal, so it is present in the Image block, the Featured image panel, galleries and “Replace image”.
• Classic Editor button – a button next to “Add Media” that inserts into the post or sets the featured image.
• Media Library button – an “Import from Image Hub” button on the Media Library screen.
• Per-provider filters – orientation, color, sort order and image type, shown only where the provider supports them.
• Masonry results grid – preserves relevance order, with the next page prefetched so infinite scroll does not stall.
• Metadata before import – set filename, title, alt text, caption and description first, or import in one click.
• Bulk import – multi-select with live per-image progress.
• Signed imports – the import endpoint only accepts images a search on your own site returned.
• Encrypted API keys – stored with libsodium or OpenSSL and never sent to the browser.
• Import history – an “Imported images” view listing everything the plugin has brought in, with source links.

The plugin is administration only. It adds nothing to the front end of your site and makes no front-end requests.

2. Requirements and installation

2.1 Requirements

• WordPress 6.2 or newer
• PHP 7.4 or newer
• The upload_files capability to search and import (Author and above by default)
• The manage_options capability to change settings and API keys
• Either the Sodium or the OpenSSL PHP extension, if you intend to save API keys
• A modern browser with JavaScript enabled

Saving an API key requires libsodium or OpenSSL with AES-256-GCM support. On a host with neither, the plugin refuses to store the key rather than saving it unencrypted. The three keyless providers still work.

2.2 Installation

1. Upload the goalprevail-image-hub folder to /wp-content/plugins/, or use Plugins → Add New → Upload Plugin.
2. Activate GoalPrevail Image Hub.
3. Open GoalPrevail Plugins → Image Hub.
4. Search Openverse, Wikimedia Commons or NASA straight away. No key is needed.
5. Optionally open the Settings tab and add API keys for the other providers.

2.3 Default configuration

New installations begin with the following configuration:

• Default provider: Openverse
• 30 results per search page
• Safe search enabled
• Automatic alt text enabled
• Automatic attribution captions enabled
• Filename pattern: image title
• Resize on import: longest side 2048 pixels
• Download size limit: 30 MB
• Delete settings on uninstall: disabled
• No API keys stored

3. Where to configure the plugin

Everything lives under:

GoalPrevail Plugins → Image Hub

The direct administration URLs are:

admin.php?page=goalprevail-image-hub
admin.php?page=goalprevail-image-hub&tab=settings

The screen has two tabs:

• Search Images – the search application, provider tabs, filters and the import history view.
• Settings – general options and API keys. Visible only to users who can manage_options.

The page header shows a status pill reading how many of the registered providers are ready to use, for example “3 of 8 providers ready”.

The Plugins screen also carries two quick links for this plugin: Search Images and Settings.

4. Quick-start

4.1 Import your first image

1. Open GoalPrevail Plugins → Image Hub.
2. Leave Openverse selected. It needs no key.
3. Type a search term and press Enter.
4. Hover a result and click Import, or click the pencil to set the filename and metadata first.
5. Follow the Edit in Media Library link that replaces the button once the import finishes.

4.2 Add an API key

1. Open the Settings tab.
2. Find the provider under API keys and click Get a key to open its signup page.
3. Paste the key into the field.
4. Click Test to verify it before saving.
5. Click Save Settings.

The Test button checks a key without storing it. It runs a single-result search for the term “nature” against that provider.

4.3 Use it while writing a post

1. Edit any post or page.
2. Add an Image block and click Media Library, or open the Featured image panel.
3. Choose the Image Hub tab in the modal that opens.
4. Search and click Use on a result.
5. Press the modal’s own button (Select, Set featured image or Insert into post) to finish.

5. Providers and API keys

5.1 Provider overview

5.2 Where to get a key

Each row on the Settings tab links to the correct page through its Get a key link.

5.3 How keys are stored

• Keys are encrypted before being written to the database.
• The encryption key is derived from your site’s AUTH_SALT and is never itself stored.
• libsodium is used when available, otherwise OpenSSL AES-256-GCM.
• A stored key is never printed back into the settings form. The field shows only a masked hint of the last four characters.
• Keys are never included in any data passed to the browser.
• All provider requests are made server-side, so keys never leave your server.

Rotating your WordPress salts makes existing stored keys unreadable. This is not data loss in any meaningful sense, but you will need to re-enter each key afterwards.

5.4 Removing a key

Once a key is stored, a Remove the saved key toggle appears beneath that provider’s field. Switch it on and save to delete the key.

Leaving the field blank keeps the existing key. Only typing a new value replaces it.

6. Searching

6.1 Provider tabs

Each provider has its own tab. A provider that still needs an API key is shown with a lock and, when selected, offers an Add API key link instead of results.

A separate Imported images tab sits at the end of the row.

6.2 Filters

Filters are per provider, and only the ones a provider genuinely supports are shown. The filter panel is hidden until you click the filter button, which carries a badge showing how many filters are active.

A filter value the provider did not declare is discarded server-side rather than forwarded.

6.3 Results behavior

• Results are laid out as a masonry grid that preserves relevance order, so the best match stays at the top left.
• Card heights are estimated from the dimensions the API reports, so the grid appears immediately and images stream in.
• The next page is prefetched in the background, so scrolling does not wait on a request.
• Your last ten searches are suggested as you type. They are stored in your own browser only.
• Each card shows a licence badge, a source link, and the author credit on hover.

6.4 Safe search

The Safe search setting is enabled by default and is applied to every provider that supports it. Providers with no such control are unaffected.

6.5 Search caching and rate limits

Identical searches are served from a short server-side cache for 12 minutes. This keeps the interface responsive and reduces load on provider APIs, several of which throttle anonymous traffic aggressively.

Per-user rate limits apply to each endpoint:

7. Importing

7.1 One-click import

Hover a result and click Import. The image is downloaded server-side, validated, added to the Media Library, and the button is replaced with an Edit in Media Library link.

7.2 Import with metadata

Click the pencil icon on a card to open a dialog with five fields:

• Filename
• Title
• Alt text
• Caption
• Description

Any field left blank falls back to the automatic value described in section 9.

7.3 Bulk import

Tick the checkbox on several cards. A bar appears showing the selection count and an Import selected button. Imports run two at a time with per-card progress.

7.4 What happens during an import

1. The signed payload is verified, so only an image a search on your site returned can be imported.
2. Providers that require it (Magnific, NASA) resolve the real file through a second API call.
3. The download URL is checked for HTTPS and, where the provider declares known hosts, for a matching hostname.
4. The file is streamed to a temporary file with the size cap enforced.
5. The real content type is inspected. The file extension alone is never trusted.
6. The file is added to the Media Library through the standard WordPress sideload routine.
7. It is downscaled if it exceeds the configured maximum dimension. Animated GIFs are never resized.
8. Alt text, caption, description and provenance metadata are written.

7.5 Allowed file types

An import may only produce one of these types, verified from the file contents:

7.6 Import history

The Imported images tab lists every attachment the plugin has ever created, newest first, with its provider, licence, source link and an edit link. The list is built by querying attachments that carry the plugin’s own provenance metadata.

8. Using Image Hub while editing

8.1 The media modal tab

The plugin adds an Image Hub tab to the WordPress media modal, alongside “Upload Files” and “Media Library”. Because every image picker in WordPress opens the same modal, one tab covers all of these:

• The Image block’s Media Library button
• The Featured image panel
• Add Media in the Classic Editor
• Gallery creation
• Replace image

The tab does not insert anything itself. It imports the image into the Media Library and places the new attachment into the modal’s selection, which enables the modal’s own button. From that point the image behaves exactly like one you uploaded, including the size and alignment controls in the attachment sidebar.

The tab stays open after an import instead of jumping to the library grid, so your search results survive while you pick more than one image. In a gallery, imports accumulate in the selection. Everywhere else, the newest import replaces the previous one.

8.2 The Classic Editor button

In the Classic Editor a GoalPrevail Image Hub button sits next to Add Media. It opens a full-screen modal where each card offers:

• Insert – import and insert the image into the post at the cursor.
• Set Featured – import and set it as the featured image.
• Edit & insert – set the metadata first.

Images imported this way are also attached to the post being edited.

8.3 The Media Library button

On the Media Library screen an Import from Image Hub button appears next to Add New Media File. It opens the same modal, and imports go straight to the library.

9. Settings reference

9.1 General

9.2 Metadata

The generated caption takes the form Image by {author} on {provider} ({licence}), or Image from {provider} ({licence}) when no author is supplied.

A credit that a provider’s API terms make mandatory, currently GIPHY, is written whatever this setting says, and is appended to a caption you typed rather than replacing it. See section 10.

9.3 Import

9.4 Uninstall

10. Licensing and attribution

10.1 Your responsibility

Every provider has its own licence terms, and they differ substantially. The plugin surfaces the licence where you make the decision rather than burying it in documentation:

• Each result card shows a licence badge and a link to the source page.
• The licence is stored with the imported attachment as metadata.
• The import history view shows the licence for every image the plugin brought in.

You remain responsible for honouring the licence of anything you publish, particularly for commercial use. Check the licence badge before you publish.

10.2 Provider notices

Two providers carry obligations that the plugin enforces on screen rather than leaving to you.

10.3 GIPHY

The GIPHY API terms require an attribution mark on any screen displaying GIPHY content, and attribution on the content itself. The plugin does both:

• A Powered by GIPHY mark is displayed above every GIPHY result set, in the admin screen and inside the media modal.
• Every imported GIF is captioned GIF by {artist} via GIPHY, or via GIPHY when GIPHY supplies no artist.
• That credit is written whether or not automatic attribution captions are enabled, and is appended to a caption you typed rather than replacing it.

GIPHY content stays subject to the GIPHY Terms of Service after import. Keep the credit on any GIF you publish.

10.4 Magnific

Magnific, formerly Freepik, is licensed content rather than free content. Its results carry an on-screen notice stating that downloads require an active Magnific API plan and that the Magnific licence, including attribution on the free tier, applies to anything you publish.

10.5 Flickr

Flickr searches are restricted server-side to openly licensed photos: Creative Commons, public domain, US Government works and no-known-restrictions. All-rights-reserved photos are never returned, so every Flickr result is safe to import.

11. Security

11.1 Signed imports

The single largest risk in a plugin of this kind is an import endpoint that will fetch any URL it is handed. This plugin closes that off.

Every search result is signed with an HMAC derived from your site’s authentication salt. The import endpoint verifies that signature before doing anything else, so it will only accept an image that a search on your own site actually returned. Signatures expire after six hours.

On top of that:

• Download URLs must use HTTPS.
• Where a provider declares known download hosts, the URL hostname must match one of them.
• All outbound requests use the WordPress safe HTTP functions, which block requests to internal and private addresses.
• The downloaded file’s real content type is inspected before it is accepted.

11.2 Capabilities

Attaching an import to a post additionally requires edit_post on that specific post, checked before the importer is allowed to act on it.

11.3 Request protection

• Every REST route carries a capability check and the standard WordPress REST nonce.
• Rate limits apply per user to search, import and key-test requests.
• The settings form uses a nonce and capability check, and every field is sanitized and constrained to a recognized value or range.
• All provider content is treated as untrusted. URLs are sanitized before they reach the browser and no interface text is inserted as HTML.
• No custom database tables are created and no remote code is executed.

12. Privacy and external services

12.1 What leaves your server

When you search, change provider or filters, or load more results, your server sends the search text, the filters and the pagination to the selected provider. The application may prefetch the next page for that search. A key test sends the query “nature” along with the key being tested. An import sends the image identifier or download URL.

These requests include your server’s IP address, the plugin version and your site URL in the user agent, plus an API key where one is required.

12.2 What your browser loads

Image previews load directly in your browser from provider CDNs, or from the original image hosts that Openverse returns. Those hosts receive your browser’s IP address and normal HTTP request information.

12.3 Services used

12.4 The WordPress.org request

When the shared GoalPrevail Plugins dashboard is opened, the plugin queries the official WordPress.org plugin API to list other plugins published by GoalPrevail.

• The request happens only in the administration area, and only when that screen is viewed.
• It includes the public author query and the requested catalog fields.
• WordPress includes the WordPress version and site home URL in its standard user agent.
• A successful response is cached for 24 hours. An empty or failed response is cached for two hours.
• The dashboard may load returned plugin icons from the WordPress.org asset CDN.

12.5 What the plugin does not do

• There is no GoalPrevail telemetry, proxy or account requirement.
• No usage data is collected or transmitted.
• Nothing is requested on the front end of your site.
• API keys are never sent to the browser or to any third party other than the provider they belong to.

13. Performance and caching

• Assets load only on the Image Hub screen and on screens where the media modal can open.
• Identical searches are served from a server-side cache for 12 minutes.
• The next results page is prefetched, so scrolling rarely waits on the network.
• Results are also cached in the browser for the current session, bounded so memory does not grow without limit.
• Downloads are streamed to a temporary file with a hard size cap, so a large image cannot exhaust memory.
• Rate limit counters and the search cache are stored as WordPress transients, so a persistent object cache is used when one is available.
• Nothing runs on the front end, so page-caching plugins and CDNs are unaffected.

To change the search cache lifetime, use the gpih_search_cache_ttl filter documented in section 14.

14. Developer information

14.1 PHP filters

14.2 PHP actions

14.3 Restrict Image Hub to editors

add_filter( 'gpih_capability', function ( $cap, $context ) {
    if ( 'settings' !== $context ) {
        return 'edit_others_posts';
    }

    return $cap;
}, 10, 2 );

14.4 Disable the search cache

add_filter( 'gpih_search_cache_ttl', '__return_zero' );

14.5 Customize the attribution caption

add_filter( 'gpih_attribution', function ( $line, $item ) {
    if ( ! empty( $item['page_url'] ) ) {
        return $line . ' | ' . $item['page_url'];
    }

    return $line;
}, 10, 2 );

14.6 Act on every import

add_action( 'gpih_imported', function ( $attachment_id, $item ) {
    update_post_meta( $attachment_id, '_my_source', $item['provider'] );
}, 10, 2 );

14.7 REST endpoints

All routes live under the gpih/v1 namespace, require an authenticated user with the appropriate capability, and require the standard WordPress REST nonce.

14.8 Front-end assets and JavaScript objects

14.9 Attachment metadata

14.10 Stored data

No custom database tables, scheduled cron jobs or cookies are created.

14.11 Adding a provider

Providers extend GPIH_Provider, normalize their API into the shared result schema and declare which filters they support. Register the class through gpih_providers:

add_filter( 'gpih_providers', function ( $map ) {
    $map['myprovider'] = 'My_GPIH_Provider';

    return $map;
} );

A provider may also implement get_notice() to display a required attribution mark or licence warning above its results, and attribution() to dictate the caption written into imports from that provider.

14.12 Shortcodes

The plugin provides no shortcode. It is an administration tool and adds nothing to the front end.

15. Troubleshooting

• A provider tab shows a lock: That provider needs an API key. Add one on the Settings tab.
• The key will not save: Your host may lack both Sodium and OpenSSL with AES-256-GCM. The plugin refuses to store a key it cannot encrypt. Ask your host to enable one of them.
• A saved key stopped working: Rotating your WordPress salts makes stored keys unreadable. Re-enter the key.
• The key test fails: Confirm you copied the whole key, and that the provider account is active. Magnific requires an active paid plan.
• “This provider needs an API key”: The key is missing or was cleared. Check the Settings tab for a masked hint next to that provider.
• “Openverse is limiting anonymous requests right now”: The keyless providers throttle anonymous traffic. Wait a moment and try again.
• “Search limit reached”: You reached the per-minute rate limit. Wait a minute, or raise the budget with the gpih_rate_limits filter.
• “This image payload is invalid or expired”: Import signatures last six hours. Search again and retry.
• “The file exceeds the import limit”: Raise the download size limit on the Settings tab, or choose a smaller image.
• “The downloaded file is not an allowed image type”: The file did not pass content inspection. Only JPEG, PNG, GIF, WebP and AVIF are accepted.
• Results are stale: Identical searches are cached for 12 minutes. Change the search term or wait for the cache to expire.
• Only 20 results from Openverse: Openverse caps keyless requests at 20 per page regardless of your Results per page setting.
• No Image Hub tab in the media modal: Confirm your user can upload files. The tab is not added for users without upload_files.
• The imported image is not selected: Wait for the toast confirming the import, then use the modal’s own button. In a gallery, imports accumulate rather than replacing.
• No button in the block editor: The GoalPrevail Image Hub button is a Classic Editor feature. In the block editor, use the Image Hub tab in the media modal instead.
• An animated GIF stopped moving: It should not. GIFs are exempt from resizing. If a GIF is static, check whether it was animated at the source.
• Imported images are too large: Lower the resize-on-import value. Set it to 0 to keep originals at full size.
• A caption appeared that I did not write: Automatic attribution captions are on by default. GIPHY credits are written regardless, because GIPHY requires them.
• The Settings tab is missing: It is visible only to users who can manage_options.
• Nothing renders on the search screen: The application requires JavaScript. Check your browser console for errors from other plugins.

16. Uninstalling the plugin

1. If you want your settings and keys removed, enable Delete settings and API keys on uninstall and save before deleting the plugin.
2. Deactivate the plugin.
3. Delete it from the WordPress Plugins page.

When the option is enabled, uninstalling removes the gpih_settings and gpih_api_keys options along with every plugin transient. When it is disabled, nothing is removed, so reinstalling restores your configuration.

On WordPress Multisite, cleanup runs for every site in the network, and each site’s own setting decides whether its data is removed.

Images you imported are ordinary Media Library attachments and are never deleted, whatever this setting says. Deactivating or deleting the plugin does not affect any image already in your library, or any post using one.

17. Support

For questions, support or feature requests, contact [email protected] or visit goalprevail.com.