More adjustments + better docs

10up · felipeelia · Aug 25, 2022 · Aug 1, 2022 · Aug 3, 2022 · Aug 3, 2022
commit a806f327c9d78dcc169ebc58e54ae25888fa8a72
diff --git a/includes/classes/Feature/Facets/Facets.php b/includes/classes/Feature/Facets/Facets.php
@@ -11,7 +11,6 @@
 use ElasticPress\Feature as Feature;
 use ElasticPress\Features as Features;
 use ElasticPress\Utils as Utils;
-use ElasticPress\FeatureRequirementsStatus as FeatureRequirementsStatus;
 use ElasticPress\Indexables as Indexables;
 
 if ( ! defined( 'ABSPATH' ) ) {
@@ -54,6 +53,26 @@ public function __construct() {
 			'taxonomy' => __NAMESPACE__ . '\Types\Taxonomy\FacetType',
 		];
 
+		/**
+		 * Filter the Facet types available.
+		 *
+		 * ```
+		 * add_filter(
+		 *     'ep_facet_types',
+		 *     function ( $types ) {
+		 *         $types['post_type'] = '\MyPlugin\PostType';
+		 *         return $types;
+		 *     }
+		 * );
+		 * ```
+		 *
+		 * @since 4.3.0
+		 * @hook ep_facet_types
+		 * @param {array} $types Array of types available. Keys are slugs, values are class names.
+		 * @return {array} New array of types available
+		 */
+		$types = apply_filters( 'ep_facet_types', $types );
+
 		foreach ( $types as $type => $class ) {
 			$this->types[ $type ] = new $class();
 		}
@@ -113,7 +132,10 @@ public function output_feature_box_settings() {
 	}
 
 	/**
-	 * If we are doing or matches, we need to remove filters from aggs
+	 * If we are doing `or` matches, we need to remove filters from aggs.
+	 *
+	 * By default, the same filters applied to the main query are applied to aggregations.
+	 * If doing `or` matches, those should be removed so we get a broader set of results.
 	 *
 	 * @param  array    $args ES arguments
 	 * @param  array    $query_args Query arguments
@@ -127,43 +149,30 @@ public function set_agg_filters( $args, $query_args, $query ) {
 			return $args;
 		}
 
-		// Without taxonomies there is nothing to do here.
-		if ( empty( $query_args['tax_query'] ) ) {
-			return $args;
-		}
-
-		$feature  = Features::factory()->get_registered_feature( 'facets' );
-		$settings = wp_parse_args(
-			$feature->get_settings(),
-			array(
-				'match_type' => 'all',
-			)
-		);
-
-		$facet_query_args = $query_args;
-
-		if ( 'any' === $settings['match_type'] ) {
-			foreach ( $facet_query_args['tax_query'] as $key => $taxonomy ) {
-				if ( is_array( $taxonomy ) ) {
-					unset( $facet_query_args['tax_query'][ $key ] );
-				}
-			}
-		}
-
-		// @todo For some reason these are appearing in the query args, need to investigate
-		$unwanted_args = [ 'category_name', 'cat', 'tag', 'tag_id', 'taxonomy', 'term' ];
-		foreach ( $unwanted_args as $unwanted_arg ) {
-			unset( $facet_query_args[ $unwanted_arg ] );
-		}
+		/**
+		 * Filter WP query arguments that will be used to build the aggregations filter.
+		 *
+		 * The returned `$query_args` will be used to build the aggregations filter passing
+		 * it through `Indexable\Post\Post::format_args()`.
+		 *
+		 * @hook ep_facet_agg_filters
+		 * @since 4.3.0
+		 * @param {array} $query_args Query arguments
+		 * @param {array} $args       ES arguments
+		 * @param {array} $query      WP Query instance
+		 * @return {array} New facets aggregations
+		 */
+		$query_args = apply_filters( 'ep_facet_agg_filters', $query_args, $args, $query );
 
 		remove_filter( 'ep_post_formatted_args', [ $this, 'set_agg_filters' ], 10, 3 );
-		$facet_formatted_args = Indexables::factory()->get( 'post' )->format_args( $facet_query_args, $query );
+		$facet_formatted_args = Indexables::factory()->get( 'post' )->format_args( $query_args, $query );
 		add_filter( 'ep_post_formatted_args', [ $this, 'set_agg_filters' ], 10, 3 );
 
 		$args['aggs']['terms']['filter'] = $facet_formatted_args['post_filter'];
 
 		return $args;
 	}
+
 	/**
 	 * Output scripts for widget admin
 	 *
@@ -387,14 +396,57 @@ public function get_selected() {
 	/**
 	 * Build query url
 	 *
-	 * @since  2.5, deprecated in 4.3.0
+	 * @since  2.5
 	 * @param  array $filters Facet filters
 	 * @return string
 	 */
 	public function build_query_url( $filters ) {
-		_deprecated_function( __METHOD__, '4.3.0', "\ElasticPress\Features::factory()->get_registered_feature( 'facets' )->types['taxonomy']->build_query_url()" );
+		$query_param = array();
+
+		foreach ( $this->types as $type_obj ) {
+			$filter_type = $type_obj->get_filter_type();
+
+			if ( ! empty( $filters[ $filter_type ] ) ) {
+				$type_filters = $filters[ $filter_type ];
+
+				foreach ( $type_filters as $facet => $filter ) {
+					if ( ! empty( $filter['terms'] ) ) {
+						$query_param[ $type_obj->get_filter_name() . $facet ] = implode( ',', array_keys( $filter['terms'] ) );
+					}
+				}
+			}
+		}
+
+		$feature      = Features::factory()->get_registered_feature( 'facets' );
+		$allowed_args = $feature->get_allowed_query_args();
+
+		if ( ! empty( $filters ) ) {
+			foreach ( $filters as $filter => $value ) {
+				if ( ! empty( $value ) && in_array( $filter, $allowed_args, true ) ) {
+					$query_param[ $filter ] = $value;
+				}
+			}
+		}
+
+		$query_string = http_build_query( $query_param );
+
+		/**
+		 * Filter facet query string
+		 *
+		 * @hook ep_facet_query_string
+		 * @param  {string} $query_string Current query string
+		 * @param  {array} $query_param Query parameters
+		 * @return  {string} New query string
+		 */
+		$query_string = apply_filters( 'ep_facet_query_string', $query_string, $query_param );
+
+		$url        = $_SERVER['REQUEST_URI'];
+		$pagination = strpos( $url, '/page' );
+		if ( false !== $pagination ) {
+			$url = substr( $url, 0, $pagination );
+		}
 
-		return $this->types['taxonomy']->build_query_url( $filters );
+		return strtok( trailingslashit( $url ), '?' ) . ( ( ! empty( $query_string ) ) ? '?' . $query_string : '' );
 	}
 
 	/**

diff --git a/includes/classes/Feature/Facets/Types/Taxonomy/Block.php b/includes/classes/Feature/Facets/Types/Taxonomy/Block.php
@@ -25,7 +25,19 @@ public function setup() {
 		add_action( 'init', [ $this, 'register_block' ] );
 		add_action( 'rest_api_init', [ $this, 'setup_endpoints' ] );
 
-		$this->renderer = new Renderer();
+		/**
+		 * Filter the class name to be used to render the Facet.
+		 *
+		 * @since 4.3.0
+		 * @hook ep_facet_renderer_class
+		 * @param {string} $classname  The name of the class to be instantiated and used as a renderer.
+		 * @param {string} $facet_type The type of the facet.
+		 * @param {string} $context    Context where the renderer will be used: `block` or `widget`, for example.
+		 * @return {string} The name of the class
+		 */
+		$renderer_class = apply_filters( 'ep_facet_renderer_class', __NAMESPACE__ . '\Renderer', 'taxonomy', 'block' );
+
+		$this->renderer = new $renderer_class();
 	}
 
 	/**

diff --git a/includes/classes/Feature/Facets/Types/Taxonomy/FacetType.php b/includes/classes/Feature/Facets/Types/Taxonomy/FacetType.php
@@ -28,7 +28,7 @@ class FacetType {
 	 */
 	public function setup() {
 		add_action( 'widgets_init', [ $this, 'register_widgets' ] );
-		add_filter( 'ep_post_formatted_args', [ $this, 'set_agg_filters' ], 10, 3 );
+		add_filter( 'ep_facet_agg_filters', [ $this, 'agg_filters' ] );
 		add_action( 'pre_get_posts', [ $this, 'facet_query' ] );
 		add_filter( 'ep_facet_wp_query_aggs_facet', [ $this, 'set_wp_query_aggs' ] );
 
@@ -39,20 +39,13 @@ public function setup() {
 	/**
 	 * If we are doing or matches, we need to remove filters from aggs
 	 *
-	 * @param  array    $args ES arguments
-	 * @param  array    $query_args Query arguments
-	 * @param  WP_Query $query WP Query instance
+	 * @param  array $query_args Query arguments
 	 * @return array
 	 */
-	public function set_agg_filters( $args, $query_args, $query ) {
-		// Not a facetable query
-		if ( empty( $query_args['ep_facet'] ) ) {
-			return $args;
-		}
-
+	public function agg_filters( $query_args ) {
 		// Without taxonomies there is nothing to do here.
 		if ( empty( $query_args['tax_query'] ) ) {
-			return $args;
+			return $query_args;
 		}
 
 		$feature  = Features::factory()->get_registered_feature( 'facets' );
@@ -63,81 +56,21 @@ public function set_agg_filters( $args, $query_args, $query ) {
 			)
 		);
 
-		$facet_query_args = $query_args;
-
 		if ( 'any' === $settings['match_type'] ) {
-			foreach ( $facet_query_args['tax_query'] as $key => $taxonomy ) {
+			foreach ( $query_args['tax_query'] as $key => $taxonomy ) {
 				if ( is_array( $taxonomy ) ) {
-					unset( $facet_query_args['tax_query'][ $key ] );
+					unset( $query_args['tax_query'][ $key ] );
 				}
 			}
 		}
 
 		// @todo For some reason these are appearing in the query args, need to investigate
 		$unwanted_args = [ 'category_name', 'cat', 'tag', 'tag_id', 'taxonomy', 'term' ];
 		foreach ( $unwanted_args as $unwanted_arg ) {
-			unset( $facet_query_args[ $unwanted_arg ] );
-		}
-
-		remove_filter( 'ep_post_formatted_args', [ $this, 'set_agg_filters' ], 10, 3 );
-		$facet_formatted_args = Indexables::factory()->get( 'post' )->format_args( $facet_query_args, $query );
-		add_filter( 'ep_post_formatted_args', [ $this, 'set_agg_filters' ], 10, 3 );
-
-		$args['aggs']['terms']['filter'] = $facet_formatted_args['post_filter'];
-
-		return $args;
-	}
-
-
-	/**
-	 * Build query url
-	 *
-	 * @param  array $filters Facet filters
-	 * @return string
-	 */
-	public function build_query_url( $filters ) {
-		$query_param = array();
-
-		if ( ! empty( $filters['taxonomies'] ) ) {
-			$tax_filters = $filters['taxonomies'];
-
-			foreach ( $tax_filters as $taxonomy => $filter ) {
-				if ( ! empty( $filter['terms'] ) ) {
-					$query_param[ $this->get_filter_name() . $taxonomy ] = implode( ',', array_keys( $filter['terms'] ) );
-				}
-			}
-		}
-
-		$feature      = Features::factory()->get_registered_feature( 'facets' );
-		$allowed_args = $feature->get_allowed_query_args();
-
-		if ( ! empty( $filters ) ) {
-			foreach ( $filters as $filter => $value ) {
-				if ( ! empty( $value ) && in_array( $filter, $allowed_args, true ) ) {
-					$query_param[ $filter ] = $value;
-				}
-			}
+			unset( $query_args[ $unwanted_arg ] );
 		}
 
-		$query_string = http_build_query( $query_param );
-
-		/**
-		 * Filter facet query string
-		 *
-		 * @hook ep_facet_query_string
-		 * @param  {string} $query_string Current query string
-		 * @param  {array} $query_param Query parameters
-		 * @return  {string} New query string
-		 */
-		$query_string = apply_filters( 'ep_facet_query_string', $query_string, $query_param );
-
-		$url        = $_SERVER['REQUEST_URI'];
-		$pagination = strpos( $url, '/page' );
-		if ( false !== $pagination ) {
-			$url = substr( $url, 0, $pagination );
-		}
-
-		return strtok( trailingslashit( $url ), '?' ) . ( ( ! empty( $query_string ) ) ? '?' . $query_string : '' );
+		return $query_args;
 	}
 
 	/**
@@ -174,7 +107,7 @@ public function get_filter_type() {
 		 * Filter the facet filter name that's added to the URL
 		 *
 		 * @hook ep_facet_filter_name
-		 * @since 4.0.0
+		 * @since 4.3.0
 		 * @param   {string} Facet filter name
 		 * @return  {string} New facet filter name
 		 */

diff --git a/includes/classes/Feature/Facets/Types/Taxonomy/Renderer.php b/includes/classes/Feature/Facets/Types/Taxonomy/Renderer.php
@@ -75,12 +75,8 @@ public function render( $args, $instance ) {
 			}
 		}
 
-		$facet_type = $feature->types['taxonomy'];
-
 		$selected_filters = $feature->get_selected();
 
-		$match_type = ( ! empty( $instance['match_type'] ) ) ? $instance['match_type'] : 'all';
-
 		/**
 		 * Get all the terms so we know if we should output the widget
 		 */
@@ -196,7 +192,7 @@ public function render( $args, $instance ) {
 							// phpcs:disable WordPress.Security.EscapeOutput.OutputNotEscaped
 							echo $this->get_facet_term_html(
 								$term,
-								$facet_type->build_query_url( $new_filters ),
+								$feature->build_query_url( $new_filters ),
 								true
 							);
 							// phpcs:enable WordPress.Security.EscapeOutput.OutputNotEscaped
@@ -259,7 +255,7 @@ public function render( $args, $instance ) {
 								// phpcs:disable WordPress.Security.EscapeOutput.OutputNotEscaped
 								echo $this->get_facet_term_html(
 									$term,
-									$facet_type->build_query_url( $new_filters ),
+									$feature->build_query_url( $new_filters ),
 									$selected
 								);
 								// phpcs:enable WordPress.Security.EscapeOutput.OutputNotEscaped
@@ -288,7 +284,7 @@ public function render( $args, $instance ) {
 					// phpcs:disable WordPress.Security.EscapeOutput.OutputNotEscaped
 					echo $this->get_facet_term_html(
 						$term,
-						$facet_type->build_query_url( $new_filters )
+						$feature->build_query_url( $new_filters )
 					);
 					// phpcs:enable WordPress.Security.EscapeOutput.OutputNotEscaped
 				endforeach;

diff --git a/includes/classes/Feature/Facets/Types/Taxonomy/Widget.php b/includes/classes/Feature/Facets/Types/Taxonomy/Widget.php
@@ -36,7 +36,10 @@ public function __construct() {
 
 		parent::__construct( 'ep-facet', esc_html__( 'ElasticPress - Facet', 'elasticpress' ), $options );
 
-		$this->renderer = new Renderer();
+		/** This filter is documented in includes/classes/Feature/Facets/Types/Taxonomy/Block.php */
+		$renderer_class = apply_filters( 'ep_facet_renderer_class', __NAMESPACE__ . '\Renderer', 'taxonomy', 'widget' );
+
+		$this->renderer = new $renderer_class();
 	}
 
 	/**