diff options
author | Christoph Wurst <christoph@winzerhof-wurst.at> | 2020-05-11 10:35:54 +0200 |
---|---|---|
committer | Christoph Wurst <christoph@winzerhof-wurst.at> | 2020-06-24 14:20:25 +0200 |
commit | 4488e846a526ed8de37e9756621b7c008d7a9466 (patch) | |
tree | 2e2a9bfe4b2c5fcfb82fc1bcd9ab23693b58fe08 /lib/public/Search | |
parent | 50b1568d48efddc315e503c6a2c3ffe485db7658 (diff) | |
download | nextcloud-server-4488e846a526ed8de37e9756621b7c008d7a9466.tar.gz nextcloud-server-4488e846a526ed8de37e9756621b7c008d7a9466.zip |
Add unified search API
Signed-off-by: Christoph Wurst <christoph@winzerhof-wurst.at>
Diffstat (limited to 'lib/public/Search')
-rw-r--r-- | lib/public/Search/ASearchResultEntry.php | 102 | ||||
-rw-r--r-- | lib/public/Search/IProvider.php | 83 | ||||
-rw-r--r-- | lib/public/Search/ISearchQuery.php | 79 | ||||
-rw-r--r-- | lib/public/Search/SearchResult.php | 112 |
4 files changed, 376 insertions, 0 deletions
diff --git a/lib/public/Search/ASearchResultEntry.php b/lib/public/Search/ASearchResultEntry.php new file mode 100644 index 00000000000..45d62525abd --- /dev/null +++ b/lib/public/Search/ASearchResultEntry.php @@ -0,0 +1,102 @@ +<?php + +declare(strict_types=1); + +/** + * @copyright 2020 Christoph Wurst <christoph@winzerhof-wurst.at> + * + * @author 2020 Christoph Wurst <christoph@winzerhof-wurst.at> + * + * @license GNU AGPL version 3 or any later version + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU Affero General Public License as + * published by the Free Software Foundation, either version 3 of the + * License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Affero General Public License for more details. + * + * You should have received a copy of the GNU Affero General Public License + * along with this program. If not, see <http://www.gnu.org/licenses/>. + */ + +namespace OCP\Search; + +use JsonSerializable; + +/** + * Represents an entry in a list of results an app returns for a unified search + * query. + * + * The app providing the results has to extend this class for customization. In + * most cases apps do not have to add any additional code. + * + * @example ``class MailResultEntry extends ASearchResultEntry {}` + * + * This approach was chosen over a final class as it allows Nextcloud to later + * add new optional properties of an entry without having to break the usage of + * this class in apps. + * + * @since 20.0.0 + */ +abstract class ASearchResultEntry implements JsonSerializable { + + /** + * @var string + * @since 20.0.0 + */ + protected $thumbnailUrl; + + /** + * @var string + * @since 20.0.0 + */ + protected $title; + + /** + * @var string + * @since 20.0.0 + */ + protected $subline; + + /** + * @var string + * @since 20.0.0 + */ + protected $resourceUrl; + + /** + * @param string $thumbnailUrl a relative or absolute URL to the thumbnail or icon of the entry + * @param string $title a main title of the entry + * @param string $subline the secondary line of the entry + * @param string $resourceUrl the URL where the user can find the detail, like a deep link inside the app + * + * @since 20.0.0 + */ + public function __construct(string $thumbnailUrl, + string $title, + string $subline, + string $resourceUrl) { + $this->thumbnailUrl = $thumbnailUrl; + $this->title = $title; + $this->subline = $subline; + $this->resourceUrl = $resourceUrl; + } + + /** + * @return array + * + * @since 20.0.0 + */ + public function jsonSerialize(): array { + return [ + 'thumbnailUrl' => $this->thumbnailUrl, + 'title' => $this->title, + 'subline' => $this->subline, + 'resourceUrl' => $this->resourceUrl, + ]; + } +} diff --git a/lib/public/Search/IProvider.php b/lib/public/Search/IProvider.php new file mode 100644 index 00000000000..57343eda0e5 --- /dev/null +++ b/lib/public/Search/IProvider.php @@ -0,0 +1,83 @@ +<?php + +declare(strict_types=1); + +/** + * @copyright 2020 Christoph Wurst <christoph@winzerhof-wurst.at> + * + * @author 2020 Christoph Wurst <christoph@winzerhof-wurst.at> + * + * @license GNU AGPL version 3 or any later version + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU Affero General Public License as + * published by the Free Software Foundation, either version 3 of the + * License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Affero General Public License for more details. + * + * You should have received a copy of the GNU Affero General Public License + * along with this program. If not, see <http://www.gnu.org/licenses/>. + */ + +namespace OCP\Search; + +use OCP\IUser; + +/** + * Interface for an app 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. + * + * @since 20.0.0 + */ +interface IProvider { + + /** + * Get the unique ID of this search provider + * + * 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' + * + * @return string + * + * @since 20.0.0 + */ + public function getId(): string; + + /** + * Find matching search entries in an app + * + * 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. + * + * @param IUser $user + * @param ISearchQuery $query + * + * @return SearchResult + * + * @since 20.0.0 + */ + public function search(IUser $user, ISearchQuery $query): SearchResult; +} diff --git a/lib/public/Search/ISearchQuery.php b/lib/public/Search/ISearchQuery.php new file mode 100644 index 00000000000..00d538050d4 --- /dev/null +++ b/lib/public/Search/ISearchQuery.php @@ -0,0 +1,79 @@ +<?php + +declare(strict_types=1); + +/** + * @copyright 2020 Christoph Wurst <christoph@winzerhof-wurst.at> + * + * @author 2020 Christoph Wurst <christoph@winzerhof-wurst.at> + * + * @license GNU AGPL version 3 or any later version + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU Affero General Public License as + * published by the Free Software Foundation, either version 3 of the + * License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Affero General Public License for more details. + * + * You should have received a copy of the GNU Affero General Public License + * along with this program. If not, see <http://www.gnu.org/licenses/>. + */ + +namespace OCP\Search; + +/** + * The query objected passed into \OCP\Search\IProvider::search + * + * This mainly wraps the search term, but will ensure that Nextcloud can add new + * optional properties to a search request without having break the interface of + * \OCP\Search\IProvider::search. + * + * @see \OCP\Search\IProvider::search + * + * @since 20.0.0 + */ +interface ISearchQuery { + + /** + * @since 20.0.0 + */ + public const SORT_DATE_DESC = 1; + + /** + * Get the user-entered search term to find matches for + * + * @return string the search term + * @since 20.0.0 + */ + public function getTerm(): string; + + /** + * Get the sort order of results as defined as SORT_* constants on this interface + * + * @return int + * @since 20.0.0 + */ + public function getSortOrder(): int; + + /** + * Get the number of items to return for a paginated result + * + * @return int + * @see \OCP\Search\IProvider for details + * @since 20.0.0 + */ + public function getLimit(): int; + + /** + * Get the app-specific cursor of the tail of the previous result entries + * + * @return int|string|null + * @see \OCP\Search\IProvider for details + * @since 20.0.0 + */ + public function getCursor(); +} diff --git a/lib/public/Search/SearchResult.php b/lib/public/Search/SearchResult.php new file mode 100644 index 00000000000..7abb5b9f188 --- /dev/null +++ b/lib/public/Search/SearchResult.php @@ -0,0 +1,112 @@ +<?php + +declare(strict_types=1); + +/** + * @copyright 2020 Christoph Wurst <christoph@winzerhof-wurst.at> + * + * @author 2020 Christoph Wurst <christoph@winzerhof-wurst.at> + * + * @license GNU AGPL version 3 or any later version + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU Affero General Public License as + * published by the Free Software Foundation, either version 3 of the + * License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Affero General Public License for more details. + * + * You should have received a copy of the GNU Affero General Public License + * along with this program. If not, see <http://www.gnu.org/licenses/>. + */ + +namespace OCP\Search; + +use JsonSerializable; + +/** + * @since 20.0.0 + */ +final class SearchResult implements JsonSerializable { + + /** @var string */ + private $name; + + /** @var bool */ + private $isPaginated; + + /** @var ASearchResultEntry[] */ + private $entries; + + /** @var int|string|null */ + private $cursor; + + /** + * @param string $name the translated name of the result section or group, e.g. "Mail" + * @param bool $isPaginated + * @param ASearchResultEntry[] $entries + * @param null $cursor + * + * @since 20.0.0 + */ + private function __construct(string $name, + bool $isPaginated, + array $entries, + $cursor = null) { + $this->name = $name; + $this->isPaginated = $isPaginated; + $this->entries = $entries; + $this->cursor = $cursor; + } + + /** + * @param ASearchResultEntry[] $entries + * + * @return static + * + * @since 20.0.0 + */ + public static function complete(string $name, array $entries): self { + return new self( + $name, + false, + $entries + ); + } + + /** + * @param ASearchResultEntry[] $entries + * @param int|string $cursor + * + * @return static + * + * @since 20.0.0 + */ + public static function paginated(string $name, + array $entries, + $cursor): self { + return new self( + $name, + true, + $entries, + $cursor + ); + } + + /** + * @return array + * + * @since 20.0.0 + */ + public function jsonSerialize(): array { + return [ + 'name' => $this->name, + 'isPaginated' => $this->isPaginated, + 'entries' => $this->entries, + 'cursor' => $this->cursor, + ]; + } +} |