Taxonomy: Add 'pre_get_term_by' filter to short-circuit get_term_by()

src/wp-includes/taxonomy.php

@@ -1098,6 +1098,31 @@ function get_term( $term, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) {
  */
 function get_term_by( $field, $value, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) {
 
+	/**
+	 * Filters a term before it is retrieved from the database, to short-circuit get_term_by().
+	 *
+	 * This allows one to short-circuit the default logic, perhaps by
+	 * replacing it with a routine that is more optimal for your setup.
+	 *
+	 * Returning a non-null value from the filter will short-circuit retrieval
+	 * and return the given value instead. Note that this bypasses the taxonomy
+	 * existence check and any sanitization normally applied by get_term_by().
+	 *
+	 * @since TBD
+	 *
+	 * @param WP_Term|array|false|null $pre      The value to return instead. Default null
+	 *                                           to continue retrieving the term.
+	 * @param string                   $field    Either 'slug', 'name', 'id' (term_id), or 'term_taxonomy_id'.
+	 * @param string|int               $value    Search for this term value.
+	 * @param string                   $taxonomy Taxonomy name. Optional, if `$field` is 'term_taxonomy_id'.
+	 * @param string                   $output   Constant OBJECT, ARRAY_A, or ARRAY_N.
+	 * @param string                   $filter   Optional, default is raw or no filter will be applied.
+	 */
+	$pre = apply_filters( 'pre_get_term_by', null, $field, $value, $taxonomy, $output, $filter );
+	if ( null !== $pre ) {
+		return $pre;
+	}
+
 	// 'term_taxonomy_id' lookups don't require taxonomy checks.
 	if ( 'term_taxonomy_id' !== $field && ! taxonomy_exists( $taxonomy ) ) {
 		return false;

tests/phpunit/tests/term/getTermBy.php

@@ -7,6 +7,8 @@ class Tests_Term_GetTermBy extends WP_UnitTestCase {
 
 	protected $query = '';
 
+	protected $pre_get_term_by_args;
+
 	public function test_get_term_by_slug() {
 		$term1 = wp_insert_term( 'Foo', 'category', array( 'slug' => 'foo' ) );
 		$term2 = get_term_by( 'slug', 'foo', 'category' );
@@ -58,6 +60,48 @@ public function test_get_term_by_unknown() {
 		$this->assertFalse( $term2 );
 	}
 
+	/**
+	 * @ticket 36978
+	 */
+	public function test_get_term_by_pre_filter() {
+		add_filter( 'pre_get_term_by', array( $this, 'filter_pre_get_term_by' ), 10, 6 );
+
+		try {
+			$term = get_term_by( 'slug', 'foo', 'category', ARRAY_A, 'display' );
+		} finally {
+			remove_filter( 'pre_get_term_by', array( $this, 'filter_pre_get_term_by' ) );
+		}
+
+		$this->assertSame( 'short-circuited', $term );
+		$this->assertSame(
+			array( 'slug', 'foo', 'category', ARRAY_A, 'display' ),
+			$this->pre_get_term_by_args
+		);
+	}
+
+	/**
+	 * @ticket 36978
+	 */
+	public function test_get_term_by_pre_filter_default_continues_normal_lookup() {
+		add_filter( 'pre_get_term_by', '__return_null' );
+
+		$term1 = wp_insert_term( 'Foo', 'category', array( 'slug' => 'foo' ) );
+
+		try {
+			$term2 = get_term_by( 'slug', 'foo', 'category' );
+		} finally {
+			remove_filter( 'pre_get_term_by', '__return_null' );
+		}
+
+		$this->assertEquals( get_term( $term1['term_id'], 'category' ), $term2 );
+	}
+
+	public function filter_pre_get_term_by( $pre, $field, $value, $taxonomy, $output, $filter ) {
+		$this->pre_get_term_by_args = array( $field, $value, $taxonomy, $output, $filter );
+
+		return 'short-circuited';
+	}
+
 	/**
 	 * @ticket 33281
 	 */