IProvider.php 3.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108
  1. <?php
  2. declare(strict_types=1);
  3. /**
  4. * @copyright 2020 Christoph Wurst <christoph@winzerhof-wurst.at>
  5. *
  6. * @author Christoph Wurst <christoph@winzerhof-wurst.at>
  7. * @author Joas Schilling <coding@schilljs.com>
  8. * @author John Molakvoæ <skjnldsv@protonmail.com>
  9. *
  10. * @license GNU AGPL version 3 or any later version
  11. *
  12. * This program is free software: you can redistribute it and/or modify
  13. * it under the terms of the GNU Affero General Public License as
  14. * published by the Free Software Foundation, either version 3 of the
  15. * License, or (at your option) any later version.
  16. *
  17. * This program is distributed in the hope that it will be useful,
  18. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  20. * GNU Affero General Public License for more details.
  21. *
  22. * You should have received a copy of the GNU Affero General Public License
  23. * along with this program. If not, see <http://www.gnu.org/licenses/>.
  24. *
  25. */
  26. namespace OCP\Search;
  27. use OCP\IUser;
  28. /**
  29. * Interface for search providers
  30. *
  31. * These providers will be implemented in apps, so they can participate in the
  32. * global search results of Nextcloud. If an app provides more than one type of
  33. * resource, e.g. contacts and address books in Nextcloud Contacts, it should
  34. * register one provider per group.
  35. *
  36. * @since 20.0.0
  37. */
  38. interface IProvider {
  39. /**
  40. * Get the unique ID of this search provider
  41. *
  42. * Ideally this should be the app name or an identifier identified with the
  43. * app name, especially if the app registers more than one provider.
  44. *
  45. * Example: 'mail', 'mail_recipients', 'files_sharing'
  46. *
  47. * @return string
  48. *
  49. * @since 20.0.0
  50. */
  51. public function getId(): string;
  52. /**
  53. * Get the translated name of this search provider
  54. *
  55. * Example: 'Mail', 'Contacts'...
  56. *
  57. * @return string
  58. *
  59. * @since 20.0.0
  60. */
  61. public function getName(): string;
  62. /**
  63. * Get the search provider order
  64. * The lower the int, the higher it will be sorted (0 will be before 10)
  65. *
  66. * @param string $route the route the user is currently at, e.g. files.view.index
  67. * @param array $routeParameters the parameters of the route the user is currently at, e.g. [fileId = 982, dir = "/"]
  68. *
  69. * @return int
  70. *
  71. * @since 20.0.0
  72. */
  73. public function getOrder(string $route, array $routeParameters): int;
  74. /**
  75. * Find matching search entries in an app
  76. *
  77. * Search results can either be a complete list of all the matches the app can
  78. * find, or ideally a paginated result set where more data can be fetched on
  79. * demand. To be able to tell where the next offset starts the search uses
  80. * "cursors" which are a property of the last result entry. E.g. search results
  81. * that show most recent entries first can look for entries older than the last
  82. * one of the first result set. This approach was chosen over a numeric limit/
  83. * offset approach as the offset moves as new data comes in. The cursor is
  84. * resistant to these changes and will still show results without overlaps or
  85. * gaps.
  86. *
  87. * See https://dev.to/jackmarchant/offset-and-cursor-pagination-explained-b89
  88. * for the concept of cursors.
  89. *
  90. * Implementations that return result pages have to adhere to the limit
  91. * property of a search query.
  92. *
  93. * @param IUser $user
  94. * @param ISearchQuery $query
  95. *
  96. * @return SearchResult
  97. *
  98. * @since 20.0.0
  99. */
  100. public function search(IUser $user, ISearchQuery $query): SearchResult;
  101. }