Keep search parameters when using WP_List_Table and navigation

WP_List_Table is a reasonably flexible way of creating data tables in WordPress Admin Plugins. While there are plenty of warnings and words of caution against using WP_List_Table throughout the WordPress documentation and elsewhere on the Internet, it is a very popular method in use by many plugin authors.

Whether or not it’s a good idea to use WP_List_Table for your plugin is beyond the scope of this post.

While developing a plugin that is using WP_List_Table, I came across a rather well-known issue. The issue is that once the user enters search data, you would (logically) think that the search data is maintaned while navigating the search result. Unfortunately, when the user clicks on the previous and next links, or clicks on one of the table headers to re-sort the search result, the search is “lost”.

This can, technically speaking, be avoided if you resort to using METHOD="GET" rather than METHOD="POST" in your table form. But I wanted to avoid this since the entire GET request is passed in the URL and thus ends up in logs, etc.

So, how to use POST instead of get, and still maintain the search parameter across page loads?

The WP_List_Table class makes extensive use of the set_url_scheme() function to create various headers and clickable links in the table view. Unfortunately, this function is rather generic in nature and does not take the parameters from WP_List_Table::search_box() into account. But, as is the case with most functions in WordPress, as a last action, the set_url_scheme() function calls any hooked filters before it returns.

Keep search parameters between page loads

The example assumes $your_table is an object derived from WP_List_Table.

echo '<div class="wrap">';
echo '<form action="admin.php?page=your_plugin_table" method="post" name="your_table_form">';
$your_table->prepare_items();
$your_table->mangle_url_scheme_start();
$your_table->search_box();
$your_table->display();
$your_table->mangle_url_scheme_stop();
echo '</form>';
echo '</div>';

The two functions of interest here are mangle_url_scheme_start() and its companion, mangle_url_scheme_stop(). These go into your class derived from WP_List_Table like this:

public function mangle_url_scheme_start() {
    add_filter( 'set_url_scheme', [$this, 'mangle_url_scheme'], 10, 3 );
}

and

public function mangle_url_scheme_stop() {
    remove_filter( 'set_url_scheme', [$this, 'mangle_url_scheme'], 10 );
}

The last piece of the workaround is the mangle_url_scheme() function:

public function mangle_url_scheme( string $url, 
                                   string $scheme, 
                                   $orig_scheme ) {
    if ( ! empty( $url ) 
        && mb_strpos( $url, '?page=your_plugin_table' ) !== false 
            && isset( $_REQUEST['s'] ) ) {
        $url = add_query_arg( 's', urlencode( $_REQUEST['s'] ), $url );
    }
    return( $url );
}

This is only done on your plugin table page, and it’s only done if the $_REQUEST['s'] parameter is set. I can’t see how this will cause any issues further down the road, but you may experience different results. You may want to sanitize the contents of $_REQUEST['s'] further before you urlencode it.

I am reasonably convinced that there are other, and better, ways of doing this. But I haven’t found one yet.