Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 3.11.x will end 14 Nov 2022 (12 months plus 6 months extension).
  • Bug fixes for security issues in 3.11.x will end 13 Nov 2023 (18 months plus 12 months extension).
  • PHP version: minimum PHP 7.3.0 Note: minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is supported too.

Differences Between: [Versions 310 and 311] [Versions 311 and 401] [Versions 311 and 402] [Versions 311 and 403] [Versions 39 and 311]

Base class for search engines. All search engines must extend this class.

Copyright: 2015 Daniel Neis
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 781 lines (29 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 3 classes


Class: engine  - X-Ref

Base class for search engines.

All search engines must extend this class.

__construct(bool $alternateconfiguration = false)   X-Ref
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 has_alternate_configuration}.

param: bool $alternateconfiguration If true, use alternate configuration settings
return: void

Class: should  - X-Ref

Class: namespace  - X-Ref

get_course($courseid)   X-Ref
Returns a course instance checking internal caching.

param: int $courseid
return: stdClass

get_user($userid)   X-Ref
Returns user data checking the internal static cache.

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

param: int $userid
return: stdClass

clear_users_cache()   X-Ref
Clears the users cache.

return: null

get_search_area($areaid)   X-Ref
Returns a search instance of the specified area checking internal caching.

param: string $areaid Area id
return: \core_search\base

to_document(\core_search\base $searcharea, $docdata)   X-Ref
Returns a document instance prepared to be rendered.

param: \core_search\base $searcharea
param: array $docdata
return: \core_search\document

add_documents($iterator, $searcharea, $options)   X-Ref
Loop through given iterator of search documents
and and have the search engine back end add them
to the index.

param: \iterator $iterator the iterator of documents to index
param: base $searcharea the area for the documents to index
param: array $options document indexing options
return: array Processed document counts

get_plugin_name()   X-Ref
Returns the plugin name.

return: string Frankenstyle plugin name.

get_document_classname()   X-Ref
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: string

index_starting($fullindex = false)   X-Ref
Run any pre-indexing operations.

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

param: bool $fullindex True if a full index will be performed
return: void

index_complete($numdocs = 0, $fullindex = false)   X-Ref
Run any post indexing operations.

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

param: int $numdocs The number of documents that were added to the index
param: bool $fullindex True if a full index was performed
return: void

area_index_starting($searcharea, $fullindex = false)   X-Ref
Do anything that may need to be done before an area is indexed.

param: \core_search\base $searcharea The search area that was complete
param: bool $fullindex True if a full index is being performed
return: void

area_index_complete($searcharea, $numdocs = 0, $fullindex = false)   X-Ref
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.

param: \core_search\base $searcharea The search area that was complete
param: int $numdocs The number of documents that were added to the index
param: bool $fullindex True if a full index is being performed
return: bool True means that data is considered indexed

optimize()   X-Ref
Optimizes the search engine.

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

return: void

is_installed()   X-Ref
Does the system satisfy all the requirements.

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

return: bool

get_query_error()   X-Ref
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: string

file_indexing_enabled()   X-Ref
Return true if file indexing is supported and enabled. False otherwise.

return: bool

clear_query_error()   X-Ref
Clears the current query error value.

return: void

skip_schema_check($skip = true)   X-Ref
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.

param: bool $skip True to skip the checks, false to start checking again

should_skip_schema_check()   X-Ref
For use by subclasses. The engine can call this inside is_server_ready to check whether it
should skip time-consuming schema checks.

return: bool True if schema checks should be skipped

add_document_batch(array $documents, bool $fileindexing = false)   X-Ref
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 supports_add_document_batch}.

The system will only call this function with up to {@see get_batch_max_documents} documents,
and each document in the batch will have content no larger than specified by
{@see get_batch_max_content}.

param: document[] $documents Documents to add
param: bool $fileindexing True if file indexing is to be used
return: int[] Array of three elements, successfully processed, failed processed, batch count

delete_index_for_context(int $oldcontextid)   X-Ref
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.

param: int $oldcontextid ID of context that has been deleted
return: bool True if implemented

delete_index_for_course(int $oldcourseid)   X-Ref
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.

param: int $oldcourseid ID of course that has been deleted
return: bool True if implemented

check_latest_schema()   X-Ref
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: bool|string True if schema is OK, a string if user needs to take action

record_applied_schema_version($version)   X-Ref
Usually called by the engine; marks that the schema has been updated.

param: int $version Records the schema version now applied

update_schema($oldversion, $newversion)   X-Ref
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.

param: int $oldversion Old schema version
param: int $newversion New schema version
return: bool|string True if schema is updated successfully, a string if it needs updating manually

supports_group_filtering()   X-Ref
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: bool True if this engine supports searching by group id field

get_supported_orders(\context $context)   X-Ref
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.

param: \context $context Context that the user requested search from
return: array Array from order name => display text

supports_users()   X-Ref
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: bool True if the search engine supports searching by user

supports_add_document_batch()   X-Ref
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: bool True if the search engine supports adding documents in a batch

get_batch_max_documents()   X-Ref
Gets the maximum number of documents to send together in batch mode.

Only relevant if the engine returns true to {@see supports_add_document_batch}.

Can be overridden by search engine if required.


get_batch_max_content()   X-Ref
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 supports_add_document_batch}.

Can be overridden by search engine if required.

return: int Max size in bytes, default 1MB

has_alternate_configuration()   X-Ref
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: bool True if an alternate configuration is defined