Repository navigation
Image Search
Adds images to the site's front-end search results. Images match on their title, caption, description, alt text and image taxonomy terms. Turn it on with Images in search results on PhotoPress › Settings › Pages & Search. Block themes show results with PhotoPress's Image Search template.
- WordPress 6.6 or later.
- The Image Search template needs a block theme and WordPress 6.7 or later (
register_block_template()). Classic themes show images in their own search results template. - Optional: Relevanssi (free or Premium). With Relevanssi active, searches run against its index and PhotoPress keeps images in that index.
Images in search results, with Posts and pages too.
| Control | What it does | Default |
|---|---|---|
| Images in search results | Includes images in front-end search results, matched by title, caption, description, alt text and the names of their image taxonomy terms. | Off |
| Posts and pages too | With images in search results, searches also find posts, pages and other searchable post types. Off, a search finds images alone. | On |
| Re-index all images (Page cache and search index card) | Starts a background job that adds every image to Relevanssi's index. Shown while Relevanssi is active. Can be started only while Images in search results is on. | — |
The Relevanssi status and Re-index all images.
The Relevanssi row shows Active, Disabled or Not installed.
Search results with the Image Search template.
The template is registered while Images in search results is on. It contains, in order:
- The core Search block.
- Search Summary.
- A Taxonomy Gallery of the images found, in the Rows layout, with File name and title under each image and links to further pages of results.
- Search Posts.
To change it, edit Image Search in the Site Editor. A theme template named search-images replaces it.
Search Summary (photopress/search-summary). It renders only on search results.
The Search Summary block's settings.
| Control | What it does | Default |
|---|---|---|
| Show label | Shows the label above the search terms. | On |
| Label | The label's text. | Search results for: |
| Show number of images | Shows the number found, as "(143 images.)". On a search without images it shows the number of results. | On |
The search terms are shown as the page's h1.
Search Posts (photopress/search-posts). It renders only on an image search.
The Search Posts block's settings.
| Control | What it does | Default |
|---|---|---|
| Show heading | Shows a heading above the posts and pages, when there are some. | On |
| Heading | The heading's text. | Posts and pages |
| Number shown | How many posts and pages to list, 1–20. Each shows its title, linked, and an excerpt of up to 30 words. | 5 |
- When more posts and pages match than are shown, a link follows: "All N matching posts and pages". It opens the theme's own search results for those post types.
- When neither images nor posts were found, the block shows "Nothing was found for "…"".
- With Posts and pages too off, the block lists nothing. It still shows the "nothing found" note when no images matched.
- Only the front end's main search query is changed. Admin searches, other queries, and searches that name a post type (
?post_type=post) are left alone. - Only public images are found: unattached images, and images attached to a published post. Attachments that are not images are left out. For visitors who are not logged in, password-protected posts are left out.
-
Block theme:
- The main query is limited to images.
- The Image Search template is chosen ahead of the theme's
searchtemplate. - Search Posts runs its own query for posts and pages.
-
Classic theme:
- The theme's search template lists images in its results.
- With Posts and pages too on, they are listed alongside posts, pages and the other searchable post types.
PhotoPress extends WordPress's own search SQL (posts_search). Each word must match one of these:
- post title
- caption (excerpt)
- description (content)
- alt text
- the name of a term in a public image taxonomy
Words are combined with AND.
- At most 9 words are used. Each word is cut to 100 characters.
- A word starting with
-excludes matches, as in WordPress's search. The prefix followswp_query_search_exclusion_prefix.
PhotoPress adds no SQL. Relevanssi runs the search from its index.
| What PhotoPress gives Relevanssi | When |
|---|---|
Media (attachment) ticked among the post types it indexes |
Images in search results on |
| The public image taxonomies ticked among the taxonomies it indexes | Images in search results on |
| Index image files on | Images in search results on |
Alt text (_wp_attachment_image_alt) among an image's custom fields |
Always |
| Results with non-image attachments removed | On an image search |
Relevanssi's settings. PhotoPress saves the first three in Relevanssi's own settings, as ticking them on its Indexing tab would (syncRelevanssi()). They show there and can be changed there.
- Turning Images in search results on ticks each one that is not already ticked. PhotoPress records which ones it ticked.
- Turning it off unticks only those. Media, taxonomies and image files the site ticked itself stay.
- A taxonomy PhotoPress ticked that is removed or made admin only is unticked.
- PhotoPress checks again when the search settings are saved, and on admin pages when Images in search results or the public image taxonomies changed since the last check (Relevanssi activated later included). A change made on Relevanssi's settings page stands until one of those changes.
Keeping the index current:
- Relevanssi indexes images itself when they are added or saved.
- PhotoPress indexes an image again when only its terms change, as when it is reprocessed or a term is added or removed. This happens at the end of the request.
- When a term is renamed, given a new slug or deleted:
- With 25 images or fewer, its images are indexed again at the end of the request.
- With more than 25, the background job Refresh the images of renamed and deleted terms (
search.terms) indexes them. A second job requested while one runs waits for it to finish.
- A post whose stored content PhotoPress rewrote in place is indexed again, as when links to a replaced image's files change.
- Turning Images in search results on starts the job Add images to the search index (
search.index), unless one is queued or running. While images were off, Relevanssi indexed none. - Re-index all images starts the same job.
Both jobs are paced:
- Batches of up to 25 images run for up to 10 seconds each.
- Between batches the job rests as long as the batch took.
- The job waits while the server has less than 300 MB of memory available, or its one-minute load is above 70% of its processors.
| Hook | Type | Code | Purpose |
|---|---|---|---|
pre_get_posts |
action | ImageSearch.php#L58 | Sets post_type, post_status and the photopress_public_images and photopress_image_search query vars on the main search (searchImages()). |
posts_search |
filter | ImageSearch.php#L59 | Replaces the search SQL when Relevanssi is not active (searchSql()). |
search_template_hierarchy |
filter | ImageSearch.php#L60 | Puts search-images before search in a block theme (addTemplate()). |
wp_query_search_exclusion_prefix |
filter (applied) | ImageSearch.php#L222 | Reads the exclusion prefix as WordPress does. |
add_option_photopress_core_search, update_option_photopress_core_search
|
action | ImageSearch.php#L105 | With Relevanssi active, syncs Relevanssi's settings (priority 5), then starts search.index when images are turned on (maybeIndex()). |
admin_init |
action | ImageSearch.php#L109 | With Relevanssi active, syncs its settings when Images in search results or the public image taxonomies changed since the last sync. |
added_term_relationship, deleted_term_relationships
|
action | TermChanges.php#L55 | An image joined or left a term (imageTermsChanged()). |
edit_terms, edited_term
|
action | TermChanges.php#L57 | A term renamed or given a new slug (termEdited()). |
pre_delete_term, delete_term
|
action | TermChanges.php#L59 | A term deleted, with its images (termDeleted()). |
shutdown |
action | ImageSearch.php#L559 | Indexes the request's changed images and posts (indexChanged()). |
Blocks and template:
-
photopress/search-summaryandphotopress/search-postsare server-rendered withregister_block_type()(L63). Their render callbacks arerenderSummary()andrenderPosts(). - Block metadata: search-summary/block.json, search-posts/block.json.
- The template
photopress//search-imagesis templates/search-images.html, registered at L70. - Posts and pages are the post types with
exclude_from_searchfalse, minusattachment(postTypes()).
Data stored: the images_in_search and posts_in_search keys of the photopress_core_search option, photopress_search_relevanssi_added (what PhotoPress ticked in Relevanssi's settings), photopress_search_relevanssi_synced (what they were last synced for, autoloaded), and photopress_search_term_changes (terms and images waiting for a running search.terms job). Job records are kept by PhotoPress's job runner.
Relevanssi is the only class that names Relevanssi's functions, filters and options. It uses documented functions and filters. Relevanssi has no filter for the post types and taxonomies it indexes, or for image files, so PhotoPress saves those settings as Relevanssi's Indexing tab saves them.
| Hook / function | Type | Code | Purpose |
|---|---|---|---|
relevanssi_do_query() |
function | Relevanssi.php#L50 | Runs the Search Posts block's query. Its existence marks Relevanssi as active. |
relevanssi_index_doc(), relevanssi_get_custom_fields()
|
function | Relevanssi.php#L44 | Indexes one image or post again. |
relevanssi_index_post_types, relevanssi_index_taxonomies_list, relevanssi_index_image_files
|
option | Relevanssi.php#L60, L76 | Read with get_option() and saved with update_option(), each only when it changes, with Relevanssi's autoloading (indexing(), setIndexing()). |
relevanssi_index_custom_fields |
filter | Relevanssi.php#L101 | Adds _wp_attachment_image_alt for attachments (indexedFields()). |
relevanssi_hits_filter |
filter | Relevanssi.php#L112 | On an image search, drops attachments that are not images (onlyImages()). |
Without Relevanssi, or with it deactivated:
- The SQL search above is used.
- The
search.indexjob is not registered. - The settings card shows Relevanssi's state in place of Re-index all images.
- A
search.indexjob left running is stopped with the message that its kind of job is not available.
| Hook | Type | Arguments | When | Code |
|---|---|---|---|---|
photopress_image_terms_changed |
action |
int $id, array $context: archives (term archive addresses, before and after a rename), job (true from search.terms) |
An image joined or left a term of a public image taxonomy, or one of its terms was renamed or deleted (25 images or fewer, or from the job). | TermChanges.php#L101 |
photopress_term_images_changed |
action |
array $images: terms (term_taxonomy_ids) or images (IDs) |
A term with more than 25 images was renamed or deleted. | TermChanges.php#L177 |
photopress_term_images_job |
filter | bool $needed |
Return true to have search.terms fire photopress_image_terms_changed for each of those images. PhotoPress returns true while Relevanssi indexes images. |
TermChanges.php#L179 |
PhotoPress's term-change handling does nothing while neither action has a listener.
- Images are off in search results until you turn them on.
- The setting's description names titles, captions, alt text and terms. The search also matches an image's description.
- Only terms of public image taxonomies are matched. Private taxonomies and WordPress's categories and tags are not.
- The Image Search template is not registered on WordPress 6.6.
- Re-index all images cannot be started while Images in search results is off.
- PhotoPress changes Relevanssi's indexing settings only while Relevanssi is active. A change to Images in search results made while it is inactive is applied on the first admin page after it is activated.
- A taxonomy PhotoPress ticks after images were turned on, such as a new one, reaches images already in the index only when they are indexed again (Re-index all images, or Relevanssi's Build the index).