SearchWP

Migration Guide

This migration guide is designed to help with the transition from SearchWP 3.x (and earlier) to SearchWP 4.

Note: your license key is the same for both SearchWP 3.x and SearchWP 4

Note: SearchWP 4 is a major release that breaks backwards compatibility

(except for SWP_Query, which has not been changed)

Because this is a major version release that has broken backwards compatibility it is strongly recommended that a migration is first performed on a staging server to ensure the process goes smoothly before the migration is performed on a production server.

Note: SearchWP 3 Engines, settings, Stopwords, and Synonyms will be migrated upon activating SearchWP 4.

The migration process can be broken down into the following steps you will need to take:

  1. Reviewing this migration guide in full.
  2. Ensuring that all installed Extensions have been updated to their latest versions.
  3. Auditing all hooks in use both in your theme and any custom plugins.
    • Updating all existing hooks to SearchWP 4 equivalents, reaching out to support if any problems arise.

      Note: Please review the documentation for all hooks as some parameters have changed!

  4. Downloading SearchWP 4 from your Account.
  5. Deactivating and deleting* (see note blow!) SearchWP 3.x from your WordPress installation.
  6. Installing and activating SearchWP 4.
  7. Automatic migration of settings from SearchWP 3.x to SearchWP 4 upon activation.

    Note: Attribute relevance weights now have three segments, and the weight slider will display the nearest weight segment. This may look different to you if you have customized weights, but the actual weights from v3 will be retained until they are changed and Engines re-saved.

  8. Building the initial SearchWP 4 index.
  9. Testing functionality.

* If you have ticked the checkbox to remove all SearchWP data on uninstall your data will be deleted. Uncheck the checkbox if necessary.

If the checkbox is not ticked and you are not using the searchwp_nuke_on_delete hook to enable the feature all of your SearchWP data will remain in tact and usable should you decide to reinstall SearchWP 3.x at any time.

Hooks

One of the breaking changes from SearchWP 3.x to SearchWP 4 is all hooks have been re-tagged. Some hooks have been renamed but otherwise function the same. Other hooks have been completely removed.

Please review all of your hooks as you update the tags by reviewing the documentation for each. Some may be a simple tag change, others a simple parameter change, but some superfluous hooks in v3 have been removed in favor of a new, better suited hook entirely. Please test each of your hooks individually. ?

There is a hooks reference table available below.

Changes from SearchWP 3

SearchWP’s index and indexer have been completely rebuilt, including the background process. That said, there is feature parity between both versions. They operate in similar ways overall, but there are some (significant) changes you should be aware of.

Media Parents

In SearchWP when parent weight transfer/attribution was enabled, Media with no parent was omitted from results. SearchWP 4 now returns those results so they are not lost.

If you prefer that Media with no parent (when parent weight transfer is enabled) is dropped from the results set, you can use the this hook:

<?php
// Tell SearchWP to drop Media with no parent when Parent Attribution has been enabled.
// This was the default behavior in SearchWP 3 but has changed in SearchWP 4.
add_filter( 'searchwp\source\post\attachment\parent_attribution\strict', '__return_true' );

Taxonomy Terms

In SearchWP 3 only term_name was indexed by default. Based on customer feedback, this behavior has changed to include the entire WP_Term object, which includes the slug, description, and other data attached to each WP_Term that SearchWP indexes.

If you would like to reverse this behavior, this snippet will do just that: https://gist.github.com/jchristopher/0ecc4c6ed172f64e7a97748026266e32

Installation

SearchWP 4 is a major release that is also a complete rewrite of SearchWP 3.x. The associated changes require that SearchWP 3.x be both deactivated and deleted before installing SearchWP 4.

It is recommended that SearchWP 3.x is deleted using the Plugins page in your WordPress installation after it is deactivated.

Note: There is a setting on the Advanced tab of the SearchWP 3.x settings screen that when ticked will remove all of SearchWP’s data permanently on installation. There is also a hook: searchwp_nuke_on_delete.

If you do not want your data deleted on uninstallation Please ensure that both the checkbox is unticked and the hook is absent.

Unless you have opted in to having your SearchWP 3.x data permanently removed on plugin deletion, your SearchWP 3.x index and settings will remain in tact throughout this process, and be available should you decide to revert back to SearchWP 3.x at any time.

If after upgrading you would like to permanently remove the data from SearchWP 3.x (while keeping your SearchWP 4 data) you can use this Extension: Legacy Data Removal.

Settings

When activated, SearchWP 4 will detect, migrate, and import all of your existing settings e.g. Engine configuration.

Your existing index will not be migrated directly as the format has significantly changed. Upon activation SearchWP 4 will begin rebuilding your index using your migrated engines. Once the index has built your migration is complete!

You should test a few searches to ensure functionality, and if you run into any problems please open a support ticket at your earliest convenience.

Please note that unless you have opted to remove your SearchWP 3.x data it is still available by removing SearchWP 4 completely and re-installing SearchWP 3.x. A download link will always be available within your Account.

Hook Migration Reference

SearchWP 3.x SearchWP 4
Actions
searchwp_after_query_index searchwp\query\after
searchwp_before_query_index searchwp\query\before
searchwp_index_initial_complete searchwp\indexer\complete
searchwp_index_pdf_metadata searchwp\document\pdf_metadata\skip
searchwp_index_post searchwp\index\add
searchwp_index_up_to_date N/A
searchwp_indexer_loopback N/A
searchwp_indexer_post_chunk searchwp\indexer\batch
searchwp_indexer_posts searchwp\indexer\has_updates
searchwp_indexer_pre searchwp\indexer\init
searchwp_indexer_pre_chunk searchwp\indexer\batch
searchwp_indexer_pre_get_comments N/A
searchwp_indexer_running searchwp\process\begin
searchwp_load searchwp\init
searchwp_loaded searchwp\loaded
searchwp_log searchwp\debug\log
searchwp_revised_search_query searchwp\query\ran
searchwp_settings_after_header searchwp\settings\header\after
searchwp_settings_after\{$view} searchwp\settings\after\{$view}
searchwp_settings_before_header searchwp\settings\header\before
searchwp_settings_before\{$view} searchwp\settings\before\{$view}
searchwp_settings_engines searchwp\settings\view\default
searchwp_settings_footer searchwp\settings\footer
searchwp_settings_init searchwp\settings\init
searchwp_settings_nav_tab searchwp\settings\nav\tab
searchwp_settings_view\{$view} searchwp\settings\view\{$view}
searchwp_dashboard_widget searchwp\admin\dashboard_widgets\statistics
searchwp_swp_query_shutdown searchwp\swp_query\shutdown
General Filters
searchwp_admin_bar searchwp\admin_bar
searchwp_dashboard_widget_cap searchwp\statistics\capability
searchwp_debug searchwp\debug
searchwp_debug_detailed N/A
searchwp_debug_include_pid N/A
searchwp_extensions searchwp\extensions
searchwp_failed_index_notice N/A
searchwp_init searchwp\loaded
searchwp_initial_engine_settings searchwp\install\engine\settings
searchwp_license_key searchwp\license\key
searchwp_locale_override locale
searchwp_missing_integration_notices searchwp\missing_integration_notices
searchwp_nuke_on_delete searchwp\nuke_on_delete
searchwp_settings_cap searchwp\settings\capability
searchwp_show_conflict_notices N/A
searchwp_show_filter_conflict_notices N/A
searchwp_skip_vendor_libs N/A
searchwp_statistics_cap searchwp\statistics\capability
searchwp_statistics_popular_days_{$days} searchwp\statistics\popular\days_{$days}
Indexer
searchwp_aggressive_delta_update searchwp\index\aggressive_delta
searchwp_alternate_indexer searchwp\indexer\alternate
searchwp_auto_reindex searchwp\index\process\enabled and searchwp\indexer\paused
searchwp_background_deltas searchwp\index\process\enabled
searchwp_basic_auth_creds searchwp\indexer\http_basic_auth_credentials
searchwp_custom_field_{$key} searchwp\source\post\attributes\meta\{$key}
searchwp_custom_fields searchwp\source\post\attributes\meta
searchwp_custom_stemmer searchwp\stemmer\custom
searchwp_do_blocks searchwp\source\post\attributes\content\do_blocks
searchwp_do_shortcode searchwp\source\post\attributes\content\do_shortcodes
searchwp_endpoint N/A
searchwp_exclude_common N/A
searchwp_excluded_custom_fields searchwp\source\post\attributes\meta\ignored
searchwp_exclusive_regex_matches searchwp\tokens\tokenize_pattern_matches
searchwp_external_pdf_processing searchwp\parser\pdf
searchwp_extra_metadata N/A see KB Article
searchwp_get_custom_fields N/A
searchwp_include_comment_author searchwp\source\post\attributes\comments\author
searchwp_include_comment_email searchwp\source\post\attributes\comments\email
searchwp_index_attachments N/A
searchwp_index_chunk_size searchwp\indexer\batch_size
searchwp_index_comments N/A
searchwp_index_emoji searchwp\allow_emoji
searchwp_indexed_post_types Partial equivalent: searchwp\sources
searchwp_indexer_additional_meta_exclusions N/A
searchwp_indexer_apply_engines_rules N/A
searchwp_indexer_comment searchwp\source\post\attributes\comment
searchwp_indexer_comments_args searchwp\source\post\attributes\comments\args
searchwp_indexer_enabled N/A
searchwp_indexer_excluded_by_rules N/A
searchwp_indexer_load_monitoring N/A
searchwp_indexer_loopback_args searchwp\indexer\loopback\args
searchwp_indexer_max_attempts N/A
searchwp_indexer_paused N/A
searchwp_indexer_pre_process_content searchwp\source\post\attributes\content
searchwp_indexer_tag_attributes searchwp\valid_html_tags
searchwp_indexer_taxonomies N/A
searchwp_indexer_taxonomy_term searchwp\source\post\attributes\taxonomy\term
searchwp_indexer_taxonomy_term_index_slug N/A
searchwp_indexer_taxonomy_terms searchwp\source\post\attributes\taxonomy\terms
searchwp_indexer_throttle N/A
searchwp_indexer_unindexed_args searchwp\post__in
searchwp\post__not_in
searchwp_indexer_unindexed_media_args searchwp\post__in
searchwp\post__not_in
searchwp_is_attribute_used N/A
searchwp_is_used_meta_key N/A
searchwp_is_used_taxonomy N/A
searchwp_keyword_stem_locale N/A
searchwp_lenient_accents searchwp\tokens\strict
searchwp_lenient_accent_result searchwp\tokens\removed_accents
searchwp_lenient_accents_conversions N/A
searchwp_load_maximum N/A
searchwp_max_delta_attempts N/A
searchwp_max_index_attempts N/A
searchwp_mimes_{$mime_type_group} N/A
searchwp_minimum_word_length searchwp\tokens\minimum_length
searchwp_omit_document_processing N/A
searchwp_omit_meta_key N/A
searchwp_omit_meta_key_{$custom_field_key} N/A
searchwp_omit_wp_metadata N/A
searchwp_pdf_metadata N/A
searchwp_pdf_spaces_to_content_percentage N/A
searchwp_post_statuses searchwp\post_stati
searchwp_pre_set_post N/A
searchwp_prevent_indexing searchwp\post__not_in
searchwp_process_term_limit searchwp\index\tokens_max
searchwp_remove_pre_get_posts N/A
searchwp_sanitize_terms N/A
searchwp_set_post N/A
searchwp_stopwords searchwp\stopwords
searchwp_term_count_limit searchwp\index\tokens_max
searchwp_term_pattern_whitelist searchwp\tokens\regex_patterns
searchwp_timeout searchwp\indexer\loopback\args
Query Filters
searchwp_allow_quoted_phrase_search searchwp\query\logic\phrase
searchwp_and_fields N/A
searchwp_and_fields_{$post_type} N/A
searchwp_and_logic searchwp\query\logic\and
searchwp_and_logic_only searchwp\query\logic\and\strict
searchwp_auto_output_revised_search_query searchwp\query\output_suggested_search
searchwp_big_selects N/A
searchwp_custom_field_keys searchwp\source\attribute\options
searchwp_debug_append_weights_to_titles N/A
searchwp_disable_impose_engine_config N/A
searchwp_do_suggestions searchwp\query\partial_matches\did_you_mean
searchwp_enable_attribution_{post_type} searchwp\source\post\{$post_type}\attribution
searchwp_enable_parent_attribution_{post_type} searchwp\source\post\{$post_type}\parent_attribution
searchwp_engine_settings_{engine} N/A
searchwp_exclude searchwp\post__not_in
searchwp_exclude_common N/A
searchwp_force_run N/A
searchwp_force_wp_query N/A
searchwp_force_wpquery_order N/A
searchwp_found_post_objects N/A
searchwp_fuzzy_digit_threshold N/A
searchwp_fuzzy_min_length searchwp\query\partial_matches\fuzzy\minimum_length
searchwp_fuzzy_threshold searchwp\query\partial_matches\fuzzy\threshold
searchwp_in_admin N/A
searchwp_include searchwp\post__in
searchwp_like_min_length searchwp\query\partial_matches\minimum_length
searchwp_like_stem N/A
searchwp_like_wildcard_after searchwp\query\partial_matches\wildcard_after
searchwp_like_wildcard_before searchwp\query\partial_matches\wildcard_before
searchwp_load_posts N/A
searchwp_log_search searchwp\statistics\log
searchwp_max_and_results N/A
searchwp_max_search_terms searchwp\query\tokens\limit
searchwp_max_search_terms_{$engine} N/A
searchwp_max_search_terms_supplemental N/A
searchwp_partial_matches_force_fuzzy searchwp\query\partial_matches\force_fuzzy
searchwp_partial_matches_lenient searchwp\query\partial_matches\force
searchwp_partial_matching_{$engine} N/A
searchwp_persist_extra_metadata N/A
searchwp_posts_per_page searchwp\query\per_page
searchwp_pre_search_terms searchwp\query\tokens
searchwp_query_allow_query_string_override_order searchwp\query\mods
searchwp_query_allow_query_string_override_orderby searchwp\query\mods
searchwp_query_conditions searchwp\query\mods
searchwp_query_join searchwp\query\mods
searchwp_query_limit_start searchwp\query\mods
searchwp_query_limit_total searchwp\query\mods
searchwp_query_main_join searchwp\query\mods
searchwp_query_offset searchwp\query\mods
searchwp_query_orderby searchwp\query\mods
searchwp_query_results searchwp\query\results
searchwp_query_select_inject searchwp\query\mods
searchwp_refine_and_results N/A
searchwp_remove_pre_get_posts_during_search N/A
searchwp_results searchwp\query\results
searchwp_return_orderby_date searchwp\query\mods
searchwp_return_orderby_random searchwp\query\mods
searchwp_search_args searchwp\query\args
searchwp_search_query_order searchwp\query\mods
searchwp_short_circuit searchwp\native\short_circuit
searchwp_swp_query_post__in_explicit N/A
searchwp_swp_query_post__not_in_explicit N/A
searchwp_term_in searchwp\query\tokens
searchwp_terms searchwp\query\search_string
searchwp_weight_max N/A
searchwp_weight_mods searchwp\query\mods
searchwp_weight_threshold searchwp\query\min_relevance
searchwp_where searchwp\query\mods
Document Processing
searchwp_file_content_limit searchwp\source\attachment\attribute\document_content\display_limit
searchwp_purge_document_content See snippet
Highlighting
searchwp_term_highlight_break_on_first_match N/A
searchwp_term_highlight_occurrence N/A
searchwp_th_auto_filter_excerpt N/A
searchwp_th_auto_highlight_content N/A
searchwp_th_do_shortcode N/A
searchwp_th_excluded_engines N/A
searchwp_th_num_words N/A
searchwp_th_partial_matches N/A
searchwp_th_password_required_message N/A
searchwp_th_pre_process_content N/A
searchwp_th_pre_process_meta_value N/A
searchwp_th_strip_shortcodes N/A
searchwp_th_use_span N/A
Settings UI
searchwp_engine_content_type_label searchwp\source\attribute\label