using the FullTextSearch Extra

Sep 1, 2019

What is it?

FullTextSearch adds the features and functionality of MySQL's FULLTEXT search to MODX, using a fully-customizable search index table. Specify Resource fields, TVs and content from other tables to include in the index. It integrates with listing Snippets like getResources and pdoResources for templated output.

For full-fledged, enterprise-ready search solutions, MODX CMS supports Solr and Elasticsearch with the well-adopted SimpleSearch Extra. This is the recommended approach for the sites that have sophisticated search requirements. SimpleSearch represents a lot of community contribution and the work of amazing developers like Jan Peca. FullTextSearch is not a "competitor"—it's just different.

FullTextSearch is about as easy to set up as SimpleSearch, has no third-party dependencies, and in some cases provides improved performance. You can do interesting things with it like power "smart" 404 pages. It might be a really good fit for your use case. Then again, it might not.

This dated but still valid post from DigitalOcean explains a lot about what MySQL's Full-Text Search (FTS) is doing behind the scenes. The official docs are also an important resource to read up on. The FullTextSearch Extra for MODX is managed on GitHub, and the README file provides additional, in-depth context about the FTS implementation for MODX.

Only by getting really familiar with the features of FTS, will you be able to make an informed decision about whether or not to use it for your site.

Why make this?

In discussions amongst MODX community members about search functionality, a common theme seems to arise with respect to a need to customize a search index, with use cases like, "index the rendered output of this TV, include that Resource field, but not this one, etc..." More info about that here.

Existing Solutions

  • Unless you deploy a 3rd-party engine like Elasticsearch, the SimpleSearch Extra relies on MySQL LIKE queries. These are somewhat limited compared to what you can do with FTS.
  • The AdvSearch Extra uses the Zend Lucene Search API, adding a dependency. It's arguably more complex to implement, and is starting to age a bit (latest commit 2016 as of this writing).

Neither of these solutions seemed to meet the need without additional dependencies. The MODX site_content table has a FULLTEXT index on some of the key Resource fields, but to search against a combination of those indices requires some gymnastics, and I'm not aware of any ready-made solutions.

As a former member of the MODX core team, I've been involved with engagements where a "custom index" was rendered into a TV, and SimpleSearch was used to perform queries against it. It worked, but the approach had limitations and was a bit clunky. Certainly with all that mucking about, the performance could stand improvement.

So when MySQL 5.6 was released with Full-Text search, it seemed worthy of having a full-featured MODX solution built upon it. Thus the FullTextSearch Extra.

There are caveats however.

What it isn't.

MySQL is not a search engine. MySQL's relevancy algorithm is based on the concept of rarity. If a word appears in very few Resources, those Resources that have it, will score very high in relevancy for that word. If a word appears in over 50% of Resources, it is ignored, and Resources that feature it will not be returned in searches for that word. So, searching for "MODX" on this site, for example, would actually return nothing. There are other idiosyncracies of MySQL's FTS that might be surprising, as well.

To get the most intuitive search results for your site's content, you'll need to play around with the various settings in the FullTextSearch Extra's indexing Plugin and search Snippet. Once you get it right, however, the FullTextSearch Extra can produce a very satisfying result.


On this site, there's a tag-based listing page for Resources related to the RecaptchaV2 Extra. However this works pretty well, too, in case someone messes up the URL. Or you can find out more about modmore's ContentBlocks by going here.

Once you've familiarized yourself with FTS and the FullTextSearch Extra for MODX, give it try. Currently it's in an alpha release. Please submit feedback and issues on GitHub. Any security issues that are responsibly reported will be met with everlasting appreciation and a monetary reward.

Thanks for using MODX!