About Features Downloads Getting Started Documentation Events Support GitHub

Love VuFind®? Consider becoming a financial supporter. Your support helps build a better VuFind®!

Site Tools

Warning: This page has not been updated in over over a year and may be outdated or deprecated.

Search Service


VuFind®'s search system integrates access to the application's remote search systems. The design goals for the search system are as follows:

  • separate re-usable classes for interacting with a specific remote system and the application-specific implementation
  • streamline the interface of backend related classes
  • use Laminas' capabilities to provide, extend and/or augment the VuFind® implementation

sequence diagram


Access to the remote system is implemented by a backend class that implements at least the two retrieval functions search() and retrieve(), and getter and setter of a unique identifier of a particular backend instance.

interface VuFindSearch\Backend\BackendInterface
  public function setIdentifier($identifier);
  public function getIdentifier();
  public function search(AbstractQuery $query, $offset, $limit, ParamBag $params = null);
  public function retrieve($id, ParamBag $params = null);

Both retrieval functions must return a (possibly empty) iterable collection of records, in most cases a simple wrapper around the remote system's response document.

VuFindSearch\Response\RecordCollectionInterface extends Countable, Iterator
  public function setSourceIdentifier($identifier);
  public function getSourceIdentifier();
  public function getTotal();
  public function getFacets();
  public function getRecords();
  public function getOffset();
  public function first();
  public function add(RecordInterface $record);

Each member of the collection must implement getters and setters for a source identifier that serves as an indicator of the record's source (where the record resides) and its search backend (where the record was found). These two values are usually the same, but in some edge cases (such as the blended search) they can differ. Results can also be optionally assigned labels to convey additional information to the end user about their source.

  public function setSourceIdentifier($identifier);
  public function setSourceIdentifiers($recordSourceId, $searchBackendId);
  public function getSearchBackendIdentifier();
  public function getSourceIdentifier();
  public function addLabel($label, $class);
  public function setLabels($labels);
  public function getLabels();

Example: The Solr Backend

The Solr backend provides most feature-rich implementation of a VuFind® backend.

The Solr backend uses a dedicated Connector class that adds another level of abstraction: While the backend translates the user-initiated retrieval operation into a set of Solr query parameters, the Connector maps the operation to the responsible Solr request handler and handles the HTTP transport layer.

The Connector returns a serialized Solr response (i.e. the body of the HTTP response) which is deserialized by the Backend. The deserialized response is then passed to a configurable factory that creates the record collection containing the records.

Search Service

The search service integrates all backends used by the VuFind® application. Instead of using the backend classes directly, all retrieval operations use the search service class and select the backend by passing its identifier as first argument. This indirection is necessary in order to implement a well-defined behavior of retrieval operations required to extend and/or modify the application without modifying the core classes or hardcoding application specific behavior.

:!: It is worth noting that every retrieval operation can be called with a 'parameter bag' that holds backend specific operation parameters. This certainly puts limitations on the integration part, but allows for a great deal of flexibility with regards to backend features :!:

The search service uses a scoped service manager bound to the namespace VuFind\Search and emits the following events:


The target of the resolve event is the name of the backend to perform a retrieval operation on. The event is short-circuited and stops as soon as a listener returns a backend instance. Backends are only resolved once during a run of the application.


The target of the pre event is the backend instance. Listeners can access the operation name and parameters via the event's parameters. Parameters that are implemented as objects, such as the parameter bag can be modified by a listener. All other parameters are immutable.


The target of the post event is the return value of the requested operation.


If a backend implementation raised an exception this event is triggered with the exception object as target. Listeners can be attached to e.g. annotate the exception or log specific errors of a third party index provider.

Additional Resources

This Video Presentation from the 2013 VuFind® Summit features some detailed discussion of the search service. Slides are available here.

The Search System Overview and Update video from 2021 provides some valuable updates to the original 2013 Summit content, addressing changes made in release 8.0.

development/architecture/search_service.txt · Last modified: 2023/11/09 21:12 by demiankatz