Deprecate overriding SearchEngine::search*

The plan is to convert these methods into final, considering
it a removal under the deprecation policy. By making entry
points into the search engine final we provide a guaranteed
point where generic handling can be applied to all search engines.

The first use case for this generic handling is pushing pagination
via overfetch into the SearchEngine class instead of re-implementing
an overfetch in individual parts of the code that perform searches.

Change-Id: I3426d6a2f32d8b368b044b154e1cb70dac007c62

diff --git a/RELEASE-NOTES-1.32 b/RELEASE-NOTES-1.32
index 9fd3161..42302f1 100644 (file)
--- a/RELEASE-NOTES-1.32
+++ b/RELEASE-NOTES-1.32
@@ -92,6 +92,9 @@ because of Phabricator reports.
   of queueing style modules as well.
 * OutputPage::addModuleScripts() and ParserOutput::addModuleScripts are
   deprecated. Use addModules() instead.
+* Overriding SearchEngine::{searchText,searchTitle,searchArchiveTitle}
+  in extending classes is deprecated.  Extend related doSearch* methods
+  instead.
 
 === Other changes in 1.32 ===
 * …

diff --git a/includes/search/SearchEngine.php b/includes/search/SearchEngine.php
index 7e6e8e6..d34731d 100644 (file)
--- a/includes/search/SearchEngine.php
+++ b/includes/search/SearchEngine.php
@@ -69,12 +69,25 @@ abstract class SearchEngine {
        /**
         * Perform a full text search query and return a result set.
         * If full text searches are not supported or disabled, return null.
-        * STUB
+        *
+        * As of 1.32 overriding this function is deprecated. It will
+        * be converted to final in 1.34. Override self::doSearchText().
+        *
+        * @param string $term Raw search term
+        * @return SearchResultSet|Status|null
+        */
+       public function searchText( $term ) {
+               return $this->doSearchText( $term );
+       }
+
+       /**
+        * Perform a full text search query and return a result set.
         *
         * @param string $term Raw search term
         * @return SearchResultSet|Status|null
+        * @since 1.32
         */
-       function searchText( $term ) {
+       protected function doSearchText( $term ) {
                return null;
        }
 
@@ -85,11 +98,25 @@ abstract class SearchEngine {
         * The results returned by this methods are only sugegstions and
         * may not end up being shown to the user.
         *
+        * As of 1.32 overriding this function is deprecated. It will
+        * be converted to final in 1.34. Override self::doSearchArchiveTitle().
+        *
         * @param string $term Raw search term
         * @return Status<Title[]>
         * @since 1.29
         */
-       function searchArchiveTitle( $term ) {
+       public function searchArchiveTitle( $term ) {
+               return $this->doSearchArchiveTitle( $term );
+       }
+
+       /**
+        * Perform a title search in the article archive.
+        *
+        * @param string $term Raw search term
+        * @return Status<Title[]>
+        * @since 1.32
+        */
+       protected function doSearchArchiveTitle( $term ) {
                return Status::newGood( [] );
        }
 
@@ -98,10 +125,24 @@ abstract class SearchEngine {
         * If title searches are not supported or disabled, return null.
         * STUB
         *
+        * As of 1.32 overriding this function is deprecated. It will
+        * be converted to final in 1.34. Override self::doSearchTitle().
+        *
+        * @param string $term Raw search term
+        * @return SearchResultSet|null
+        */
+       public function searchTitle( $term ) {
+               return $this->doSearchTitle( $term );
+       }
+
+       /**
+        * Perform a title-only search query and return a result set.
+        *
         * @param string $term Raw search term
         * @return SearchResultSet|null
+        * @since 1.32
         */
-       function searchTitle( $term ) {
+       protected function doSearchTitle( $term ) {
                return null;
        }
 

diff --git a/includes/search/SearchMssql.php b/includes/search/SearchMssql.php
index 57ca06e..00b80fc 100644 (file)
--- a/includes/search/SearchMssql.php
+++ b/includes/search/SearchMssql.php
@@ -31,9 +31,8 @@ class SearchMssql extends SearchDatabase {
         *
         * @param string $term Raw search term
         * @return SqlSearchResultSet
-        * @access public
         */
-       function searchText( $term ) {
+       protected function doSearchText( $term ) {
                $resultSet = $this->db->query( $this->getQuery( $this->filter( $term ), true ) );
                return new SqlSearchResultSet( $resultSet, $this->searchTerms );
        }
@@ -43,9 +42,8 @@ class SearchMssql extends SearchDatabase {
         *
         * @param string $term Raw search term
         * @return SqlSearchResultSet
-        * @access public
         */
-       function searchTitle( $term ) {
+       protected function doSearchTitle( $term ) {
                $resultSet = $this->db->query( $this->getQuery( $this->filter( $term ), false ) );
                return new SqlSearchResultSet( $resultSet, $this->searchTerms );
        }

diff --git a/includes/search/SearchMySQL.php b/includes/search/SearchMySQL.php
index c98f7e3..61983d1 100644 (file)
--- a/includes/search/SearchMySQL.php
+++ b/includes/search/SearchMySQL.php
@@ -167,7 +167,7 @@ class SearchMySQL extends SearchDatabase {
         * @param string $term Raw search term
         * @return SqlSearchResultSet
         */
-       function searchText( $term ) {
+       protected function doSearchText( $term ) {
                return $this->searchInternal( $term, true );
        }
 
@@ -177,7 +177,7 @@ class SearchMySQL extends SearchDatabase {
         * @param string $term Raw search term
         * @return SqlSearchResultSet
         */
-       function searchTitle( $term ) {
+       protected function doSearchTitle( $term ) {
                return $this->searchInternal( $term, false );
        }
 

diff --git a/includes/search/SearchOracle.php b/includes/search/SearchOracle.php
index 8bcd78f..22edfb7 100644 (file)
--- a/includes/search/SearchOracle.php
+++ b/includes/search/SearchOracle.php
@@ -64,7 +64,7 @@ class SearchOracle extends SearchDatabase {
         * @param string $term Raw search term
         * @return SqlSearchResultSet
         */
-       function searchText( $term ) {
+       protected function doSearchText( $term ) {
                if ( $term == '' ) {
                        return new SqlSearchResultSet( false, '' );
                }
@@ -79,7 +79,7 @@ class SearchOracle extends SearchDatabase {
         * @param string $term Raw search term
         * @return SqlSearchResultSet
         */
-       function searchTitle( $term ) {
+       protected function doSearchTitle( $term ) {
                if ( $term == '' ) {
                        return new SqlSearchResultSet( false, '' );
                }

diff --git a/includes/search/SearchPostgres.php b/includes/search/SearchPostgres.php
index 5a50b17..15e7d10 100644 (file)
--- a/includes/search/SearchPostgres.php
+++ b/includes/search/SearchPostgres.php
@@ -37,7 +37,7 @@ class SearchPostgres extends SearchDatabase {
         * @param string $term Raw search term
         * @return SqlSearchResultSet
         */
-       function searchTitle( $term ) {
+       protected function doSearchTitle( $term ) {
                $q = $this->searchQuery( $term, 'titlevector', 'page_title' );
                $olderror = error_reporting( E_ERROR );
                $resultSet = $this->db->query( $q, 'SearchPostgres', true );
@@ -45,7 +45,7 @@ class SearchPostgres extends SearchDatabase {
                return new SqlSearchResultSet( $resultSet, $this->searchTerms );
        }
 
-       function searchText( $term ) {
+       protected function doSearchText( $term ) {
                $q = $this->searchQuery( $term, 'textvector', 'old_text' );
                $olderror = error_reporting( E_ERROR );
                $resultSet = $this->db->query( $q, 'SearchPostgres', true );

diff --git a/includes/search/SearchResultSet.php b/includes/search/SearchResultSet.php
index f25c728..e3eb4c2 100644 (file)
--- a/includes/search/SearchResultSet.php
+++ b/includes/search/SearchResultSet.php
@@ -173,6 +173,7 @@ class SearchResultSet {
         * Fetches next search result, or false.
         * STUB
         * FIXME: refactor as iterator, so we could use nicer interfaces.
+        * @deprecated since 1.32; Use self::extractResults()
         * @return SearchResult|false
         */
        function next() {
@@ -181,6 +182,7 @@ class SearchResultSet {
 
        /**
         * Rewind result set back to beginning
+        * @deprecated since 1.32; Use self::extractResults()
         */
        function rewind() {
        }

diff --git a/includes/search/SearchSqlite.php b/includes/search/SearchSqlite.php
index af29212..06c7963 100644 (file)
--- a/includes/search/SearchSqlite.php
+++ b/includes/search/SearchSqlite.php
@@ -156,7 +156,7 @@ class SearchSqlite extends SearchDatabase {
         * @param string $term Raw search term
         * @return SqlSearchResultSet
         */
-       function searchText( $term ) {
+       protected function doSearchText( $term ) {
                return $this->searchInternal( $term, true );
        }
 
@@ -166,7 +166,7 @@ class SearchSqlite extends SearchDatabase {
         * @param string $term Raw search term
         * @return SqlSearchResultSet
         */
-       function searchTitle( $term ) {
+       protected function doSearchTitle( $term ) {
                return $this->searchInternal( $term, false );
        }