Nextcloud PHP API (master)

IFullTextSearchProvider
in

Interface IFullTextSearchProvider

This interface must be use when creating a Content Provider for FullTextSearch.

A Content Provider is an extension to the FullTextSearch that will extract and provide content to the FullTextSearch.

There is no limit to the number of Content Provider that can be integrated to FullTextSearch. Each Content Provider corresponding to a type of content available in Nextcloud (files, bookmarks, notes, deck cards, mails, ...)

Content is split in document identified by an ID and the ID of the Content Provider. The content is indexed by a Search Platform that will returns a documentId as a result on a search request.

To oversimplify the mechanism:

  • When indexing, FullTextSearch will ask for documents to every Content Provider.
  • On search, results from the Search Platform, identified by documentId, will be improved by each relative Content Provider.

The Content Provider is a PHP class that implement this interface and is defined in appinfo/info.xml of the app that contains that class:

OCA\YourApp\YourContentProvider

Multiple Content Provider can be defined in a single app.

Tags
since
15.0.0

Table of Contents

Methods

fillIndexDocument()  : mixed
Must fill IIndexDocument with all information relative to the document, before its indexing by the Search Platform.
generateChunks()  : array<string|int, string>
Allow the provider to generate a list of chunk to split a huge list of indexable documents
generateIndexableDocuments()  : array<string|int, IIndexDocument>
Returns all indexable document for a user as an array of IIndexDocument.
getConfiguration()  : array<string|int, mixed>
Should returns the current configuration of the Content Provider.
getId()  : string
Must returns a unique Id used to identify the Content Provider.
getName()  : string
Must returns a descriptive name of the Content Provider.
getSearchTemplate()  : ISearchTemplate
Must returns a ISearchTemplate that contains displayable items and available options to users when searching.
improveSearchRequest()  : mixed
Method is called when a search request is initiated by a user, prior to be sent to the Search Platform.
improveSearchResult()  : mixed
Method is called after results of a search are returned by the Search Platform.
isDocumentUpToDate()  : bool
Called to verify that the document is not already indexed and that the old index is not up-to-date, using the IIndex from IIndexDocument->getIndex()
loadProvider()  : mixed
Called when FullTextSearch is loading your Content Provider.
onInitializingIndex()  : mixed
Called when an index is initiated by the administrator.
onResettingIndex()  : mixed
Called when administrator is resetting the index.
setIndexOptions()  : mixed
This method is called when the administrator specify options when running the ./occ fulltextsearch:index or ./occ fulltextsearch:live
setRunner()  : mixed
Set the wrapper of the currently executed process.
unloadProvider()  : mixed
not used yet.
updateDocument()  : IIndexDocument
The Search Provider must create and return an IIndexDocument based on the IIndex and its status. The IIndexDocument must contains all information as it will be send for indexing.

Methods

fillIndexDocument()

Must fill IIndexDocument with all information relative to the document, before its indexing by the Search Platform.

public fillIndexDocument(IIndexDocument $document) : mixed

Method is called for each element returned previously by generateIndexableDocuments().

Parameters
$document : IIndexDocument
Tags
see
IIndexDocument
since
15.0.0

generateChunks()

Allow the provider to generate a list of chunk to split a huge list of indexable documents

public generateChunks(string $userId) : array<string|int, string>

During the indexing the generateIndexableDocuments method will be called for each entry of the returned array. If the returned array is empty, the generateIndexableDocuments() will be called only once (per user).

Parameters
$userId : string
Tags
since
16.0.0
Return values
array<string|int, string>

generateIndexableDocuments()

Returns all indexable document for a user as an array of IIndexDocument.

public generateIndexableDocuments(string $userId, string $chunk) : array<string|int, IIndexDocument>

There is no need to fill each IIndexDocument with content; at this point, only fill the object with the minimum information to not waste memory while still being able to identify the document it is referring to.

FullTextSearch will call 2 other methods of this interface for each IIndexDocument of the array, prior to their indexing:

  • first, to compare the date of the last index,
  • then, to fill each IIndexDocument with complete data
Parameters
$userId : string
$chunk : string
Tags
see
IIndexDocument
since
15.0.0

-> 16.0.0: the parameter "$chunk" was added

Return values
array<string|int, IIndexDocument>

getConfiguration()

Should returns the current configuration of the Content Provider.

public getConfiguration() : array<string|int, mixed>

This is used to display the configuration when using the ./occ fulltextsearch:check command line.

Tags
since
15.0.0
Return values
array<string|int, mixed>

getId()

Must returns a unique Id used to identify the Content Provider.

public getId() : string

Id must contains only alphanumeric chars, with no space.

Tags
since
15.0.0
Return values
string

getName()

Must returns a descriptive name of the Content Provider.

public getName() : string

This is used in multiple places, so better use a clear display name.

Tags
since
15.0.0
Return values
string

improveSearchRequest()

Method is called when a search request is initiated by a user, prior to be sent to the Search Platform.

public improveSearchRequest(ISearchRequest $searchRequest) : mixed

Your Content Provider can interact with the ISearchRequest to apply the search options and make the search more precise.

Parameters
$searchRequest : ISearchRequest
Tags
see
ISearchRequest
since
15.0.0

improveSearchResult()

Method is called after results of a search are returned by the Search Platform.

public improveSearchResult(ISearchResult $searchResult) : mixed

Your Content Provider can detail each entry with local data to improve the display of the search result.

Parameters
$searchResult : ISearchResult
Tags
see
ISearchResult
since
15.0.0

isDocumentUpToDate()

Called to verify that the document is not already indexed and that the old index is not up-to-date, using the IIndex from IIndexDocument->getIndex()

public isDocumentUpToDate(IIndexDocument $document) : bool

Returning true will not queue the current IIndexDocument to any further operation and will continue on the next element from the list returned by generateIndexableDocuments().

Parameters
$document : IIndexDocument
Tags
since
15.0.0
Return values
bool

loadProvider()

Called when FullTextSearch is loading your Content Provider.

public loadProvider() : mixed
Tags
since
15.0.0

setIndexOptions()

This method is called when the administrator specify options when running the ./occ fulltextsearch:index or ./occ fulltextsearch:live

public setIndexOptions(IIndexOptions $options) : mixed
Parameters
$options : IIndexOptions
Tags
since
15.0.0

setRunner()

Set the wrapper of the currently executed process.

public setRunner(IRunner $runner) : mixed

Because the index process can be long and heavy, and because errors can be encountered during the process, the IRunner is a wrapper that allow the Content Provider to communicate with the process initiated by FullTextSearch.

The IRunner is coming with some methods so the Content Provider can returns important information and errors to be displayed to the admin.

Parameters
$runner : IRunner
Tags
since
15.0.0

updateDocument()

The Search Provider must create and return an IIndexDocument based on the IIndex and its status. The IIndexDocument must contains all information as it will be send for indexing.

public updateDocument(IIndex $index) : IIndexDocument

Method is called during a cron or a ./occ fulltextsearch:live after a new document is created, or an old document is set as modified.

Parameters
$index : IIndex
Tags
since
15.0.0
Return values
IIndexDocument 

        

        
    




    

    

                                

                

                            
    

        On this page

        
    


                

                            

            

    

        

            
Search results