Nextcloud PHP API (master)

IFilteringProvider extends IProvider

Interface for advanced search providers

These providers will be implemented in apps, so they can participate in the global search results of Nextcloud. If an app provides more than one type of resource, e.g. contacts and address books in Nextcloud Contacts, it should register one provider per group.

Tags
since
28.0.0

Table of Contents

Methods

getAlternateIds()  : array<string|int, string>
Get alternate IDs handled by this provider
getCustomFilters()  : array<int, FilterDefinition>
Allows application to declare custom filters
getId()  : string
Get the unique ID of this search provider
getName()  : string
Get the translated name of this search provider
getOrder()  : int|null
Get the search provider order The lower the int, the higher it will be sorted (0 will be before 10) If null, the search provider will be hidden in the UI and the API not called
getSupportedFilters()  : array<string|int, string>
Return the names of filters supported by the application
search()  : SearchResult
Find matching search entries in an app

Methods

getAlternateIds()

Get alternate IDs handled by this provider

public getAlternateIds() : array<string|int, string>

A search provider can complete results from other search providers. For example, files and full-text-search can search in files. If you use in:files in a search, provider files will be invoked, with all other providers declaring files in this method

Tags
since
28.0.0
Return values
array<string|int, string>

IDs

getId()

Get the unique ID of this search provider

public getId() : string

Ideally this should be the app name or an identifier identified with the app name, especially if the app registers more than one provider.

Example: 'mail', 'mail_recipients', 'files_sharing'

Tags
since
20.0.0
Return values
string

getName()

Get the translated name of this search provider

public getName() : string

Example: 'Mail', 'Contacts'...

Tags
since
20.0.0
Return values
string

getOrder()

Get the search provider order The lower the int, the higher it will be sorted (0 will be before 10) If null, the search provider will be hidden in the UI and the API not called

public getOrder(string $route, array<string|int, mixed> $routeParameters) : int|null
Parameters
$route : string

the route the user is currently at, e.g. files.view.index

$routeParameters : array<string|int, mixed>

the parameters of the route the user is currently at, e.g. [fileId = 982, dir = "/"]

Tags
since
20.0.0
since
28.0.0

Can return null

Return values
int|null

getSupportedFilters()

Return the names of filters supported by the application

public getSupportedFilters() : array<string|int, string>

If a filter sent by client is not in this list, the current provider will be ignored. Example: array('term', 'since', 'custom-filter');

Tags
since
28.0.0
Return values
array<string|int, string>

Name of supported filters (default or defined by application)

Find matching search entries in an app

public search(IUser $user, ISearchQuery $query) : SearchResult

Search results can either be a complete list of all the matches the app can find, or ideally a paginated result set where more data can be fetched on demand. To be able to tell where the next offset starts the search uses "cursors" which are a property of the last result entry. E.g. search results that show most recent entries first can look for entries older than the last one of the first result set. This approach was chosen over a numeric limit/ offset approach as the offset moves as new data comes in. The cursor is resistant to these changes and will still show results without overlaps or gaps.

See https://dev.to/jackmarchant/offset-and-cursor-pagination-explained-b89 for the concept of cursors.

Implementations that return result pages have to adhere to the limit property of a search query.

Parameters
$user : IUser
$query : ISearchQuery
Tags
since
20.0.0
Return values
SearchResult

        
On this page

Search results