Moodle PHP Documentation 4.5
Moodle 4.5dev (Build: 20240606) (d3ae1391abe)
core_search\engine Class Reference

Base class for search engines. More...

Inheritance diagram for core_search\engine:
search_simpledb\engine search_solr\engine

Public Member Functions

 __construct (bool $alternateconfiguration=false)
 Initialises the search engine configuration.
 
 add_document ($document, $fileindexing=false)
 Adds a document to the search engine.
 
 add_document_batch (array $documents, bool $fileindexing=false)
 Adds multiple documents to the search engine.
 
 add_documents ($iterator, $searcharea, $options)
 Loop through given iterator of search documents and and have the search engine back end add them to the index.
 
 area_index_complete ($searcharea, $numdocs=0, $fullindex=false)
 Do any area cleanup needed, and do anything to confirm contents.
 
 area_index_starting ($searcharea, $fullindex=false)
 Do anything that may need to be done before an area is indexed.
 
 check_latest_schema ()
 Checks that the schema is the latest version.
 
 clear_query_error ()
 Clears the current query error value.
 
 delete ($areaid=null)
 Delete all documents.
 
 delete_index_for_context (int $oldcontextid)
 Deletes information related to a specific context id.
 
 delete_index_for_course (int $oldcourseid)
 Deletes information related to a specific course id.
 
 execute_query ($filters, $accessinfo, $limit=0)
 Executes the query on the engine.
 
 file_indexing_enabled ()
 Return true if file indexing is supported and enabled.
 
 get_batch_max_content ()
 Gets the maximum size of document content to be included in a shared batch (if the document is bigger then it will be sent on its own; batching does not provide a performance improvement for big documents anyway).
 
int get_batch_max_documents ()
 Gets the maximum number of documents to send together in batch mode.
 
 get_document_classname ()
 Gets the document class used by this search engine.
 
 get_plugin_name ()
 Returns the plugin name.
 
 get_query_error ()
 Returns any error reported by the search engine when executing the provided query.
 
 get_query_total_count ()
 Returns the total number of documents available for the most recent call to execute_query.
 
 get_supported_orders (\context $context)
 Obtain a list of results orders (and names for them) that are supported by this search engine in the given context.
 
 get_user ($userid)
 Returns user data checking the internal static cache.
 
 has_alternate_configuration ()
 Checks if the search engine has an alternate configuration.
 
 index_complete ($numdocs=0, $fullindex=false)
 Run any post indexing operations.
 
 index_starting ($fullindex=false)
 Run any pre-indexing operations.
 
 is_installed ()
 Does the system satisfy all the requirements.
 
 is_server_ready ()
 Is the server ready to use?
 
 optimize ()
 Optimizes the search engine.
 
 record_applied_schema_version ($version)
 Usually called by the engine; marks that the schema has been updated.
 
 skip_schema_check ($skip=true)
 Tells the search engine to skip any time-consuming checks that it might do as part of the is_server_ready function, and only carry out a basic check that it can contact the server.
 
 supports_add_document_batch ()
 Checks if the search engine supports adding documents in a batch.
 
 supports_group_filtering ()
 Checks if this search engine supports groups.
 
 supports_users ()
 Checks if the search engine supports searching by user.
 

Static Public Member Functions

static clear_users_cache ()
 Clears the users cache.
 

Protected Member Functions

 get_course ($courseid)
 Returns a course instance checking internal caching.
 
 get_search_area ($areaid)
 Returns a search instance of the specified area checking internal caching.
 
 should_skip_schema_check ()
 For use by subclasses.
 
 to_document (\core_search\base $searcharea, $docdata)
 Returns a document instance prepared to be rendered.
 
 update_schema ($oldversion, $newversion)
 Requests the search engine to upgrade the schema.
 

Protected Attributes

array $cachedareas = array()
 Internal cache.
 
array $cachedcourses = array()
 Internal cache.
 
stdClass $config = null
 The search engine configuration.
 
string $pluginname = null
 Frankenstyle plugin name.
 
string $queryerror = null
 Last executed query error, if there was any.
 
bool $skipschemacheck = false
 If true, should skip schema validity check when checking the search engine is ready.
 

Static Protected Attributes

static stdClass[] $cachedusers = array()
 User data required to show their fullnames.
 

Detailed Description

Base class for search engines.

All search engines must extend this class.

License
http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

Constructor & Destructor Documentation

◆ __construct()

core_search\engine::__construct ( bool $alternateconfiguration = false)

Initialises the search engine configuration.

Search engine availability should be checked separately.

The alternate configuration option is only used to construct a special second copy of the search engine object, as described in {

See also
has_alternate_configuration}.
Parameters
bool$alternateconfigurationIf true, use alternate configuration settings
Return values
void

Reimplemented in search_solr\engine.

Member Function Documentation

◆ add_document()

core_search\engine::add_document ( $document,
$fileindexing = false )
abstract

Adds a document to the search engine.

Parameters
document$document
bool$fileindexingTrue if file indexing is to be used
Return values
boolFalse if the file was skipped or failed, true on success

Reimplemented in search_simpledb\engine, and search_solr\engine.

◆ add_document_batch()

core_search\engine::add_document_batch ( array $documents,
bool $fileindexing = false )

Adds multiple documents to the search engine.

It should return the number successfully processed, and the number of batches they were processed in (for example if you add 100 documents and there is an error processing one of those documents, and it took 4 batches, it would return [99, 1, 4]).

If the engine implements this, it should return true to {

See also
supports_add_document_batch}.

The system will only call this function with up to {

See also
get_batch_max_documents} documents, and each document in the batch will have content no larger than specified by {
get_batch_max_content}.
Parameters
document[]$documentsDocuments to add
bool$fileindexingTrue if file indexing is to be used
Return values
int[]Array of three elements, successfully processed, failed processed, batch count

Reimplemented in search_solr\engine.

◆ add_documents()

core_search\engine::add_documents ( $iterator,
$searcharea,
$options )

Loop through given iterator of search documents and and have the search engine back end add them to the index.

Parameters
iterator$iteratorthe iterator of documents to index
base$searchareathe area for the documents to index
array$optionsdocument indexing options
Return values
arrayProcessed document counts

◆ area_index_complete()

core_search\engine::area_index_complete ( $searcharea,
$numdocs = 0,
$fullindex = false )

Do any area cleanup needed, and do anything to confirm contents.

Return false to prevent the search area completed time and stats from being updated.

Parameters
core_search\base$searchareaThe search area that was complete
int$numdocsThe number of documents that were added to the index
bool$fullindexTrue if a full index is being performed
Return values
boolTrue means that data is considered indexed

Reimplemented in search_solr\engine.

◆ area_index_starting()

core_search\engine::area_index_starting ( $searcharea,
$fullindex = false )

Do anything that may need to be done before an area is indexed.

Parameters
core_search\base$searchareaThe search area that was complete
bool$fullindexTrue if a full index is being performed
Return values
void

◆ check_latest_schema()

core_search\engine::check_latest_schema ( )

Checks that the schema is the latest version.

If the version stored in config does not match the current, this function will attempt to upgrade the schema.

Return values
bool|stringTrue if schema is OK, a string if user needs to take action

◆ clear_query_error()

core_search\engine::clear_query_error ( )

Clears the current query error value.

Return values
void

◆ clear_users_cache()

static core_search\engine::clear_users_cache ( )
static

Clears the users cache.

Return values
null

◆ delete()

core_search\engine::delete ( $areaid = null)
abstract

Delete all documents.

Parameters
string$areaidTo filter by area
Return values
void

Reimplemented in search_simpledb\engine, and search_solr\engine.

◆ delete_index_for_context()

core_search\engine::delete_index_for_context ( int $oldcontextid)

Deletes information related to a specific context id.

This should be used when the context itself is deleted from Moodle.

This only deletes information for the specified context - not for any child contexts.

This function is optional; if not supported it will return false and the information will not be deleted from the search index.

If an engine implements this function it should also implement delete_index_for_course; otherwise, nothing will be deleted when users delete an entire course at once.

Parameters
int$oldcontextidID of context that has been deleted
Return values
boolTrue if implemented
Exceptions
core_search\engine_exceptionEngines may throw this exception for any problem

Reimplemented in search_simpledb\engine, and search_solr\engine.

◆ delete_index_for_course()

core_search\engine::delete_index_for_course ( int $oldcourseid)

Deletes information related to a specific course id.

This should be used when the course itself is deleted from Moodle.

This deletes all information relating to that course from the index, including all child contexts.

This function is optional; if not supported it will return false and the information will not be deleted from the search index.

If an engine implements this function then, ideally, it should also implement delete_index_for_context so that deletion of single activities/blocks also works.

Parameters
int$oldcourseidID of course that has been deleted
Return values
boolTrue if implemented
Exceptions
core_search\engine_exceptionEngines may throw this exception for any problem

Reimplemented in search_simpledb\engine, and search_solr\engine.

◆ execute_query()

core_search\engine::execute_query ( $filters,
$accessinfo,
$limit = 0 )
abstract

Executes the query on the engine.

Implementations of this function should check user context array to limit the results to contexts where the user have access. They should also limit the owneruserid field to manger\NO_OWNER_ID or the current user's id. Engines must use area->check_access() to confirm user access.

Engines should reasonably attempt to fill up to limit with valid results if they are available.

The $filters object may include the following fields (optional except q):

  • q: value of main search field; results should include this text
  • title: if included, title must match this search
  • areaids: array of search area id strings (only these areas will be searched)
  • courseids: array of course ids (only these courses will be searched)
  • groupids: array of group ids (only results specifically from these groupids will be searched) - this option will be ignored if the search engine doesn't support groups

The $accessinfo parameter has two different values (for historical compatibility). If the engine returns false to supports_group_filtering then it is an array of user contexts, or true if the user can access all contexts. (This parameter used to be called $usercontexts.) If the engine returns true to supports_group_filtering then it will be an object containing these fields:

  • everything (true if admin is searching with no restrictions)
  • usercontexts (same as above)
  • separategroupscontexts (array of context ids where separate groups are used)
  • visiblegroupscontextsareas (array of subset of those where some areas use visible groups)
  • usergroups (array of relevant group ids that user belongs to)

The engine should apply group restrictions to those contexts listed in the 'separategroupscontexts' array. In these contexts, it shouled only include results if the groupid is not set, or if the groupid matches one of the values in USER_GROUPS array, or if the search area is one of those listed in 'visiblegroupscontextsareas' for that context.

Parameters
stdClass$filtersQuery and filters to apply.
stdClass$accessinfoInformation about the contexts the user can access
int$limitThe maximum number of results to return. If empty, limit to manager\MAX_RESULTS.
Return values
core_search\document[]Results or false if no results

Reimplemented in search_simpledb\engine, and search_solr\engine.

◆ file_indexing_enabled()

core_search\engine::file_indexing_enabled ( )

Return true if file indexing is supported and enabled.

False otherwise.

Return values
bool

Reimplemented in search_solr\engine.

◆ get_batch_max_content()

core_search\engine::get_batch_max_content ( )

Gets the maximum size of document content to be included in a shared batch (if the document is bigger then it will be sent on its own; batching does not provide a performance improvement for big documents anyway).

Only relevant if the engine returns true to {

See also
supports_add_document_batch}.

Can be overridden by search engine if required.

Return values
intMax size in bytes, default 1MB

◆ get_batch_max_documents()

int core_search\engine::get_batch_max_documents ( )

Gets the maximum number of documents to send together in batch mode.

Only relevant if the engine returns true to {

See also
supports_add_document_batch}.

Can be overridden by search engine if required.

Number of documents to send together in batch mode, default 100.

◆ get_course()

core_search\engine::get_course ( $courseid)
protected

Returns a course instance checking internal caching.

Parameters
int$courseid
Return values
stdClass

◆ get_document_classname()

core_search\engine::get_document_classname ( )

Gets the document class used by this search engine.

Search engines can overwrite core_search\document with search_ENGINENAME\document class.

Looks for a document class in the current search engine namespace, falling back to core_search\document.

Publicly available because search areas do not have access to the engine details, core_search\document_factory accesses this function.

Return values
string

◆ get_plugin_name()

core_search\engine::get_plugin_name ( )

Returns the plugin name.

Return values
stringFrankenstyle plugin name.

◆ get_query_error()

core_search\engine::get_query_error ( )

Returns any error reported by the search engine when executing the provided query.

It should be called from static\execute_query when an exception is triggered.

Return values
string

◆ get_query_total_count()

core_search\engine::get_query_total_count ( )
abstract

Returns the total number of documents available for the most recent call to execute_query.

This can be an estimate, but should get more accurate the higher the limited passed to execute_query is. To do that, the engine can use (actual result returned count + count of unchecked documents), or (total possible docs - docs that have been checked and rejected).

Engine can limit to manager\MAX_RESULTS if there is cost to determining more. If this cannot be computed in a reasonable way, manager\MAX_RESULTS may be returned.

Return values
int

Reimplemented in search_simpledb\engine, and search_solr\engine.

◆ get_search_area()

core_search\engine::get_search_area ( $areaid)
protected

Returns a search instance of the specified area checking internal caching.

Parameters
string$areaidArea id
Return values
core_search\base

◆ get_supported_orders()

core_search\engine::get_supported_orders ( \context $context)

Obtain a list of results orders (and names for them) that are supported by this search engine in the given context.

By default, engines sort by relevance only.

Parameters
context$contextContext that the user requested search from
Return values
arrayArray from order name => display text

Reimplemented in search_solr\engine.

◆ get_user()

core_search\engine::get_user ( $userid)

Returns user data checking the internal static cache.

Including here the minimum required user information as this may grow big.

Parameters
int$userid
Return values
stdClass

◆ has_alternate_configuration()

core_search\engine::has_alternate_configuration ( )

Checks if the search engine has an alternate configuration.

This is used where the same search engine class supports two different configurations, which are both shown on the settings screen. The alternate configuration is selected by passing 'true' parameter to the constructor.

The feature is used when a different connection is in use for indexing vs. querying the search engine.

This function should only return true if the engine supports an alternate configuration and the user has filled in the settings. (We do not need to test they are valid, that will happen as normal.)

Return values
boolTrue if an alternate configuration is defined

Reimplemented in search_solr\engine.

◆ index_complete()

core_search\engine::index_complete ( $numdocs = 0,
$fullindex = false )

Run any post indexing operations.

Should be overwritten if the search engine needs to do any post index cleanup.

Parameters
int$numdocsThe number of documents that were added to the index
bool$fullindexTrue if a full index was performed
Return values
void

◆ index_starting()

core_search\engine::index_starting ( $fullindex = false)

Run any pre-indexing operations.

Should be overwritten if the search engine needs to do any pre index preparation.

Parameters
bool$fullindexTrue if a full index will be performed
Return values
void

◆ is_installed()

core_search\engine::is_installed ( )

Does the system satisfy all the requirements.

Should be overwritten if the search engine has any system dependencies that needs to be checked.

Return values
bool

Reimplemented in search_simpledb\engine, and search_solr\engine.

◆ is_server_ready()

core_search\engine::is_server_ready ( )
abstract

Is the server ready to use?

This should also check that the search engine configuration is ok.

If the function $this->should_skip_schema_check() returns true, then this function may leave out time-consuming checks that the schema is valid. (This allows for improved performance on critical pages such as the main search form.)

Return values
true|stringReturns true if all good or an error string.

Reimplemented in search_simpledb\engine, and search_solr\engine.

◆ optimize()

core_search\engine::optimize ( )

Optimizes the search engine.

Should be overwritten if the search engine can optimize its contents.

Return values
void

◆ record_applied_schema_version()

core_search\engine::record_applied_schema_version ( $version)

Usually called by the engine; marks that the schema has been updated.

Parameters
int$versionRecords the schema version now applied

◆ should_skip_schema_check()

core_search\engine::should_skip_schema_check ( )
protected

For use by subclasses.

The engine can call this inside is_server_ready to check whether it should skip time-consuming schema checks.

Since
Moodle 3.5
Return values
boolTrue if schema checks should be skipped

◆ skip_schema_check()

core_search\engine::skip_schema_check ( $skip = true)

Tells the search engine to skip any time-consuming checks that it might do as part of the is_server_ready function, and only carry out a basic check that it can contact the server.

This setting is not remembered and applies only to the current request.

Since
Moodle 3.5
Parameters
bool$skipTrue to skip the checks, false to start checking again

◆ supports_add_document_batch()

core_search\engine::supports_add_document_batch ( )

Checks if the search engine supports adding documents in a batch.

If it returns true to this function, the search engine must implement the add_document_batch function.

Return values
boolTrue if the search engine supports adding documents in a batch

Reimplemented in search_solr\engine.

◆ supports_group_filtering()

core_search\engine::supports_group_filtering ( )

Checks if this search engine supports groups.

Note that returning true to this function causes the parameters to execute_query to be passed differently!

In order to implement groups and return true to this function, the search engine should:

  1. Handle the fields ->separategroupscontexts and ->usergroups in the $accessinfo parameter to execute_query (ideally, using these to automatically restrict search results).
  2. Support the optional groupids parameter in the $filter parameter for execute_query to restrict results to only those where the stored groupid matches the given value.
Return values
boolTrue if this engine supports searching by group id field

Reimplemented in search_solr\engine.

◆ supports_users()

core_search\engine::supports_users ( )

Checks if the search engine supports searching by user.

If it returns true to this function, the search engine should support the 'userids' option in the $filters value passed to execute_query(), returning only items where the userid in the search document matches one of those user ids.

Return values
boolTrue if the search engine supports searching by user

Reimplemented in search_solr\engine.

◆ to_document()

core_search\engine::to_document ( \core_search\base $searcharea,
$docdata )
protected

Returns a document instance prepared to be rendered.

Parameters
core_search\base$searcharea
array$docdata
Return values
core_search\document

◆ update_schema()

core_search\engine::update_schema ( $oldversion,
$newversion )
protected

Requests the search engine to upgrade the schema.

The engine should update the schema if possible/necessary, and should ensure that record_applied_schema_version is called as a result.

If it is not possible to upgrade the schema at the moment, it can do nothing and return; the function will be called again next time search is initialised.

The default implementation just returns, with a DEBUG_DEVELOPER warning.

Parameters
int$oldversionOld schema version
int$newversionNew schema version
Return values
bool|stringTrue if schema is updated successfully, a string if it needs updating manually

Reimplemented in search_solr\engine.

Member Data Documentation

◆ $cachedusers

stdClass [] core_search\engine::$cachedusers = array()
staticprotected

User data required to show their fullnames.

Indexed by userid.


The documentation for this class was generated from the following file: