Represent an AFS query. More...

Inheritance diagram for AfsQuery:

Public Member Functions
	__construct (AfsQuery $afs_query=null)
	Construct new AFS query object.
Filter management
	set_filter ($facet_id, $values)
	Assign new value(s) to specific facet replacing any existing one.
	set_filter_on_feed ($facet_id, array $values, $feed)
	Assign new value(s) to specific facet on feed replacing any existing one.
	add_filter ($facet_id, $values)
	Assign new value(s) to specific facet.
	add_filter_on_feed ($facet_id, $values, $feed)
	Assign new value(s) to specific facet.
	remove_filter ($facet_id, $value)
	Remove existing value from specific facet.
	remove_filter_on_feed ($facet_id, $value, $feed=null)
	Remove existing value from specific facet.
	set_geoDist_filter ($lat, $lon, $range, $lat_facet_id='geo:lat', $lon_facet_id='geo:long')
	set a new geolocation filter (replacing existing one) using a center point and a range.
	remove_geoDist_filter ()
	remove geolocation filter if exists
	set_geoDist_sort ($lat, $lon, $order=AfsSortOrder::DESC, $lat_facet_id='geo:lat', $lon_facet_id='geo:long')
	has_filter ($facet_id, $value, $feed=null)
	Check whether instance has a value associated with specified facet id.
	get_filter_values ($facet_id, $feed=null)
	Retrieve the list of values for specific facet id.
	get_filters ($feed_name=null)
	Retrieve the list of all managed facet ids.
Advanced filter management
These filters are intended to be exposed to AFS search engine only.
	has_advanced_filter ()
	Checks whether at least one advanced filter is defined.
	get_advanced_filters ()
	Retrieves advanced filters.
	set_advanced_filter (AfsFilterWrapper $filter)
	Defines new advanced filter replacing any existing ones.
	add_advanced_filter (AfsFilterWrapper $filter)
	Appends new advanced filter to the query.
	reset_advanced_filter ()
	Remove any advanced filter definition from the query.
Language management
	has_lang ()
	Check whether language is set.
	reset_lang ()
	Remove filter on language.
	set_lang ($lang)
	Define new language.
	get_lang ()
	Retrieve current language filter.
Facet management
	get_facet_manager ()
	Retrieves facet manager.
	set_default_standard_selection_facets ()
	Defines standard selection mode for all facets.
	set_default_multi_selection_facets ()
	Defines multi-selection mode for all facets.
	set_default_mono_selection_facets ()
	Defines mono-selection mode for all facets.
	set_facet_order ()
	Defines facet sort order.
	set_facets_values_sort_order ($mode, $order)
	Defines sort order for all facet values.
	set_facet_values_sort_order ($facet_id, $mode, $order)
	Defines sort order for all facet values.
	set_facets_values_nb_replies ($nb_replies)
	Defines maximum number of facet values replied per facet.
	set_standard_selection_facets ()
	Defines standard selection mode for one or more facets.
	set_multi_selection_facets ($ids, $and_mode=false)
	Defines multi-selection mode for one or more facets.
	set_mono_selection_facets ($ids)
	Defines mono-selection mode for one or more facets.
	set_fts_default ($ftsDefault)
	Defines Full Text Search mode.
	set_client_data ($id)
	Defines id or array of ids of client data to retrieve This method overwrite any id set before.
	add_client_data ($id)
	Adds id or array of ids of client data to retrieve.
Public Member Functions inherited from AfsQueryBase
	__construct (AfsQueryBase $afs_query=null)
	Constructs new AFS ACP query object.
	get_parameters ($all=true)
	Retrieves query parameters.
	__get ($name)
	Add ability to get custom params as member fields.
	has_query ($feed=null)
	Checks whether current instance has a query.
	get_query ($feed=null)
	Retrieves the query.
	set_query ($new_query, $feed=null)
	Assigns new query value.
	has_replies ($feed=null)
	Checks whether replies is set.
	set_replies ($replies_nb, $feed=null)
	Defines new number of replies.
	get_replies ($feed=null)
	Get number of replies per page.
	auto_set_from ($auto_set=true)
	Defines whether `from` parameter should be auto set when possible.
	set_from ($from, $feed=null)
	Defines the origin of the query.
	get_from ($feed=null)
	Retrieves origin of the query.
	set_user_id ($user_id)
	Defines user id.
	has_user_id ()
	Checks whether user id is set.
	get_user_id ()
	Retrieves user identifier.
	set_session_id ($session_id)
	Defines session id.
	has_session_id ()
	Checks whether session id is set.
	get_session_id ()
	Retrieves session id.
	initialize_user_and_session_id (AfsUserSessionManager $mgr)
	Initializes user id and session id.
	update_user_and_session_id ($user_id, $session_id)
	Updates user and session identifiers.
	add_log ($value)
	Adds new logging information.
	get_logs ()
	Retrieves current defined logs.
	has_key ($feed=null)
	Checks whether key parameter is set.
	set_key ($key_id, $feed=null)
	Defines key id.
	get_key ($feed=null)
	Retrieves key value.
	has_feed ($feed=null)
	Checks whether feed parameter is set.
	set_feed ($feed)
	Assigns new feed name replacing any existing one.
	add_feed ($feed)
	Assigns new feed name.
	get_feeds ()
	Retrieves all defined feeds.

Protected Member Functions
	on_assignment ()
	Action to perform when an assignment occurs.
Protected Member Functions inherited from AfsQueryBase
	get_feed ($feed)

Page management
	has_page ($feed=null)
	Check whether reply page is set.
	set_page ($page, $feed=null)
	Define new result page.
	get_page ($feed=null)
	Retrieve current reply page.
	reset_page ()
	Shortcut for set_page(1).

Sort order management
	has_sort ($name=null, $feed=null)
	Checks whether sort parameter is set.
	reset_sort ()
	Resets sort order to AFS default sort order.
	set_sort ($sort_param, $order=AfsSortOrder::DESC, $feed=null)
	Defines new sort order.
	add_sort ($sort_param, $order=AfsSortOrder::DESC, $feed=null)
	Defines additional sort order.
	get_sort ($feed=null)
	Retrieves sort order.
	get_sort_order ($name, $feed=null)
	Retrieves sort order of the specified parameter.

Clustering
	has_cluster ()
	Checks whether cluster is set for current query.
	set_cluster ($facet_id, $replies_per_cluster)
	Defines new cluster query.
	unset_cluster ()
	Unsets cluster definition.
	get_cluster_id ()
	Retrieves cluster identifier.
	get_nb_replies_per_cluster ()
	Retrieves maximum number of replies per cluster.
	has_max_clusters ()
	Checks whether number of cluster is limited.
	set_max_clusters ($max_nb_of_clusters)
	Defines maximum number of cluster replies shown in AFS response.
	get_max_clusters ()
	Retrieves maximum number of clusters.
	has_overspill ()
	Checks wether overspill has been activated.
	set_overspill ($status=true)
	Activates or deactivate overspill mode.
	get_count_mode ($feed=null)
	Retrieves count mode when cluster mode is active.
	set_count ($count_mode, $feed=null)
	Defines new count mode.
	set_maxClusters ($max_nb_of_clusters)

Full configuration through array of parameters
	get_relevant_parameters ()
	Retrieves relevant parameters.
	get_additional_parameters ()
	Retrieves additional parameters.
static	create_from_parameters (array $params)
	Creates full query from array of parameters.

Detailed Description

Represent an AFS query.

All instances of this class are immutable: each method call involves creation of new instance copied from current one. Newly created instance is modified according to called method and returned. So, don't forget to store returned object.

$query = new AfsQuery();
$query->set_query('my query');
if (! $query->has_query())
{
  echo 'You do not save the result of set_query!';
}

Constructor & Destructor Documentation

__construct ( AfsQuery $afs_query = null )

Construct new AFS query object.

Parameters

$afs_query [in] instance used for initialization (default: create new empty instance).

Member Function Documentation

add_advanced_filter ( AfsFilterWrapper $filter )

Appends new advanced filter to the query.

Parameters

$filter [in] Advanced filter to add.

Returns: new up to date instance.

add_client_data ( $id )

Adds id or array of ids of client data to retrieve.

Parameters

$id	id or array of ids of client data

add_filter	(	$facet_id,
		$values
	)

Assign new value(s) to specific facet.

Parameters

$facet_id	[in] id of the facet for which new value should be added.
$values	[in] value(s) to add to the facet.

Returns: new up to date instance.

add_filter_on_feed	(	$facet_id,
		$values,
		$feed
	)

Assign new value(s) to specific facet.

Parameters

$facet_id	[in] id of the facet for which new value should be added.
$values	[in] value(s) to add to the facet.
$feed	[in] feed to filter on

Returns: new up to date instance.

add_sort	(	$sort_param,
		$order = `AfsSortOrder::DESC`,
		$feed = `null`
	)

Defines additional sort order.

Provided sort parameter should be a built-in facet like: afs:weight, afs:relevance, afs:words (see AfsSortBuiltins)... or user defined facet.

Parameters

$sort_param	[in] new sort parameter. When set to emty string or null, this call to this method is equivalent to call to reset_sort.
$order	[in] order applied to the given parameter. Allowed values are AfsSortOrder::DESC (default) or AfsSortOrder:ASC.
@feed	[in] the feed name. If not set, sort is add for all feeds.

Exceptions

Exception when provided sort parameter does not conform to required syntax.

static create_from_parameters ( array $params )

static

Creates full query from array of parameters.

Unknown parameters are silently ignored.

Parameters

$params [in] structured array of parameters.

Returns: correctly initialized query.

get_additional_parameters ( )

protected

Retrieves additional parameters.

Derived class should override this method with only its own parameters.

Returns: class specific additional parameters.

Reimplemented from AfsQueryBase.

get_advanced_filters ( )

Retrieves advanced filters.

Returns: Advanced filters.

get_cluster_id ( )

Retrieves cluster identifier.

Returns: Filter identifier used to make the clusters.

Exceptions

AfsUninitializedClusterException when no cluster has been previously set.

get_count_mode ( $feed = null )

Retrieves count mode when cluster mode is active.

Count mode influences number of replies value which corresponds to the number of documents (default) or the number of clusters.

Returns: Current count mode. AfsCount::DOCUMENTS, AfsCount::CLUSTERS or null when no specific count mode has been set.

get_facet_manager ( )

Retrieves facet manager.

Returns: Facet manager associated to this instance.

get_filter_values	(	$facet_id,
		$feed = `null`
	)

Retrieve the list of values for specific facet id.

Remarks: You should ensure that the required facet_id is valid.

Parameters

$facet_id	[in] facet id to consider.
$feed	[in] the feed name. If not set, filter values applied on all feeds will be returned.

Returns: list of values associated to the given facet_id.

get_filters ( $feed_name = null )

Retrieve the list of all managed facet ids.

Only elements from this list should be used to query get_filter_values method.

Parameters

@feed [in] the feed name. If not set return all filter not set on feed.

Returns: list of facet ids.

get_lang ( )

Retrieve current language filter.

Returns: language filter or null when no language is set.

get_max_clusters ( )

Retrieves maximum number of clusters.

Returns: Maximum number of clusters or null when not set (ie no limit).

get_nb_replies_per_cluster ( )

Retrieves maximum number of replies per cluster.

Returns: Number of replies per cluster reply.

Exceptions

AfsUninitializedClusterException when no cluster has been previously set.

get_page ( $feed = null )

Retrieve current reply page.

Parameters

$feed [in] the feed name. If not set the default page will be returned (used when feed is not specified, see AfsQuery::set_page)

Remarks: For a new query, this value is reset to 1.

Returns: reply page number.

get_relevant_parameters ( )

protected

Retrieves relevant parameters.

Derived class should override this method with only its own parameters.

Returns: class specific relevant parameters.

Reimplemented from AfsQueryBase.

get_sort ( $feed = null )

Retrieves sort order.

Deprecated:: This method will be removed soon!

Parameters

@feed [in] the feed name. If not set, sort for all feed is return.

Returns: sort order as string.

get_sort_order	(	$name,
		$feed = `null`
	)

Retrieves sort order of the specified parameter.

Parameters

$name	[in] parameter name to check.
@feed	[in] the feed name. If not set, sort order for all feeds is return.

Returns: AfsSortOrder::ASC or AfsSortOrder::DESC.

Exceptions

OutOfBoundsException when required sort parameter is not defined.

has_advanced_filter ( )

Checks whether at least one advanced filter is defined.

Returns: True when one or more advanced filters have been defined, false otherwise.

has_cluster ( )

Checks whether cluster is set for current query.

Returns: True when cluster is defined for the query, false otherwise.

has_filter	(	$facet_id,
		$value,
		$feed = `null`
	)

Check whether instance has a value associated with specified facet id.

Parameters

$facet_id	[in] id of the facet to check.
$value	[in] value to check in the list of values for the given facet_id.
$feed	[in] the feed name. If no set, filter is set on all feed.

Returns: true when the value is present in the list of values associated with facet_id, false otherwise. Always false when provided facet_id is unknown.

has_lang ( )

Check whether language is set.

Returns: true when language parameter is set, false otherwise.

has_max_clusters ( )

Checks whether number of cluster is limited.

When no limit is set, one cluster is created per facet value.

Returns: True when number of clusters is limited, false otherwise.

has_overspill ( )

Checks wether overspill has been activated.

Returns: True when overspill is active, false otherwise.

has_page ( $feed = null )

Check whether reply page is set.

Parameters

@feed [in] the feed name. If not set check if default page is set.

Returns: always true.

has_sort	(	$name = `null`,
		$feed = `null`
	)

Checks whether sort parameter is set.

Parameters

$name	[in] check this specific parameter name (default=null: checks whether at least one sort parameter is set).
$feed	[in] the feed name. If not set, check if sort in set for all feeds.

Returns: true when sort parameter is set, false otherwise.

on_assignment ( )

protected

Action to perform when an assignment occurs.

Page number is reset.

Reimplemented from AfsQueryBase.

remove_filter	(	$facet_id,
		$value
	)

Remove existing value from specific facet.

Remarks: No error is reported when the removed value is not already set.

Parameters

$facet_id	[in] id of the facet to update.
$value	[in] value to be removed from the list of values associated to the facet.

Returns: new up to date instance.

remove_filter_on_feed	(	$facet_id,
		$value,
		$feed = `null`
	)

Remove existing value from specific facet.

Remarks: No error is reported when the removed value is not already set.

Parameters

$facet_id	[in] id of the facet to update.
$value	[in] value to be removed from the list of values associated to the facet.

Returns: new up to date instance.

remove_geoDist_filter ( )

remove geolocation filter if exists

Returns: new up to date instance

reset_advanced_filter ( )

Remove any advanced filter definition from the query.

Returns: new up to date instance.

reset_page ( )

protected

Shortcut for set_page(1).

This method do not copy the instance and change current one inplace.

set_advanced_filter ( AfsFilterWrapper $filter )

Defines new advanced filter replacing any existing ones.

Parameters

$filter [in] Advanced filter to set.

Returns: new up to date instance.

set_client_data ( $id )

Defines id or array of ids of client data to retrieve This method overwrite any id set before.

Parameters

$id	id or array of ids of client data

set_cluster	(	$facet_id,
		$replies_per_cluster
	)

Defines new cluster query.

Parameters

$facet_id	[in] Facet identifier used to make clusters.
$replies_per_cluster	[in] Number of replies provided by AFS search engine per cluster reply.

Returns: new up to date instance.

set_count	(	$count_mode,
		$feed = `null`
	)

Defines new count mode.

Parameters

$count_mode [in] New count mode to set. Available values are AfsCount::DOCUMENTS, AfsCount::CLUSTERS or null to rely on default AFS search engine count mode.

Returns: new up to date instance.

set_default_mono_selection_facets ( )

Defines mono-selection mode for all facets.

Replaces default mode (standard selection facets).

Mono-selection mode allows to filter on one facet value whereas all facet values are still present in AFS search reply. Selecting new facet value replaces previously selected one. See AfsFacetMode::OR_MODE for simple example.

set_default_multi_selection_facets ( )

Defines multi-selection mode for all facets.

Replaces default mode (standard selection facets).

Multi-selection mode allows to filter on one or more facet values whereas all facet values are still present in AFS search reply. See AfsFacetMode::OR_MODE for simple example.

set_default_standard_selection_facets ( )

Defines standard selection mode for all facets.

This is the default mode.

Standard selection mode allows to filter on one or more facet values whereas only relevant facet values are present in AFS search reply. See AfsFacetMode::AND_MODE for simple example.

set_facet_order ( )

Defines facet sort order.

Remarks: Parameters are a list of facet identifiers in the right sort order (list of strings or array of strings).

set_facet_values_sort_order	(	$facet_id,
		$mode,
		$order
	)

Defines sort order for all facet values.

AFS search default sort for facet values is alphanumeric. This method allows to change this behaviour.

Remarks: This configuration is not exposed to AfsQueryCoder.

Parameters

$mode	[in] Sort mode (see AfsFacetValuesSortMode).
$order	[in] Sort order (see AfsSortOrder).

Exceptions

InvalidArgumentException when $mode or $order is invalid.

set_facets_values_nb_replies ( $nb_replies )

Defines maximum number of facet values replied per facet.

Default maximum value is 1000.

Parameters

$nb_replies [in] maximum number of facet values.

set_facets_values_sort_order	(	$mode,
		$order
	)

Defines sort order for all facet values.

AFS search default sort for facet values is alphanumeric. This method allows to change this behaviour.

Remarks: This configuration is not exposed to AfsQueryCoder.

Parameters

$mode	[in] Sort mode (see AfsFacetValuesSortMode).
$order	[in] Sort order (see AfsSortOrder).

Exceptions

InvalidArgumentException when $mode or $order is invalid.

set_filter	(	$facet_id,
		$values
	)

Assign new value(s) to specific facet replacing any existing one.

Parameters

$facet_id	[in] id of the facet to update.
$values	[in] new value(s) to filter on.

Returns: new up to date instance.

set_filter_on_feed	(		$facet_id,
		array	$values,
			$feed
	)

Assign new value(s) to specific facet on feed replacing any existing one.

Parameters

$facet_id	[in] id of the facet to update.
$values	[in] new value(s) to filter on.
$feed	[in] feed to filter on

Returns: new up to date instance.

set_fts_default ( $ftsDefault )

Defines Full Text Search mode.

Parameters

$ftsDefault Full Text Search mode

set_geoDist_filter	(	$lat,
		$lon,
		$range,
		$lat_facet_id = `'geo:lat'`,
		$lon_facet_id = `'geo:long'`
	)

set a new geolocation filter (replacing existing one) using a center point and a range.

Parameters

	$lat	the center point latitude
	$lon	the center point longitude
int	$range	the range used to filter
string	$lat_facet_id	the facet id used to compare latitudes
string	$lon_facet_id	the facet id used to compare longitude

Returns: new up to date instance

set_geoDist_sort	(	$lat,
		$lon,
		$order = `AfsSortOrder::DESC`,
		$lat_facet_id = `'geo:lat'`,
		$lon_facet_id = `'geo:long'`
	)

Parameters

	$lat
	$lon
string	$lat_facet_id
string	$lon_facet_id

Returns: copy

set_lang ( $lang )

Define new language.

See AfsLanguage for more details on valid values.

Remarks: Page value is preserved when this method is called.

Parameters

$lang [in] New language to filter on. Empty string or null value resets current language filter.

Exceptions

Exception when provided language is invalid.

set_max_clusters ( $max_nb_of_clusters )

Defines maximum number of cluster replies shown in AFS response.

Parameters

$max_nb_of_clusters [in] Maximum number of clusters.

Returns: new up to date instance.

set_mono_selection_facets ( $ids )

Defines mono-selection mode for one or more facets.

See AfsSearch::set_default_mono_selection_facets or AfsFacetMode::SINGLE_MODE for more details.

Remarks: Parameters: one (string) or more facet identifiers (individual strings or array of strings).

set_multi_selection_facets	(	$ids,
		$and_mode = `false`
	)

Defines multi-selection mode for one or more facets.

Default facet behavior is OR_MODE => see AfsFacetMode::OR_MODE for more details. If $and_mode is set to true, facet behavior is STICKY_AND_MODE => see AfsFacetMode::STICKY_AND_MODE for more details.

Remarks: Parameters: one (string) or more facet identifiers (individual strings or array of strings).

set_overspill ( $status = true )

Activates or deactivate overspill mode.

When overspill is activated, replies that could not be fitted in clusters are added, in sorted order, after all clusters.

Parameters

$status [in] Activates (default: true) or deactivates (false) overspill.

Returns: new up to date instance.

set_page	(	$page,
		$feed = `null`
	)

Define new result page.

Parameters

$page	[in] result page to output. It should be greater than or equal to 1.
$feed	[in] the feed to set the page on. Default behavior will set the page number for all feeds

Returns: new up to date instance.

Exceptions

Exception on invalid page number.

set_sort	(	$sort_param,
		$order = `AfsSortOrder::DESC`,
		$feed = `null`
	)

Defines new sort order.

Provided sort parameter should be a built-in facet like: afs:weight, afs:relevance, afs:words ... or user defined facet

Parameters

$sort_param	[in] new sort parameter. When set to emty string or null, this call to this method is equivalent to call to reset_sort.
$order	[in] order applied to the given parameter. Allowed values are AfsSortOrder::DESC (default) or AfsSortOrder:ASC.
@feed	[in] the feed name. If not set, sort is set for all feeds.

Exceptions

Exception when provided sort parameter does not conform to required syntax.

set_standard_selection_facets ( )

Defines standard selection mode for one or more facets.

See AfsSearch::set_default_standard_selection_facets or AfsFacetMode::AND_MODE for more details.

Remarks: Parameters: one (string) or more facet identifiers (individual strings or array of strings).

unset_cluster ( )

Unsets cluster definition.

Returns: new up to date instance.

Public Member Functions

Protected Member Functions

Page management

Sort order management

Clustering

Full configuration through array of parameters

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation